diff -ru handbook/cross-compiler.xml handbook_new/cross-compiler.xml --- handbook/cross-compiler.xml 2010-04-13 14:45:31.000000000 -0400 +++ handbook/cross-compiler.xml 2010-07-24 11:22:54.655923716 -0400 @@ -152,24 +152,61 @@ 

-$ sh4-unknown-linux-gnu-gcc --version
+# sh4-unknown-linux-gnu-gcc --version
 sh4-unknown-linux-gnu-gcc (GCC) 4.2.0 (Gentoo 4.2.0 p1.4)
 Copyright (C) 2007 Free Software Foundation, Inc.
 This is free software; see the source for copying conditions.  There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-$ echo 'int main(){return 0;}' > sh4-test.c
-$ sh4-unknown-linux-gnu-gcc -Wall sh4-test.c -o sh4-test
-$ file sh4-test
+# echo 'int main(){return 0;}' > sh4-test.c
+# sh4-unknown-linux-gnu-gcc -Wall sh4-test.c -o sh4-test
+# file sh4-test
 sh4-test: ELF 32-bit LSB executable, Renesas SH, version 1 (SYSV), for GNU/Linux 2.6.9, dynamically linked (uses shared libs), not stripped

-If the crossdev command failed, you have the log file which you can review to +If the crossdev command failed, you are told the log file which you can review to see if the problem is local. If you're unable to fix the issue, you're welcome to file a bug in our bugzilla. See the Communication page for more information.

+

+To find out which tuple you should use, look over the output from the following +command: +

+ +
+# crossdev -t help
+
+ +

+You can now find a newly compiled cross-compiler in the sysroot at +/usr/CTARGET/. It's a good idea to create pre-built binary packages +so you don't end up waiting another two to three hours every time you want to +reinstall this toolchain. +

+ +
+# quickpkg --include-unmodified-config=y cross-sh4-unknown-linux-gnu/gcc
+# quickpkg --include-unmodified-config=y cross-sh4-unknown-linux-gnu/glibc
+# quickpkg --include-unmodified-config=y cross-sh4-unknown-linux-gnu/binutils
+# quickpkg --include-unmodified-config=y cross-sh4-unknown-linux-gnu/linux-headers
+
+ + +If quickpkg warns you about excluded files, please follow its prompts to include +all files. + + +

+In the future you can reinstall your sysroot by executing the following simple +portage command: +

+ +
+# emerge -k cross-sh4-unknown-linux-gnu/gcc cross-sh4-unknown-linux-gnu/glibc cross-sh4-unknown-linux-gnu/binutils cross-sh4-unknown-linux-gnu/linux-headers
+
+ @@ -179,8 +216,8 @@

To uninstall a toolchain, simply use the --clean option. If you modified -the sysroot by hand, you'll be prompted to delete things inside of it, so you -may want to pipe yes | into the command. +the sysroot by hand, you'll be prompted to delete every file inside, so you will +want to prepend yes | to this command if you are sure. 

@@ -194,17 +231,6 @@
 
 
 
-
-Options
-
-
-

-Obviously crossdev can do a lot more, so to find out more, simply run
-crossdev --help.
-

-
-
-
 
 
 

@@ -220,16 +246,20 @@
 meant to cover/document/whatever the myriad of build failures you are likely
 to see along the way.  If you need such help, see the
 Beyond section in the handbook for
-some pointers.  You certainly should not bug me or anyone else in Gentoo.
+some pointers.
 
 
 
+Let's be very clear: we do not support toolchains which are built by hand!
+
+
+
 If you're still reading, you should really check out the crosstool project
 (refer to the Beyond section) as
 that provides a distribution independent method for generating cross-compilers.
 While it does kind of suck (imo), it is certainly the best (and really only)
 option out there for creating cross-compilers.
-
+
 
 
 
@@ -349,13 +379,13 @@
 	

 
 
-$ ./configure \
+# ./configure \
 	--target=$CTARGET \
 	--prefix=/usr \
 	--with-sysroot=/usr/$CTARGET \
 	--disable-werror
-$ make
-$ make install DESTDIR=$PWD/install-root
+# make
+# make install DESTDIR=$PWD/install-root
 

 
 	

@@ -366,7 +396,7 @@
 	

 
 
-$ rm -rf install-root/usr/{info,lib,man,share}
+# rm -rf install-root/usr/{info,lib,man,share}
 

 
 	

@@ -395,7 +425,7 @@
 	
 
 
-$ yes "" | make ARCH=$ARCH oldconfig prepare
+# yes "" | make ARCH=$ARCH oldconfig prepare
 # mkdir -p /usr/$CTARGET/usr/include
 # cp -a include/linux include/asm-generic /usr/$CTARGET/usr/include/
 # cp -a include/asm-$ARCH /usr/$CTARGET/usr/include/asm
@@ -416,9 +446,9 @@
 	

 
 
-$ mkdir build
-$ cd build
-$ ../configure \
+# mkdir build
+# cd build
+# ../configure \
 	--host=$CTARGET \
 	--prefix=/usr \
 	--with-headers=/usr/$CTARGET/usr/include \
@@ -455,9 +485,9 @@
 	

 
 
-$ mkdir build
-$ cd build
-$ ../configure \
+# mkdir build
+# cd build
+# ../configure \
 	--target=$CTARGET \
 	--prefix=/usr \
 	--with-sysroot=/usr/$CTARGET \
@@ -468,8 +498,8 @@
 	--disable-libmudflap \
 	--disable-libssp \
 	--disable-libgomp
-$ make
-$ make install DESTDIR=$PWD/install-root
+# make
+# make install DESTDIR=$PWD/install-root
 

 
 	

@@ -477,7 +507,7 @@
 	

 
 
-$ rm -rf install-root/usr/{info,include,lib/libiberty.a,man,share}
+# rm -rf install-root/usr/{info,include,lib/libiberty.a,man,share}
 

 
 	

@@ -499,14 +529,14 @@
 	

 
 
-$ rm -rf build
-$ mkdir build
-$ cd build
-$ ../configure \
+# rm -rf build
+# mkdir build
+# cd build
+# ../configure \
 	--host=$CTARGET \
 	--prefix=/usr \
 	--without-cvs
-$ make
+# make
 # make install install_root=/usr/$CTARGET
 

 	
@@ -521,7 +551,7 @@
 	

 
 
-$ ./configure \
+# ./configure \
 	--target=$CTARGET \
 	--prefix=/usr \
 	--with-sysroot=/usr/$CTARGET \
@@ -529,7 +559,7 @@
 	--enable-shared \
 	--disable-checking \
 	--disable-werror
-$ make
+# make
 # make install
 

 	
diff -ru handbook/cross-compiling-packages.xml handbook_new/cross-compiling-packages.xml
--- handbook/cross-compiling-packages.xml	2010-03-04 14:50:38.000000000 -0500
+++ handbook/cross-compiling-packages.xml	2010-07-24 11:15:43.307806513 -0400
@@ -60,12 +60,20 @@
 
 
 

-Cross-compiling a system generally involves two directory trees.  The first is
-where all development files are normally installed.  This is your sysroot.  The
-other tree is where only your runtime files are installed.  You emerge all of
-your fun packages into your sysroot (without trimming down any files), and then
-either install via binary packages or copying files by hand all the stuff you
-need in your runtime tree.
+Cross-compiling a system generally involves two directory trees. The differences
+between them can be difficult to understand, but they are important concepts to
+cross-compiling.
+

+
+

+The first tree to consider is sysroot. Please read the
+Introduction chapter for the sysroot definition.
+

+
+

+The second tree is real root. This one is much simpler to understand: it's
+where you're trying to create a bootable stage3-like installation of Gentoo
+that you can copy to your target device.
 

 
 

@@ -73,12 +81,26 @@
 sysroot as the include/library directories in this tree are already encoded
 into the gcc cross-compiler for searching.  You could use another directory
 and then add custom -I/-L paths to your CPPFLAGS/LDFLAGS, but this has
-historically proven to be problematic.  Yes, it works most of the time, but
-the corner cases are why this method is discouraged.  In the embedded handbook,
-we'll assume you're using the sysroot as your development ROOT.
+historically proven to be problematic in enough corner cases to be discouraged
+for practical use.
 

 
 

+A less common convention, but common nonetheless, is to set ROOT and
+SYSROOT to exactly the same thing. This seems odd, given the definitions
+and differences of ROOT and SYSROOT. Remember from the
+Introduction chapter that the cross-compiler
+sometimes wants libraries preinstalled to SYSROOT first before they're
+used in ROOT, which often is enough aggravation to cause some to install
+everything to SYSROOT. What ends up happening is a mixed, somewhat messy
+ROOT/SYSROOT tree is installed to SYSROOT. However, as
+long as you're generating binary packages, you can later ignore the
+SYSROOT/ROOT directories entirely and install a new ROOT
+elsewhere using those binary packages.
+

+
+
 
 
 

@@ -106,6 +129,11 @@
 # emerge crossdev
+ +crossdev's wrappers automatically configure CBUILD and CHOST. +Do not set these by hand in your environment! + +

We can use these tools for both installing into your development root (sysroot) and into your runtime root. For the latter, simply specify @@ -126,7 +154,7 @@

-By default the wrappers will link to the generic embedded profile. This +By default crossdev will link to the generic embedded profile. This is done to simpilify things, but the user may wish to use a more advanced targeted profile. In order to do that we can update the profile symlink.

@@ -136,8 +164,9 @@

-And naturally to change settings for the target system like USE flags, -FEATURES, and VIDEO_CARDS. We would edit the standard portage config files. +To change settings for the target system like USE flags, FEATURES, and +VIDEO_CARDS, edit the standard portage config files, wherever +PORTAGE_CONFIGROOT points. 

@@ -145,16 +174,18 @@

-Sometimes there are some additional tests we need override for configure -scripts. To do this the wrappers export a few variables to force the test to get -the answer it should. This will help prevent bloat in packages which add local -functions to workaround issues it assumes your system has because it could not -run the test. From time to time you may find you need to add additional -variables to these files in /usr/share/crossdev/include/site/ to -get a package to compile. To figure out the variable you need to add, it's often -as simple as greping the configure script for the autoconf variable and adding -it to the appropriate target file. This becomes obvious after the first few -times of doing it. +Sometimes there are some additional, cross-compile-incomplatible tests we +need override for configure scripts. To do this crossdev exports a few variables +to force the test to get the answer it should. This will help prevent bloat +in packages which add local functions to workaround issues it assumes your +target system has because it could not run the test while cross-compiling +(because, of course, it's not running on the target system). From time to +time you may find you need to add additional variables to these files in +/usr/share/crossdev/include/site/ to get a package to compile. +To figure out the variable you need to add, it's often as simple as greping +the configure script for the autoconf variable (which often begins with "ac_") +and adding it to the appropriate target file. This becomes easy once you +know what you're looking for.

diff -ru handbook/intro.xml handbook_new/intro.xml --- handbook/intro.xml 2010-04-13 14:45:31.000000000 -0400 +++ handbook/intro.xml 2010-07-24 11:24:19.740172352 -0400 @@ -176,8 +176,12 @@
sysroot: system root
- The root directory a compiler uses to find its standard headers and - libraries + This is where all the cross-compiler libraries and headers are installed. + In other words, every library and header the cross-compiler needs to generate + cross-compiled binaries are put here. In theory, this means the toolchain + is good enough. In practice, the cross-compiler often wants some of a + packages's library dependancies, such as ncurses, installed into sysroot + first.
hardfloat