diff -r edc7c7958e80 -r b58109b7b321 docs/overview.txt --- a/docs/overview.txt Tue Aug 10 13:25:52 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -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...