aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorSergei Trofimovich <slyfox@gentoo.org>2018-04-07 16:56:49 +0100
committerSergei Trofimovich <slyfox@gentoo.org>2018-04-07 16:56:49 +0100
commit3b51089b55836bb36e0e0123f68068642ee0437f (patch)
tree83aff317d352e1e13c0af905435a52b5e770e516 /README
parentcrossdev: don't try to delete files from /usr/${CTARGET}/bin/ (diff)
downloadcrossdev-3b51089b55836bb36e0e0123f68068642ee0437f.tar.gz
crossdev-3b51089b55836bb36e0e0123f68068642ee0437f.tar.bz2
crossdev-3b51089b55836bb36e0e0123f68068642ee0437f.zip
README: wordsmithing, fixed a few typos
Signed-off-by: Sergei Trofimovich <slyfox@gentoo.org>
Diffstat (limited to 'README')
-rw-r--r--README146
1 files 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: