Intro: crossdev-wrappers

-There are a few important variables that we will use throughout this section. -

-You can either set this all by hand, but that obviously gets quite tedious very +There are a few important variables that we will use throughout this section +which we discussed earlier: CBUILD, CHOST, CTARGET, +ROOT, and PORTAGE_CONFIGROOT. +

+You can set this all by hand, but that obviously gets quite tedious very quickly. A better idea is to stick these into a shell script so you can avoid -typing it out all the time. +typing it out all the time. Having it all in a shell script also allows +you to set autoconf test assumptions to skip ./configure tests that are +troublesome for cross-compiling. +

+Something like the following works well to start, and can be tweaked as +desired: +

-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 +86,25 @@ The common convention is to use your /usr/CTARGET/ tree as your 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. +

-Intro: crossdev-wrappers +Intro: crossdev's wrappers

These are simple wrapper scripts that will setup the environment variables to point to the right places for you to be able to cross -compile using emerge. PORTAGE_CONFIGROOT and ROOT both point to the -SYSROOT. +compile using emerge. PORTAGE_CONFIGROOT and ROOT both point to the +SYSROOT by default, but you can change that with the example script above.

+ +crossdev's wrappers automatically configure CBUILD and CHOST. +Do not set these by hand in your environment! (Bug #301751 states that CTARGET +is not set, so you may wish to do so by hand.) + +

 # echo sys-devel/crossdev-wrappers >> /etc/portage/package.keywords
 # emerge crossdev-wrappers

+ +crossdev-wrappers has been merged into crossdev as of version 20100108. If +you have crossdev 20100108 or later, crossdev-wrappers should not and will +not be installed. + + +

+We can use these tools for installing into whichever directory ROOT +points to. You can set ROOT equal to SYSROOT for installation +into sysroot, or ROOT to a different directory for installation into +a "runtime" root. +

-We can use these tools for both installing into your development root -(sysroot) and into your runtime root. For the latter, simply specify -by using the --root option. For example if you had merged via crossdev -an armv4tl-softfloat-linux-gnueabi toolchain you would then invoke the -command just like normal emerge. But using the ctarget prefix: +If you had merged via crossdev an armv4tl-softfloat-linux-gnueabi +toolchain, you would invoke emerge normally, but prepend "emerge" with the +ctarget prefix:

@@ -124,7 +166,7 @@ dependencies from being pulled into the deptree.
 
 
 
-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.
 
@@ -134,25 +176,28 @@ advanced targeted profile. In order to do that we can update the profile symlink

-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 additional portage settings like USE flags, FEATURES, and VIDEO_CARDS, +we would edit the standard portage config files, but this time wherever +PORTAGE_CONFIGROOT points.

-# $EDITOR ${SYSROOT}/etc/make.conf
++# $EDITOR ${PORTAGE_CONFIGROOT}/etc/make.conf
 
 
 
-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.
 
 
 
@@ -163,9 +208,10 @@ times of doing it.
 
 
 
-If you want to uninstall and delete your work, then you can safely remove the
-sysroot tree without affecting any native packages.  See also the section in
-the crossdev guide about uninstalling.
+You can safely remove the sysroot tree at any time without affecting any
+native packages.  See the section in the
+crossdev guide about uninstalling for
+more information.
 
 
 
diff --git a/xml/htdocs/proj/en/base/embedded/handbook/intro.xml b/xml/htdocs/proj/en/base/embedded/handbook/intro.xml
index 89dbc3e..ea01a16 100644
--- a/xml/htdocs/proj/en/base/embedded/handbook/intro.xml
+++ b/xml/htdocs/proj/en/base/embedded/handbook/intro.xml
@@ -174,7 +174,13 @@ PDA we wanted to develop for, the above table would look like:
 
 
 sysroot: system root
-The root directory a compiler uses to find its standard headers and libraries. Sometimes a compiler wants more than just standard headers and libraries in this directory, as though they were "standard" too. We'll explain how to resolve this when it happens in future chapters.
+
+	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 package's
+	library dependancies, such as ncurses, installed into sysroot first.
+
 
 hardfloat
 The system has a hardware Floating Point Unit (FPU) to handle floating point math.
-- 
1.6.4.4