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@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, rpjday@436: - other projects (openembedded.org for example), which is 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@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@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@168: ____________________________ yann@168: / yann@168: Configuring crosstool-NG / yann@168: _________________________/ yann@168: yann@277: crosstool-NG is configured by a configurator presenting a menu-stuctured set of yann@277: options. These options let you specify the way you want your toolchain built, yann@277: 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@294: versions are hidden behind CT_OBSOLETE. 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@246: hidden behind CT_EXPERIMENTAL. yann@246: yann@246: CT_BROKEN: yann@246: Show broken versions or tools. Some usefull tools are currently broken: they yann@246: won't compile, run, or worse, cause defects when running. But if you are yann@246: brave enough, you can try and debug them. They are hidden behind CT_BROKEN, yann@476: which itself is hidden behind CT_EXPERIMENTAL. 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@276: but is quite easy. The options to build a toolchain are saved in the build log yann@276: file that is saved within the toolchain. crosstool-NG can extract those options yann@276: to recreate a new configuration: yann@276: ct-ng extractconfig the function "CT_DoArchValues" yann@381: + parameters: none yann@381: + environment: yann@381: - all variables from the ".config" file, yann@381: - the two variables "target_endian_eb" and "target_endian_el" which are yann@383: 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@391: - the environment variables to configure the cross-gcc yann@391: - CT_ARCH_WITH_ARCH yann@391: - CT_ARCH_WITH_ABI yann@391: - CT_ARCH_WITH_CPU yann@391: - CT_ARCH_WITH_TUNE yann@391: - CT_ARCH_WITH_FPU yann@391: - CT_ARCH_WITH_FLOAT yann@391: - contain (defaults): yann@391: - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" ) yann@456: - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" ) yann@456: - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" ) yann@456: - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" ) yann@456: - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" ) yann@391: - 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@391: - the environment variables to pass to the cross-gcc to build target binaries yann@391: - CT_ARCH_ARCH_CFLAG yann@391: - CT_ARCH_ABI_CFLAG yann@391: - CT_ARCH_CPU_CFLAG yann@391: - CT_ARCH_TUNE_CFLAG yann@391: - CT_ARCH_FPU_CFLAG yann@391: - CT_ARCH_FLOAT_CFLAG yann@391: - CT_ARCH_ENDIAN_CFLAG yann@391: - contain (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@391: yann@476: Adding a new version of a conponent | 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@476: tools/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...