From 3b51089b55836bb36e0e0123f68068642ee0437f Mon Sep 17 00:00:00 2001 From: Sergei Trofimovich Date: Sat, 7 Apr 2018 16:56:49 +0100 Subject: README: wordsmithing, fixed a few typos Signed-off-by: Sergei Trofimovich --- 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/ to install cross-compiled packages into a new root on a filesystem to avoid cluttering host. - ability to override PORTAGE_CONFIGROOT=/usr/ to untangle - from host's portage configuration. - - Namely crossdev populates /usr//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//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 because libc defines various aspects of userland ABI and features provided. -- and libc for 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 + . 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) - . After this step the outcomes are: + . 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: -- cgit v1.2.3-65-gdbad