From a211f4100d3e0196807dbd3b4f1839c41f79f5b1 Mon Sep 17 00:00:00 2001 From: "Yann E. MORIN\"" Date: Sat, 14 Aug 2010 16:37:11 +0200 Subject: 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" diff --git a/Makefile.in b/Makefile.in index d0b63ee..81d23b7 100644 --- a/Makefile.in +++ b/Makefile.in @@ -241,8 +241,8 @@ install-lib-samples: $(DESTDIR)$(LIBDIR) install-lib-main done install-doc: $(DESTDIR)$(DOCDIR) - @for doc_file in docs/CREDITS docs/overview.txt; do \ - echo " INST '$${doc_file}'"; \ + @echo " INST 'docs/*.txt'" + @for doc_file in docs/*.txt; do \ $(install) -m 644 "$${doc_file}" "$(DESTDIR)$(DOCDIR)"; \ done diff --git a/ct-ng.in b/ct-ng.in index c006c86..ca3c759 100644 --- a/ct-ng.in +++ b/ct-ng.in @@ -94,11 +94,11 @@ help-distrib:: help-env:: @echo - @echo 'Environement variables (see @@CT_DOCDIR@@/overview.txt):' + @echo 'Environement variables (see @@CT_DOCDIR@@/0 - Table of content.txt):' help-tail:: @echo - @echo 'Use action "menuconfig" to configure crosstool-NG' + @echo 'Use action "menuconfig" to configure your toolchain' @echo 'Use action "build" to build your toolchain' @echo 'Use action "version" to see the version' @echo 'See "man 1 ct-ng" for some help as well' 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 +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 +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 +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 +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 .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 +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 +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 +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 +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 + +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" + # 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 + + + + + # 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] + + + # 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] " +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] " +and you get the chance to set the . + +Here is a sample `hg email` complete command line: +Note: replace " (at) " with "@" + + hg email --outgoing --intro \ + --to '"Yann E. MORIN" ' \ + --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): + + # and execute again + hg qrefresh -D [-e] + + +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. + + # and execute again + hg qrefresh -D [-e] + + # 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 + # 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 +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 + 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 + 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/A - Credits.txt b/docs/A - Credits.txt new file mode 100644 index 0000000..133478a --- /dev/null +++ b/docs/A - Credits.txt @@ -0,0 +1,86 @@ +File.........: A - Credits.txt +Copyrigth....: (C) 2010 Yann E. MORIN +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/ + Dan was very helpfull and willing to help when I build my first toolchains. + I owe him one. Thank you Dan! + Some crosstool-NG scripts have code snippets coming almost as-is from the + original work by Dan. + +And in order of appearance on the crossgcc ML: + + Allan CLARK for his investigations on building toolchains on MacOS-X. + Allan made extensive tests of the first alpha of crosstool-NG on his + MacOS-X, and unveiled some bash-2.05 weirdness. + + Enrico WEIGELT + - some improvements to the build procedure + - cxa_atexit disabling for C libraries not supporting it (old uClibc) + - misc suggestions (restartable build, ...) + - get rid of some bashisms in ./configure + - contributed OpenRISC or32 support + + Robert P. J. DAY: + - some small improvements to the configurator, misc prompting glitches + - 'sanitised' patches for binutils-2.17 + - patches for glibc-2.5 + - misc patches, typos and eye candy + - too many to list any more! + + Al Stone: + - initial ia64 support + - some cosmetics + + Szilveszter Ordog: + - a uClibc floating point fix + - initial support for ARM EABI + + Mark Jonas: + - initiated Super-H port + + Michael Abbott: + - make it build with ancient findutils + + Willy Tarreau: + - a patch to glibc to build on 'ancient' shells + - reported mis-use of $CT_CC_NATIVE + + Matthias Kaehlcke: + - fix building glibc-2.7 (and 2.6.1) with newer kernels + + Daniel Dittmann: + - PowerPC support + + Ioannis E. Venetis: + - preliminary Alpha support + - intense gcc-4.3 brainstorming + + Thomas Jourdan: + - intense gcc-4.3 brainstorming + - eglibc support + + Many others have contributed, either in form of patches, suggestions, + comments, or testing... Thank you to all of you! + +Special dedication to the buildroot people for maintaining a set of patches I +happily and shamelessly vampirise from time to time... :-) + + +20100530: Status of this file + +It's been about a year now that we've moved the repository to Mercurial. +The repository now has proper authorship for each changeset, and this is +used to build the changelog at each release. This file will probably no +longer be updated, and is here to credit people prior to the Mercurial +migration, or for people discussing ideas or otherwise helping without +code. + +If you think you deserve being cited in this file, do yell at me! ;-) diff --git a/docs/B - Known issues.txt b/docs/B - Known issues.txt new file mode 100644 index 0000000..e09d3f5 --- /dev/null +++ b/docs/B - Known issues.txt @@ -0,0 +1,148 @@ +File.........: B - Known issues.txt +Copyrigth....: (C) 2010 Yann E. MORIN +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. + +The file has one section for each known issue, each section containing four +sub-sections: Symptoms, Explanations, Fix, and Workaround. + +Each section is separated from the others with a lines of at least 4 dashes. + +The following dummy section explains it all. + + -------------------------------- + Symptoms: + A one-liner of what you would observe. + + Explanations: + An as much as possible in-depth explanations of the context, why it + happens, what has been investigated so far, and possible orientations + as how to try to solve this (eg. URLs, code snippets...). + + Fix: + What you have to do to fix it, if at all possible. + The fact that there is a fix, and yet this is a known issue means that + time to incorporate the fix in crosstool-NG was missing, or planned for + a future release. + + Workaround: + What you can do to fix it *temporarily*, if at all possible. + A workaround is not a real fix, as it can break other parts of + crosstool-NG, but at least makes you going in your particular case. + +So now, on for the real issues... + +-------------------------------- +Symptoms: + gcc is not found, although I *do* have gcc installed. + +Explanations: + This is an issue on at least RHEL systems, where gcc is a symlink to ccache. + Because crosstool-NG create links to gcc for the build and host environment, + those symlinks are in fact pointing to ccache, which then doesn't know how + to run the compiler. + + A possible fix could probably set the environment variable CCACHE_CC to the + actual compiler used. + +Fix: + None known. + +Workaround: + Uninstall ccache. + +-------------------------------- +Symptoms: + The extract and/or path steps fail under Cygwin. + +Explanations: + This is not related to crosstool-NG. Mounts under Cygwin are by default not + case-sensitive. You have to use so-called "managed" mounts. See: + http://cygwin.com/faq.html section 4, question 32. + +Fix: + Use "managed" mounts for the directories where you build *and* install your + toolchains. + +Workaround: + None. + +-------------------------------- +Symptoms: + uClibc fails to build under Cygwin. + +Explanations: + With uClibc, it is possible to build a cross-ldd. Unfortunately, it is + not (currently) possible to build this cross-ldd under Cygwin. + +Fix: + None so far. + +Workaround: + Disable the cross-ldd build. + +-------------------------------- +Symptoms: + On 64-bit build systems, the glibc (possibly eglibc too) build fails for + 64-bit targets, because it can not find libgcc. + +Explanations: + This issue has been observed when the companion libraries are built + statically. For an unknown reason, in this case, the libgcc built by the + core gcc is not located in the same place it is located when building + with shared companion libraries. + +Fix: + None so far. + +Workaround: + Build shared companion libraries. + +-------------------------------- +Symptoms: + While building the final gcc, I get an error message that ends with: + libtool.m4: error: problem compiling FC test program + +Explanations: + The gcc build procedure tries to run a Fortran test to see if it has a + working native fortran compiler installed on the build machine, and it + can't find one. A native Fortran compiler is needed (seems to be neede) + to build the Fortran frontend of the cross-compiler. + Even if you don't want to build the Fortran frontend, gcc tries to see + if it has one, but fails. This is no problem, as the Fortran frontend + will not be built. There is nothing to be worry about (unless you do + want to build the Fortran frontend, of course). + +Fix: + None so far. It's a spurious error, so there will probably never be + a fix for this issue. + +Workaround: + None needed, it's a spurious error. + +-------------------------------- +Symptoms: + gcc barfs because it is "unable to detect the exception model". + +Explanations: + On some architectures, proper stack unwinding (C++) requires that + setjmp/longjmp (sjlj) be used, while on other architectures do not + need sjlj. On some architectures, gcc is unable to determine whether + sjlj are needed or not. + +Fix: + None so far. + +Workaround: + Trying setting use of sjlj to either 'Y' or 'N' (instead of the + default 'M') in the menuconfig, option CT_CC_GCC_SJLJ_EXCEPTIONS + labelled "Use sjlj for exceptions". + +-------------------------------- diff --git a/docs/C - Misc. tutorials.txt b/docs/C - Misc. tutorials.txt new file mode 100644 index 0000000..817ba2b --- /dev/null +++ b/docs/C - Misc. tutorials.txt @@ -0,0 +1,93 @@ +File.........: C - Misc. tutorials.txt +Copyrigth....: (C) 2010 Yann E. MORIN +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. + +0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or + Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed + via macports + +1) You have to use a case sensitive file system for ct-ng's build and target + directories. Use a disk or disk image with a case sensitive fs that you + mount somewhere. + +2) Install macports (or similar easy means of installing 3rd party software), + make sure that macport's bin dir is in your PATH. + Furtheron assuming it is /opt/local/bin. + +3) Install (at least) the following macports + ncurses + lzmautils + libtool + binutils + gsed + gawk + gcc43 (only necessary for Leopard OSX 10.5) + + On Leopard, make sure that the macport's gcc is called with the default + commands (gcc, g++,...), e.g. via macport gcc_select + +4) run ct-ng's configure with the following tool configuration + (assuming you have installed the tools via macports in /opt/local): + ./configure --with-sed=/opt/local/bin/gsed \ + --with-libtool=/opt/local/bin/glibtool \ + --with-objcopy=/opt/local/bin/gobjcopy \ + --with-objdump=/opt/local/bin/gobjdump \ + --with-readelf=/opt/local/bin/greadelf \ + [...other configure parameters as you like...] + +5) proceed as described in standard documentation + +----- + +HINTS: +- Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured + under MacOS: It does not include lib%.dylib. + This affects build of (at least) gdb-7.1 + Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment + before executing ct-ng build. + See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html + as an explanation. diff --git a/docs/CREDITS b/docs/CREDITS deleted file mode 100644 index df19097..0000000 --- a/docs/CREDITS +++ /dev/null @@ -1,77 +0,0 @@ -I would like to thank these fine people for making crosstool-NG possible: - - Dan KEGEL, the original author of crosstool: http://www.kegel.com/ - Dan was very helpfull and willing to help when I build my first toolchains. - I owe him one. Thank you Dan! - Some crosstool-NG scripts have code snippets coming almost as-is from the - original work by Dan. - -And in order of appearance on the crossgcc ML: - - Allan CLARK for his investigations on building toolchains on MacOS-X. - Allan made extensive tests of the first alpha of crosstool-NG on his - MacOS-X, and unveiled some bash-2.05 weirdness. - - Enrico WEIGELT - - some improvements to the build procedure - - cxa_atexit disabling for C libraries not supporting it (old uClibc) - - misc suggestions (restartable build, ...) - - get rid of some bashisms in ./configure - - contributed OpenRISC or32 support - - Robert P. J. DAY: - - some small improvements to the configurator, misc prompting glitches - - 'sanitised' patches for binutils-2.17 - - patches for glibc-2.5 - - misc patches, typos and eye candy - - too many to list any more! - - Al Stone: - - initial ia64 support - - some cosmetics - - Szilveszter Ordog: - - a uClibc floating point fix - - initial support for ARM EABI - - Mark Jonas: - - initiated Super-H port - - Michael Abbott: - - make it build with ancient findutils - - Willy Tarreau: - - a patch to glibc to build on 'ancient' shells - - reported mis-use of $CT_CC_NATIVE - - Matthias Kaehlcke: - - fix building glibc-2.7 (and 2.6.1) with newer kernels - - Daniel Dittmann: - - PowerPC support - - Ioannis E. Venetis: - - preliminary Alpha support - - intense gcc-4.3 brainstorming - - Thomas Jourdan: - - intense gcc-4.3 brainstorming - - eglibc support - - Many others have contributed, either in form of patches, suggestions, - comments, or testing... Thank you to all of you! - -Special dedication to the buildroot people for maintaining a set of patches I -happily and shamelessly vampirise from time to time... :-) - - -20100530: Status of this file - -It's been about a year now that we've moved the repository to Mercurial. -The repository now has proper authorship for each changeset, and this is -used to build the changelog at each release. This file will probably no -longer be updated, and is here to credit people prior to the Mercurial -migration, or for people discussing ideas or otherwise helping without -code. - -If you think you deserve being cited in this file, do yell at me! ;-) 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/README.macos.txt b/docs/README.macos.txt deleted file mode 100644 index a933284..0000000 --- a/docs/README.macos.txt +++ /dev/null @@ -1,50 +0,0 @@ -22 May 2010 - Titus - -Prerequisites and instructions for using crosstool-NG for building a cross -toolchain on MacOS as host. - -0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or - Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed - via macports - -1) You have to use a case sensitive file system for ct-ng's build and target - directories. Use a disk or disk image with a case sensitive fs that you - mount somewhere. - -2) Install macports (or similar easy means of installing 3rd party software), - make sure that macport's bin dir is in your PATH. - Furtheron assuming it is /opt/local/bin. - -3) Install (at least) the following macports - ncurses - lzmautils - libtool - binutils - gsed - gawk - gcc43 (only necessary for Leopard OSX 10.5) - - On Leopard, make sure that the macport's gcc is called with the default - commands (gcc, g++,...), e.g. via macport gcc_select - -4) run ct-ng's configure with the following tool configuration - (assuming you have installed the tools via macports in /opt/local): - ./configure --with-sed=/opt/local/bin/gsed \ - --with-libtool=/opt/local/bin/glibtool \ - --with-objcopy=/opt/local/bin/gobjcopy \ - --with-objdump=/opt/local/bin/gobjdump \ - --with-readelf=/opt/local/bin/greadelf \ - [...other configure parameters as you like...] - -5) proceed as described in standard documentation - ------ - -HINTS: -- Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured - under MacOS: It does not include lib%.dylib. - This affects build of (at least) gdb-7.1 - Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment - before executing ct-ng build. - See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html - as an explanation. diff --git a/docs/known-issues.txt b/docs/known-issues.txt deleted file mode 100644 index b787479..0000000 --- a/docs/known-issues.txt +++ /dev/null @@ -1,139 +0,0 @@ -This files lists the known issues encountered while developping crosstool-NG, -but that could not be addressed before the release. - -The file has one section for each known issue, each section containing four -sub-sections: Symptoms, Explanations, Fix, and Workaround. - -Each section is separated from the others with a lines of at least 4 dashes. - -The following dummy section explains it all. - - -------------------------------- - Symptoms: - A one-liner of what you would observe. - - Explanations: - An as much as possible in-depth explanations of the context, why it - happens, what has been investigated so far, and possible orientations - as how to try to solve this (eg. URLs, code snippets...). - - Fix: - What you have to do to fix it, if at all possible. - The fact that there is a fix, and yet this is a known issue means that - time to incorporate the fix in crosstool-NG was missing, or planned for - a future release. - - Workaround: - What you can do to fix it *temporarily*, if at all possible. - A workaround is not a real fix, as it can break other parts of - crosstool-NG, but at least makes you going in your particular case. - -So now, on for the real issues... - --------------------------------- -Symptoms: - gcc is not found, although I *do* have gcc installed. - -Explanations: - This is an issue on at least RHEL systems, where gcc is a symlink to ccache. - Because crosstool-NG create links to gcc for the build and host environment, - those symlinks are in fact pointing to ccache, which then doesn't know how - to run the compiler. - - A possible fix could probably set the environment variable CCACHE_CC to the - actual compiler used. - -Fix: - None known. - -Workaround: - Uninstall ccache. - --------------------------------- -Symptoms: - The extract and/or path steps fail under Cygwin. - -Explanations: - This is not related to crosstool-NG. Mounts under Cygwin are by default not - case-sensitive. You have to use so-called "managed" mounts. See: - http://cygwin.com/faq.html section 4, question 32. - -Fix: - Use "managed" mounts for the directories where you build *and* install your - toolchains. - -Workaround: - None. - --------------------------------- -Symptoms: - uClibc fails to build under Cygwin. - -Explanations: - With uClibc, it is possible to build a cross-ldd. Unfortunately, it is - not (currently) possible to build this cross-ldd under Cygwin. - -Fix: - None so far. - -Workaround: - Disable the cross-ldd build. - --------------------------------- -Symptoms: - On 64-bit build systems, the glibc (possibly eglibc too) build fails for - 64-bit targets, because it can not find libgcc. - -Explanations: - This issue has been observed when the companion libraries are built - statically. For an unknown reason, in this case, the libgcc built by the - core gcc is not located in the same place it is located when building - with shared companion libraries. - -Fix: - None so far. - -Workaround: - Build shared companion libraries. - --------------------------------- -Symptoms: - While building the final gcc, I get an error message that ends with: - libtool.m4: error: problem compiling FC test program - -Explanations: - The gcc build procedure tries to run a Fortran test to see if it has a - working native fortran compiler installed on the build machine, and it - can't find one. A native Fortran compiler is needed (seems to be neede) - to build the Fortran frontend of the cross-compiler. - Even if you don't want to build the Fortran frontend, gcc tries to see - if it has one, but fails. This is no problem, as the Fortran frontend - will not be built. There is nothing to be worry about (unless you do - want to build the Fortran frontend, of course). - -Fix: - None so far. It's a spurious error, so there will probably never be - a fix for this issue. - -Workaround: - None needed, it's a spurious error. - --------------------------------- -Symptoms: - gcc barfs because it is "unable to detect the exception model". - -Explanations: - On some architectures, proper stack unwinding (C++) requires that - setjmp/longjmp (sjlj) be used, while on other architectures do not - need sjlj. On some architectures, gcc is unable to determine whether - sjlj are needed or not. - -Fix: - None so far. - -Workaround: - Trying setting use of sjlj to either 'Y' or 'N' (instead of the - default 'M') in the menuconfig, option CT_CC_GCC_SJLJ_EXCEPTIONS - labelled "Use sjlj for exceptions". - --------------------------------- 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 -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 .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 - -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" - # 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 - - - - - # 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] - - - # 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] " -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] " -and you get the chance to set the . - -Here is a sample `hg email` complete command line: -Note: replace " (at) " with "@" - - hg email --outgoing --intro \ - --to '"Yann E. MORIN" ' \ - --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): - - # and execute again - hg qrefresh -D [-e] - - -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. - - # and execute again - hg qrefresh -D [-e] - - # 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 - # 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 - 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 - 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... -- cgit v0.10.2-6-g49f6