summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorYann E. MORIN" <yann.morin.1998@anciens.enib.fr>2010-08-14 14:37:11 (GMT)
committerYann E. MORIN" <yann.morin.1998@anciens.enib.fr>2010-08-14 14:37:11 (GMT)
commita211f4100d3e0196807dbd3b4f1839c41f79f5b1 (patch)
treed29a9ed57c0946e22afaed850658e4075c6ab1d9 /docs
parentebaebdacf45166a587e4e4d2d5e7b2f7a08965e2 (diff)
docs: split into multiple files
The overview.txt file has evolved into more than just an overview. Split it into chapters, and include the misc tutorials. Signed-off-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Diffstat (limited to 'docs')
-rw-r--r--docs/0 - Table of content.txt56
-rw-r--r--docs/1 - Introduction.txt108
-rw-r--r--docs/2 - Installing crosstool-NG.txt93
-rw-r--r--docs/3 - Configuring a toolchain.txt133
-rw-r--r--docs/4 - Building the toolchain.txt142
-rw-r--r--docs/5 - Using the toolchain.txt103
-rw-r--r--docs/6 - Toolchain types.txt64
-rw-r--r--docs/7 - Contributing to crosstool-NG.txt226
-rw-r--r--docs/8 - Internals.txt294
-rw-r--r--docs/A - Credits.txt (renamed from docs/CREDITS)9
-rw-r--r--docs/B - Known issues.txt (renamed from docs/known-issues.txt)9
-rw-r--r--docs/C - Misc. tutorials.txt (renamed from docs/README.macos.txt)45
-rw-r--r--docs/README.freebsd.txt26
-rw-r--r--docs/overview.txt1172
14 files changed, 1281 insertions, 1199 deletions
diff --git a/docs/0 - Table of content.txt b/docs/0 - Table of content.txt
new file mode 100644
index 0000000..ae67cad
--- /dev/null
+++ b/docs/0 - Table of content.txt
@@ -0,0 +1,56 @@
+File.........: 0 - Table of content.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Table Of Content /
+_________________/
+
+
+1- Introduction
+ - History
+ - Referring to crosstool-NG
+
+2- Installing crosstool-NG
+ - Install method
+ - The hacker's way
+ - Preparing for packaging
+ - Shell completion
+ - Contributed code
+
+3- Configuring a toolchain
+ - Interesting config options
+ - Re-building an existing toolchain
+ - Using as a backend for a build-system
+
+4- Building the toolchain
+ - Stopping and restarting a build
+ - Testing all toolchains at once
+ - Overriding the number of // jobs
+ - Note on // jobs
+ - Tools wrapper
+
+5- Using the toolchain
+ - The 'populate' script
+
+6- Toolchain types
+ - Seemingly-native toolchains
+
+7- Contributing
+ - Sending a bug report
+ - Sending patches
+
+8- Internals
+ - Makefile front-end
+ - Kconfig parser
+ - Architecture-specific
+ - Adding a new version of a component
+ - Build scripts
+
+A- Credits
+
+B- Known issues
+
+C- Misc. tutorials
+ - Using crosstool-NG on FreeBSD (and other *BSD)
+ - Using crosstool-NG on MacOS-X
diff --git a/docs/1 - Introduction.txt b/docs/1 - Introduction.txt
new file mode 100644
index 0000000..085b034
--- /dev/null
+++ b/docs/1 - Introduction.txt
@@ -0,0 +1,108 @@
+File.........: 1 - Introduction.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Introduction /
+_____________/
+
+
+crosstool-NG aims at building toolchains. Toolchains are an essential component
+in a software development project. It will compile, assemble and link the code
+that is being developed. Some pieces of the toolchain will eventually end up
+in the resulting binary/ies: static libraries are but an example.
+
+So, a toolchain is a very sensitive piece of software, as any bug in one of the
+components, or a poorly configured component, can lead to execution problems,
+ranging from poor performance, to applications ending unexpectedly, to
+mis-behaving software (which more than often is hard to detect), to hardware
+damage, or even to human risks (which is more than regrettable).
+
+Toolchains are made of different piece of software, each being quite complex
+and requiring specially crafted options to build and work seamlessly. This
+is usually not that easy, even in the not-so-trivial case of native toolchains.
+The work reaches a higher degree of complexity when it comes to cross-
+compilation, where it can become quite a nightmare...
+
+Some cross-toolchains exist on the internet, and can be used for general
+development, but they have a number of limitations:
+ - they can be general purpose, in that they are configured for the majority:
+ no optimisation for your specific target,
+ - they can be prepared for a specific target and thus are not easy to use,
+ nor optimised for, or even supporting your target,
+ - they often are using aging components (compiler, C library, etc...) not
+ supporting special features of your shiny new processor;
+On the other side, these toolchain offer some advantages:
+ - they are ready to use and quite easy to install and setup,
+ - they are proven if used by a wide community.
+
+But once you want to get all the juice out of your specific hardware, you will
+want to build your own toolchain. This is where crosstool-NG comes into play.
+
+There are also a number of tools that build toolchains for specific needs,
+which are not really scalable. Examples are:
+ - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
+ systems, hence the name. But once you have your toolchain with buildroot,
+ part of it is installed in the root-to-be, so if you want to build a whole
+ new root, you either have to save the existing one as a template and
+ restore it later, or restart again from scratch. This is not convenient,
+ - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
+ similar to buildroot,
+ - other projects (openembedded.org for example), which are again used to
+ build root file systems.
+
+crosstool-NG is really targeted at building toolchains, and only toolchains.
+It is then up to you to use it the way you want.
+
+
+History |
+--------+
+
+crosstool was first 'conceived' by Dan Kegel, who offered it to the community
+as a set of scripts, a repository of patches, and some pre-configured, general
+purpose setup files to be used to configure crosstool. This is available at
+http://www.kegel.com/crosstool, and the subversion repository is hosted on
+google at http://code.google.com/p/crosstool/.
+
+I once managed to add support for uClibc-based toolchains, but it did not make
+into mainline, mostly because I didn't have time to port the patch forward to
+the new versions, due in part to the big effort it was taking.
+
+So I decided to clean up crosstool in the state it was, re-order the things
+in place, add appropriate support for what I needed, that is uClibc support
+and a menu-driven configuration, named the new implementation crosstool-NG,
+(standing for crosstool Next Generation, as many other comunity projects do,
+and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
+made it available to the community, in case it was of interest to any one.
+
+
+Referring to crosstool-NG |
+--------------------------+
+
+The long name of the project is crosstool-NG:
+ * no leading uppercase (except as first word in a sentence)
+ * crosstool and NG separated with a hyphen (dash)
+ * NG in uppercase
+
+Crosstool-NG can also be referred to by its short name CT-NG:
+ * all in uppercase
+ * CT and NG separated with a hyphen (dash)
+
+The long name is preferred over the short name, except in mail subjects, where
+the short name is a better fit.
+
+When referring to a specific version of crosstool-NG, append the version number
+either as:
+ * crosstool-NG X.Y.Z
+ - the long name, a space, and the version string
+ * crosstool-ng-X.Y.Z
+ - the long name in lowercase, a hyphen (dash), and the version string
+ - this is used to name the release tarballs
+ * crosstool-ng-X.Y.Z+hg_id
+ - the long name in lowercase, a hyphen, the version string, and the Hg id
+ (as returned by: ct-ng version)
+ - this is used to differentiate between releases and snapshots
+
+The frontend to crosstool-NG is the command ct-ng:
+ * all in lowercase
+ * ct and ng separated by a hyphen (dash)
diff --git a/docs/2 - Installing crosstool-NG.txt b/docs/2 - Installing crosstool-NG.txt
new file mode 100644
index 0000000..1b7c17e
--- /dev/null
+++ b/docs/2 - Installing crosstool-NG.txt
@@ -0,0 +1,93 @@
+File.........: 2 - Installing crosstool-NG.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Installing crosstool-NG /
+________________________/
+
+
+There are two ways you can use crosstool-NG:
+ - build and install it, then get rid of the sources like you'd do for most
+ programs,
+ - or only build it and run from the source directory.
+
+The former should be used if you got crosstool-NG from a packaged tarball, see
+"Install method", below, while the latter is most useful for developpers that
+use a clone of the repository, and want to submit patches, see "The Hacker's
+way", below.
+
+
+Install method |
+---------------+
+
+If you go for the install, then you just follow the classical, but yet easy
+./configure way:
+ ./configure --prefix=/some/place
+ make
+ make install
+ export PATH="${PATH}:/some/place/bin"
+
+You can then get rid of crosstool-NG source. Next create a directory to serve
+as a working place, cd in there and run:
+ ct-ng help
+
+See below for complete usage.
+
+
+The Hacker's way |
+-----------------+
+
+If you go the hacker's way, then the usage is a bit different, although very
+simple:
+ ./configure --local
+ make
+
+Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
+Stay in the directory holding the sources, and run:
+ ./ct-ng help
+
+See below for complete usage.
+
+Now, provided you used a clone of the repository, you can send me your changes.
+See the section titled CONTRIBUTING, below, for how to submit changees.
+
+
+Preparing for packaging |
+------------------------+
+
+If you plan on packaging crosstool-NG, you surely don't want to install it
+in your root file system. The install procedure of crosstool-NG honors the
+DESTDIR variable:
+
+ ./configure --prefix=/usr
+ make
+ make DESTDIR=/packaging/place install
+
+
+Shell completion |
+-----------------+
+
+crosstool-NG comes with a shell script fragment that defines bash-compatible
+completion. That shell fragment is currently not installed automatically, but
+this is planned.
+
+To install the shell script fragment, you have two options:
+ - install system-wide, most probably by copying ct-ng.comp into
+ /etc/bash_completion.d/
+ - install for a single user, by copying ct-ng.comp into ${HOME}/ and
+ sourcing this file from your ${HOME}/.bashrc
+
+
+Contributed code |
+-----------------+
+
+Some people contibuted code that couldn't get merged for various reasons. This
+code is available as lzma-compressed patches, in the contrib/ sub-directory.
+These patches are to be applied to the source of crosstool-NG, prior to
+installing, using something like the following:
+ lzcat contrib/foobar.patch.lzma |patch -p1
+
+There is no guarantee that a particuliar contribution applies to the current
+version of crosstool-ng, or that it will work at all. Use contributions at
+your own risk.
diff --git a/docs/3 - Configuring a toolchain.txt b/docs/3 - Configuring a toolchain.txt
new file mode 100644
index 0000000..8d5cff3
--- /dev/null
+++ b/docs/3 - Configuring a toolchain.txt
@@ -0,0 +1,133 @@
+File.........: 3 - Configuring a toolchain.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+
+Configuring crosstool-NG /
+_________________________/
+
+
+crosstool-NG is configured with a configurator presenting a menu-stuctured set
+of options. These options let you specify the way you want your toolchain
+built, where you want it installed, what architecture and specific processor it
+will support, the version of the components you want to use, etc... The
+value for those options are then stored in a configuration file.
+
+The configurator works the same way you configure your Linux kernel. It is
+assumed you now how to handle this.
+
+To enter the menu, type:
+ ct-ng menuconfig
+
+Almost every config item has a help entry. Read them carefully.
+
+String and number options can refer to environment variables. In such a case,
+you must use the shell syntax: ${VAR}. You shall neither single- nor double-
+quote the string/number options.
+
+There are three environment variables that are computed by crosstool-NG, and
+that you can use:
+
+CT_TARGET:
+ It represents the target tuple you are building for. You can use it for
+ example in the installation/prefix directory, such as:
+ /opt/x-tools/${CT_TARGET}
+
+CT_TOP_DIR:
+ The top directory where crosstool-NG is running. You shouldn't need it in
+ most cases. There is one case where you may need it: if you have local
+ patches and you store them in your running directory, you can refer to them
+ by using CT_TOP_DIR, such as:
+ ${CT_TOP_DIR}/patches.myproject
+
+CT_VERSION:
+ The version of crosstool-NG you are using. Not much use for you, but it's
+ there if you need it.
+
+
+Interesting config options |
+---------------------------+
+
+CT_LOCAL_TARBALLS_DIR:
+ If you already have some tarballs in a direcotry, enter it here. That will
+ speed up the retrieving phase, where crosstool-NG would otherwise download
+ those tarballs.
+
+CT_PREFIX_DIR:
+ This is where the toolchain will be installed in (and for now, where it
+ will run from). Common use is to add the target tuple in the directory
+ path, such as (see above):
+ /opt/x-tools/${CT_TARGET}
+
+CT_TARGET_VENDOR:
+ An identifier for your toolchain, will take place in the vendor part of the
+ target tuple. It shall *not* contain spaces or dashes. Usually, keep it
+ to a one-word string, or use underscores to separate words if you need.
+ Avoid dots, commas, and special characters.
+
+CT_TARGET_ALIAS:
+ An alias for the toolchian. It will be used as a prefix to the toolchain
+ tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
+
+Also, if you think you don't see enough versions, you can try to enable one of
+those:
+
+CT_OBSOLETE:
+ Show obsolete versions or tools. Most of the time, you don't want to base
+ your toolchain on too old a version (of gcc, for example). But at times, it
+ can come handy to use such an old version for regression tests. Those old
+ versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
+ marked because maintaining support for those in crosstool-NG would be too
+ costly, time-wise, and time is dear.
+
+CT_EXPERIMENTAL:
+ Show experimental versions or tools. Again, you might not want to base your
+ toolchain on too recent tools (eg. gcc) for production. But if you need a
+ feature present only in a recent version, or a new tool, you can find them
+ hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
+ receive thorough testing in crosstool-NG, and/or are not mature enough to
+ be blindly trusted.
+
+
+Re-building an existing toolchain |
+----------------------------------+
+
+If you have an existing toolchain, you can re-use the options used to build it
+to create a new toolchain. That needs a very little bit of effort on your side
+but is quite easy. The options to build a toolchain are saved with the
+toolchain, and you can retrieve this configuration by running:
+ ${CT_TARGET}-ct-ng.config
+
+An alternate method is to extract the configuration from a build.log file.
+This will be necessary if your toolchain was build with crosstool-NG prior
+to 1.4.0, but can be used with build.log files from any version:
+ ct-ng extractconfig <build.log >.config
+
+Or, if your build.log file is compressed (most probably!):
+ bzcat build.log.bz2 |ct-ng extractconfig >.config
+
+The above commands will dump the configuration to stdout, so to rebuild a
+toolchain with this configuration, just redirect the output to the
+.config file:
+ ${CT_TARGET}-ct-ng.config >.config
+ ct-ng oldconfig
+
+Then, you can review and change the configuration by running:
+ ct-ng menuconfig
+
+
+Using as a backend for a build-system |
+--------------------------------------+
+
+Crosstool-NG can be used as a backend for an automated build-system. In this
+case, some components that are expected to run on the target (eg. the native
+gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
+build either, as it is considered the responsibility of the build-system to
+build its own versions of those tools.
+
+If you want to use crosstool-NG as a backend to generate your toolchains for
+your build-system, you have to set and export this environment variable:
+ CT_IS_A_BACKEND=y
+
+(case is not sensitive, you can say Y).
diff --git a/docs/4 - Building the toolchain.txt b/docs/4 - Building the toolchain.txt
new file mode 100644
index 0000000..9c10e81
--- /dev/null
+++ b/docs/4 - Building the toolchain.txt
@@ -0,0 +1,142 @@
+File.........: 4 - Building the toolchain.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Building the toolchain /
+_______________________/
+
+
+To build the toolchain, simply type:
+ ct-ng build
+
+This will use the above configuration to retrieve, extract and patch the
+components, build, install and eventually test your newly built toolchain.
+
+You are then free to add the toolchain /bin directory in your PATH to use
+it at will.
+
+In any case, you can get some terse help. Just type:
+ ct-ng help
+or:
+ man 1 ct-ng
+
+
+Stopping and restarting a build |
+--------------------------------+
+
+If you want to stop the build after a step you are debugging, you can pass the
+variable STOP to make:
+ ct-ng build STOP=some_step
+
+Conversely, if you want to restart a build at a specific step you are
+debugging, you can pass the RESTART variable to make:
+ ct-ng build RESTART=some_step
+
+Alternatively, you can call make with the name of a step to just do that step:
+ ct-ng libc_headers
+is equivalent to:
+ ct-ng build RESTART=libc_headers STOP=libc_headers
+
+The shortcuts +step_name and step_name+ allow to respectively stop or restart
+at that step. Thus:
+ ct-ng +libc_headers and: ct-ng libc_headers+
+are equivalent to:
+ ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
+
+To obtain the list of acceptable steps, please call:
+ ct-ng list-steps
+
+Note that in order to restart a build, you'll have to say 'Y' to the config
+option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
+that far.
+
+
+Building all toolchains at once |
+--------------------------------+
+
+You can build all samples; simply call:
+ ct-ng build-all
+
+
+Overriding the number of // jobs |
+---------------------------------+
+
+If you want to override the number of jobs to run in // (the -j option to
+make), you can either re-enter the menuconfig, or simply add it on the command
+line, as such:
+ ct-ng build.4
+
+which tells crosstool-NG to override the number of // jobs to 4.
+
+You can see the actions that support overriding the number of // jobs in
+the help menu. Those are the ones with [.#] after them (eg. build[.#] or
+build-all[.#], and so on...).
+
+
+Note on // jobs |
+----------------+
+
+The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
+in parallel (there is not much to gain). When speaking of // jobs, we are
+refering to the number of // jobs when making the *components*. That is, we
+speak of the number of // jobs used to build gcc, glibc, and so on...
+
+
+Tools wrapper |
+--------------+
+
+Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
+come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
+dependency on libelf. These are libraries that enable advanced features to
+gcc. Additionally, some of those libraries can be used by binutils and gdb.
+Unfortunately, not all systems on which crosstool-NG runs have all of those
+libraries. And for those that do, the versions of those libraries may be
+older than the version required by gcc (and binutils and gdb). To date,
+Debian stable (aka Lenny) is lagging behind on some, and is missing the
+others.
+
+This is why crosstool-NG builds its own set of libraries as part of the
+toolchain.
+
+The companion libraries can be built either as static libraries, or as shared
+libraries. The default is to build static libraries, and is the safe way.
+If you decide to use static companion libraries, then you can stop reading
+this section.
+
+But if you prefer to have shared libraries, then read on...
+
+Building shared companion libraries poses no problem at build time, as
+crosstool-NG correctly points gcc (and binutils and gdb) to the correct
+place where our own version of the libraries are installed. But it poses
+a problem when gcc et al. are run: the place where the libraries are is most
+probably not known to the host dynamic linker. Still worse, if the host system
+has its own versions, then ld.so would load the wrong libraries!
+
+So we have to force the dynamic linker to load the correct version. We do this
+by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
+to look for shared libraries prior to searching its standard places. But we
+can't impose that burden on all the system (because it'd be a nightmare to
+configure, and because two toolchains on the same system may use different
+versions of the libraries); so we have to do it on a per-toolchain basis.
+
+So we rename all binaries of the toolchain (by adding a dot '.' as their first
+character), and add a small program, the so-called "tools wrapper", that
+correctly sets LD_LIBRARY_PATH prior to running the real tool.
+
+First, the wrapper was written as a POSIX-compliant shell script. That shell
+script is very simple, if not trivial, and works great. The only drawback is
+that it does not work on host systems that lack a shell, for example the
+MingW32 environment. To solve the issue, the wrapper has been re-written in C,
+and compiled at build time. This C wrapper is much more complex than the shell
+script, and although it sems to be working, it's been only lightly tested.
+Some of the expected short-comings with this C wrapper are;
+ - multi-byte file names may not be handled correctly
+ - it's really big for what it does
+
+So, the default wrapper installed with your toolchain is the shell script.
+If you know that your system is missing a shell, then you shall use the C
+wrapper (and report back whether it works, or does not work, for you).
+
+A final word on the subject: do not build shared libraries. Build them
+static, and you'll be safe.
diff --git a/docs/5 - Using the toolchain.txt b/docs/5 - Using the toolchain.txt
new file mode 100644
index 0000000..0c38da1
--- /dev/null
+++ b/docs/5 - Using the toolchain.txt
@@ -0,0 +1,103 @@
+File.........: 5 - Using the toolchain.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Using the toolchain /
+____________________/
+
+
+Using the toolchain is as simple as adding the toolchain's bin directory in
+your PATH, such as:
+ export PATH="${PATH}:/your/toolchain/path/bin"
+
+and then using the target tuple to tell the build systems to use your
+toolchain:
+ ./configure --target=your-target-tuple
+or
+ make CC=your-target-tuple-gcc
+or
+ make CROSS_COMPILE=your-target-tuple-
+and so on...
+
+It is strongly advised not to use the toolchain sys-root directory as an
+install directory for your programs/packages. If you do so, you will not be
+able to use your toolchain for another project. It is even strongly advised
+that your toolchain is chmod-ed to read-only once successfully build, so that
+you don't go polluting your toolchain with your programs/packages' files.
+
+Thus, when you build a program/package, install it in a separate directory,
+eg. /your/root. This directory is the /image/ of what would be in the root file
+system of your target, and will contain all that your programs/packages have
+installed.
+
+
+The 'populate' script |
+----------------------+
+
+When your root directory is ready, it is still missing some important bits: the
+toolchain's libraries. To populate your root directory with those libs, just
+run:
+ your-target-tuple-populate -s /your/root -d /your/root-populated
+
+This will copy /your/root into /your/root-populated, and put the needed and only
+the needed libraries there. Thus you don't polute /your/root with any cruft that
+would no longer be needed should you have to remove stuff. /your/root always
+contains only those things you install in it.
+
+You can then use /your/root-populated to build up your file system image, a
+tarball, or to NFS-mount it from your target, or whatever you need.
+
+The populate script accepts the following options:
+
+ -s src_dir
+ Use 'src_dir' as the un-populated root directory.
+
+ -d dst_dir
+ Put the populated root directory in 'dst_dir'.
+
+ -l lib1 [...]
+ Always add specified libraries.
+
+ -L file
+ Always add libraries listed in 'file'.
+
+ -f
+ Remove 'dst_dir' if it previously existed; continue even if any library
+ specified with -l or -L is missing.
+
+ -v
+ Be verbose, and tell what's going on (you can see exactly where libs are
+ coming from).
+
+ -h
+ Print the help.
+
+See 'your-target-tuple-populate -h' for more information on the options.
+
+Here is how populate works:
+
+ 1) performs some sanity checks:
+ - src_dir and dst_dir are specified
+ - src_dir exists
+ - unless forced, dst_dir does not exist
+ - src_dir != dst_dir
+
+ 2) copy src_dir to dst_dir
+
+ 3) add forced libraries to dst_dir
+ - build the list from -l and -L options
+ - get forced libraries from the sysroot (see below for heuristics)
+ - abort on the first missing library, unless -f is specified
+
+ 4) add all missing libraries to dst_dir
+ - scan dst_dir for every ELF files that are 'executable' or
+ 'shared object'
+ - list the "NEEDED Shared library" fields
+ - check if the library is already in dst_dir/lib or dst_dir/usr/lib
+ - if not, get the library from the sysroot
+ - if it's in sysroot/lib, copy it to dst_dir/lib
+ - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
+ - in both cases, use the SONAME of the library to create the file
+ in dst_dir
+ - if it was not found in the sysroot, this is an error.
diff --git a/docs/6 - Toolchain types.txt b/docs/6 - Toolchain types.txt
new file mode 100644
index 0000000..a490a3b
--- /dev/null
+++ b/docs/6 - Toolchain types.txt
@@ -0,0 +1,64 @@
+File.........: 6 - Toolchain types.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Toolchain types /
+________________/
+
+
+There are four kinds of toolchains you could encounter.
+
+First off, you must understand the following: when it comes to compilers there
+are up to four machines involved:
+ 1) the machine configuring the toolchain components: the config machine
+ 2) the machine building the toolchain components: the build machine
+ 3) the machine running the toolchain: the host machine
+ 4) the machine the toolchain is generating code for: the target machine
+
+We can most of the time assume that the config machine and the build machine
+are the same. Most of the time, this will be true. The only time it isn't
+is if you're using distributed compilation (such as distcc). Let's forget
+this for the sake of simplicity.
+
+So we're left with three machines:
+ - build
+ - host
+ - target
+
+Any toolchain will involve those three machines. You can be as pretty sure of
+this as "2 and 2 are 4". Here is how they come into play:
+
+1) build == host == target
+ This is a plain native toolchain, targetting the exact same machine as the
+ one it is built on, and running again on this exact same machine. You have
+ to build such a toolchain when you want to use an updated component, such
+ as a newer gcc for example.
+ crosstool-NG calls it "native".
+
+2) build == host != target
+ This is a classic cross-toolchain, which is expected to be run on the same
+ machine it is compiled on, and generate code to run on a second machine,
+ the target.
+ crosstool-NG calls it "cross".
+
+3) build != host == target
+ Such a toolchain is also a native toolchain, as it targets the same machine
+ as it runs on. But it is build on another machine. You want such a
+ toolchain when porting to a new architecture, or if the build machine is
+ much faster than the host machine.
+ crosstool-NG calls it "cross-native".
+
+4) build != host != target
+ This one is called a canadian-toolchain (*), and is tricky. The three
+ machines in play are different. You might want such a toolchain if you
+ have a fast build machine, but the users will use it on another machine,
+ and will produce code to run on a third machine.
+ crosstool-NG calls it "canadian".
+
+crosstool-NG can build all these kinds of toolchains (or is aiming at it,
+anyway!)
+
+(*) The term Canadian Cross came about because at the time that these issues
+ were all being hashed out, Canada had three national political parties.
+ http://en.wikipedia.org/wiki/Cross_compiler
diff --git a/docs/7 - Contributing to crosstool-NG.txt b/docs/7 - Contributing to crosstool-NG.txt
new file mode 100644
index 0000000..41af5e8
--- /dev/null
+++ b/docs/7 - Contributing to crosstool-NG.txt
@@ -0,0 +1,226 @@
+File.........: 7 - Contributing to crosstool-NG.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Contributing to crosstool-NG /
+_____________________________/
+
+
+Sending a bug report |
+---------------------+
+
+If you need to send a bug report, please send a mail with subject
+prefixed with "[CT_NG]" with to following destinations:
+ TO: yann.morin.1998 (at) anciens.enib.fr
+ CC: crossgcc (at) sourceware.org
+
+
+Sending patches |
+----------------+
+
+If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
+
+Patches should come with the appropriate SoB line. A SoB line is typically
+something like:
+ Signed-off-by: John DOE <john.doe@somewhere.net>
+
+The SoB line is clearly described in Documentation/SubmittingPatches , section
+12, of your favourite Linux kernel source tree.
+
+
+How to Use Mercurial |
+---------------------+
+
+For larger or more frequent contributions, mercurial should be used.
+
+PREREQUISITES:
+
+Configuring Mercurial:
+ You need mercurial with the following extensions:
+ - mq : http://mercurial.selenic.com/wiki/MqExtension
+ - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
+ Usually, these two extensions are already part of the installation package.
+ The mq extension maintains a separate queue of your local changes
+ that you can change at any later time.
+ With the patchbomb extension you can email those patches directly
+ from your local repo.
+
+ Your configuration file for mercurial, e.g. ~/.hgrc should contain
+ at least the following sections (but have a look at `man hgrc`):
+ # ---
+ [email]
+ # configure sending patches directly via Mercurial
+ from = "Your Name" <your@email.address>
+ # How to send email:
+ method = smtp
+
+ [smtp]
+ # SMTP configuration (only for method=smtp)
+ host = localhost
+ tls = true
+ username =
+ password =
+
+ [extensions]
+ # The following lines enable the two extensions:
+ hgext.mq =
+ hgext.patchbomb =
+ # ----
+
+Create your local repository as a clone:
+ hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
+
+Setting up the mq extension in your local copy:
+ cd crosstool-ng
+ hg qinit
+
+
+CREATING PATCHES:
+
+Recording your changes in the patch queue maintained by mq:
+ # First, create a new patch entry in the patch queue:
+ hg qnew -D -U -e short_patch_name1
+ <edit patch description as commit message (see below for an example)>
+
+ <now edit the ct-ng sources and check them>
+
+ # if you execute `hg status` here, your modifications of the working
+ # copy should show up.
+
+ # Now the following command takes your modifications from the working copy
+ # into the patch entry
+ hg qrefresh -D [-e]
+ <reedit patch description [-e] if desired>
+
+ # Now your changes are recorded, and `hg status` should show a clean
+ # working copy
+
+Repeat the above steps for all your modifications.
+The command `hg qseries` informs you about the content of your patch queue.
+
+
+CONTRIBUTING YOUR PATCHES:
+
+Once you are satisfied with your patch series, you can (you should!)
+contribute them back to upstream.
+This is easily done using the `hg email` command.
+
+`hg email` sends your new changesets to a specified list of recipients,
+each patch in its own email, all ordered in the way you entered them (oldest
+first). The command line flag --outgoing selects all changesets that are in
+your local but not yet in the upstream repository. Here, these are exactly
+the ones you entered into your local patch queue in the section above, so
+--outgoing is what you want.
+
+Each email gets the subject set to: "[PATCH x of n] <series summary>"
+where 'x' is the serial number in the email series, and 'n' is the total number
+of patches in the series. The body of the email is the complete patch, plus
+a handful of metadata, that helps properly apply the patch, keeping the log
+message, attribution and date, tracking file changes (move, delete, modes...)
+
+`hg email` also threads all outgoing patch emails below an introductory
+message. You should use the introductory message (command line flag --intro)
+to describe the scope and motivation for the whole patch series. The subject
+for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
+and you get the chance to set the <series summary>.
+
+Here is a sample `hg email` complete command line:
+Note: replace " (at) " with "@"
+
+ hg email --outgoing --intro \
+ --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
+ --cc 'crossgcc (at) sourceware.org'
+
+ # It then opens an editor and lets you enter the subject
+ # and the body for the introductory message.
+
+Use `hg email` with the additional command line switch -n to
+first have a look at the email(s) without actually sending them.
+
+
+MAINTAINING YOUR PATCHES:
+
+When the patches are refined by discussing them on the mailing list,
+you may want to finalize and resend them.
+
+The mq extension has the idiosyncrasy of imposing a stack onto the queue:
+You can always reedit/refresh only the patch on top of stack.
+The queue consists of applied and unapplied patches
+(if you reached here via the above steps, all of your patches are applied),
+where the 'stack' consists of the applied patches, and 'top of stack'
+is the latest applied patch.
+
+The following output of `hg qseries` is now used as an example:
+ 0 A short_patch_name1
+ 1 A short_patch_name2
+ 2 A short_patch_name3
+ 3 A short_patch_name4
+
+You are now able to edit patch 'short_patch_name4' (which is top of stack):
+ <Edit the sources>
+ # and execute again
+ hg qrefresh -D [-e]
+ <and optionally [-e] reedit the commit message>
+
+If you want to edit e.g. patch short_patch_name2, you have to modify
+mq's stack so this patch gets top of stack.
+For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
+
+ hg qgoto short_patch_name2
+ # The patch queue should now look like
+ hg qseries
+ 0 A short_patch_name1
+ 1 A short_patch_name2
+ 2 U short_patch_name3
+ 3 U short_patch_name4
+ # so patch # 1 (short_patch_name2) is top of stack.
+ <now reedit the sources for short_patch_name2>
+ # and execute again
+ hg qrefresh -D [-e]
+ <and optionally [-e] reedit the commit message>
+ # the following command reapplies the now unapplied two patches:
+ hg qpush -a
+ # you can also use `hg qgoto short_patch_name4` to get there again.
+
+
+RESENDING YOUR REEDITED PATCHES:
+
+By mailing list policy, please resend your complete patch series.
+--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
+
+
+SYNCING WITH UPSTREAM AGAIN:
+
+You can sync your repo with upstream at any time by executing
+ # first unapply all your patches:
+ hg qpop -a
+ # next fetch new changesets from upstream
+ hg pull
+ # then update your working copy
+ hg up
+ # optionally remove already upstream integrated patches (see below)
+ hg qdelete <short_name_of_already_applied_patch>
+ # and reapply your patches if any non upstream-integrated left (but see below)
+ hg qpush -a
+
+Eventually, your patches get included into the upstream repository
+which you initially cloned.
+In this case, before executing the hg qpush -a from above
+you should manually "hg qdelete" the patches that are already integrated upstream.
+
+
+HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
+
+Commit messages should look like (without leading pipes):
+ |component: short, one-line description
+ |
+ |optional longer description
+ |on multiple lines if needed
+
+Here is an example commit message (see revision a53a5e1d61db):
+ |comp-libs/cloog: fix building
+ |
+ |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
+ |For any later versions, the directory name does have the version, such as
+ |cloog-ppl-0.15.4.
diff --git a/docs/8 - Internals.txt b/docs/8 - Internals.txt
new file mode 100644
index 0000000..395c402
--- /dev/null
+++ b/docs/8 - Internals.txt
@@ -0,0 +1,294 @@
+File.........: 8 - Internals.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Internals /
+__________/
+
+
+Internally, crosstool-NG is script-based. To ease usage, the frontend is
+Makefile-based.
+
+
+Makefile front-end |
+-------------------+
+
+The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
+script with an action will act exactly as if the Makefile was in the current
+working directory and make was called with the action as rule. Thus:
+ ct-ng menuconfig
+
+is equivalent to having the Makefile in CWD, and calling:
+ make menuconfig
+
+Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
+traditional command.
+
+ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
+at configuration time with ./configure.
+
+ct-ng also searches for config files, sub-tools, samples, scripts and patches in
+that library directory.
+
+Because of a stupid make behavior/bug I was unable to track down, implicit make
+rules are disabled: installing with --local would triger those rules, and mconf
+was unbuildable.
+
+
+Kconfig parser |
+---------------+
+
+The kconfig language is a hacked version, vampirised from the Linux kernel
+(http://www.kernel.org/), and (heavily) adapted to my needs.
+
+The list of the most notable changes (at least the ones I remember) follows:
+- the CONFIG_ prefix has been replaced with CT_
+- a leading | in prompts is skipped, and subsequent leading spaces are not
+ trimmed; otherwise leading spaces are silently trimmed
+- removed the warning about undefined environment variable
+
+The kconfig parsers (conf and mconf) are not installed pre-built, but as
+source files. Thus you can have the directory where crosstool-NG is installed,
+exported (via NFS or whatever) and have clients with different architectures
+use the same crosstool-NG installation, and most notably, the same set of
+patches.
+
+
+Architecture-specific |
+----------------------+
+
+Note: this chapter is not really well written, and might thus be a little bit
+complex to understand. To get a better grasp of what an architecture is, the
+reader is kindly encouraged to look at the "arch/" sub-directory, and to the
+existing architectures to see how things are laid out.
+
+An architecture is defined by:
+
+ - a human-readable name, in lower case letters, with numbers as appropriate.
+ The underscore is allowed; space and special characters are not.
+ Eg.: arm, x86_64
+ - a file in "config/arch/", named after the architecture's name, and suffixed
+ with ".in".
+ Eg.: config/arch/arm.in
+ - a file in "scripts/build/arch/", named after the architecture's name, and
+ suffixed with ".sh".
+ Eg.: scripts/build/arch/arm.sh
+
+The architecture's ".in" file API:
+ > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
+ actual architecture name).
+ That config option must have *neither* a type, *nor* a prompt! Also, it can
+ *not* depend on any other config option (EXPERIMENTAL is managed as above).
+ Eg.:
+ config ARCH_arm
+ + mandatory:
+ defines a (terse) help entry for this architecture:
+ Eg.:
+ config ARCH_arm
+ help
+ The ARM architecture.
+ + optional:
+ selects adequate associated config options.
+ Note: 64-bit architectures *shall* select ARCH_64
+ Eg.:
+ config ARCH_arm
+ select ARCH_SUPPORTS_BOTH_ENDIAN
+ select ARCH_DEFAULT_LE
+ help
+ The ARM architecture.
+ Eg.:
+ config ARCH_x86_64
+ select ARCH_64
+ help
+ The x86_64 architecture.
+
+ > other target-specific options, at your discretion. Note however that to
+ avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
+ where %arch% is again replaced by the actual architecture name.
+ (Note: due to historical reasons, and lack of time to clean up the code,
+ I may have left some config options that do not completely conform to
+ this, as the architecture name was written all upper case. However, the
+ prefix is unique among architectures, and does not cause harm).
+
+The architecture's ".sh" file API:
+ > the function "CT_DoArchTupleValues"
+ + parameters: none
+ + environment:
+ - all variables from the ".config" file,
+ - the two variables "target_endian_eb" and "target_endian_el" which are
+ the endianness suffixes
+ + return value: 0 upon success, !0 upon failure
+ + provides:
+ - mandatory
+ - the environment variable CT_TARGET_ARCH
+ - contains:
+ the architecture part of the target tuple.
+ Eg.: "armeb" for big endian ARM
+ "i386" for an i386
+ + provides:
+ - optional
+ - the environment variable CT_TARGET_SYS
+ - contains:
+ the sytem part of the target tuple.
+ Eg.: "gnu" for glibc on most architectures
+ "gnueabi" for glibc on an ARM EABI
+ - defaults to:
+ - for glibc-based toolchain: "gnu"
+ - for uClibc-based toolchain: "uclibc"
+ + provides:
+ - optional
+ - the environment variables to configure the cross-gcc (defaults)
+ - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
+ - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
+ - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
+ - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
+ - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
+ - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
+ + provides:
+ - optional
+ - the environment variables to pass to the cross-gcc to build target binaries (defaults)
+ - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
+ - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
+ - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
+ - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
+ - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
+ - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
+ - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
+ - default to:
+ see above.
+ + provides:
+ - optional
+ - the environement variables to configure the core and final compiler, specific to this architecture:
+ - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
+ - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
+ - default to:
+ - all empty
+ + provides:
+ - optional
+ - the architecture-specific CFLAGS and LDFLAGS:
+ - CT_ARCH_TARGET_CLFAGS
+ - CT_ARCH_TARGET_LDFLAGS
+ - default to:
+ - all empty
+
+You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
+a quite complete example of what an actual architecture description looks like.
+
+
+Kernel specific |
+----------------+
+
+A kernel is defined by:
+
+ - a human-readable name, in lower case letters, with numbers as appropriate.
+ The underscore is allowed; space and special characters are not (although
+ they are internally replaced with underscores.
+ Eg.: linux, bare-metal
+ - a file in "config/kernel/", named after the kernel name, and suffixed with
+ ".in".
+ Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
+ - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
+ with ".sh".
+ Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
+
+The kernel's ".in" file must contain:
+ > an optional lines containing exactly "# EXPERIMENTAL", starting on the
+ first column, and without any following space or other character.
+ If this line is present, then this kernel is considered EXPERIMENTAL,
+ and correct dependency on EXPERIMENTAL will be set.
+
+ > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
+ replaced with the actual kernel name, with all special characters and
+ spaces replaced by underscores).
+ That config option must have *neither* a type, *nor* a prompt! Also, it can
+ *not* depends on EXPERIMENTAL.
+ Eg.: KERNEL_linux, KERNEL_bare_metal
+ + mandatory:
+ defines a (terse) help entry for this kernel.
+ Eg.:
+ config KERNEL_bare_metal
+ help
+ Build a compiler for use without any kernel.
+ + optional:
+ selects adequate associated config options.
+ Eg.:
+ config KERNEL_bare_metal
+ select BARE_METAL
+ help
+ Build a compiler for use without any kernel.
+
+ > other kernel specific options, at your discretion. Note however that, to
+ avoid name-clashing, such options should be prefixed with
+ "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
+ the actual kernel name.
+ (Note: due to historical reasons, and lack of time to clean up the code,
+ I may have left some config options that do not completely conform to
+ this, as the kernel name was written all upper case. However, the prefix
+ is unique among kernels, and does not cause harm).
+
+The kernel's ".sh" file API:
+ > is a bash script fragment
+
+ > defines the function CT_DoKernelTupleValues
+ + see the architecture's CT_DoArchTupleValues, except for:
+ + set the environment variable CT_TARGET_KERNEL, the kernel part of the
+ target tuple
+ + return value: ignored
+
+ > defines the function "do_kernel_get":
+ + parameters: none
+ + environment:
+ - all variables from the ".config" file.
+ + return value: 0 for success, !0 for failure.
+ + behavior: download the kernel's sources, and store the tarball into
+ "${CT_TARBALLS_DIR}". To this end, a functions is available, that
+ abstracts downloading tarballs:
+ - CT_DoGet <tarball_base_name> <URL1 [URL...]>
+ Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
+ Note: retrieving sources from svn, cvs, git and the likes is not supported
+ by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
+ "scripts/build/libc/eglibc.sh"
+
+ > defines the function "do_kernel_extract":
+ + parameters: none
+ + environment:
+ - all variables from the ".config" file,
+ + return value: 0 for success, !0 for failure.
+ + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
+ required patches. To this end, a function is available, that abstracts
+ extracting tarballs:
+ - CT_ExtractAndPatch <tarball_base_name>
+ Eg.: CT_ExtractAndPatch linux-2.6.26.5
+
+ > defines the function "do_kernel_headers":
+ + parameters: none
+ + environment:
+ - all variables from the ".config" file,
+ + return value: 0 for success, !0 for failure.
+ + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
+
+ > defines any kernel-specific helper functions
+ These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
+ where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
+ any name-clashing.
+
+You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
+as an example of what a complex kernel description looks like.
+
+
+Adding a new version of a component |
+------------------------------------+
+
+When a new component, such as the Linux kernel, gcc or any other is released,
+adding the new version to crosstool-NG is quite easy. There is a script that
+will do all that for you:
+ scripts/addToolVersion.sh
+
+Run it with no option to get some help.
+
+
+Build scripts |
+--------------+
+
+To Be Written later...
diff --git a/docs/CREDITS b/docs/A - Credits.txt
index df19097..133478a 100644
--- a/docs/CREDITS
+++ b/docs/A - Credits.txt
@@ -1,3 +1,12 @@
+File.........: A - Credits.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Credits /
+________/
+
+
I would like to thank these fine people for making crosstool-NG possible:
Dan KEGEL, the original author of crosstool: http://www.kegel.com/
diff --git a/docs/known-issues.txt b/docs/B - Known issues.txt
index b787479..e09d3f5 100644
--- a/docs/known-issues.txt
+++ b/docs/B - Known issues.txt
@@ -1,3 +1,12 @@
+File.........: B - Known issues.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Known issues /
+_____________/
+
+
This files lists the known issues encountered while developping crosstool-NG,
but that could not be addressed before the release.
diff --git a/docs/README.macos.txt b/docs/C - Misc. tutorials.txt
index a933284..817ba2b 100644
--- a/docs/README.macos.txt
+++ b/docs/C - Misc. tutorials.txt
@@ -1,4 +1,47 @@
-22 May 2010 - Titus
+File.........: C - Misc. tutorials.txt
+Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
+License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
+
+
+Misc. tutorials /
+________________/
+
+
+Using crosstool-NG on FreeBSD (and other *BSD) |
+-----------------------------------------------+
+
+Contributed by: Titus von Boxberg
+
+Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.
+
+0) Tested on FreeBSD 8.0
+
+1) Install (at least) the following ports
+ archivers/lzma
+ textproc/gsed
+ devel/gmake
+ devel/patch
+ shells/bash
+ devel/bison
+ lang/gawk
+ devel/automake110
+ ftp/wget
+
+ Of course, you should have /usr/local/bin in your PATH.
+
+2) run ct-ng's configure with the following tool configuration:
+ ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
+ --with-patch=/usr/local/bin/gpatch
+ [...other configure parameters as you like...]
+
+3) proceed as described in general documentation
+ but use gmake instead of make
+
+
+Using crosstool-NG on MacOS-X |
+------------------------------+
+
+Contributed by: Titus von Boxberg
Prerequisites and instructions for using crosstool-NG for building a cross
toolchain on MacOS as host.
diff --git a/docs/README.freebsd.txt b/docs/README.freebsd.txt
deleted file mode 100644
index 6968876..0000000
--- a/docs/README.freebsd.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-22 May 2010 - Titus von Boxberg
-
-Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.
-
-0) Tested on FreeBSD 8.0
-
-1) Install (at least) the following ports
- archivers/lzma
- textproc/gsed
- devel/gmake
- devel/patch
- shells/bash
- devel/bison
- lang/gawk
- devel/automake110
- ftp/wget
-
- Of course, you should have /usr/local/bin in your PATH.
-
-2) run ct-ng's configure with the following tool configuration:
- ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
- --with-patch=/usr/local/bin/gpatch
- [...other configure parameters as you like...]
-
-3) proceed as described in general documentation
- but use gmake instead of make
diff --git a/docs/overview.txt b/docs/overview.txt
deleted file mode 100644
index 14ce337..0000000
--- a/docs/overview.txt
+++ /dev/null
@@ -1,1172 +0,0 @@
-File.........: overview.txt
-Content......: Overview of how crosstool-NG works.
-Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
-License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
-
-____________________
- /
-Table Of Content /
-_________________/
-
-
-Introduction
-History
-Referring to crosstool-NG
-Installing crosstool-NG
- Install method
- The hacker's way
- Preparing for packaging
- Shell completion
- Contributed code
-Configuring crosstool-NG
- Interesting config options
- Re-building an existing toolchain
- Using as a backend for a build-system
-Running crosstool-NG
- Stopping and restarting a build
- Testing all toolchains at once
- Overriding the number of // jobs
- Note on // jobs
- Tools wrapper
-Using the toolchain
- The 'populate' script
-Toolchain types
- Seemingly-native toolchains
-Contributing
- Sending a bug report
- Sending patches
-Internals
- Makefile front-end
- Kconfig parser
- Architecture-specific
- Adding a new version of a component
- Build scripts
-
-
-________________
- /
-Introduction /
-_____________/
-
-crosstool-NG aims at building toolchains. Toolchains are an essential component
-in a software development project. It will compile, assemble and link the code
-that is being developed. Some pieces of the toolchain will eventually end up
-in the resulting binary/ies: static libraries are but an example.
-
-So, a toolchain is a very sensitive piece of software, as any bug in one of the
-components, or a poorly configured component, can lead to execution problems,
-ranging from poor performance, to applications ending unexpectedly, to
-mis-behaving software (which more than often is hard to detect), to hardware
-damage, or even to human risks (which is more than regrettable).
-
-Toolchains are made of different piece of software, each being quite complex
-and requiring specially crafted options to build and work seamlessly. This
-is usually not that easy, even in the not-so-trivial case of native toolchains.
-The work reaches a higher degree of complexity when it comes to cross-
-compilation, where it can become quite a nightmare...
-
-Some cross-toolchains exist on the internet, and can be used for general
-development, but they have a number of limitations:
- - they can be general purpose, in that they are configured for the majority:
- no optimisation for your specific target,
- - they can be prepared for a specific target and thus are not easy to use,
- nor optimised for, or even supporting your target,
- - they often are using aging components (compiler, C library, etc...) not
- supporting special features of your shiny new processor;
-On the other side, these toolchain offer some advantages:
- - they are ready to use and quite easy to install and setup,
- - they are proven if used by a wide community.
-
-But once you want to get all the juice out of your specific hardware, you will
-want to build your own toolchain. This is where crosstool-NG comes into play.
-
-There are also a number of tools that build toolchains for specific needs,
-which are not really scalable. Examples are:
- - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
- systems, hence the name. But once you have your toolchain with buildroot,
- part of it is installed in the root-to-be, so if you want to build a whole
- new root, you either have to save the existing one as a template and
- restore it later, or restart again from scratch. This is not convenient,
- - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
- similar to buildroot,
- - other projects (openembedded.org for example), which are again used to
- build root file systems.
-
-crosstool-NG is really targeted at building toolchains, and only toolchains.
-It is then up to you to use it the way you want.
-
-
-___________
- /
-History /
-________/
-
-crosstool was first 'conceived' by Dan Kegel, who offered it to the community
-as a set of scripts, a repository of patches, and some pre-configured, general
-purpose setup files to be used to configure crosstool. This is available at
-http://www.kegel.com/crosstool, and the subversion repository is hosted on
-google at http://code.google.com/p/crosstool/.
-
-I once managed to add support for uClibc-based toolchains, but it did not make
-into mainline, mostly because I didn't have time to port the patch forward to
-the new versions, due in part to the big effort it was taking.
-
-So I decided to clean up crosstool in the state it was, re-order the things
-in place, add appropriate support for what I needed, that is uClibc support
-and a menu-driven configuration, named the new implementation crosstool-NG,
-(standing for crosstool Next Generation, as many other comunity projects do,
-and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
-made it available to the community, in case it was of interest to any one.
-
-
-_____________________________
- /
-Referring to crosstool-NG /
-__________________________/
-
-
-The long name of the project is crosstool-NG:
- * no leading uppercase (except as first word in a sentence)
- * crosstool and NG separated with a hyphen (dash)
- * NG in uppercase
-
-Crosstool-NG can also be referred to by its short name CT-NG:
- * all in uppercase
- * CT and NG separated with a hyphen (dash)
-
-The long name is preferred over the short name, except in mail subjects, where
-the short name is a better fit.
-
-When referring to a specific version of crosstool-NG, append the version number
-either as:
- * crosstool-NG X.Y.Z
- - the long name, a space, and the version string
- * crosstool-ng-X.Y.Z
- - the long name in lowercase, a hyphen (dash), and the version string
- - this is used to name the release tarballs
- * crosstool-ng-X.Y.Z+hg_id
- - the long name in lowercase, a hyphen, the version string, and the Hg id
- (as returned by: ct-ng version)
- - this is used to differentiate between releases and snapshots
-
-The frontend to crosstool-NG is the command ct-ng:
- * all in lowercase
- * ct and ng separated by a hyphen (dash)
-
-
-___________________________
- /
-Installing crosstool-NG /
-________________________/
-
-There are two ways you can use crosstool-NG:
- - build and install it, then get rid of the sources like you'd do for most
- programs,
- - or only build it and run from the source directory.
-
-The former should be used if you got crosstool-NG from a packaged tarball, see
-"Install method", below, while the latter is most useful for developpers that
-use a clone of the repository, and want to submit patches, see "The Hacker's
-way", below.
-
-Install method |
----------------+
-
-If you go for the install, then you just follow the classical, but yet easy
-./configure way:
- ./configure --prefix=/some/place
- make
- make install
- export PATH="${PATH}:/some/place/bin"
-
-You can then get rid of crosstool-NG source. Next create a directory to serve
-as a working place, cd in there and run:
- ct-ng help
-
-See below for complete usage.
-
-The Hacker's way |
------------------+
-
-If you go the hacker's way, then the usage is a bit different, although very
-simple:
- ./configure --local
- make
-
-Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
-Stay in the directory holding the sources, and run:
- ./ct-ng help
-
-See below for complete usage.
-
-Now, provided you used a clone of the repository, you can send me your changes.
-See the section titled CONTRIBUTING, below, for how to submit changees.
-
-Preparing for packaging |
-------------------------+
-
-If you plan on packaging crosstool-NG, you surely don't want to install it
-in your root file system. The install procedure of crosstool-NG honors the
-DESTDIR variable:
-
- ./configure --prefix=/usr
- make
- make DESTDIR=/packaging/place install
-
-Shell completion |
------------------+
-
-crosstool-NG comes with a shell script fragment that defines bash-compatible
-completion. That shell fragment is currently not installed automatically, but
-this is planned.
-
-To install the shell script fragment, you have two options:
- - install system-wide, most probably by copying ct-ng.comp into
- /etc/bash_completion.d/
- - install for a single user, by copying ct-ng.comp into ${HOME}/ and
- sourcing this file from your ${HOME}/.bashrc
-
-Contributed code |
------------------+
-
-Some people contibuted code that couldn't get merged for various reasons. This
-code is available as lzma-compressed patches, in the contrib/ sub-directory.
-These patches are to be applied to the source of crosstool-NG, prior to
-installing, using something like the following:
- lzcat contrib/foobar.patch.lzma |patch -p1
-
-There is no guarantee that a particuliar contribution applies to the current
-version of crosstool-ng, or that it will work at all. Use contributions at
-your own risk.
-
-
-____________________________
- /
-Configuring crosstool-NG /
-_________________________/
-
-crosstool-NG is configured with a configurator presenting a menu-stuctured set
-of options. These options let you specify the way you want your toolchain
-built, where you want it installed, what architecture and specific processor it
-will support, the version of the components you want to use, etc... The
-value for those options are then stored in a configuration file.
-
-The configurator works the same way you configure your Linux kernel. It is
-assumed you now how to handle this.
-
-To enter the menu, type:
- ct-ng menuconfig
-
-Almost every config item has a help entry. Read them carefully.
-
-String and number options can refer to environment variables. In such a case,
-you must use the shell syntax: ${VAR}. You shall neither single- nor double-
-quote the string/number options.
-
-There are three environment variables that are computed by crosstool-NG, and
-that you can use:
-
-CT_TARGET:
- It represents the target tuple you are building for. You can use it for
- example in the installation/prefix directory, such as:
- /opt/x-tools/${CT_TARGET}
-
-CT_TOP_DIR:
- The top directory where crosstool-NG is running. You shouldn't need it in
- most cases. There is one case where you may need it: if you have local
- patches and you store them in your running directory, you can refer to them
- by using CT_TOP_DIR, such as:
- ${CT_TOP_DIR}/patches.myproject
-
-CT_VERSION:
- The version of crosstool-NG you are using. Not much use for you, but it's
- there if you need it.
-
-Interesting config options |
----------------------------+
-
-CT_LOCAL_TARBALLS_DIR:
- If you already have some tarballs in a direcotry, enter it here. That will
- speed up the retrieving phase, where crosstool-NG would otherwise download
- those tarballs.
-
-CT_PREFIX_DIR:
- This is where the toolchain will be installed in (and for now, where it
- will run from). Common use is to add the target tuple in the directory
- path, such as (see above):
- /opt/x-tools/${CT_TARGET}
-
-CT_TARGET_VENDOR:
- An identifier for your toolchain, will take place in the vendor part of the
- target tuple. It shall *not* contain spaces or dashes. Usually, keep it
- to a one-word string, or use underscores to separate words if you need.
- Avoid dots, commas, and special characters.
-
-CT_TARGET_ALIAS:
- An alias for the toolchian. It will be used as a prefix to the toolchain
- tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
-
-Also, if you think you don't see enough versions, you can try to enable one of
-those:
-
-CT_OBSOLETE:
- Show obsolete versions or tools. Most of the time, you don't want to base
- your toolchain on too old a version (of gcc, for example). But at times, it
- can come handy to use such an old version for regression tests. Those old
- versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
- marked because maintaining support for those in crosstool-NG would be too
- costly, time-wise, and time is dear.
-
-CT_EXPERIMENTAL:
- Show experimental versions or tools. Again, you might not want to base your
- toolchain on too recent tools (eg. gcc) for production. But if you need a
- feature present only in a recent version, or a new tool, you can find them
- hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
- receive thorough testing in crosstool-NG, and/or are not mature enough to
- be blindly trusted.
-
-Re-building an existing toolchain |
-----------------------------------+
-
-If you have an existing toolchain, you can re-use the options used to build it
-to create a new toolchain. That needs a very little bit of effort on your side
-but is quite easy. The options to build a toolchain are saved with the
-toolchain, and you can retrieve this configuration by running:
- ${CT_TARGET}-ct-ng.config
-
-An alternate method is to extract the configuration from a build.log file.
-This will be necessary if your toolchain was build with crosstool-NG prior
-to 1.4.0, but can be used with build.log files from any version:
- ct-ng extractconfig <build.log >.config
-
-Or, if your build.log file is compressed (most probably!):
- bzcat build.log.bz2 |ct-ng extractconfig >.config
-
-The above commands will dump the configuration to stdout, so to rebuild a
-toolchain with this configuration, just redirect the output to the
-.config file:
- ${CT_TARGET}-ct-ng.config >.config
- ct-ng oldconfig
-
-Then, you can review and change the configuration by running:
- ct-ng menuconfig
-
-Using as a backend for a build-system |
---------------------------------------+
-
-Crosstool-NG can be used as a backend for an automated build-system. In this
-case, some components that are expected to run on the target (eg. the native
-gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
-build either, as it is considered the responsibility of the build-system to
-build its own versions of those tools.
-
-If you want to use crosstool-NG as a backend to generate your toolchains for
-your build-system, you have to set and export this environment variable:
- CT_IS_A_BACKEND=y
-
-(case is not sensitive, you can say Y).
-
-
-________________________
- /
-Running crosstool-NG /
-_____________________/
-
-To build the toolchain, simply type:
- ct-ng build
-
-This will use the above configuration to retrieve, extract and patch the
-components, build, install and eventually test your newly built toolchain.
-
-You are then free to add the toolchain /bin directory in your PATH to use
-it at will.
-
-In any case, you can get some terse help. Just type:
- ct-ng help
-or:
- man 1 ct-ng
-
-Stopping and restarting a build |
---------------------------------+
-
-If you want to stop the build after a step you are debugging, you can pass the
-variable STOP to make:
- ct-ng build STOP=some_step
-
-Conversely, if you want to restart a build at a specific step you are
-debugging, you can pass the RESTART variable to make:
- ct-ng build RESTART=some_step
-
-Alternatively, you can call make with the name of a step to just do that step:
- ct-ng libc_headers
-is equivalent to:
- ct-ng build RESTART=libc_headers STOP=libc_headers
-
-The shortcuts +step_name and step_name+ allow to respectively stop or restart
-at that step. Thus:
- ct-ng +libc_headers and: ct-ng libc_headers+
-are equivalent to:
- ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
-
-To obtain the list of acceptable steps, please call:
- ct-ng list-steps
-
-Note that in order to restart a build, you'll have to say 'Y' to the config
-option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
-that far.
-
-Building all toolchains at once |
---------------------------------+
-
-You can build all samples; simply call:
- ct-ng build-all
-
-Overriding the number of // jobs |
----------------------------------+
-
-If you want to override the number of jobs to run in // (the -j option to
-make), you can either re-enter the menuconfig, or simply add it on the command
-line, as such:
- ct-ng build.4
-
-which tells crosstool-NG to override the number of // jobs to 4.
-
-You can see the actions that support overriding the number of // jobs in
-the help menu. Those are the ones with [.#] after them (eg. build[.#] or
-build-all[.#], and so on...).
-
-Note on // jobs |
-----------------+
-
-The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
-in parallel (there is not much to gain). When speaking of // jobs, we are
-refering to the number of // jobs when making the *components*. That is, we
-speak of the number of // jobs used to build gcc, glibc, and so on...
-
-Tools wrapper |
---------------+
-
-Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
-come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
-dependency on libelf. These are libraries that enable advanced features to
-gcc. Additionally, some of those libraries can be used by binutils and gdb.
-Unfortunately, not all systems on which crosstool-NG runs have all of those
-libraries. And for those that do, the versions of those libraries may be
-older than the version required by gcc (and binutils and gdb). To date,
-Debian stable (aka Lenny) is lagging behind on some, and is missing the
-others.
-
-This is why crosstool-NG builds its own set of libraries as part of the
-toolchain.
-
-The companion libraries can be built either as static libraries, or as shared
-libraries. The default is to build static libraries, and is the safe way.
-If you decide to use static companion libraries, then you can stop reading
-this section.
-
-But if you prefer to have shared libraries, then read on...
-
-Building shared companion libraries poses no problem at build time, as
-crosstool-NG correctly points gcc (and binutils and gdb) to the correct
-place where our own version of the libraries are installed. But it poses
-a problem when gcc et al. are run: the place where the libraries are is most
-probably not known to the host dynamic linker. Still worse, if the host system
-has its own versions, then ld.so would load the wrong libraries!
-
-So we have to force the dynamic linker to load the correct version. We do this
-by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
-to look for shared libraries prior to searching its standard places. But we
-can't impose that burden on all the system (because it'd be a nightmare to
-configure, and because two toolchains on the same system may use different
-versions of the libraries); so we have to do it on a per-toolchain basis.
-
-So we rename all binaries of the toolchain (by adding a dot '.' as their first
-character), and add a small program, the so-called "tools wrapper", that
-correctly sets LD_LIBRARY_PATH prior to running the real tool.
-
-First, the wrapper was written as a POSIX-compliant shell script. That shell
-script is very simple, if not trivial, and works great. The only drawback is
-that it does not work on host systems that lack a shell, for example the
-MingW32 environment. To solve the issue, the wrapper has been re-written in C,
-and compiled at build time. This C wrapper is much more complex than the shell
-script, and although it sems to be working, it's been only lightly tested.
-Some of the expected short-comings with this C wrapper are;
- - multi-byte file names may not be handled correctly
- - it's really big for what it does
-
-So, the default wrapper installed with your toolchain is the shell script.
-If you know that your system is missing a shell, then you shall use the C
-wrapper (and report back whether it works, or does not work, for you).
-
-A final word on the subject: do not build shared libraries. Build them
-static, and you'll be safe.
-
-
-_______________________
- /
-Using the toolchain /
-____________________/
-
-Using the toolchain is as simple as adding the toolchain's bin directory in
-your PATH, such as:
- export PATH="${PATH}:/your/toolchain/path/bin"
-
-and then using the target tuple to tell the build systems to use your
-toolchain:
- ./configure --target=your-target-tuple
-or
- make CC=your-target-tuple-gcc
-or
- make CROSS_COMPILE=your-target-tuple-
-and so on...
-
-It is strongly advised not to use the toolchain sys-root directory as an
-install directory for your programs/packages. If you do so, you will not be
-able to use your toolchain for another project. It is even strongly advised
-that your toolchain is chmod-ed to read-only once successfully build, so that
-you don't go polluting your toolchain with your programs/packages' files.
-
-Thus, when you build a program/package, install it in a separate directory,
-eg. /your/root. This directory is the /image/ of what would be in the root file
-system of your target, and will contain all that your programs/packages have
-installed.
-
-The 'populate' script |
-----------------------+
-
-When your root directory is ready, it is still missing some important bits: the
-toolchain's libraries. To populate your root directory with those libs, just
-run:
- your-target-tuple-populate -s /your/root -d /your/root-populated
-
-This will copy /your/root into /your/root-populated, and put the needed and only
-the needed libraries there. Thus you don't polute /your/root with any cruft that
-would no longer be needed should you have to remove stuff. /your/root always
-contains only those things you install in it.
-
-You can then use /your/root-populated to build up your file system image, a
-tarball, or to NFS-mount it from your target, or whatever you need.
-
-The populate script accepts the following options:
-
- -s src_dir
- Use 'src_dir' as the un-populated root directory.
-
- -d dst_dir
- Put the populated root directory in 'dst_dir'.
-
- -l lib1 [...]
- Always add specified libraries.
-
- -L file
- Always add libraries listed in 'file'.
-
- -f
- Remove 'dst_dir' if it previously existed; continue even if any library
- specified with -l or -L is missing.
-
- -v
- Be verbose, and tell what's going on (you can see exactly where libs are
- coming from).
-
- -h
- Print the help.
-
-See 'your-target-tuple-populate -h' for more information on the options.
-
-Here is how populate works:
-
- 1) performs some sanity checks:
- - src_dir and dst_dir are specified
- - src_dir exists
- - unless forced, dst_dir does not exist
- - src_dir != dst_dir
-
- 2) copy src_dir to dst_dir
-
- 3) add forced libraries to dst_dir
- - build the list from -l and -L options
- - get forced libraries from the sysroot (see below for heuristics)
- - abort on the first missing library, unless -f is specified
-
- 4) add all missing libraries to dst_dir
- - scan dst_dir for every ELF files that are 'executable' or
- 'shared object'
- - list the "NEEDED Shared library" fields
- - check if the library is already in dst_dir/lib or dst_dir/usr/lib
- - if not, get the library from the sysroot
- - if it's in sysroot/lib, copy it to dst_dir/lib
- - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
- - in both cases, use the SONAME of the library to create the file
- in dst_dir
- - if it was not found in the sysroot, this is an error.
-
-
-___________________
- /
-Toolchain types /
-________________/
-
-There are four kinds of toolchains you could encounter.
-
-First off, you must understand the following: when it comes to compilers there
-are up to four machines involved:
- 1) the machine configuring the toolchain components: the config machine
- 2) the machine building the toolchain components: the build machine
- 3) the machine running the toolchain: the host machine
- 4) the machine the toolchain is generating code for: the target machine
-
-We can most of the time assume that the config machine and the build machine
-are the same. Most of the time, this will be true. The only time it isn't
-is if you're using distributed compilation (such as distcc). Let's forget
-this for the sake of simplicity.
-
-So we're left with three machines:
- - build
- - host
- - target
-
-Any toolchain will involve those three machines. You can be as pretty sure of
-this as "2 and 2 are 4". Here is how they come into play:
-
-1) build == host == target
- This is a plain native toolchain, targetting the exact same machine as the
- one it is built on, and running again on this exact same machine. You have
- to build such a toolchain when you want to use an updated component, such
- as a newer gcc for example.
- crosstool-NG calls it "native".
-
-2) build == host != target
- This is a classic cross-toolchain, which is expected to be run on the same
- machine it is compiled on, and generate code to run on a second machine,
- the target.
- crosstool-NG calls it "cross".
-
-3) build != host == target
- Such a toolchain is also a native toolchain, as it targets the same machine
- as it runs on. But it is build on another machine. You want such a
- toolchain when porting to a new architecture, or if the build machine is
- much faster than the host machine.
- crosstool-NG calls it "cross-native".
-
-4) build != host != target
- This one is called a canadian-toolchain (*), and is tricky. The three
- machines in play are different. You might want such a toolchain if you
- have a fast build machine, but the users will use it on another machine,
- and will produce code to run on a third machine.
- crosstool-NG calls it "canadian".
-
-crosstool-NG can build all these kinds of toolchains (or is aiming at it,
-anyway!)
-
-(*) The term Canadian Cross came about because at the time that these issues
- were all being hashed out, Canada had three national political parties.
- http://en.wikipedia.org/wiki/Cross_compiler
-
-
-________________
- /
-Contributing /
-_____________/
-
-Sending a bug report |
----------------------+
-
-If you need to send a bug report, please send a mail with subject
-prefixed with "[CT_NG]" with to following destinations:
- TO: yann.morin.1998 (at) anciens.enib.fr
- CC: crossgcc (at) sourceware.org
-
-Sending patches |
-----------------+
-
-If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
-
-Patches should come with the appropriate SoB line. A SoB line is typically
-something like:
- Signed-off-by: John DOE <john.doe@somewhere.net>
-
-The SoB line is clearly described in Documentation/SubmittingPatches , section
-12, of your favourite Linux kernel source tree.
-
-
-How to Use Mercurial |
----------------------+
-
-For larger or more frequent contributions, mercurial should be used.
-
-PREREQUISITES:
-
-Configuring Mercurial:
- You need mercurial with the following extensions:
- - mq : http://mercurial.selenic.com/wiki/MqExtension
- - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
- Usually, these two extensions are already part of the installation package.
- The mq extension maintains a separate queue of your local changes
- that you can change at any later time.
- With the patchbomb extension you can email those patches directly
- from your local repo.
-
- Your configuration file for mercurial, e.g. ~/.hgrc should contain
- at least the following sections (but have a look at `man hgrc`):
- # ---
- [email]
- # configure sending patches directly via Mercurial
- from = "Your Name" <your@email.address>
- # How to send email:
- method = smtp
-
- [smtp]
- # SMTP configuration (only for method=smtp)
- host = localhost
- tls = true
- username =
- password =
-
- [extensions]
- # The following lines enable the two extensions:
- hgext.mq =
- hgext.patchbomb =
- # ----
-
-Create your local repository as a clone:
- hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
-
-Setting up the mq extension in your local copy:
- cd crosstool-ng
- hg qinit
-
-
-CREATING PATCHES:
-
-Recording your changes in the patch queue maintained by mq:
- # First, create a new patch entry in the patch queue:
- hg qnew -D -U -e short_patch_name1
- <edit patch description as commit message (see below for an example)>
-
- <now edit the ct-ng sources and check them>
-
- # if you execute `hg status` here, your modifications of the working
- # copy should show up.
-
- # Now the following command takes your modifications from the working copy
- # into the patch entry
- hg qrefresh -D [-e]
- <reedit patch description [-e] if desired>
-
- # Now your changes are recorded, and `hg status` should show a clean
- # working copy
-
-Repeat the above steps for all your modifications.
-The command `hg qseries` informs you about the content of your patch queue.
-
-
-CONTRIBUTING YOUR PATCHES:
-
-Once you are satisfied with your patch series, you can (you should!)
-contribute them back to upstream.
-This is easily done using the `hg email` command.
-
-`hg email` sends your new changesets to a specified list of recipients,
-each patch in its own email, all ordered in the way you entered them (oldest
-first). The command line flag --outgoing selects all changesets that are in
-your local but not yet in the upstream repository. Here, these are exactly
-the ones you entered into your local patch queue in the section above, so
---outgoing is what you want.
-
-Each email gets the subject set to: "[PATCH x of n] <series summary>"
-where 'x' is the serial number in the email series, and 'n' is the total number
-of patches in the series. The body of the email is the complete patch, plus
-a handful of metadata, that helps properly apply the patch, keeping the log
-message, attribution and date, tracking file changes (move, delete, modes...)
-
-`hg email` also threads all outgoing patch emails below an introductory
-message. You should use the introductory message (command line flag --intro)
-to describe the scope and motivation for the whole patch series. The subject
-for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
-and you get the chance to set the <series summary>.
-
-Here is a sample `hg email` complete command line:
-Note: replace " (at) " with "@"
-
- hg email --outgoing --intro \
- --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
- --cc 'crossgcc (at) sourceware.org'
-
- # It then opens an editor and lets you enter the subject
- # and the body for the introductory message.
-
-Use `hg email` with the additional command line switch -n to
-first have a look at the email(s) without actually sending them.
-
-
-MAINTAINING YOUR PATCHES:
-
-When the patches are refined by discussing them on the mailing list,
-you may want to finalize and resend them.
-
-The mq extension has the idiosyncrasy of imposing a stack onto the queue:
-You can always reedit/refresh only the patch on top of stack.
-The queue consists of applied and unapplied patches
-(if you reached here via the above steps, all of your patches are applied),
-where the 'stack' consists of the applied patches, and 'top of stack'
-is the latest applied patch.
-
-The following output of `hg qseries` is now used as an example:
- 0 A short_patch_name1
- 1 A short_patch_name2
- 2 A short_patch_name3
- 3 A short_patch_name4
-
-You are now able to edit patch 'short_patch_name4' (which is top of stack):
- <Edit the sources>
- # and execute again
- hg qrefresh -D [-e]
- <and optionally [-e] reedit the commit message>
-
-If you want to edit e.g. patch short_patch_name2, you have to modify
-mq's stack so this patch gets top of stack.
-For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
-
- hg qgoto short_patch_name2
- # The patch queue should now look like
- hg qseries
- 0 A short_patch_name1
- 1 A short_patch_name2
- 2 U short_patch_name3
- 3 U short_patch_name4
- # so patch # 1 (short_patch_name2) is top of stack.
- <now reedit the sources for short_patch_name2>
- # and execute again
- hg qrefresh -D [-e]
- <and optionally [-e] reedit the commit message>
- # the following command reapplies the now unapplied two patches:
- hg qpush -a
- # you can also use `hg qgoto short_patch_name4` to get there again.
-
-
-RESENDING YOUR REEDITED PATCHES:
-
-By mailing list policy, please resend your complete patch series.
---> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
-
-
-SYNCING WITH UPSTREAM AGAIN:
-
-You can sync your repo with upstream at any time by executing
- # first unapply all your patches:
- hg qpop -a
- # next fetch new changesets from upstream
- hg pull
- # then update your working copy
- hg up
- # optionally remove already upstream integrated patches (see below)
- hg qdelete <short_name_of_already_applied_patch>
- # and reapply your patches if any non upstream-integrated left (but see below)
- hg qpush -a
-
-Eventually, your patches get included into the upstream repository
-which you initially cloned.
-In this case, before executing the hg qpush -a from above
-you should manually "hg qdelete" the patches that are already integrated upstream.
-
-
-HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
-
-Commit messages should look like (without leading pipes):
- |component: short, one-line description
- |
- |optional longer description
- |on multiple lines if needed
-
-Here is an example commit message (see revision a53a5e1d61db):
- |comp-libs/cloog: fix building
- |
- |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
- |For any later versions, the directory name does have the version, such as
- |cloog-ppl-0.15.4.
-
-_____________
- /
-Internals /
-__________/
-
-Internally, crosstool-NG is script-based. To ease usage, the frontend is
-Makefile-based.
-
-Makefile front-end |
--------------------+
-
-The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
-script with an action will act exactly as if the Makefile was in the current
-working directory and make was called with the action as rule. Thus:
- ct-ng menuconfig
-
-is equivalent to having the Makefile in CWD, and calling:
- make menuconfig
-
-Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
-traditional command.
-
-ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
-at configuration time with ./configure.
-
-ct-ng also searches for config files, sub-tools, samples, scripts and patches in
-that library directory.
-
-Because of a stupid make behavior/bug I was unable to track down, implicit make
-rules are disabled: installing with --local would triger those rules, and mconf
-was unbuildable.
-
-Kconfig parser |
----------------+
-
-The kconfig language is a hacked version, vampirised from the Linux kernel
-(http://www.kernel.org/), and (heavily) adapted to my needs.
-
-The list of the most notable changes (at least the ones I remember) follows:
-- the CONFIG_ prefix has been replaced with CT_
-- a leading | in prompts is skipped, and subsequent leading spaces are not
- trimmed; otherwise leading spaces are silently trimmed
-- removed the warning about undefined environment variable
-
-The kconfig parsers (conf and mconf) are not installed pre-built, but as
-source files. Thus you can have the directory where crosstool-NG is installed,
-exported (via NFS or whatever) and have clients with different architectures
-use the same crosstool-NG installation, and most notably, the same set of
-patches.
-
-Architecture-specific |
-----------------------+
-
-Note: this chapter is not really well written, and might thus be a little bit
-complex to understand. To get a better grasp of what an architecture is, the
-reader is kindly encouraged to look at the "arch/" sub-directory, and to the
-existing architectures to see how things are laid out.
-
-An architecture is defined by:
-
- - a human-readable name, in lower case letters, with numbers as appropriate.
- The underscore is allowed; space and special characters are not.
- Eg.: arm, x86_64
- - a file in "config/arch/", named after the architecture's name, and suffixed
- with ".in".
- Eg.: config/arch/arm.in
- - a file in "scripts/build/arch/", named after the architecture's name, and
- suffixed with ".sh".
- Eg.: scripts/build/arch/arm.sh
-
-The architecture's ".in" file API:
- > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
- actual architecture name).
- That config option must have *neither* a type, *nor* a prompt! Also, it can
- *not* depend on any other config option (EXPERIMENTAL is managed as above).
- Eg.:
- config ARCH_arm
- + mandatory:
- defines a (terse) help entry for this architecture:
- Eg.:
- config ARCH_arm
- help
- The ARM architecture.
- + optional:
- selects adequate associated config options.
- Note: 64-bit architectures *shall* select ARCH_64
- Eg.:
- config ARCH_arm
- select ARCH_SUPPORTS_BOTH_ENDIAN
- select ARCH_DEFAULT_LE
- help
- The ARM architecture.
- Eg.:
- config ARCH_x86_64
- select ARCH_64
- help
- The x86_64 architecture.
-
- > other target-specific options, at your discretion. Note however that to
- avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
- where %arch% is again replaced by the actual architecture name.
- (Note: due to historical reasons, and lack of time to clean up the code,
- I may have left some config options that do not completely conform to
- this, as the architecture name was written all upper case. However, the
- prefix is unique among architectures, and does not cause harm).
-
-The architecture's ".sh" file API:
- > the function "CT_DoArchTupleValues"
- + parameters: none
- + environment:
- - all variables from the ".config" file,
- - the two variables "target_endian_eb" and "target_endian_el" which are
- the endianness suffixes
- + return value: 0 upon success, !0 upon failure
- + provides:
- - mandatory
- - the environment variable CT_TARGET_ARCH
- - contains:
- the architecture part of the target tuple.
- Eg.: "armeb" for big endian ARM
- "i386" for an i386
- + provides:
- - optional
- - the environment variable CT_TARGET_SYS
- - contains:
- the sytem part of the target tuple.
- Eg.: "gnu" for glibc on most architectures
- "gnueabi" for glibc on an ARM EABI
- - defaults to:
- - for glibc-based toolchain: "gnu"
- - for uClibc-based toolchain: "uclibc"
- + provides:
- - optional
- - the environment variables to configure the cross-gcc (defaults)
- - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
- - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
- - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
- - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
- - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
- - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
- + provides:
- - optional
- - the environment variables to pass to the cross-gcc to build target binaries (defaults)
- - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
- - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
- - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
- - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
- - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
- - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
- - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
- - default to:
- see above.
- + provides:
- - optional
- - the environement variables to configure the core and final compiler, specific to this architecture:
- - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
- - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
- - default to:
- - all empty
- + provides:
- - optional
- - the architecture-specific CFLAGS and LDFLAGS:
- - CT_ARCH_TARGET_CLFAGS
- - CT_ARCH_TARGET_LDFLAGS
- - default to:
- - all empty
-
-You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
-a quite complete example of what an actual architecture description looks like.
-
-Kernel specific |
-----------------+
-
-A kernel is defined by:
-
- - a human-readable name, in lower case letters, with numbers as appropriate.
- The underscore is allowed; space and special characters are not (although
- they are internally replaced with underscores.
- Eg.: linux, bare-metal
- - a file in "config/kernel/", named after the kernel name, and suffixed with
- ".in".
- Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
- - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
- with ".sh".
- Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
-
-The kernel's ".in" file must contain:
- > an optional lines containing exactly "# EXPERIMENTAL", starting on the
- first column, and without any following space or other character.
- If this line is present, then this kernel is considered EXPERIMENTAL,
- and correct dependency on EXPERIMENTAL will be set.
-
- > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
- replaced with the actual kernel name, with all special characters and
- spaces replaced by underscores).
- That config option must have *neither* a type, *nor* a prompt! Also, it can
- *not* depends on EXPERIMENTAL.
- Eg.: KERNEL_linux, KERNEL_bare_metal
- + mandatory:
- defines a (terse) help entry for this kernel.
- Eg.:
- config KERNEL_bare_metal
- help
- Build a compiler for use without any kernel.
- + optional:
- selects adequate associated config options.
- Eg.:
- config KERNEL_bare_metal
- select BARE_METAL
- help
- Build a compiler for use without any kernel.
-
- > other kernel specific options, at your discretion. Note however that, to
- avoid name-clashing, such options should be prefixed with
- "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
- the actual kernel name.
- (Note: due to historical reasons, and lack of time to clean up the code,
- I may have left some config options that do not completely conform to
- this, as the kernel name was written all upper case. However, the prefix
- is unique among kernels, and does not cause harm).
-
-The kernel's ".sh" file API:
- > is a bash script fragment
-
- > defines the function CT_DoKernelTupleValues
- + see the architecture's CT_DoArchTupleValues, except for:
- + set the environment variable CT_TARGET_KERNEL, the kernel part of the
- target tuple
- + return value: ignored
-
- > defines the function "do_kernel_get":
- + parameters: none
- + environment:
- - all variables from the ".config" file.
- + return value: 0 for success, !0 for failure.
- + behavior: download the kernel's sources, and store the tarball into
- "${CT_TARBALLS_DIR}". To this end, a functions is available, that
- abstracts downloading tarballs:
- - CT_DoGet <tarball_base_name> <URL1 [URL...]>
- Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
- Note: retrieving sources from svn, cvs, git and the likes is not supported
- by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
- "scripts/build/libc/eglibc.sh"
-
- > defines the function "do_kernel_extract":
- + parameters: none
- + environment:
- - all variables from the ".config" file,
- + return value: 0 for success, !0 for failure.
- + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
- required patches. To this end, a function is available, that abstracts
- extracting tarballs:
- - CT_ExtractAndPatch <tarball_base_name>
- Eg.: CT_ExtractAndPatch linux-2.6.26.5
-
- > defines the function "do_kernel_headers":
- + parameters: none
- + environment:
- - all variables from the ".config" file,
- + return value: 0 for success, !0 for failure.
- + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
-
- > defines any kernel-specific helper functions
- These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
- where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
- any name-clashing.
-
-You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
-as an example of what a complex kernel description looks like.
-
-Adding a new version of a component |
-------------------------------------+
-
-When a new component, such as the Linux kernel, gcc or any other is released,
-adding the new version to crosstool-NG is quite easy. There is a script that
-will do all that for you:
- scripts/addToolVersion.sh
-
-Run it with no option to get some help.
-
-Build scripts |
---------------+
-
-To Be Written later...