[gentoo-commits] proj/crossdev:master commit in: /

[Sergei Trofimovich]

commit:     3b51089b55836bb36e0e0123f68068642ee0437f
Author:     Sergei Trofimovich <slyfox <AT> gentoo <DOT> org>
AuthorDate: Sat Apr  7 15:56:49 2018 +0000
Commit:     Sergei Trofimovich <slyfox <AT> gentoo <DOT> org>
CommitDate: Sat Apr  7 15:56:49 2018 +0000
URL:        https://gitweb.gentoo.org/proj/crossdev.git/commit/?id=3b51089b

README: wordsmithing, fixed a few typos

Signed-off-by: Sergei Trofimovich <slyfox <AT> gentoo.org>

 README | 146 ++++++++++++++++++++++++++++++++++-------------------------------
 1 file changed, 76 insertions(+), 70 deletions(-)

diff --git a/README b/README
index 65703cb..99287a1 100644
--- a/README
+++ b/README
@@ -6,27 +6,31 @@ crossdev is a cross-compiler environment generator for Gentoo.
 It is useful for various purposes:
 
 - build cross-compiler toolchain for an operating system
-- build cross-compiler toolchain for embedded targets (bare metal)
+- build cross-compiler toolchain for embedded target (bare metal)
 - cross-compile whole Gentoo on a new (or existing) target
 - cross-compile your favourite tool for every target out there
   just to make sure it still compiles and works. Countless bugs
-  were found fixed like that :)
+  were found and fixed like that :)
 
 Crossdev nano HOWTO
 -------------------
 
-So you want to cross-compile a Gentoo package (say busybox):
+So you want to cross-compile a Gentoo package (say busybox to s390x):
 
-# crossdev -t s390x-unknown-linux-gnu
-# (optional) ARCH=s390 PORTAGE_CONFIGROOT=/usr/s390x-unknown-linux-gnu eselect profile set default/linux/s390/17.0/s390x
-# USE=static s390x-unknown-linux-gnu emerge -v1 busybox
-# file /usr/s390x-unknown-linux-gnu/bin/busybox
-/usr/s390x-unknown-linux-gnu/bin/busybox: ELF 64-bit MSB executable, IBM S/390, version 1 (GNU/Linux), statically linked, for GNU/Linux 3.2.0, stripped
+  # crossdev -t s390x-unknown-linux-gnu
+  # (optional) ARCH=s390 PORTAGE_CONFIGROOT=/usr/s390x-unknown-linux-gnu eselect profile set default/linux/s390/17.0/s390x
+  # USE=static s390x-unknown-linux-gnu-emerge -v1 busybox
+  # file /usr/s390x-unknown-linux-gnu/bin/busybox
+  /usr/s390x-unknown-linux-gnu/bin/busybox: ELF 64-bit MSB executable, IBM S/390, version 1 (GNU/Linux), statically linked, for GNU/Linux 3.2.0, stripped
 
 Done!
 
-You can even use qemu-user to run this binary (or even chroot
-to /usr/s390x-unknown-linux-gnu!
+You can use qemu-user to run this binary:
+
+  $ qemu-s390x -L /usr/s390x-unknown-linux-gnu/ /usr/s390x-unknown-linux-gnu/bin/busybox uname -m
+  s390x
+
+or even chroot to /usr/s390x-unknown-linux-gnu directory!
 
 https://wiki.gentoo.org/wiki/Crossdev_qemu-static-user-chroot
 
@@ -36,7 +40,7 @@ Supported platforms
 Cross-compilation is fairly well supported to linux targets.
 Windows is not too broken either.
 
-But prepare for rough corners. This doc will try to help you
+Be prepared for rough corners. This doc will try to help you
 understand what crossdev does and does not do.
 
 A few examples of targets that worked today (produce running
@@ -75,31 +79,31 @@ executables or kernels if applies):
  x86_64-pc-linux-gnu-7.3.0
  x86_64-w64-mingw32-7.3.0
 
-A few more things are likely to Just Work
-and many more can be made work with a litle touch.
+A few more targets are likely to Just Work.
+And many more can be made to work with a litle touch.
 
 How crossdev works (high-level overview)
 ----------------------------------------
 
-crossdev is a tiny shell wrapper around emerge. Wrapper overrides
-a few variabled to aim emerge to another target.
+crossdev is a tiny shell wrapper around emerge tool. The wrapper
+overrides a few variables to aim emerge at another target.
 
-Crossdev leverages following features of portage (and ::gentoo ebulds):
+Crossdev leverages the following features of portage (and ::gentoo
+ebulds):
 
 - ability to override ROOT=/usr/<target> to install cross-compiled
   packages into a new root on a filesystem to avoid cluttering host.
 
 - ability to override PORTAGE_CONFIGROOT=/usr/<target> to untangle
-  from host's portage configuration.
-
-  Namely crossdev populates /usr/<target>/etc/portage/ with defaults
-  suitable for cross-compiling (ARCH, KERNEL, ELIBC variables and so on).
-  You can change all of it.
+  from host's /etc/portage/ configuration. Namely crossdev populates
+      /usr/<target>/etc/portage/
+  with defaults suitable for cross-compiling (ARCH, KERNEL, ELIBC
+  variables and so on). You can change all of them.
 
 - set CBUILD/CHOST/CTARGET variables accordingly to force build
   system into cross-compiling mode. For autotools-based system
-  it means running the following configure script:
-    ./configure --build=${CBUILD} --host=${CHOST} --target=${CTARGET}
+  it means running ./configure script using following options:
+    ./configure --build=${CBUILD} --host=${CHOST} --target=${CTARGET} ...
 
 If toolchains were simple programs crossdev would be a one-liner script:
 
@@ -114,27 +118,29 @@ Unfortunately todays' toolchains have loops in their build-time dependencies:
 
 - cross-compiler itself normally needs a libc built for <target> because
   libc defines various aspects of userland ABI and features provided.
-- and libc for <target> needs a cross-comiler because it's written in C
+- and libc is written in C and thus needs a cross-compiler to be built for
+  <target>.
 
 That's where crossdev comes in useful. It unties this vicious compiler<->libc
-circle by carefully running the following emerge commands (assume s390x-linux
+circle by carefully running the following emerge commands (assume s390x
 example).
 
 Here is what crossdev actually does:
 
 1. create an overlay with new ebuilds (symlinks to existing ebuilds)
-2. build cross-binutils
-    $ emerge cross-s390x-unknown-linux-gnu/binutils
-3. Install minimal set of system headers (kernel and libc)
+2. build cross-binutils:
+   $ emerge cross-s390x-unknown-linux-gnu/binutils
+3. Install system headers (kernel headers and libc headers):
    $ USE="headers-only" emerge cross-s390x-unknown-linux-gnu/linux-headers
    $ USE="headers-only" emerge cross-s390x-unknown-linux-gnu/glibc
-4. Build minimal GCC without libc support (not able link final executables yet)
+4. Build minimal GCC without libc support (not able to link final
+   executables yet)
    $ USE="-*" emerge cross-s390x-unknown-linux-gnu/gcc
-5. Build complete libc
-   $ USE="-headers-only" emerge cross-s390x-unknown-linux-gnu/linux-headers
-   $ USE="-headers-only" emerge cross-s390x-unknown-linux-gnu/glibc
-6. Build full GCC (able to link final binaries and can do c++)
-   $ USE="" emerge cross-s390x-unknown-linux-gnu/gcc
+5. Build complete libc (gcc will need crt.o files)
+   $ emerge cross-s390x-unknown-linux-gnu/linux-headers
+   $ emerge cross-s390x-unknown-linux-gnu/glibc
+6. Build full GCC (able to link final binaries for C and C++)
+   $ emerge cross-s390x-unknown-linux-gnu/gcc
 
 Done!
 
@@ -142,12 +148,13 @@ How crossdev works (more details)
 ---------------------------------
 
 This section contains more details on what actually happens.
-Here we expand on each step briefly outlined in previous section:
+Here we elaborate on each step outlined in previous section:
 
 1. create an overlay with new ebuilds (symlinks to existing ebuilds)
-   <skipping actual commands>. After this step the outcomes are:
+   <skipping numeruos mkdir and ln commands>. After this step the
+   outcomes are:
 
-   - overlay layout is formed:
+   - overlay layout is formed in cross-overlay/:
 
      $ ls -l cross-overlay/cross-s390x-unknown-linux-gnu
      binutils -> /gentoo-ebuilds/gentoo/sys-devel/binutils
@@ -165,7 +172,6 @@ Here we expand on each step briefly outlined in previous section:
      Here we override ARCH, LIBC, KERNEL, CBUILD, CHOST, CTARGET and a
      few other variables.
 
-
    - a few convenience wrappers are created:
 
      /usr/bin/s390x-unknown-linux-gnu-emerge -> cross-emerge
@@ -173,13 +179,13 @@ Here we expand on each step briefly outlined in previous section:
      /usr/bin/s390x-unknown-linux-gnu-fix-root -> cross-fix-root
 
    This way we share ebuild code and still can install cross-compilers
-   independently. Each with it's owv version of libc.
+   independently. Each with it's own version of libc.
 
 2. build cross-binutils
-   $ emerge cross-s390x-unknown-linux-gnu/binutils
+   # emerge cross-s390x-unknown-linux-gnu/binutils
 
-   This way we can install the same version of binutils aiming different
-   targets. As a result we get tools like:
+   This way we can install the same version of binutils aiming at
+   a new target. As a result we get tools like:
    s390x-unknown-linux-gnu-ar (static library archiver)
    s390x-unknown-linux-gnu-as (assembler)
    s390x-unknown-linux-gnu-ld (linker)
@@ -191,56 +197,56 @@ Here we expand on each step briefly outlined in previous section:
    $ USE="headers-only" emerge cross-s390x-unknown-linux-gnu/linux-headers
    $ USE="headers-only" emerge cross-s390x-unknown-linux-gnu/glibc
 
-   As we don't have cross-compiler yet we just copy a bunch on
+   As we don't have cross-compiler yet ebuilds just copy a bunch of
    header files into
        /usr/s390x-unknown-linux-gnu/usr/include
    and setup symlinks like:
        /usr/s390x-unknown-linux-gnu/sys-include -> usr/include
    to make cross-gcc happy.
 
-   These symlinks are target-dependent. A few unusual examples:
+   These include symlinks are target-dependent. A few unusual examples:
 
    - windows (mingw): /usr/x86_64-w64-mingw32/mingw -> usr
    - hurd: /usr/i686-pc-gnu/include -> usr/include
-   - DOS (didn't try yet): /usr/i686-pc-gnu/dev/env/DJDIR/include -> ../../../usr/include
+   - DOS: /usr/i686-pc-gnu/dev/env/DJDIR/include -> ../../../usr/include
 
    Side note: we could have omited symlink creation completely
    and build gcc with parameter:
      --with-native-system-header-dir=${EPREFIX}/usr/include
-   That way ${SYSROOT} would be even more like normal root.
-   Worth a try this one line :)
+   That way ${SYSROOT} directory contents would be even more like normal
+   root. Worth a try! TODO: actually do it.
 
-4. Build minimal GCC without libc support (not able link final executables yet)
-   $ USE="-*" emerge cross-s390x-unknown-linux-gnu/gcc
+4. Build minimal GCC without libc support (not able to link final executables
+   yet)
+   # USE="-*" emerge cross-s390x-unknown-linux-gnu/gcc
 
-   Here gcc uses headers from step [3.] to find out what
-   target libc can do:
+   Here gcc uses headers from step [3.] to find out what target libc can do:
 
    - POSIX support
    - trigonometry functions
    - threading
    - vital constants
 
-   As a result we only get C code generator. No knowledge
-   of how to link executables or shared libraries as those
-   require bits of libc.
+   As a result we only get C code generator. No knowledge of how to link
+   executables or shared libraries as those require bits of libc.
 
-   For tiniest targets (bare-metal) this can be a final step to get basic toolchain.
+   For tiniest targets (bare-metal) this can be a final step to get basic
+   C toolchain.
 
 5. Build complete libc
-   $ USE="-headers-only" emerge cross-s390x-unknown-linux-gnu/linux-headers
-   $ USE="-headers-only" emerge cross-s390x-unknown-linux-gnu/glibc
+   # emerge cross-s390x-unknown-linux-gnu/linux-headers
+   # emerge cross-s390x-unknown-linux-gnu/glibc
 
-   Here we rebuild full libc against system headers. As a result we get C startup
-   files and can link full programs!
+   Here we build full libc against system headers. As a result we get C
+   startup files (crt.o) and can now link full C programs!
 
-6. Build full GCC (able to link final binaries and can do c++)
-   $ USE="" emerge cross-s390x-unknown-linux-gnu/gcc
+6. Build full GCC (able to link final binaries for C and C++)
+   # USE="" emerge cross-s390x-unknown-linux-gnu/gcc
 
-   Here we get full c++ support, various default flags enabled (pie, sanitizers,
-   stack protectors and many other things).
+   Here we get full C++ support, various default flags enabled (pie,
+   sanitizers, stack protectors and others).
 
-   This thing is ready for large-scale operations.
+   The final result is ready for large-scale operations.
 
 Various notes (AKA dirty little tricks)
 ---------------------------------------
@@ -252,22 +258,22 @@ Various notes (AKA dirty little tricks)
 
   crossdev installs /usr/share/config.site with a bunch of cache
   variables preset for targets. It might be a nice place to drop
-  more things into. Or a source of all your cross-compilation
-  problems :)
+  more things into. Or it could be a source of all your cross-compilation
+  problems if variables set incorrect values.
 
-- eclass inheritance
+- eclass importing
 
   To find out various things about target crossdev loads multilib.eclass
   and tries to find out default ABI supported by the target.
 
 - crossdev is just a tiny shell script around emerge :)
 
-  It's full source code of comparable to the size of this README.
+  It's full source code is comparable to the size of this README.
 
 - USE=headers-only
 
-  Many toolchain ebuilds (mostly libcs and kernel headers) are aware
-  of headers-only install specifically for crossdev and similar tools
+  Many toolchain ebuilds (libcs and kernel headers) are aware of
+  headers-only install specifically for crossdev and similar tools
   to be able to build cross-toolchains.
 
 - How to test crossdev layout generation: