yann@1: File.........: overview.txt yann@197: Content......: Overview of how crosstool-NG works. yann@92: Copyrigth....: (C) 2007 Yann E. MORIN yann@192: License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5 yann@92: yann@628: ____________________ yann@628: / yann@628: Table Of Content / yann@628: _________________/ yann@628: yann@628: yann@628: Introduction yann@628: History yann@628: Installing crosstool-NG yann@628: Install method yann@628: The hacker's way yann@1048: Preparing for packaging yann@837: Shell completion yann@628: Contributed code yann@628: Configuring crosstool-NG yann@628: Interesting config options yann@628: Re-building an existing toolchain yann@628: Running crosstool-NG yann@628: Stopping and restarting a build yann@628: Testing all toolchains at once yann@628: Overriding the number of // jobs yann@628: Using the toolchain yann@628: Toolchain types yann@628: Internals yann@628: Makefile front-end yann@628: Kconfig parser yann@628: Architecture-specific yann@628: Adding a new version of a component yann@628: Build scripts yann@628: yann@1: ________________ yann@1: / yann@1: Introduction / yann@1: _____________/ yann@1: yann@1: crosstool-NG aims at building toolchains. Toolchains are an essential component yann@1: in a software development project. It will compile, assemble and link the code rpjday@436: that is being developed. Some pieces of the toolchain will eventually end up yann@1: in the resulting binary/ies: static libraries are but an example. yann@1: yann@1: So, a toolchain is a very sensitive piece of software, as any bug in one of the yann@1: components, or a poorly configured component, can lead to execution problems, yann@1: ranging from poor performance, to applications ending unexpectedly, to yann@1: mis-behaving software (which more than often is hard to detect), to hardware rpjday@436: damage, or even to human risks (which is more than regrettable). yann@1: yann@1: Toolchains are made of different piece of software, each being quite complex yann@1: and requiring specially crafted options to build and work seamlessly. This yann@1: is usually not that easy, even in the not-so-trivial case of native toolchains. yann@1: The work reaches a higher degree of complexity when it comes to cross- yann@40: compilation, where it can become quite a nightmare... yann@1: yann@40: Some cross-toolchains exist on the internet, and can be used for general yann@1: development, but they have a number of limitations: yann@1: - they can be general purpose, in that they are configured for the majority: yann@1: no optimisation for your specific target, yann@1: - they can be prepared for a specific target and thus are not easy to use, yann@1: nor optimised for, or even supporting your target, rpjday@436: - they often are using aging components (compiler, C library, etc...) not yann@1: supporting special features of your shiny new processor; yann@1: On the other side, these toolchain offer some advantages: yann@1: - they are ready to use and quite easy to install and setup, yann@1: - they are proven if used by a wide community. yann@1: yann@1: But once you want to get all the juice out of your specific hardware, you will yann@197: want to build your own toolchain. This is where crosstool-NG comes into play. yann@1: rpjday@436: There are also a number of tools that build toolchains for specific needs, rpjday@436: which are not really scalable. Examples are: rpjday@436: - buildroot (buildroot.uclibc.org) whose main purpose is to build root file yann@1: systems, hence the name. But once you have your toolchain with buildroot, yann@1: part of it is installed in the root-to-be, so if you want to build a whole yann@1: new root, you either have to save the existing one as a template and yann@1: restore it later, or restart again from scratch. This is not convenient, yann@1: - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very yann@1: similar to buildroot, yann@702: - other projects (openembedded.org for example), which are again used to yann@1: build root file systems. yann@1: rpjday@436: crosstool-NG is really targeted at building toolchains, and only toolchains. yann@1: It is then up to you to use it the way you want. yann@1: yann@1: ___________ yann@1: / yann@1: History / yann@1: ________/ yann@1: rpjday@436: crosstool was first 'conceived' by Dan Kegel, who offered it to the community yann@1: as a set of scripts, a repository of patches, and some pre-configured, general yann@1: purpose setup files to be used to configure crosstool. This is available at yann@203: http://www.kegel.com/crosstool, and the subversion repository is hosted on yann@203: google at http://code.google.com/p/crosstool/. yann@1: yann@1: I once managed to add support for uClibc-based toolchains, but it did not make yann@437: into mainline, mostly because I didn't have time to port the patch forward to yann@1: the new versions, due in part to the big effort it was taking. yann@1: yann@1: So I decided to clean up crosstool in the state it was, re-order the things yann@437: in place, add appropriate support for what I needed, that is uClibc support yann@437: and a menu-driven configuration, named the new implementation crosstool-NG, yann@437: (standing for crosstool Next Generation, as many other comunity projects do, yann@437: and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and yann@437: made it available to the community, in case it was of interest to any one. yann@1: yann@294: ___________________________ yann@294: / yann@294: Installing crosstool-NG / yann@294: ________________________/ yann@294: yann@294: There are two ways you can use crosstool-NG: yann@294: - build and install it, then get rid of the sources like you'd do for most yann@294: programs, yann@294: - or only build it and run from the source directory. yann@294: yann@294: The former should be used if you got crosstool-NG from a packaged tarball, see rpjday@436: "Install method", below, while the latter is most useful for developpers that yann@294: checked the code out from SVN, and want to submit patches, see "The Hacker's yann@294: way", below. yann@294: yann@294: Install method | yann@294: ---------------+ yann@294: yann@294: If you go for the install, then you just follow the classical, but yet easy yann@294: ./configure way: yann@294: ./configure --prefix=/some/place yann@294: make yann@294: make install yann@294: export PATH="${PATH}:/some/place/bin" yann@294: yann@294: You can then get rid of crosstool-NG source. Next create a directory to serve yann@294: as a working place, cd in there and run: yann@294: ct-ng help yann@294: yann@294: See below for complete usage. yann@294: yann@294: The Hacker's way | yann@294: -----------------+ yann@294: yann@294: If you go the hacker's way, then the usage is a bit different, although very yann@294: simple: yann@294: ./configure --local yann@294: make yann@1048: make install yann@294: yann@294: Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG! yann@294: Stay in the directory holding the sources, and run: yann@294: ./ct-ng help yann@294: yann@294: See below for complete usage. yann@294: yann@294: Now, provided you checked-out the code, you can send me your interesting changes yann@294: by running: yann@294: svn diff yann@294: yann@294: and mailing me the result! :-P yann@294: yann@1048: Preparing for packaging | yann@1048: ------------------------+ yann@1048: yann@1048: If you plan on packaging crosstool-NG, you surely don't want to install it yann@1048: in your root file system. The install procedure of crosstool-NG honors the yann@1048: DESTDIR variable: yann@1048: yann@1048: ./configure --prefix=/usr yann@1048: make rpjday@1291: make DESTDIR=/packaging/place install yann@1048: yann@837: Shell completion | yann@837: -----------------+ yann@837: yann@837: crosstool-NG comes with a shell script fragment that defines bash-compatible yann@837: completion. That shell fragment is currently not installed automatically, but yann@837: this is planned. yann@837: yann@837: To install the shell script fragment, you have two options: yann@837: - install system-wide, most probably by copying ct-ng.comp into yann@837: /etc/bash_completion.d/ yann@837: - install for a single user, by copying ct-ng.comp into ${HOME}/ and yann@837: sourcing this file from your ${HOME}/.bashrc yann@837: yann@456: Contributed code | yann@456: -----------------+ yann@456: yann@456: Some people contibuted code that couldn't get merged for various reasons. This yann@456: code is available as patches in the contrib/ sub-directory. These patches are yann@456: to be applied to the source of crosstool-NG, prior to installing. yann@456: yann@620: An easy way to use contributed code is to pass the --with-contrib= option to yann@620: ./configure. The possible values depend upon which contributions are packaged yann@620: with your version, but you can get with it with passing one of those two yann@620: special values: yann@620: --with-contrib=list yann@620: will list all available contributions yann@620: yann@620: --with-contrib=all yann@620: will select all avalaible contributions yann@620: yann@620: There is no guarantee that a particuliar contribution applies to the current yann@620: version of crosstool-ng, or that it will work at all. Use contributions at yann@620: your own risk. yann@620: yann@168: ____________________________ yann@168: / yann@168: Configuring crosstool-NG / yann@168: _________________________/ yann@168: yann@620: crosstool-NG is configured with a configurator presenting a menu-stuctured set yann@620: of options. These options let you specify the way you want your toolchain yann@620: built, where you want it installed, what architecture and specific processor it yann@277: will support, the version of the components you want to use, etc... The yann@277: value for those options are then stored in a configuration file. yann@277: yann@476: The configurator works the same way you configure your Linux kernel. It is yann@277: assumed you now how to handle this. yann@168: yann@168: To enter the menu, type: yann@192: ct-ng menuconfig yann@168: yann@203: Almost every config item has a help entry. Read them carefully. yann@168: yann@168: String and number options can refer to environment variables. In such a case, yann@192: you must use the shell syntax: ${VAR}. You shall neither single- nor double- yann@294: quote the string/number options. yann@168: yann@192: There are three environment variables that are computed by crosstool-NG, and yann@168: that you can use: yann@168: yann@168: CT_TARGET: yann@335: It represents the target tuple you are building for. You can use it for yann@168: example in the installation/prefix directory, such as: yann@168: /opt/x-tools/${CT_TARGET} yann@168: yann@168: CT_TOP_DIR: yann@182: The top directory where crosstool-NG is running. You shouldn't need it in yann@182: most cases. There is one case where you may need it: if you have local yann@182: patches and you store them in your running directory, you can refer to them yann@168: by using CT_TOP_DIR, such as: yann@168: ${CT_TOP_DIR}/patches.myproject yann@168: yann@168: CT_VERSION: yann@192: The version of crosstool-NG you are using. Not much use for you, but it's yann@168: there if you need it. yann@168: yann@168: Interesting config options | yann@476: ---------------------------+ yann@168: yann@168: CT_LOCAL_TARBALLS_DIR: yann@277: If you already have some tarballs in a direcotry, enter it here. That will yann@197: speed up the retrieving phase, where crosstool-NG would otherwise download yann@168: those tarballs. yann@168: yann@168: CT_PREFIX_DIR: yann@168: This is where the toolchain will be installed in (and for now, where it yann@437: will run from). Common use is to add the target tuple in the directory yann@277: path, such as (see above): yann@277: /opt/x-tools/${CT_TARGET} yann@168: yann@168: CT_TARGET_VENDOR: yann@168: An identifier for your toolchain, will take place in the vendor part of the yann@335: target tuple. It shall *not* contain spaces or dashes. Usually, keep it yann@168: to a one-word string, or use underscores to separate words if you need. yann@168: Avoid dots, commas, and special characters. yann@168: yann@168: CT_TARGET_ALIAS: yann@168: An alias for the toolchian. It will be used as a prefix to the toolchain yann@168: tools. For example, you will have ${CT_TARGET_ALIAS}-gcc yann@168: yann@246: Also, if you think you don't see enough versions, you can try to enable one of yann@246: those: yann@246: yann@246: CT_OBSOLETE: yann@246: Show obsolete versions or tools. Most of the time, you don't want to base yann@246: your toolchain on too old a version (of gcc, for example). But at times, it yann@246: can come handy to use such an old version for regression tests. Those old yann@1300: versions are hidden behind CT_OBSOLETE. Those versions (or features) are so yann@1300: marked because maintaining support for those in crosstool-NG would be too yann@1300: costly, time-wise, and time is dear. yann@246: yann@246: CT_EXPERIMENTAL: yann@246: Show experimental versions or tools. Again, you might not want to base your yann@246: toolchain on too recent tools (eg. gcc) for production. But if you need a yann@246: feature present only in a recent version, or a new tool, you can find them yann@1300: hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet) yann@1300: receive thorough testing in crosstool-NG, and/or are not mature enough to yann@1300: be blindly trusted. yann@246: yann@276: Re-building an existing toolchain | yann@276: ----------------------------------+ yann@276: yann@276: If you have an existing toolchain, you can re-use the options used to build it yann@276: to create a new toolchain. That needs a very little bit of effort on your side yann@894: but is quite easy. The options to build a toolchain are saved with the yann@894: toolchain, and you can retrieve this configuration by running: yann@894: ${CT_TARGET}-config yann@276: yann@894: This will dump the configuration to stdout, so to rebuild a toolchain with this yann@894: configuration, the following is all you need to do: yann@894: ${CT_TARGET}-config >.config yann@1098: ct-ng oldconfig yann@276: yann@894: Then, you can review and change the configuration by running: yann@894: ct-ng menuconfig yann@276: yann@168: ________________________ yann@168: / yann@168: Running crosstool-NG / yann@168: _____________________/ yann@1: yann@168: To build the toolchain, simply type: yann@203: ct-ng build yann@135: yann@135: This will use the above configuration to retrieve, extract and patch the yann@135: components, build, install and eventually test your newly built toolchain. yann@1: yann@1: You are then free to add the toolchain /bin directory in your PATH to use yann@1: it at will. yann@1: yann@135: In any case, you can get some terse help. Just type: yann@192: ct-ng help yann@203: or: yann@203: man 1 ct-ng yann@135: rpjday@436: Stopping and restarting a build | yann@476: --------------------------------+ yann@135: yann@135: If you want to stop the build after a step you are debugging, you can pass the yann@135: variable STOP to make: yann@192: ct-ng STOP=some_step yann@135: yann@135: Conversely, if you want to restart a build at a specific step you are yann@135: debugging, you can pass the RESTART variable to make: yann@192: ct-ng RESTART=some_step yann@135: yann@136: Alternatively, you can call make with the name of a step to just do that step: yann@192: ct-ng libc_headers yann@136: is equivalent to: yann@620: ct-ng RESTART=libc_headers STOP=libc_headers yann@136: yann@304: The shortcuts +step_name and step_name+ allow to respectively stop or restart yann@136: at that step. Thus: yann@304: ct-ng +libc_headers and: ct-ng libc_headers+ yann@136: are equivalent to: yann@192: ct-ng STOP=libc_headers and: ct-ng RESTART=libc_headers yann@136: yann@181: To obtain the list of acceptable steps, please call: yann@544: ct-ng list-steps yann@181: yann@168: Note that in order to restart a build, you'll have to say 'Y' to the config yann@168: option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went yann@168: that far. yann@92: yann@1025: Building all toolchains at once | yann@1025: --------------------------------+ yann@92: yann@1025: You can build all samples; simply call: yann@1025: ct-ng build-all yann@40: yann@335: Overriding the number of // jobs | yann@476: ---------------------------------+ yann@335: yann@335: If you want to override the number of jobs to run in // (the -j option to yann@335: make), you can either re-enter the menuconfig, or simply add it on the command yann@335: line, as such: yann@335: ct-ng build.4 yann@335: yann@335: which tells crosstool-NG to override the number of // jobs to 4. yann@335: yann@335: You can see the actions that support overriding the number of // jobs in yann@335: the help menu. Those are the ones with [.#] after them (eg. build[.#] or yann@1025: build-all[.#], and so on...). yann@1025: yann@1025: Note on // jobs | yann@1025: ----------------+ yann@1025: yann@1025: The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute yann@1025: in parallel (there is not much to gain). When speaking of // jobs, we are yann@1025: refering to the number of // jobs when making the *components*. That is, we yann@1025: speak of the number of // jobs used to build gcc, glibc, and so on... yann@1025: yann@335: yann@227: _______________________ yann@227: / yann@227: Using the toolchain / yann@227: ____________________/ yann@227: yann@227: Using the toolchain is as simple as adding the toolchain's bin directory in yann@227: your PATH, such as: yann@227: export PATH="${PATH}:/your/toolchain/path/bin" yann@227: yann@335: and then using the target tuple to tell the build systems to use your yann@227: toolchain: yann@335: ./configure --target=your-target-tuple yann@294: or yann@335: make CC=your-target-tuple-gcc yann@294: or yann@335: make CROSS_COMPILE=your-target-tuple- yann@294: and so on... yann@227: yann@476: It is strongly advised not to use the toolchain sys-root directory as an yann@620: install directory for your programs/packages. If you do so, you will not be yann@476: able to use your toolchain for another project. It is even strongly advised yann@476: that your toolchain is chmod-ed to read-only once successfully build, so that yann@620: you don't go polluting your toolchain with your programs/packages' files. yann@476: yann@476: Thus, when you build a program/package, install it in a separate directory, yann@476: eg. /your/root. This directory is the /image/ of what would be in the root file yann@620: system of your target, and will contain all that your programs/packages have yann@476: installed. yann@476: yann@227: When your root directory is ready, it is still missing some important bits: the yann@227: toolchain's libraries. To populate your root directory with those libs, just yann@227: run: yann@335: your-target-tuple-populate -s /your/root -d /your/root-populated yann@227: yann@227: This will copy /your/root into /your/root-populated, and put the needed and only yann@227: the needed libraries there. Thus you don't polute /your/root with any cruft that yann@227: would no longer be needed should you have to remove stuff. /your/root always yann@227: contains only those things you install in it. yann@227: yann@227: You can then use /your/root-populated to build up your file system image, a yann@227: tarball, or to NFS-mount it from your target, or whatever you need. yann@227: yann@294: populate accepts the following options: yann@294: yann@294: -s [src_dir] yann@294: Use 'src_dir' as the 'source', un-populated root directory yann@294: yann@294: -d [dst_dir] yann@294: Put the 'destination', populated root directory in 'dst_dir' yann@294: yann@294: -f yann@294: Remove 'dst_dir' if it previously existed yann@294: yann@294: -v yann@294: Be verbose, and tell what's going on (you can see exactly where libs are yann@294: coming from). yann@294: yann@294: -h yann@294: Print the help yann@294: yann@40: ___________________ yann@40: / yann@40: Toolchain types / yann@40: ________________/ yann@40: yann@40: There are four kinds of toolchains you could encounter. yann@40: yann@40: First off, you must understand the following: when it comes to compilers there yann@40: are up to four machines involved: yann@40: 1) the machine configuring the toolchain components: the config machine yann@40: 2) the machine building the toolchain components: the build machine yann@40: 3) the machine running the toolchain: the host machine yann@203: 4) the machine the toolchain is generating code for: the target machine yann@40: yann@40: We can most of the time assume that the config machine and the build machine yann@40: are the same. Most of the time, this will be true. The only time it isn't yann@40: is if you're using distributed compilation (such as distcc). Let's forget yann@40: this for the sake of simplicity. yann@40: yann@40: So we're left with three machines: yann@40: - build yann@40: - host yann@40: - target yann@40: yann@40: Any toolchain will involve those three machines. You can be as pretty sure of yann@40: this as "2 and 2 are 4". Here is how they come into play: yann@40: yann@40: 1) build == host == target yann@40: This is a plain native toolchain, targetting the exact same machine as the yann@40: one it is built on, and running again on this exact same machine. You have yann@40: to build such a toolchain when you want to use an updated component, such yann@40: as a newer gcc for example. yann@197: crosstool-NG calls it "native". yann@40: yann@40: 2) build == host != target yann@40: This is a classic cross-toolchain, which is expected to be run on the same yann@40: machine it is compiled on, and generate code to run on a second machine, yann@40: the target. yann@197: crosstool-NG calls it "cross". yann@40: yann@40: 3) build != host == target yann@40: Such a toolchain is also a native toolchain, as it targets the same machine yann@40: as it runs on. But it is build on another machine. You want such a yann@40: toolchain when porting to a new architecture, or if the build machine is yann@40: much faster than the host machine. yann@197: crosstool-NG calls it "cross-native". yann@40: yann@40: 4) build != host != target yann@92: This one is called a canadian-toolchain (*), and is tricky. The three yann@40: machines in play are different. You might want such a toolchain if you yann@40: have a fast build machine, but the users will use it on another machine, yann@40: and will produce code to run on a third machine. yann@197: crosstool-NG calls it "canadian". yann@40: yann@197: crosstool-NG can build all these kinds of toolchains (or is aiming at it, yann@197: anyway!) yann@40: yann@40: (*) The term Canadian Cross came about because at the time that these issues yann@40: were all being hashed out, Canada had three national political parties. yann@40: http://en.wikipedia.org/wiki/Cross_compiler yann@40: yann@1: _____________ yann@1: / yann@1: Internals / yann@1: __________/ yann@1: yann@92: Internally, crosstool-NG is script-based. To ease usage, the frontend is yann@92: Makefile-based. yann@92: yann@92: Makefile front-end | yann@476: -------------------+ yann@92: yann@203: The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this yann@203: script with an action will act exactly as if the Makefile was in the current yann@203: working directory and make was called with the action as rule. Thus: yann@203: ct-ng menuconfig yann@294: yann@203: is equivalent to having the Makefile in CWD, and calling: yann@203: make menuconfig yann@203: yann@203: Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a yann@203: traditional command. yann@203: yann@203: ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up yann@203: at configuration time with ./configure. yann@203: yann@437: ct-ng also searches for config files, sub-tools, samples, scripts and patches in yann@203: that library directory. yann@92: yann@294: Because of a stupid make behavior/bug I was unable to track down, implicit make yann@294: rules are disabled: installing with --local would triger those rules, and mconf yann@294: was unbuildable. yann@294: yann@182: Kconfig parser | yann@476: ---------------+ yann@92: yann@965: The kconfig language is a hacked version, vampirised from the Linux kernel yann@965: (http://www.kernel.org/), and (heavily) adapted to my needs. yann@92: yann@1040: The list of the most notable changes (at least the ones I remember) follows: yann@1040: - the CONFIG_ prefix has been replaced with CT_ yann@1040: - a leading | in prompts is skipped, and subsequent leading spaces are not yann@1040: trimmed yann@1040: - otherwise leading spaces are silently trimmed yann@1040: yann@203: The kconfig parsers (conf and mconf) are not installed pre-built, but as yann@203: source files. Thus you can have the directory where crosstool-NG is installed, yann@203: exported (via NFS or whatever) and have clients with different architectures yann@203: use the same crosstool-NG installation, and most notably, the same set of yann@203: patches. yann@203: yann@381: Architecture-specific | yann@476: ----------------------+ yann@381: yann@628: Note: this chapter is not really well written, and might thus be a little bit yann@628: complex to understand. To get a better grasp of what an architecture is, the yann@628: reader is kindly encouraged to look at the "arch/" sub-directory, and to the yann@628: existing architectures to see how things are laid out. yann@628: yann@381: An architecture is defined by: yann@381: yann@381: - a human-readable name, in lower case letters, with numbers as appropriate. yann@628: The underscore is allowed; space and special characters are not. yann@628: Eg.: arm, x86_64 yann@903: - a file in "config/arch/", named after the architecture's name, and suffixed yann@903: with ".in". yann@903: Eg.: config/arch/arm.in yann@903: - a file in "scripts/build/arch/", named after the architecture's name, and yann@903: suffixed with ".sh". yann@903: Eg.: scripts/build/arch/arm.sh yann@628: yann@903: The architecture's ".in" file API: yann@628: > the config option "ARCH_%arch%" (where %arch% is to be replaced with the yann@628: actual architecture name). yann@628: That config option must have *neither* a type, *nor* a prompt! Also, it can yann@628: *not* depend on any other config option (EXPERIMENTAL is managed as above). yann@628: Eg.: yann@628: config ARCH_arm yann@630: + mandatory: yann@702: defines a (terse) help entry for this architecture: yann@630: Eg.: yann@630: config ARCH_arm yann@630: help yann@630: The ARM architecture. yann@628: + optional: yann@628: selects adequate associated config options. yann@1038: Note: 64-bit architectures *shall* select ARCH_64 yann@628: Eg.: yann@628: config ARCH_arm yann@628: select ARCH_SUPPORTS_BOTH_ENDIAN yann@628: select ARCH_DEFAULT_LE yann@630: help yann@630: The ARM architecture. yann@1038: Eg.: yann@1038: config ARCH_x86_64 yann@1038: select ARCH_64 yann@1038: help yann@1038: The x86_64 architecture. yann@628: yann@628: > other target-specific options, at your discretion. Note however that to yann@628: avoid name-clashing, such options shall be prefixed with "ARCH_%arch%", yann@628: where %arch% is again replaced by the actual architecture name. yann@628: (Note: due to historical reasons, and lack of time to clean up the code, yann@628: I may have left some config options that do not completely conform to yann@628: this, as the architecture name was written all upper case. However, the yann@628: prefix is unique among architectures, and does not cause harm). yann@381: yann@903: The architecture's ".sh" file API: yann@965: > the function "CT_DoArchTupleValues" yann@381: + parameters: none yann@381: + environment: yann@901: - all variables from the ".config" file, yann@901: - the two variables "target_endian_eb" and "target_endian_el" which are yann@901: the endianness suffixes yann@381: + return value: 0 upon success, !0 upon failure yann@381: + provides: yann@391: - mandatory yann@383: - the environment variable CT_TARGET_ARCH yann@389: - contains: yann@389: the architecture part of the target tuple. yann@389: Eg.: "armeb" for big endian ARM yann@389: "i386" for an i386 yann@389: + provides: yann@391: - optional yann@389: - the environment variable CT_TARGET_SYS yann@456: - contains: yann@383: the sytem part of the target tuple. yann@383: Eg.: "gnu" for glibc on most architectures yann@383: "gnueabi" for glibc on an ARM EABI yann@383: - defaults to: yann@383: - for glibc-based toolchain: "gnu" yann@383: - for uClibc-based toolchain: "uclibc" yann@383: + provides: yann@383: - optional yann@391: - the environment variable CT_KERNEL_ARCH yann@383: - contains: yann@391: the architecture name as understandable by the Linux kernel build yann@391: system. yann@391: Eg.: "arm" for an ARM yann@391: "powerpc" for a PowerPC yann@391: "i386" for an x86 yann@383: - defaults to: yann@391: ${CT_ARCH} yann@391: + provides: yann@391: - optional yann@767: - the environment variables to configure the cross-gcc (defaults) yann@767: - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" ) yann@767: - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" ) yann@767: - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" ) yann@767: - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" ) yann@767: - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" ) yann@767: - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ ) yann@391: + provides: yann@391: - optional yann@767: - the environment variables to pass to the cross-gcc to build target binaries (defaults) yann@391: - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" ) yann@456: - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" ) yann@391: - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" ) yann@391: - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" ) yann@391: - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" ) yann@391: - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ ) yann@391: - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" ) yann@391: - default to: yann@391: see above. yann@767: + provides: yann@767: - optional yann@767: - the environement variables to configure the core and final compiler, specific to this architecture: yann@767: - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags yann@767: - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags yann@767: - default to: yann@767: - all empty yann@767: + provides: yann@767: - optional yann@767: - the architecture-specific CFLAGS and LDFLAGS: yann@767: - CT_ARCH_TARGET_CLFAGS yann@767: - CT_ARCH_TARGET_LDFLAGS yann@767: - default to: yann@767: - all empty yann@628: yann@903: You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for yann@903: a quite complete example of what an actual architecture description looks like. yann@901: yann@890: Kernel specific | yann@890: ----------------+ yann@890: yann@890: A kernel is defined by: yann@890: yann@890: - a human-readable name, in lower case letters, with numbers as appropriate. yann@890: The underscore is allowed; space and special characters are not (although yann@890: they are internally replaced with underscores. yann@890: Eg.: linux, bare-metal yann@890: - a file in "config/kernel/", named after the kernel name, and suffixed with yann@890: ".in". yann@890: Eg.: config/kernel/linux.in, config/kernel/bare-metal.in yann@901: - a file in "scripts/build/kernel/", named after the kernel name, and suffixed yann@901: with ".sh". yann@901: Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh yann@890: yann@890: The kernel's ".in" file must contain: yann@890: > an optional lines containing exactly "# EXPERIMENTAL", starting on the yann@890: first column, and without any following space or other character. yann@890: If this line is present, then this kernel is considered EXPERIMENTAL, yann@890: and correct dependency on EXPERIMENTAL will be set. yann@901: yann@890: > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be yann@890: replaced with the actual kernel name, with all special characters and yann@890: spaces replaced by underscores). yann@890: That config option must have *neither* a type, *nor* a prompt! Also, it can yann@890: *not* depends on EXPERIMENTAL. yann@890: Eg.: KERNEL_linux, KERNEL_bare_metal yann@890: + mandatory: yann@890: defines a (terse) help entry for this kernel. yann@890: Eg.: yann@890: config KERNEL_bare_metal yann@890: help yann@890: Build a compiler for use without any kernel. yann@890: + optional: yann@890: selects adequate associated config options. yann@890: Eg.: yann@890: config KERNEL_bare_metal yann@890: select BARE_METAL yann@890: help yann@890: Build a compiler for use without any kernel. yann@890: yann@890: > other kernel specific options, at your discretion. Note however that, to yann@890: avoid name-clashing, such options should be prefixed with yann@890: "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with yann@890: the actual kernel name. yann@890: (Note: due to historical reasons, and lack of time to clean up the code, yann@890: I may have left some config options that do not completely conform to yann@890: this, as the kernel name was written all upper case. However, the prefix yann@890: is unique among kernels, and does not cause harm). yann@890: yann@901: The kernel's ".sh" file API: yann@901: > is a bash script fragment yann@901: yann@965: > defines the function CT_DoKernelTupleValues yann@965: + see the architecture's CT_DoArchTupleValues, except for: yann@965: + set the environment variable CT_TARGET_KERNEL, the kernel part of the yann@965: target tuple yann@965: + return value: ignored yann@965: yann@901: > defines the function "do_kernel_get": yann@901: + parameters: none yann@901: + environment: yann@901: - all variables from the ".config" file. yann@901: + return value: 0 for success, !0 for failure. yann@901: + behavior: download the kernel's sources, and store the tarball into yann@901: "${CT_TARBALLS_DIR}". To this end, a functions is available, that yann@901: abstracts downloading tarballs: yann@901: - CT_DoGet yann@901: Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6 yann@901: Note: retrieving sources from svn, cvs, git and the likes is not supported yann@901: by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in yann@901: "scripts/build/libc/eglibc.sh" yann@901: yann@901: > defines the function "do_kernel_extract": yann@901: + parameters: none yann@901: + environment: yann@901: - all variables from the ".config" file, yann@901: + return value: 0 for success, !0 for failure. yann@901: + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply yann@901: required patches. To this end, a function is available, that abstracts yann@901: extracting tarballs: yann@901: - CT_ExtractAndPatch yann@901: Eg.: CT_ExtractAndPatch linux-2.6.26.5 yann@901: yann@901: > defines the function "do_kernel_headers": yann@901: + parameters: none yann@901: + environment: yann@901: - all variables from the ".config" file, yann@901: + return value: 0 for success, !0 for failure. yann@901: + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include" yann@901: yann@901: > defines any kernel-specific helper functions yann@901: These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_", yann@901: where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid yann@901: any name-clashing. yann@901: yann@901: You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh" yann@903: as an example of what a complex kernel description looks like. yann@901: yann@620: Adding a new version of a component | yann@476: ------------------------------------+ yann@476: yann@476: When a new component, such as the Linux kernel, gcc or any other is released, yann@476: adding the new version to crosstool-NG is quite easy. There is a script that yann@476: will do all that for you: yann@1095: scripts/addToolVersion.sh yann@476: yann@476: Run it with no option to get some help. yann@381: yann@203: Build scripts | yann@476: --------------+ yann@203: yann@203: To Be Written later...