1.1 --- a/Makefile.in Tue Aug 10 13:25:52 2010 +0200
1.2 +++ b/Makefile.in Sat Aug 14 16:37:11 2010 +0200
1.3 @@ -241,8 +241,8 @@
1.4 done
1.5
1.6 install-doc: $(DESTDIR)$(DOCDIR)
1.7 - @for doc_file in docs/CREDITS docs/overview.txt; do \
1.8 - echo " INST '$${doc_file}'"; \
1.9 + @echo " INST 'docs/*.txt'"
1.10 + @for doc_file in docs/*.txt; do \
1.11 $(install) -m 644 "$${doc_file}" "$(DESTDIR)$(DOCDIR)"; \
1.12 done
1.13
2.1 --- a/ct-ng.in Tue Aug 10 13:25:52 2010 +0200
2.2 +++ b/ct-ng.in Sat Aug 14 16:37:11 2010 +0200
2.3 @@ -94,11 +94,11 @@
2.4
2.5 help-env::
2.6 @echo
2.7 - @echo 'Environement variables (see @@CT_DOCDIR@@/overview.txt):'
2.8 + @echo 'Environement variables (see @@CT_DOCDIR@@/0 - Table of content.txt):'
2.9
2.10 help-tail::
2.11 @echo
2.12 - @echo 'Use action "menuconfig" to configure crosstool-NG'
2.13 + @echo 'Use action "menuconfig" to configure your toolchain'
2.14 @echo 'Use action "build" to build your toolchain'
2.15 @echo 'Use action "version" to see the version'
2.16 @echo 'See "man 1 ct-ng" for some help as well'
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/0 - Table of content.txt Sat Aug 14 16:37:11 2010 +0200
3.3 @@ -0,0 +1,56 @@
3.4 +File.........: 0 - Table of content.txt
3.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
3.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
3.7 +
3.8 +
3.9 +Table Of Content /
3.10 +_________________/
3.11 +
3.12 +
3.13 +1- Introduction
3.14 + - History
3.15 + - Referring to crosstool-NG
3.16 +
3.17 +2- Installing crosstool-NG
3.18 + - Install method
3.19 + - The hacker's way
3.20 + - Preparing for packaging
3.21 + - Shell completion
3.22 + - Contributed code
3.23 +
3.24 +3- Configuring a toolchain
3.25 + - Interesting config options
3.26 + - Re-building an existing toolchain
3.27 + - Using as a backend for a build-system
3.28 +
3.29 +4- Building the toolchain
3.30 + - Stopping and restarting a build
3.31 + - Testing all toolchains at once
3.32 + - Overriding the number of // jobs
3.33 + - Note on // jobs
3.34 + - Tools wrapper
3.35 +
3.36 +5- Using the toolchain
3.37 + - The 'populate' script
3.38 +
3.39 +6- Toolchain types
3.40 + - Seemingly-native toolchains
3.41 +
3.42 +7- Contributing
3.43 + - Sending a bug report
3.44 + - Sending patches
3.45 +
3.46 +8- Internals
3.47 + - Makefile front-end
3.48 + - Kconfig parser
3.49 + - Architecture-specific
3.50 + - Adding a new version of a component
3.51 + - Build scripts
3.52 +
3.53 +A- Credits
3.54 +
3.55 +B- Known issues
3.56 +
3.57 +C- Misc. tutorials
3.58 + - Using crosstool-NG on FreeBSD (and other *BSD)
3.59 + - Using crosstool-NG on MacOS-X
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/1 - Introduction.txt Sat Aug 14 16:37:11 2010 +0200
4.3 @@ -0,0 +1,108 @@
4.4 +File.........: 1 - Introduction.txt
4.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
4.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
4.7 +
4.8 +
4.9 +Introduction /
4.10 +_____________/
4.11 +
4.12 +
4.13 +crosstool-NG aims at building toolchains. Toolchains are an essential component
4.14 +in a software development project. It will compile, assemble and link the code
4.15 +that is being developed. Some pieces of the toolchain will eventually end up
4.16 +in the resulting binary/ies: static libraries are but an example.
4.17 +
4.18 +So, a toolchain is a very sensitive piece of software, as any bug in one of the
4.19 +components, or a poorly configured component, can lead to execution problems,
4.20 +ranging from poor performance, to applications ending unexpectedly, to
4.21 +mis-behaving software (which more than often is hard to detect), to hardware
4.22 +damage, or even to human risks (which is more than regrettable).
4.23 +
4.24 +Toolchains are made of different piece of software, each being quite complex
4.25 +and requiring specially crafted options to build and work seamlessly. This
4.26 +is usually not that easy, even in the not-so-trivial case of native toolchains.
4.27 +The work reaches a higher degree of complexity when it comes to cross-
4.28 +compilation, where it can become quite a nightmare...
4.29 +
4.30 +Some cross-toolchains exist on the internet, and can be used for general
4.31 +development, but they have a number of limitations:
4.32 + - they can be general purpose, in that they are configured for the majority:
4.33 + no optimisation for your specific target,
4.34 + - they can be prepared for a specific target and thus are not easy to use,
4.35 + nor optimised for, or even supporting your target,
4.36 + - they often are using aging components (compiler, C library, etc...) not
4.37 + supporting special features of your shiny new processor;
4.38 +On the other side, these toolchain offer some advantages:
4.39 + - they are ready to use and quite easy to install and setup,
4.40 + - they are proven if used by a wide community.
4.41 +
4.42 +But once you want to get all the juice out of your specific hardware, you will
4.43 +want to build your own toolchain. This is where crosstool-NG comes into play.
4.44 +
4.45 +There are also a number of tools that build toolchains for specific needs,
4.46 +which are not really scalable. Examples are:
4.47 + - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
4.48 + systems, hence the name. But once you have your toolchain with buildroot,
4.49 + part of it is installed in the root-to-be, so if you want to build a whole
4.50 + new root, you either have to save the existing one as a template and
4.51 + restore it later, or restart again from scratch. This is not convenient,
4.52 + - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
4.53 + similar to buildroot,
4.54 + - other projects (openembedded.org for example), which are again used to
4.55 + build root file systems.
4.56 +
4.57 +crosstool-NG is really targeted at building toolchains, and only toolchains.
4.58 +It is then up to you to use it the way you want.
4.59 +
4.60 +
4.61 +History |
4.62 +--------+
4.63 +
4.64 +crosstool was first 'conceived' by Dan Kegel, who offered it to the community
4.65 +as a set of scripts, a repository of patches, and some pre-configured, general
4.66 +purpose setup files to be used to configure crosstool. This is available at
4.67 +http://www.kegel.com/crosstool, and the subversion repository is hosted on
4.68 +google at http://code.google.com/p/crosstool/.
4.69 +
4.70 +I once managed to add support for uClibc-based toolchains, but it did not make
4.71 +into mainline, mostly because I didn't have time to port the patch forward to
4.72 +the new versions, due in part to the big effort it was taking.
4.73 +
4.74 +So I decided to clean up crosstool in the state it was, re-order the things
4.75 +in place, add appropriate support for what I needed, that is uClibc support
4.76 +and a menu-driven configuration, named the new implementation crosstool-NG,
4.77 +(standing for crosstool Next Generation, as many other comunity projects do,
4.78 +and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
4.79 +made it available to the community, in case it was of interest to any one.
4.80 +
4.81 +
4.82 +Referring to crosstool-NG |
4.83 +--------------------------+
4.84 +
4.85 +The long name of the project is crosstool-NG:
4.86 + * no leading uppercase (except as first word in a sentence)
4.87 + * crosstool and NG separated with a hyphen (dash)
4.88 + * NG in uppercase
4.89 +
4.90 +Crosstool-NG can also be referred to by its short name CT-NG:
4.91 + * all in uppercase
4.92 + * CT and NG separated with a hyphen (dash)
4.93 +
4.94 +The long name is preferred over the short name, except in mail subjects, where
4.95 +the short name is a better fit.
4.96 +
4.97 +When referring to a specific version of crosstool-NG, append the version number
4.98 +either as:
4.99 + * crosstool-NG X.Y.Z
4.100 + - the long name, a space, and the version string
4.101 + * crosstool-ng-X.Y.Z
4.102 + - the long name in lowercase, a hyphen (dash), and the version string
4.103 + - this is used to name the release tarballs
4.104 + * crosstool-ng-X.Y.Z+hg_id
4.105 + - the long name in lowercase, a hyphen, the version string, and the Hg id
4.106 + (as returned by: ct-ng version)
4.107 + - this is used to differentiate between releases and snapshots
4.108 +
4.109 +The frontend to crosstool-NG is the command ct-ng:
4.110 + * all in lowercase
4.111 + * ct and ng separated by a hyphen (dash)
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/2 - Installing crosstool-NG.txt Sat Aug 14 16:37:11 2010 +0200
5.3 @@ -0,0 +1,93 @@
5.4 +File.........: 2 - Installing crosstool-NG.txt
5.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
5.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
5.7 +
5.8 +
5.9 +Installing crosstool-NG /
5.10 +________________________/
5.11 +
5.12 +
5.13 +There are two ways you can use crosstool-NG:
5.14 + - build and install it, then get rid of the sources like you'd do for most
5.15 + programs,
5.16 + - or only build it and run from the source directory.
5.17 +
5.18 +The former should be used if you got crosstool-NG from a packaged tarball, see
5.19 +"Install method", below, while the latter is most useful for developpers that
5.20 +use a clone of the repository, and want to submit patches, see "The Hacker's
5.21 +way", below.
5.22 +
5.23 +
5.24 +Install method |
5.25 +---------------+
5.26 +
5.27 +If you go for the install, then you just follow the classical, but yet easy
5.28 +./configure way:
5.29 + ./configure --prefix=/some/place
5.30 + make
5.31 + make install
5.32 + export PATH="${PATH}:/some/place/bin"
5.33 +
5.34 +You can then get rid of crosstool-NG source. Next create a directory to serve
5.35 +as a working place, cd in there and run:
5.36 + ct-ng help
5.37 +
5.38 +See below for complete usage.
5.39 +
5.40 +
5.41 +The Hacker's way |
5.42 +-----------------+
5.43 +
5.44 +If you go the hacker's way, then the usage is a bit different, although very
5.45 +simple:
5.46 + ./configure --local
5.47 + make
5.48 +
5.49 +Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
5.50 +Stay in the directory holding the sources, and run:
5.51 + ./ct-ng help
5.52 +
5.53 +See below for complete usage.
5.54 +
5.55 +Now, provided you used a clone of the repository, you can send me your changes.
5.56 +See the section titled CONTRIBUTING, below, for how to submit changees.
5.57 +
5.58 +
5.59 +Preparing for packaging |
5.60 +------------------------+
5.61 +
5.62 +If you plan on packaging crosstool-NG, you surely don't want to install it
5.63 +in your root file system. The install procedure of crosstool-NG honors the
5.64 +DESTDIR variable:
5.65 +
5.66 + ./configure --prefix=/usr
5.67 + make
5.68 + make DESTDIR=/packaging/place install
5.69 +
5.70 +
5.71 +Shell completion |
5.72 +-----------------+
5.73 +
5.74 +crosstool-NG comes with a shell script fragment that defines bash-compatible
5.75 +completion. That shell fragment is currently not installed automatically, but
5.76 +this is planned.
5.77 +
5.78 +To install the shell script fragment, you have two options:
5.79 + - install system-wide, most probably by copying ct-ng.comp into
5.80 + /etc/bash_completion.d/
5.81 + - install for a single user, by copying ct-ng.comp into ${HOME}/ and
5.82 + sourcing this file from your ${HOME}/.bashrc
5.83 +
5.84 +
5.85 +Contributed code |
5.86 +-----------------+
5.87 +
5.88 +Some people contibuted code that couldn't get merged for various reasons. This
5.89 +code is available as lzma-compressed patches, in the contrib/ sub-directory.
5.90 +These patches are to be applied to the source of crosstool-NG, prior to
5.91 +installing, using something like the following:
5.92 + lzcat contrib/foobar.patch.lzma |patch -p1
5.93 +
5.94 +There is no guarantee that a particuliar contribution applies to the current
5.95 +version of crosstool-ng, or that it will work at all. Use contributions at
5.96 +your own risk.
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/3 - Configuring a toolchain.txt Sat Aug 14 16:37:11 2010 +0200
6.3 @@ -0,0 +1,133 @@
6.4 +File.........: 3 - Configuring a toolchain.txt
6.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
6.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
6.7 +
6.8 +
6.9 +
6.10 +Configuring crosstool-NG /
6.11 +_________________________/
6.12 +
6.13 +
6.14 +crosstool-NG is configured with a configurator presenting a menu-stuctured set
6.15 +of options. These options let you specify the way you want your toolchain
6.16 +built, where you want it installed, what architecture and specific processor it
6.17 +will support, the version of the components you want to use, etc... The
6.18 +value for those options are then stored in a configuration file.
6.19 +
6.20 +The configurator works the same way you configure your Linux kernel. It is
6.21 +assumed you now how to handle this.
6.22 +
6.23 +To enter the menu, type:
6.24 + ct-ng menuconfig
6.25 +
6.26 +Almost every config item has a help entry. Read them carefully.
6.27 +
6.28 +String and number options can refer to environment variables. In such a case,
6.29 +you must use the shell syntax: ${VAR}. You shall neither single- nor double-
6.30 +quote the string/number options.
6.31 +
6.32 +There are three environment variables that are computed by crosstool-NG, and
6.33 +that you can use:
6.34 +
6.35 +CT_TARGET:
6.36 + It represents the target tuple you are building for. You can use it for
6.37 + example in the installation/prefix directory, such as:
6.38 + /opt/x-tools/${CT_TARGET}
6.39 +
6.40 +CT_TOP_DIR:
6.41 + The top directory where crosstool-NG is running. You shouldn't need it in
6.42 + most cases. There is one case where you may need it: if you have local
6.43 + patches and you store them in your running directory, you can refer to them
6.44 + by using CT_TOP_DIR, such as:
6.45 + ${CT_TOP_DIR}/patches.myproject
6.46 +
6.47 +CT_VERSION:
6.48 + The version of crosstool-NG you are using. Not much use for you, but it's
6.49 + there if you need it.
6.50 +
6.51 +
6.52 +Interesting config options |
6.53 +---------------------------+
6.54 +
6.55 +CT_LOCAL_TARBALLS_DIR:
6.56 + If you already have some tarballs in a direcotry, enter it here. That will
6.57 + speed up the retrieving phase, where crosstool-NG would otherwise download
6.58 + those tarballs.
6.59 +
6.60 +CT_PREFIX_DIR:
6.61 + This is where the toolchain will be installed in (and for now, where it
6.62 + will run from). Common use is to add the target tuple in the directory
6.63 + path, such as (see above):
6.64 + /opt/x-tools/${CT_TARGET}
6.65 +
6.66 +CT_TARGET_VENDOR:
6.67 + An identifier for your toolchain, will take place in the vendor part of the
6.68 + target tuple. It shall *not* contain spaces or dashes. Usually, keep it
6.69 + to a one-word string, or use underscores to separate words if you need.
6.70 + Avoid dots, commas, and special characters.
6.71 +
6.72 +CT_TARGET_ALIAS:
6.73 + An alias for the toolchian. It will be used as a prefix to the toolchain
6.74 + tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
6.75 +
6.76 +Also, if you think you don't see enough versions, you can try to enable one of
6.77 +those:
6.78 +
6.79 +CT_OBSOLETE:
6.80 + Show obsolete versions or tools. Most of the time, you don't want to base
6.81 + your toolchain on too old a version (of gcc, for example). But at times, it
6.82 + can come handy to use such an old version for regression tests. Those old
6.83 + versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
6.84 + marked because maintaining support for those in crosstool-NG would be too
6.85 + costly, time-wise, and time is dear.
6.86 +
6.87 +CT_EXPERIMENTAL:
6.88 + Show experimental versions or tools. Again, you might not want to base your
6.89 + toolchain on too recent tools (eg. gcc) for production. But if you need a
6.90 + feature present only in a recent version, or a new tool, you can find them
6.91 + hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
6.92 + receive thorough testing in crosstool-NG, and/or are not mature enough to
6.93 + be blindly trusted.
6.94 +
6.95 +
6.96 +Re-building an existing toolchain |
6.97 +----------------------------------+
6.98 +
6.99 +If you have an existing toolchain, you can re-use the options used to build it
6.100 +to create a new toolchain. That needs a very little bit of effort on your side
6.101 +but is quite easy. The options to build a toolchain are saved with the
6.102 +toolchain, and you can retrieve this configuration by running:
6.103 + ${CT_TARGET}-ct-ng.config
6.104 +
6.105 +An alternate method is to extract the configuration from a build.log file.
6.106 +This will be necessary if your toolchain was build with crosstool-NG prior
6.107 +to 1.4.0, but can be used with build.log files from any version:
6.108 + ct-ng extractconfig <build.log >.config
6.109 +
6.110 +Or, if your build.log file is compressed (most probably!):
6.111 + bzcat build.log.bz2 |ct-ng extractconfig >.config
6.112 +
6.113 +The above commands will dump the configuration to stdout, so to rebuild a
6.114 +toolchain with this configuration, just redirect the output to the
6.115 +.config file:
6.116 + ${CT_TARGET}-ct-ng.config >.config
6.117 + ct-ng oldconfig
6.118 +
6.119 +Then, you can review and change the configuration by running:
6.120 + ct-ng menuconfig
6.121 +
6.122 +
6.123 +Using as a backend for a build-system |
6.124 +--------------------------------------+
6.125 +
6.126 +Crosstool-NG can be used as a backend for an automated build-system. In this
6.127 +case, some components that are expected to run on the target (eg. the native
6.128 +gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
6.129 +build either, as it is considered the responsibility of the build-system to
6.130 +build its own versions of those tools.
6.131 +
6.132 +If you want to use crosstool-NG as a backend to generate your toolchains for
6.133 +your build-system, you have to set and export this environment variable:
6.134 + CT_IS_A_BACKEND=y
6.135 +
6.136 +(case is not sensitive, you can say Y).
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/docs/4 - Building the toolchain.txt Sat Aug 14 16:37:11 2010 +0200
7.3 @@ -0,0 +1,142 @@
7.4 +File.........: 4 - Building the toolchain.txt
7.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
7.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
7.7 +
7.8 +
7.9 +Building the toolchain /
7.10 +_______________________/
7.11 +
7.12 +
7.13 +To build the toolchain, simply type:
7.14 + ct-ng build
7.15 +
7.16 +This will use the above configuration to retrieve, extract and patch the
7.17 +components, build, install and eventually test your newly built toolchain.
7.18 +
7.19 +You are then free to add the toolchain /bin directory in your PATH to use
7.20 +it at will.
7.21 +
7.22 +In any case, you can get some terse help. Just type:
7.23 + ct-ng help
7.24 +or:
7.25 + man 1 ct-ng
7.26 +
7.27 +
7.28 +Stopping and restarting a build |
7.29 +--------------------------------+
7.30 +
7.31 +If you want to stop the build after a step you are debugging, you can pass the
7.32 +variable STOP to make:
7.33 + ct-ng build STOP=some_step
7.34 +
7.35 +Conversely, if you want to restart a build at a specific step you are
7.36 +debugging, you can pass the RESTART variable to make:
7.37 + ct-ng build RESTART=some_step
7.38 +
7.39 +Alternatively, you can call make with the name of a step to just do that step:
7.40 + ct-ng libc_headers
7.41 +is equivalent to:
7.42 + ct-ng build RESTART=libc_headers STOP=libc_headers
7.43 +
7.44 +The shortcuts +step_name and step_name+ allow to respectively stop or restart
7.45 +at that step. Thus:
7.46 + ct-ng +libc_headers and: ct-ng libc_headers+
7.47 +are equivalent to:
7.48 + ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
7.49 +
7.50 +To obtain the list of acceptable steps, please call:
7.51 + ct-ng list-steps
7.52 +
7.53 +Note that in order to restart a build, you'll have to say 'Y' to the config
7.54 +option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
7.55 +that far.
7.56 +
7.57 +
7.58 +Building all toolchains at once |
7.59 +--------------------------------+
7.60 +
7.61 +You can build all samples; simply call:
7.62 + ct-ng build-all
7.63 +
7.64 +
7.65 +Overriding the number of // jobs |
7.66 +---------------------------------+
7.67 +
7.68 +If you want to override the number of jobs to run in // (the -j option to
7.69 +make), you can either re-enter the menuconfig, or simply add it on the command
7.70 +line, as such:
7.71 + ct-ng build.4
7.72 +
7.73 +which tells crosstool-NG to override the number of // jobs to 4.
7.74 +
7.75 +You can see the actions that support overriding the number of // jobs in
7.76 +the help menu. Those are the ones with [.#] after them (eg. build[.#] or
7.77 +build-all[.#], and so on...).
7.78 +
7.79 +
7.80 +Note on // jobs |
7.81 +----------------+
7.82 +
7.83 +The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
7.84 +in parallel (there is not much to gain). When speaking of // jobs, we are
7.85 +refering to the number of // jobs when making the *components*. That is, we
7.86 +speak of the number of // jobs used to build gcc, glibc, and so on...
7.87 +
7.88 +
7.89 +Tools wrapper |
7.90 +--------------+
7.91 +
7.92 +Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
7.93 +come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
7.94 +dependency on libelf. These are libraries that enable advanced features to
7.95 +gcc. Additionally, some of those libraries can be used by binutils and gdb.
7.96 +Unfortunately, not all systems on which crosstool-NG runs have all of those
7.97 +libraries. And for those that do, the versions of those libraries may be
7.98 +older than the version required by gcc (and binutils and gdb). To date,
7.99 +Debian stable (aka Lenny) is lagging behind on some, and is missing the
7.100 +others.
7.101 +
7.102 +This is why crosstool-NG builds its own set of libraries as part of the
7.103 +toolchain.
7.104 +
7.105 +The companion libraries can be built either as static libraries, or as shared
7.106 +libraries. The default is to build static libraries, and is the safe way.
7.107 +If you decide to use static companion libraries, then you can stop reading
7.108 +this section.
7.109 +
7.110 +But if you prefer to have shared libraries, then read on...
7.111 +
7.112 +Building shared companion libraries poses no problem at build time, as
7.113 +crosstool-NG correctly points gcc (and binutils and gdb) to the correct
7.114 +place where our own version of the libraries are installed. But it poses
7.115 +a problem when gcc et al. are run: the place where the libraries are is most
7.116 +probably not known to the host dynamic linker. Still worse, if the host system
7.117 +has its own versions, then ld.so would load the wrong libraries!
7.118 +
7.119 +So we have to force the dynamic linker to load the correct version. We do this
7.120 +by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
7.121 +to look for shared libraries prior to searching its standard places. But we
7.122 +can't impose that burden on all the system (because it'd be a nightmare to
7.123 +configure, and because two toolchains on the same system may use different
7.124 +versions of the libraries); so we have to do it on a per-toolchain basis.
7.125 +
7.126 +So we rename all binaries of the toolchain (by adding a dot '.' as their first
7.127 +character), and add a small program, the so-called "tools wrapper", that
7.128 +correctly sets LD_LIBRARY_PATH prior to running the real tool.
7.129 +
7.130 +First, the wrapper was written as a POSIX-compliant shell script. That shell
7.131 +script is very simple, if not trivial, and works great. The only drawback is
7.132 +that it does not work on host systems that lack a shell, for example the
7.133 +MingW32 environment. To solve the issue, the wrapper has been re-written in C,
7.134 +and compiled at build time. This C wrapper is much more complex than the shell
7.135 +script, and although it sems to be working, it's been only lightly tested.
7.136 +Some of the expected short-comings with this C wrapper are;
7.137 + - multi-byte file names may not be handled correctly
7.138 + - it's really big for what it does
7.139 +
7.140 +So, the default wrapper installed with your toolchain is the shell script.
7.141 +If you know that your system is missing a shell, then you shall use the C
7.142 +wrapper (and report back whether it works, or does not work, for you).
7.143 +
7.144 +A final word on the subject: do not build shared libraries. Build them
7.145 +static, and you'll be safe.
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/5 - Using the toolchain.txt Sat Aug 14 16:37:11 2010 +0200
8.3 @@ -0,0 +1,103 @@
8.4 +File.........: 5 - Using the toolchain.txt
8.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
8.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
8.7 +
8.8 +
8.9 +Using the toolchain /
8.10 +____________________/
8.11 +
8.12 +
8.13 +Using the toolchain is as simple as adding the toolchain's bin directory in
8.14 +your PATH, such as:
8.15 + export PATH="${PATH}:/your/toolchain/path/bin"
8.16 +
8.17 +and then using the target tuple to tell the build systems to use your
8.18 +toolchain:
8.19 + ./configure --target=your-target-tuple
8.20 +or
8.21 + make CC=your-target-tuple-gcc
8.22 +or
8.23 + make CROSS_COMPILE=your-target-tuple-
8.24 +and so on...
8.25 +
8.26 +It is strongly advised not to use the toolchain sys-root directory as an
8.27 +install directory for your programs/packages. If you do so, you will not be
8.28 +able to use your toolchain for another project. It is even strongly advised
8.29 +that your toolchain is chmod-ed to read-only once successfully build, so that
8.30 +you don't go polluting your toolchain with your programs/packages' files.
8.31 +
8.32 +Thus, when you build a program/package, install it in a separate directory,
8.33 +eg. /your/root. This directory is the /image/ of what would be in the root file
8.34 +system of your target, and will contain all that your programs/packages have
8.35 +installed.
8.36 +
8.37 +
8.38 +The 'populate' script |
8.39 +----------------------+
8.40 +
8.41 +When your root directory is ready, it is still missing some important bits: the
8.42 +toolchain's libraries. To populate your root directory with those libs, just
8.43 +run:
8.44 + your-target-tuple-populate -s /your/root -d /your/root-populated
8.45 +
8.46 +This will copy /your/root into /your/root-populated, and put the needed and only
8.47 +the needed libraries there. Thus you don't polute /your/root with any cruft that
8.48 +would no longer be needed should you have to remove stuff. /your/root always
8.49 +contains only those things you install in it.
8.50 +
8.51 +You can then use /your/root-populated to build up your file system image, a
8.52 +tarball, or to NFS-mount it from your target, or whatever you need.
8.53 +
8.54 +The populate script accepts the following options:
8.55 +
8.56 + -s src_dir
8.57 + Use 'src_dir' as the un-populated root directory.
8.58 +
8.59 + -d dst_dir
8.60 + Put the populated root directory in 'dst_dir'.
8.61 +
8.62 + -l lib1 [...]
8.63 + Always add specified libraries.
8.64 +
8.65 + -L file
8.66 + Always add libraries listed in 'file'.
8.67 +
8.68 + -f
8.69 + Remove 'dst_dir' if it previously existed; continue even if any library
8.70 + specified with -l or -L is missing.
8.71 +
8.72 + -v
8.73 + Be verbose, and tell what's going on (you can see exactly where libs are
8.74 + coming from).
8.75 +
8.76 + -h
8.77 + Print the help.
8.78 +
8.79 +See 'your-target-tuple-populate -h' for more information on the options.
8.80 +
8.81 +Here is how populate works:
8.82 +
8.83 + 1) performs some sanity checks:
8.84 + - src_dir and dst_dir are specified
8.85 + - src_dir exists
8.86 + - unless forced, dst_dir does not exist
8.87 + - src_dir != dst_dir
8.88 +
8.89 + 2) copy src_dir to dst_dir
8.90 +
8.91 + 3) add forced libraries to dst_dir
8.92 + - build the list from -l and -L options
8.93 + - get forced libraries from the sysroot (see below for heuristics)
8.94 + - abort on the first missing library, unless -f is specified
8.95 +
8.96 + 4) add all missing libraries to dst_dir
8.97 + - scan dst_dir for every ELF files that are 'executable' or
8.98 + 'shared object'
8.99 + - list the "NEEDED Shared library" fields
8.100 + - check if the library is already in dst_dir/lib or dst_dir/usr/lib
8.101 + - if not, get the library from the sysroot
8.102 + - if it's in sysroot/lib, copy it to dst_dir/lib
8.103 + - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
8.104 + - in both cases, use the SONAME of the library to create the file
8.105 + in dst_dir
8.106 + - if it was not found in the sysroot, this is an error.
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/6 - Toolchain types.txt Sat Aug 14 16:37:11 2010 +0200
9.3 @@ -0,0 +1,64 @@
9.4 +File.........: 6 - Toolchain types.txt
9.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
9.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
9.7 +
9.8 +
9.9 +Toolchain types /
9.10 +________________/
9.11 +
9.12 +
9.13 +There are four kinds of toolchains you could encounter.
9.14 +
9.15 +First off, you must understand the following: when it comes to compilers there
9.16 +are up to four machines involved:
9.17 + 1) the machine configuring the toolchain components: the config machine
9.18 + 2) the machine building the toolchain components: the build machine
9.19 + 3) the machine running the toolchain: the host machine
9.20 + 4) the machine the toolchain is generating code for: the target machine
9.21 +
9.22 +We can most of the time assume that the config machine and the build machine
9.23 +are the same. Most of the time, this will be true. The only time it isn't
9.24 +is if you're using distributed compilation (such as distcc). Let's forget
9.25 +this for the sake of simplicity.
9.26 +
9.27 +So we're left with three machines:
9.28 + - build
9.29 + - host
9.30 + - target
9.31 +
9.32 +Any toolchain will involve those three machines. You can be as pretty sure of
9.33 +this as "2 and 2 are 4". Here is how they come into play:
9.34 +
9.35 +1) build == host == target
9.36 + This is a plain native toolchain, targetting the exact same machine as the
9.37 + one it is built on, and running again on this exact same machine. You have
9.38 + to build such a toolchain when you want to use an updated component, such
9.39 + as a newer gcc for example.
9.40 + crosstool-NG calls it "native".
9.41 +
9.42 +2) build == host != target
9.43 + This is a classic cross-toolchain, which is expected to be run on the same
9.44 + machine it is compiled on, and generate code to run on a second machine,
9.45 + the target.
9.46 + crosstool-NG calls it "cross".
9.47 +
9.48 +3) build != host == target
9.49 + Such a toolchain is also a native toolchain, as it targets the same machine
9.50 + as it runs on. But it is build on another machine. You want such a
9.51 + toolchain when porting to a new architecture, or if the build machine is
9.52 + much faster than the host machine.
9.53 + crosstool-NG calls it "cross-native".
9.54 +
9.55 +4) build != host != target
9.56 + This one is called a canadian-toolchain (*), and is tricky. The three
9.57 + machines in play are different. You might want such a toolchain if you
9.58 + have a fast build machine, but the users will use it on another machine,
9.59 + and will produce code to run on a third machine.
9.60 + crosstool-NG calls it "canadian".
9.61 +
9.62 +crosstool-NG can build all these kinds of toolchains (or is aiming at it,
9.63 +anyway!)
9.64 +
9.65 +(*) The term Canadian Cross came about because at the time that these issues
9.66 + were all being hashed out, Canada had three national political parties.
9.67 + http://en.wikipedia.org/wiki/Cross_compiler
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/docs/7 - Contributing to crosstool-NG.txt Sat Aug 14 16:37:11 2010 +0200
10.3 @@ -0,0 +1,226 @@
10.4 +File.........: 7 - Contributing to crosstool-NG.txt
10.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
10.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
10.7 +
10.8 +
10.9 +Contributing to crosstool-NG /
10.10 +_____________________________/
10.11 +
10.12 +
10.13 +Sending a bug report |
10.14 +---------------------+
10.15 +
10.16 +If you need to send a bug report, please send a mail with subject
10.17 +prefixed with "[CT_NG]" with to following destinations:
10.18 + TO: yann.morin.1998 (at) anciens.enib.fr
10.19 + CC: crossgcc (at) sourceware.org
10.20 +
10.21 +
10.22 +Sending patches |
10.23 +----------------+
10.24 +
10.25 +If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
10.26 +
10.27 +Patches should come with the appropriate SoB line. A SoB line is typically
10.28 +something like:
10.29 + Signed-off-by: John DOE <john.doe@somewhere.net>
10.30 +
10.31 +The SoB line is clearly described in Documentation/SubmittingPatches , section
10.32 +12, of your favourite Linux kernel source tree.
10.33 +
10.34 +
10.35 +How to Use Mercurial |
10.36 +---------------------+
10.37 +
10.38 +For larger or more frequent contributions, mercurial should be used.
10.39 +
10.40 +PREREQUISITES:
10.41 +
10.42 +Configuring Mercurial:
10.43 + You need mercurial with the following extensions:
10.44 + - mq : http://mercurial.selenic.com/wiki/MqExtension
10.45 + - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
10.46 + Usually, these two extensions are already part of the installation package.
10.47 + The mq extension maintains a separate queue of your local changes
10.48 + that you can change at any later time.
10.49 + With the patchbomb extension you can email those patches directly
10.50 + from your local repo.
10.51 +
10.52 + Your configuration file for mercurial, e.g. ~/.hgrc should contain
10.53 + at least the following sections (but have a look at `man hgrc`):
10.54 + # ---
10.55 + [email]
10.56 + # configure sending patches directly via Mercurial
10.57 + from = "Your Name" <your@email.address>
10.58 + # How to send email:
10.59 + method = smtp
10.60 +
10.61 + [smtp]
10.62 + # SMTP configuration (only for method=smtp)
10.63 + host = localhost
10.64 + tls = true
10.65 + username =
10.66 + password =
10.67 +
10.68 + [extensions]
10.69 + # The following lines enable the two extensions:
10.70 + hgext.mq =
10.71 + hgext.patchbomb =
10.72 + # ----
10.73 +
10.74 +Create your local repository as a clone:
10.75 + hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
10.76 +
10.77 +Setting up the mq extension in your local copy:
10.78 + cd crosstool-ng
10.79 + hg qinit
10.80 +
10.81 +
10.82 +CREATING PATCHES:
10.83 +
10.84 +Recording your changes in the patch queue maintained by mq:
10.85 + # First, create a new patch entry in the patch queue:
10.86 + hg qnew -D -U -e short_patch_name1
10.87 + <edit patch description as commit message (see below for an example)>
10.88 +
10.89 + <now edit the ct-ng sources and check them>
10.90 +
10.91 + # if you execute `hg status` here, your modifications of the working
10.92 + # copy should show up.
10.93 +
10.94 + # Now the following command takes your modifications from the working copy
10.95 + # into the patch entry
10.96 + hg qrefresh -D [-e]
10.97 + <reedit patch description [-e] if desired>
10.98 +
10.99 + # Now your changes are recorded, and `hg status` should show a clean
10.100 + # working copy
10.101 +
10.102 +Repeat the above steps for all your modifications.
10.103 +The command `hg qseries` informs you about the content of your patch queue.
10.104 +
10.105 +
10.106 +CONTRIBUTING YOUR PATCHES:
10.107 +
10.108 +Once you are satisfied with your patch series, you can (you should!)
10.109 +contribute them back to upstream.
10.110 +This is easily done using the `hg email` command.
10.111 +
10.112 +`hg email` sends your new changesets to a specified list of recipients,
10.113 +each patch in its own email, all ordered in the way you entered them (oldest
10.114 +first). The command line flag --outgoing selects all changesets that are in
10.115 +your local but not yet in the upstream repository. Here, these are exactly
10.116 +the ones you entered into your local patch queue in the section above, so
10.117 +--outgoing is what you want.
10.118 +
10.119 +Each email gets the subject set to: "[PATCH x of n] <series summary>"
10.120 +where 'x' is the serial number in the email series, and 'n' is the total number
10.121 +of patches in the series. The body of the email is the complete patch, plus
10.122 +a handful of metadata, that helps properly apply the patch, keeping the log
10.123 +message, attribution and date, tracking file changes (move, delete, modes...)
10.124 +
10.125 +`hg email` also threads all outgoing patch emails below an introductory
10.126 +message. You should use the introductory message (command line flag --intro)
10.127 +to describe the scope and motivation for the whole patch series. The subject
10.128 +for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
10.129 +and you get the chance to set the <series summary>.
10.130 +
10.131 +Here is a sample `hg email` complete command line:
10.132 +Note: replace " (at) " with "@"
10.133 +
10.134 + hg email --outgoing --intro \
10.135 + --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
10.136 + --cc 'crossgcc (at) sourceware.org'
10.137 +
10.138 + # It then opens an editor and lets you enter the subject
10.139 + # and the body for the introductory message.
10.140 +
10.141 +Use `hg email` with the additional command line switch -n to
10.142 +first have a look at the email(s) without actually sending them.
10.143 +
10.144 +
10.145 +MAINTAINING YOUR PATCHES:
10.146 +
10.147 +When the patches are refined by discussing them on the mailing list,
10.148 +you may want to finalize and resend them.
10.149 +
10.150 +The mq extension has the idiosyncrasy of imposing a stack onto the queue:
10.151 +You can always reedit/refresh only the patch on top of stack.
10.152 +The queue consists of applied and unapplied patches
10.153 +(if you reached here via the above steps, all of your patches are applied),
10.154 +where the 'stack' consists of the applied patches, and 'top of stack'
10.155 +is the latest applied patch.
10.156 +
10.157 +The following output of `hg qseries` is now used as an example:
10.158 + 0 A short_patch_name1
10.159 + 1 A short_patch_name2
10.160 + 2 A short_patch_name3
10.161 + 3 A short_patch_name4
10.162 +
10.163 +You are now able to edit patch 'short_patch_name4' (which is top of stack):
10.164 + <Edit the sources>
10.165 + # and execute again
10.166 + hg qrefresh -D [-e]
10.167 + <and optionally [-e] reedit the commit message>
10.168 +
10.169 +If you want to edit e.g. patch short_patch_name2, you have to modify
10.170 +mq's stack so this patch gets top of stack.
10.171 +For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
10.172 +
10.173 + hg qgoto short_patch_name2
10.174 + # The patch queue should now look like
10.175 + hg qseries
10.176 + 0 A short_patch_name1
10.177 + 1 A short_patch_name2
10.178 + 2 U short_patch_name3
10.179 + 3 U short_patch_name4
10.180 + # so patch # 1 (short_patch_name2) is top of stack.
10.181 + <now reedit the sources for short_patch_name2>
10.182 + # and execute again
10.183 + hg qrefresh -D [-e]
10.184 + <and optionally [-e] reedit the commit message>
10.185 + # the following command reapplies the now unapplied two patches:
10.186 + hg qpush -a
10.187 + # you can also use `hg qgoto short_patch_name4` to get there again.
10.188 +
10.189 +
10.190 +RESENDING YOUR REEDITED PATCHES:
10.191 +
10.192 +By mailing list policy, please resend your complete patch series.
10.193 +--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
10.194 +
10.195 +
10.196 +SYNCING WITH UPSTREAM AGAIN:
10.197 +
10.198 +You can sync your repo with upstream at any time by executing
10.199 + # first unapply all your patches:
10.200 + hg qpop -a
10.201 + # next fetch new changesets from upstream
10.202 + hg pull
10.203 + # then update your working copy
10.204 + hg up
10.205 + # optionally remove already upstream integrated patches (see below)
10.206 + hg qdelete <short_name_of_already_applied_patch>
10.207 + # and reapply your patches if any non upstream-integrated left (but see below)
10.208 + hg qpush -a
10.209 +
10.210 +Eventually, your patches get included into the upstream repository
10.211 +which you initially cloned.
10.212 +In this case, before executing the hg qpush -a from above
10.213 +you should manually "hg qdelete" the patches that are already integrated upstream.
10.214 +
10.215 +
10.216 +HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
10.217 +
10.218 +Commit messages should look like (without leading pipes):
10.219 + |component: short, one-line description
10.220 + |
10.221 + |optional longer description
10.222 + |on multiple lines if needed
10.223 +
10.224 +Here is an example commit message (see revision a53a5e1d61db):
10.225 + |comp-libs/cloog: fix building
10.226 + |
10.227 + |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
10.228 + |For any later versions, the directory name does have the version, such as
10.229 + |cloog-ppl-0.15.4.
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/docs/8 - Internals.txt Sat Aug 14 16:37:11 2010 +0200
11.3 @@ -0,0 +1,294 @@
11.4 +File.........: 8 - Internals.txt
11.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
11.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
11.7 +
11.8 +
11.9 +Internals /
11.10 +__________/
11.11 +
11.12 +
11.13 +Internally, crosstool-NG is script-based. To ease usage, the frontend is
11.14 +Makefile-based.
11.15 +
11.16 +
11.17 +Makefile front-end |
11.18 +-------------------+
11.19 +
11.20 +The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
11.21 +script with an action will act exactly as if the Makefile was in the current
11.22 +working directory and make was called with the action as rule. Thus:
11.23 + ct-ng menuconfig
11.24 +
11.25 +is equivalent to having the Makefile in CWD, and calling:
11.26 + make menuconfig
11.27 +
11.28 +Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
11.29 +traditional command.
11.30 +
11.31 +ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
11.32 +at configuration time with ./configure.
11.33 +
11.34 +ct-ng also searches for config files, sub-tools, samples, scripts and patches in
11.35 +that library directory.
11.36 +
11.37 +Because of a stupid make behavior/bug I was unable to track down, implicit make
11.38 +rules are disabled: installing with --local would triger those rules, and mconf
11.39 +was unbuildable.
11.40 +
11.41 +
11.42 +Kconfig parser |
11.43 +---------------+
11.44 +
11.45 +The kconfig language is a hacked version, vampirised from the Linux kernel
11.46 +(http://www.kernel.org/), and (heavily) adapted to my needs.
11.47 +
11.48 +The list of the most notable changes (at least the ones I remember) follows:
11.49 +- the CONFIG_ prefix has been replaced with CT_
11.50 +- a leading | in prompts is skipped, and subsequent leading spaces are not
11.51 + trimmed; otherwise leading spaces are silently trimmed
11.52 +- removed the warning about undefined environment variable
11.53 +
11.54 +The kconfig parsers (conf and mconf) are not installed pre-built, but as
11.55 +source files. Thus you can have the directory where crosstool-NG is installed,
11.56 +exported (via NFS or whatever) and have clients with different architectures
11.57 +use the same crosstool-NG installation, and most notably, the same set of
11.58 +patches.
11.59 +
11.60 +
11.61 +Architecture-specific |
11.62 +----------------------+
11.63 +
11.64 +Note: this chapter is not really well written, and might thus be a little bit
11.65 +complex to understand. To get a better grasp of what an architecture is, the
11.66 +reader is kindly encouraged to look at the "arch/" sub-directory, and to the
11.67 +existing architectures to see how things are laid out.
11.68 +
11.69 +An architecture is defined by:
11.70 +
11.71 + - a human-readable name, in lower case letters, with numbers as appropriate.
11.72 + The underscore is allowed; space and special characters are not.
11.73 + Eg.: arm, x86_64
11.74 + - a file in "config/arch/", named after the architecture's name, and suffixed
11.75 + with ".in".
11.76 + Eg.: config/arch/arm.in
11.77 + - a file in "scripts/build/arch/", named after the architecture's name, and
11.78 + suffixed with ".sh".
11.79 + Eg.: scripts/build/arch/arm.sh
11.80 +
11.81 +The architecture's ".in" file API:
11.82 + > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
11.83 + actual architecture name).
11.84 + That config option must have *neither* a type, *nor* a prompt! Also, it can
11.85 + *not* depend on any other config option (EXPERIMENTAL is managed as above).
11.86 + Eg.:
11.87 + config ARCH_arm
11.88 + + mandatory:
11.89 + defines a (terse) help entry for this architecture:
11.90 + Eg.:
11.91 + config ARCH_arm
11.92 + help
11.93 + The ARM architecture.
11.94 + + optional:
11.95 + selects adequate associated config options.
11.96 + Note: 64-bit architectures *shall* select ARCH_64
11.97 + Eg.:
11.98 + config ARCH_arm
11.99 + select ARCH_SUPPORTS_BOTH_ENDIAN
11.100 + select ARCH_DEFAULT_LE
11.101 + help
11.102 + The ARM architecture.
11.103 + Eg.:
11.104 + config ARCH_x86_64
11.105 + select ARCH_64
11.106 + help
11.107 + The x86_64 architecture.
11.108 +
11.109 + > other target-specific options, at your discretion. Note however that to
11.110 + avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
11.111 + where %arch% is again replaced by the actual architecture name.
11.112 + (Note: due to historical reasons, and lack of time to clean up the code,
11.113 + I may have left some config options that do not completely conform to
11.114 + this, as the architecture name was written all upper case. However, the
11.115 + prefix is unique among architectures, and does not cause harm).
11.116 +
11.117 +The architecture's ".sh" file API:
11.118 + > the function "CT_DoArchTupleValues"
11.119 + + parameters: none
11.120 + + environment:
11.121 + - all variables from the ".config" file,
11.122 + - the two variables "target_endian_eb" and "target_endian_el" which are
11.123 + the endianness suffixes
11.124 + + return value: 0 upon success, !0 upon failure
11.125 + + provides:
11.126 + - mandatory
11.127 + - the environment variable CT_TARGET_ARCH
11.128 + - contains:
11.129 + the architecture part of the target tuple.
11.130 + Eg.: "armeb" for big endian ARM
11.131 + "i386" for an i386
11.132 + + provides:
11.133 + - optional
11.134 + - the environment variable CT_TARGET_SYS
11.135 + - contains:
11.136 + the sytem part of the target tuple.
11.137 + Eg.: "gnu" for glibc on most architectures
11.138 + "gnueabi" for glibc on an ARM EABI
11.139 + - defaults to:
11.140 + - for glibc-based toolchain: "gnu"
11.141 + - for uClibc-based toolchain: "uclibc"
11.142 + + provides:
11.143 + - optional
11.144 + - the environment variables to configure the cross-gcc (defaults)
11.145 + - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
11.146 + - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
11.147 + - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
11.148 + - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
11.149 + - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
11.150 + - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
11.151 + + provides:
11.152 + - optional
11.153 + - the environment variables to pass to the cross-gcc to build target binaries (defaults)
11.154 + - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
11.155 + - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
11.156 + - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
11.157 + - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
11.158 + - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
11.159 + - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
11.160 + - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
11.161 + - default to:
11.162 + see above.
11.163 + + provides:
11.164 + - optional
11.165 + - the environement variables to configure the core and final compiler, specific to this architecture:
11.166 + - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
11.167 + - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
11.168 + - default to:
11.169 + - all empty
11.170 + + provides:
11.171 + - optional
11.172 + - the architecture-specific CFLAGS and LDFLAGS:
11.173 + - CT_ARCH_TARGET_CLFAGS
11.174 + - CT_ARCH_TARGET_LDFLAGS
11.175 + - default to:
11.176 + - all empty
11.177 +
11.178 +You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
11.179 +a quite complete example of what an actual architecture description looks like.
11.180 +
11.181 +
11.182 +Kernel specific |
11.183 +----------------+
11.184 +
11.185 +A kernel is defined by:
11.186 +
11.187 + - a human-readable name, in lower case letters, with numbers as appropriate.
11.188 + The underscore is allowed; space and special characters are not (although
11.189 + they are internally replaced with underscores.
11.190 + Eg.: linux, bare-metal
11.191 + - a file in "config/kernel/", named after the kernel name, and suffixed with
11.192 + ".in".
11.193 + Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
11.194 + - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
11.195 + with ".sh".
11.196 + Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
11.197 +
11.198 +The kernel's ".in" file must contain:
11.199 + > an optional lines containing exactly "# EXPERIMENTAL", starting on the
11.200 + first column, and without any following space or other character.
11.201 + If this line is present, then this kernel is considered EXPERIMENTAL,
11.202 + and correct dependency on EXPERIMENTAL will be set.
11.203 +
11.204 + > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
11.205 + replaced with the actual kernel name, with all special characters and
11.206 + spaces replaced by underscores).
11.207 + That config option must have *neither* a type, *nor* a prompt! Also, it can
11.208 + *not* depends on EXPERIMENTAL.
11.209 + Eg.: KERNEL_linux, KERNEL_bare_metal
11.210 + + mandatory:
11.211 + defines a (terse) help entry for this kernel.
11.212 + Eg.:
11.213 + config KERNEL_bare_metal
11.214 + help
11.215 + Build a compiler for use without any kernel.
11.216 + + optional:
11.217 + selects adequate associated config options.
11.218 + Eg.:
11.219 + config KERNEL_bare_metal
11.220 + select BARE_METAL
11.221 + help
11.222 + Build a compiler for use without any kernel.
11.223 +
11.224 + > other kernel specific options, at your discretion. Note however that, to
11.225 + avoid name-clashing, such options should be prefixed with
11.226 + "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
11.227 + the actual kernel name.
11.228 + (Note: due to historical reasons, and lack of time to clean up the code,
11.229 + I may have left some config options that do not completely conform to
11.230 + this, as the kernel name was written all upper case. However, the prefix
11.231 + is unique among kernels, and does not cause harm).
11.232 +
11.233 +The kernel's ".sh" file API:
11.234 + > is a bash script fragment
11.235 +
11.236 + > defines the function CT_DoKernelTupleValues
11.237 + + see the architecture's CT_DoArchTupleValues, except for:
11.238 + + set the environment variable CT_TARGET_KERNEL, the kernel part of the
11.239 + target tuple
11.240 + + return value: ignored
11.241 +
11.242 + > defines the function "do_kernel_get":
11.243 + + parameters: none
11.244 + + environment:
11.245 + - all variables from the ".config" file.
11.246 + + return value: 0 for success, !0 for failure.
11.247 + + behavior: download the kernel's sources, and store the tarball into
11.248 + "${CT_TARBALLS_DIR}". To this end, a functions is available, that
11.249 + abstracts downloading tarballs:
11.250 + - CT_DoGet <tarball_base_name> <URL1 [URL...]>
11.251 + Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
11.252 + Note: retrieving sources from svn, cvs, git and the likes is not supported
11.253 + by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
11.254 + "scripts/build/libc/eglibc.sh"
11.255 +
11.256 + > defines the function "do_kernel_extract":
11.257 + + parameters: none
11.258 + + environment:
11.259 + - all variables from the ".config" file,
11.260 + + return value: 0 for success, !0 for failure.
11.261 + + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
11.262 + required patches. To this end, a function is available, that abstracts
11.263 + extracting tarballs:
11.264 + - CT_ExtractAndPatch <tarball_base_name>
11.265 + Eg.: CT_ExtractAndPatch linux-2.6.26.5
11.266 +
11.267 + > defines the function "do_kernel_headers":
11.268 + + parameters: none
11.269 + + environment:
11.270 + - all variables from the ".config" file,
11.271 + + return value: 0 for success, !0 for failure.
11.272 + + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
11.273 +
11.274 + > defines any kernel-specific helper functions
11.275 + These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
11.276 + where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
11.277 + any name-clashing.
11.278 +
11.279 +You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
11.280 +as an example of what a complex kernel description looks like.
11.281 +
11.282 +
11.283 +Adding a new version of a component |
11.284 +------------------------------------+
11.285 +
11.286 +When a new component, such as the Linux kernel, gcc or any other is released,
11.287 +adding the new version to crosstool-NG is quite easy. There is a script that
11.288 +will do all that for you:
11.289 + scripts/addToolVersion.sh
11.290 +
11.291 +Run it with no option to get some help.
11.292 +
11.293 +
11.294 +Build scripts |
11.295 +--------------+
11.296 +
11.297 +To Be Written later...
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
12.2 +++ b/docs/A - Credits.txt Sat Aug 14 16:37:11 2010 +0200
12.3 @@ -0,0 +1,86 @@
12.4 +File.........: A - Credits.txt
12.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
12.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
12.7 +
12.8 +
12.9 +Credits /
12.10 +________/
12.11 +
12.12 +
12.13 +I would like to thank these fine people for making crosstool-NG possible:
12.14 +
12.15 + Dan KEGEL, the original author of crosstool: http://www.kegel.com/
12.16 + Dan was very helpfull and willing to help when I build my first toolchains.
12.17 + I owe him one. Thank you Dan!
12.18 + Some crosstool-NG scripts have code snippets coming almost as-is from the
12.19 + original work by Dan.
12.20 +
12.21 +And in order of appearance on the crossgcc ML:
12.22 +
12.23 + Allan CLARK for his investigations on building toolchains on MacOS-X.
12.24 + Allan made extensive tests of the first alpha of crosstool-NG on his
12.25 + MacOS-X, and unveiled some bash-2.05 weirdness.
12.26 +
12.27 + Enrico WEIGELT
12.28 + - some improvements to the build procedure
12.29 + - cxa_atexit disabling for C libraries not supporting it (old uClibc)
12.30 + - misc suggestions (restartable build, ...)
12.31 + - get rid of some bashisms in ./configure
12.32 + - contributed OpenRISC or32 support
12.33 +
12.34 + Robert P. J. DAY:
12.35 + - some small improvements to the configurator, misc prompting glitches
12.36 + - 'sanitised' patches for binutils-2.17
12.37 + - patches for glibc-2.5
12.38 + - misc patches, typos and eye candy
12.39 + - too many to list any more!
12.40 +
12.41 + Al Stone:
12.42 + - initial ia64 support
12.43 + - some cosmetics
12.44 +
12.45 + Szilveszter Ordog:
12.46 + - a uClibc floating point fix
12.47 + - initial support for ARM EABI
12.48 +
12.49 + Mark Jonas:
12.50 + - initiated Super-H port
12.51 +
12.52 + Michael Abbott:
12.53 + - make it build with ancient findutils
12.54 +
12.55 + Willy Tarreau:
12.56 + - a patch to glibc to build on 'ancient' shells
12.57 + - reported mis-use of $CT_CC_NATIVE
12.58 +
12.59 + Matthias Kaehlcke:
12.60 + - fix building glibc-2.7 (and 2.6.1) with newer kernels
12.61 +
12.62 + Daniel Dittmann:
12.63 + - PowerPC support
12.64 +
12.65 + Ioannis E. Venetis:
12.66 + - preliminary Alpha support
12.67 + - intense gcc-4.3 brainstorming
12.68 +
12.69 + Thomas Jourdan:
12.70 + - intense gcc-4.3 brainstorming
12.71 + - eglibc support
12.72 +
12.73 + Many others have contributed, either in form of patches, suggestions,
12.74 + comments, or testing... Thank you to all of you!
12.75 +
12.76 +Special dedication to the buildroot people for maintaining a set of patches I
12.77 +happily and shamelessly vampirise from time to time... :-)
12.78 +
12.79 +
12.80 +20100530: Status of this file
12.81 +
12.82 +It's been about a year now that we've moved the repository to Mercurial.
12.83 +The repository now has proper authorship for each changeset, and this is
12.84 +used to build the changelog at each release. This file will probably no
12.85 +longer be updated, and is here to credit people prior to the Mercurial
12.86 +migration, or for people discussing ideas or otherwise helping without
12.87 +code.
12.88 +
12.89 +If you think you deserve being cited in this file, do yell at me! ;-)
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
13.2 +++ b/docs/B - Known issues.txt Sat Aug 14 16:37:11 2010 +0200
13.3 @@ -0,0 +1,148 @@
13.4 +File.........: B - Known issues.txt
13.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
13.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
13.7 +
13.8 +
13.9 +Known issues /
13.10 +_____________/
13.11 +
13.12 +
13.13 +This files lists the known issues encountered while developping crosstool-NG,
13.14 +but that could not be addressed before the release.
13.15 +
13.16 +The file has one section for each known issue, each section containing four
13.17 +sub-sections: Symptoms, Explanations, Fix, and Workaround.
13.18 +
13.19 +Each section is separated from the others with a lines of at least 4 dashes.
13.20 +
13.21 +The following dummy section explains it all.
13.22 +
13.23 + --------------------------------
13.24 + Symptoms:
13.25 + A one-liner of what you would observe.
13.26 +
13.27 + Explanations:
13.28 + An as much as possible in-depth explanations of the context, why it
13.29 + happens, what has been investigated so far, and possible orientations
13.30 + as how to try to solve this (eg. URLs, code snippets...).
13.31 +
13.32 + Fix:
13.33 + What you have to do to fix it, if at all possible.
13.34 + The fact that there is a fix, and yet this is a known issue means that
13.35 + time to incorporate the fix in crosstool-NG was missing, or planned for
13.36 + a future release.
13.37 +
13.38 + Workaround:
13.39 + What you can do to fix it *temporarily*, if at all possible.
13.40 + A workaround is not a real fix, as it can break other parts of
13.41 + crosstool-NG, but at least makes you going in your particular case.
13.42 +
13.43 +So now, on for the real issues...
13.44 +
13.45 +--------------------------------
13.46 +Symptoms:
13.47 + gcc is not found, although I *do* have gcc installed.
13.48 +
13.49 +Explanations:
13.50 + This is an issue on at least RHEL systems, where gcc is a symlink to ccache.
13.51 + Because crosstool-NG create links to gcc for the build and host environment,
13.52 + those symlinks are in fact pointing to ccache, which then doesn't know how
13.53 + to run the compiler.
13.54 +
13.55 + A possible fix could probably set the environment variable CCACHE_CC to the
13.56 + actual compiler used.
13.57 +
13.58 +Fix:
13.59 + None known.
13.60 +
13.61 +Workaround:
13.62 + Uninstall ccache.
13.63 +
13.64 +--------------------------------
13.65 +Symptoms:
13.66 + The extract and/or path steps fail under Cygwin.
13.67 +
13.68 +Explanations:
13.69 + This is not related to crosstool-NG. Mounts under Cygwin are by default not
13.70 + case-sensitive. You have to use so-called "managed" mounts. See:
13.71 + http://cygwin.com/faq.html section 4, question 32.
13.72 +
13.73 +Fix:
13.74 + Use "managed" mounts for the directories where you build *and* install your
13.75 + toolchains.
13.76 +
13.77 +Workaround:
13.78 + None.
13.79 +
13.80 +--------------------------------
13.81 +Symptoms:
13.82 + uClibc fails to build under Cygwin.
13.83 +
13.84 +Explanations:
13.85 + With uClibc, it is possible to build a cross-ldd. Unfortunately, it is
13.86 + not (currently) possible to build this cross-ldd under Cygwin.
13.87 +
13.88 +Fix:
13.89 + None so far.
13.90 +
13.91 +Workaround:
13.92 + Disable the cross-ldd build.
13.93 +
13.94 +--------------------------------
13.95 +Symptoms:
13.96 + On 64-bit build systems, the glibc (possibly eglibc too) build fails for
13.97 + 64-bit targets, because it can not find libgcc.
13.98 +
13.99 +Explanations:
13.100 + This issue has been observed when the companion libraries are built
13.101 + statically. For an unknown reason, in this case, the libgcc built by the
13.102 + core gcc is not located in the same place it is located when building
13.103 + with shared companion libraries.
13.104 +
13.105 +Fix:
13.106 + None so far.
13.107 +
13.108 +Workaround:
13.109 + Build shared companion libraries.
13.110 +
13.111 +--------------------------------
13.112 +Symptoms:
13.113 + While building the final gcc, I get an error message that ends with:
13.114 + libtool.m4: error: problem compiling FC test program
13.115 +
13.116 +Explanations:
13.117 + The gcc build procedure tries to run a Fortran test to see if it has a
13.118 + working native fortran compiler installed on the build machine, and it
13.119 + can't find one. A native Fortran compiler is needed (seems to be neede)
13.120 + to build the Fortran frontend of the cross-compiler.
13.121 + Even if you don't want to build the Fortran frontend, gcc tries to see
13.122 + if it has one, but fails. This is no problem, as the Fortran frontend
13.123 + will not be built. There is nothing to be worry about (unless you do
13.124 + want to build the Fortran frontend, of course).
13.125 +
13.126 +Fix:
13.127 + None so far. It's a spurious error, so there will probably never be
13.128 + a fix for this issue.
13.129 +
13.130 +Workaround:
13.131 + None needed, it's a spurious error.
13.132 +
13.133 +--------------------------------
13.134 +Symptoms:
13.135 + gcc barfs because it is "unable to detect the exception model".
13.136 +
13.137 +Explanations:
13.138 + On some architectures, proper stack unwinding (C++) requires that
13.139 + setjmp/longjmp (sjlj) be used, while on other architectures do not
13.140 + need sjlj. On some architectures, gcc is unable to determine whether
13.141 + sjlj are needed or not.
13.142 +
13.143 +Fix:
13.144 + None so far.
13.145 +
13.146 +Workaround:
13.147 + Trying setting use of sjlj to either 'Y' or 'N' (instead of the
13.148 + default 'M') in the menuconfig, option CT_CC_GCC_SJLJ_EXCEPTIONS
13.149 + labelled "Use sjlj for exceptions".
13.150 +
13.151 +--------------------------------
14.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
14.2 +++ b/docs/C - Misc. tutorials.txt Sat Aug 14 16:37:11 2010 +0200
14.3 @@ -0,0 +1,93 @@
14.4 +File.........: C - Misc. tutorials.txt
14.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
14.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
14.7 +
14.8 +
14.9 +Misc. tutorials /
14.10 +________________/
14.11 +
14.12 +
14.13 +Using crosstool-NG on FreeBSD (and other *BSD) |
14.14 +-----------------------------------------------+
14.15 +
14.16 +Contributed by: Titus von Boxberg
14.17 +
14.18 +Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.
14.19 +
14.20 +0) Tested on FreeBSD 8.0
14.21 +
14.22 +1) Install (at least) the following ports
14.23 + archivers/lzma
14.24 + textproc/gsed
14.25 + devel/gmake
14.26 + devel/patch
14.27 + shells/bash
14.28 + devel/bison
14.29 + lang/gawk
14.30 + devel/automake110
14.31 + ftp/wget
14.32 +
14.33 + Of course, you should have /usr/local/bin in your PATH.
14.34 +
14.35 +2) run ct-ng's configure with the following tool configuration:
14.36 + ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
14.37 + --with-patch=/usr/local/bin/gpatch
14.38 + [...other configure parameters as you like...]
14.39 +
14.40 +3) proceed as described in general documentation
14.41 + but use gmake instead of make
14.42 +
14.43 +
14.44 +Using crosstool-NG on MacOS-X |
14.45 +------------------------------+
14.46 +
14.47 +Contributed by: Titus von Boxberg
14.48 +
14.49 +Prerequisites and instructions for using crosstool-NG for building a cross
14.50 +toolchain on MacOS as host.
14.51 +
14.52 +0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or
14.53 + Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed
14.54 + via macports
14.55 +
14.56 +1) You have to use a case sensitive file system for ct-ng's build and target
14.57 + directories. Use a disk or disk image with a case sensitive fs that you
14.58 + mount somewhere.
14.59 +
14.60 +2) Install macports (or similar easy means of installing 3rd party software),
14.61 + make sure that macport's bin dir is in your PATH.
14.62 + Furtheron assuming it is /opt/local/bin.
14.63 +
14.64 +3) Install (at least) the following macports
14.65 + ncurses
14.66 + lzmautils
14.67 + libtool
14.68 + binutils
14.69 + gsed
14.70 + gawk
14.71 + gcc43 (only necessary for Leopard OSX 10.5)
14.72 +
14.73 + On Leopard, make sure that the macport's gcc is called with the default
14.74 + commands (gcc, g++,...), e.g. via macport gcc_select
14.75 +
14.76 +4) run ct-ng's configure with the following tool configuration
14.77 + (assuming you have installed the tools via macports in /opt/local):
14.78 + ./configure --with-sed=/opt/local/bin/gsed \
14.79 + --with-libtool=/opt/local/bin/glibtool \
14.80 + --with-objcopy=/opt/local/bin/gobjcopy \
14.81 + --with-objdump=/opt/local/bin/gobjdump \
14.82 + --with-readelf=/opt/local/bin/greadelf \
14.83 + [...other configure parameters as you like...]
14.84 +
14.85 +5) proceed as described in standard documentation
14.86 +
14.87 +-----
14.88 +
14.89 +HINTS:
14.90 +- Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured
14.91 + under MacOS: It does not include lib%.dylib.
14.92 + This affects build of (at least) gdb-7.1
14.93 + Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment
14.94 + before executing ct-ng build.
14.95 + See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
14.96 + as an explanation.
15.1 --- a/docs/CREDITS Tue Aug 10 13:25:52 2010 +0200
15.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
15.3 @@ -1,77 +0,0 @@
15.4 -I would like to thank these fine people for making crosstool-NG possible:
15.5 -
15.6 - Dan KEGEL, the original author of crosstool: http://www.kegel.com/
15.7 - Dan was very helpfull and willing to help when I build my first toolchains.
15.8 - I owe him one. Thank you Dan!
15.9 - Some crosstool-NG scripts have code snippets coming almost as-is from the
15.10 - original work by Dan.
15.11 -
15.12 -And in order of appearance on the crossgcc ML:
15.13 -
15.14 - Allan CLARK for his investigations on building toolchains on MacOS-X.
15.15 - Allan made extensive tests of the first alpha of crosstool-NG on his
15.16 - MacOS-X, and unveiled some bash-2.05 weirdness.
15.17 -
15.18 - Enrico WEIGELT
15.19 - - some improvements to the build procedure
15.20 - - cxa_atexit disabling for C libraries not supporting it (old uClibc)
15.21 - - misc suggestions (restartable build, ...)
15.22 - - get rid of some bashisms in ./configure
15.23 - - contributed OpenRISC or32 support
15.24 -
15.25 - Robert P. J. DAY:
15.26 - - some small improvements to the configurator, misc prompting glitches
15.27 - - 'sanitised' patches for binutils-2.17
15.28 - - patches for glibc-2.5
15.29 - - misc patches, typos and eye candy
15.30 - - too many to list any more!
15.31 -
15.32 - Al Stone:
15.33 - - initial ia64 support
15.34 - - some cosmetics
15.35 -
15.36 - Szilveszter Ordog:
15.37 - - a uClibc floating point fix
15.38 - - initial support for ARM EABI
15.39 -
15.40 - Mark Jonas:
15.41 - - initiated Super-H port
15.42 -
15.43 - Michael Abbott:
15.44 - - make it build with ancient findutils
15.45 -
15.46 - Willy Tarreau:
15.47 - - a patch to glibc to build on 'ancient' shells
15.48 - - reported mis-use of $CT_CC_NATIVE
15.49 -
15.50 - Matthias Kaehlcke:
15.51 - - fix building glibc-2.7 (and 2.6.1) with newer kernels
15.52 -
15.53 - Daniel Dittmann:
15.54 - - PowerPC support
15.55 -
15.56 - Ioannis E. Venetis:
15.57 - - preliminary Alpha support
15.58 - - intense gcc-4.3 brainstorming
15.59 -
15.60 - Thomas Jourdan:
15.61 - - intense gcc-4.3 brainstorming
15.62 - - eglibc support
15.63 -
15.64 - Many others have contributed, either in form of patches, suggestions,
15.65 - comments, or testing... Thank you to all of you!
15.66 -
15.67 -Special dedication to the buildroot people for maintaining a set of patches I
15.68 -happily and shamelessly vampirise from time to time... :-)
15.69 -
15.70 -
15.71 -20100530: Status of this file
15.72 -
15.73 -It's been about a year now that we've moved the repository to Mercurial.
15.74 -The repository now has proper authorship for each changeset, and this is
15.75 -used to build the changelog at each release. This file will probably no
15.76 -longer be updated, and is here to credit people prior to the Mercurial
15.77 -migration, or for people discussing ideas or otherwise helping without
15.78 -code.
15.79 -
15.80 -If you think you deserve being cited in this file, do yell at me! ;-)
16.1 --- a/docs/README.freebsd.txt Tue Aug 10 13:25:52 2010 +0200
16.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
16.3 @@ -1,26 +0,0 @@
16.4 -22 May 2010 - Titus von Boxberg
16.5 -
16.6 -Prerequisites and instructions for using ct-ng for building a cross toolchain on FreeBSD as host.
16.7 -
16.8 -0) Tested on FreeBSD 8.0
16.9 -
16.10 -1) Install (at least) the following ports
16.11 - archivers/lzma
16.12 - textproc/gsed
16.13 - devel/gmake
16.14 - devel/patch
16.15 - shells/bash
16.16 - devel/bison
16.17 - lang/gawk
16.18 - devel/automake110
16.19 - ftp/wget
16.20 -
16.21 - Of course, you should have /usr/local/bin in your PATH.
16.22 -
16.23 -2) run ct-ng's configure with the following tool configuration:
16.24 - ./configure --with-sed=/usr/local/bin/gsed --with-make=/usr/local/bin/gmake \
16.25 - --with-patch=/usr/local/bin/gpatch
16.26 - [...other configure parameters as you like...]
16.27 -
16.28 -3) proceed as described in general documentation
16.29 - but use gmake instead of make
17.1 --- a/docs/README.macos.txt Tue Aug 10 13:25:52 2010 +0200
17.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
17.3 @@ -1,50 +0,0 @@
17.4 -22 May 2010 - Titus
17.5 -
17.6 -Prerequisites and instructions for using crosstool-NG for building a cross
17.7 -toolchain on MacOS as host.
17.8 -
17.9 -0) Mac OS Snow Leopard, with Developer Tools 3.2 installed, or
17.10 - Mac OS Leopard, with Developer Tools & newer gcc (>= 4.3) installed
17.11 - via macports
17.12 -
17.13 -1) You have to use a case sensitive file system for ct-ng's build and target
17.14 - directories. Use a disk or disk image with a case sensitive fs that you
17.15 - mount somewhere.
17.16 -
17.17 -2) Install macports (or similar easy means of installing 3rd party software),
17.18 - make sure that macport's bin dir is in your PATH.
17.19 - Furtheron assuming it is /opt/local/bin.
17.20 -
17.21 -3) Install (at least) the following macports
17.22 - ncurses
17.23 - lzmautils
17.24 - libtool
17.25 - binutils
17.26 - gsed
17.27 - gawk
17.28 - gcc43 (only necessary for Leopard OSX 10.5)
17.29 -
17.30 - On Leopard, make sure that the macport's gcc is called with the default
17.31 - commands (gcc, g++,...), e.g. via macport gcc_select
17.32 -
17.33 -4) run ct-ng's configure with the following tool configuration
17.34 - (assuming you have installed the tools via macports in /opt/local):
17.35 - ./configure --with-sed=/opt/local/bin/gsed \
17.36 - --with-libtool=/opt/local/bin/glibtool \
17.37 - --with-objcopy=/opt/local/bin/gobjcopy \
17.38 - --with-objdump=/opt/local/bin/gobjdump \
17.39 - --with-readelf=/opt/local/bin/greadelf \
17.40 - [...other configure parameters as you like...]
17.41 -
17.42 -5) proceed as described in standard documentation
17.43 -
17.44 ------
17.45 -
17.46 -HINTS:
17.47 -- Apparently, GNU make's builtin variable .LIBPATTERNS is misconfigured
17.48 - under MacOS: It does not include lib%.dylib.
17.49 - This affects build of (at least) gdb-7.1
17.50 - Put 'lib%.a lib%.so lib%.dylib' as .LIBPATTERNS into your environment
17.51 - before executing ct-ng build.
17.52 - See http://www.gnu.org/software/make/manual/html_node/Libraries_002fSearch.html
17.53 - as an explanation.
18.1 --- a/docs/known-issues.txt Tue Aug 10 13:25:52 2010 +0200
18.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
18.3 @@ -1,139 +0,0 @@
18.4 -This files lists the known issues encountered while developping crosstool-NG,
18.5 -but that could not be addressed before the release.
18.6 -
18.7 -The file has one section for each known issue, each section containing four
18.8 -sub-sections: Symptoms, Explanations, Fix, and Workaround.
18.9 -
18.10 -Each section is separated from the others with a lines of at least 4 dashes.
18.11 -
18.12 -The following dummy section explains it all.
18.13 -
18.14 - --------------------------------
18.15 - Symptoms:
18.16 - A one-liner of what you would observe.
18.17 -
18.18 - Explanations:
18.19 - An as much as possible in-depth explanations of the context, why it
18.20 - happens, what has been investigated so far, and possible orientations
18.21 - as how to try to solve this (eg. URLs, code snippets...).
18.22 -
18.23 - Fix:
18.24 - What you have to do to fix it, if at all possible.
18.25 - The fact that there is a fix, and yet this is a known issue means that
18.26 - time to incorporate the fix in crosstool-NG was missing, or planned for
18.27 - a future release.
18.28 -
18.29 - Workaround:
18.30 - What you can do to fix it *temporarily*, if at all possible.
18.31 - A workaround is not a real fix, as it can break other parts of
18.32 - crosstool-NG, but at least makes you going in your particular case.
18.33 -
18.34 -So now, on for the real issues...
18.35 -
18.36 ---------------------------------
18.37 -Symptoms:
18.38 - gcc is not found, although I *do* have gcc installed.
18.39 -
18.40 -Explanations:
18.41 - This is an issue on at least RHEL systems, where gcc is a symlink to ccache.
18.42 - Because crosstool-NG create links to gcc for the build and host environment,
18.43 - those symlinks are in fact pointing to ccache, which then doesn't know how
18.44 - to run the compiler.
18.45 -
18.46 - A possible fix could probably set the environment variable CCACHE_CC to the
18.47 - actual compiler used.
18.48 -
18.49 -Fix:
18.50 - None known.
18.51 -
18.52 -Workaround:
18.53 - Uninstall ccache.
18.54 -
18.55 ---------------------------------
18.56 -Symptoms:
18.57 - The extract and/or path steps fail under Cygwin.
18.58 -
18.59 -Explanations:
18.60 - This is not related to crosstool-NG. Mounts under Cygwin are by default not
18.61 - case-sensitive. You have to use so-called "managed" mounts. See:
18.62 - http://cygwin.com/faq.html section 4, question 32.
18.63 -
18.64 -Fix:
18.65 - Use "managed" mounts for the directories where you build *and* install your
18.66 - toolchains.
18.67 -
18.68 -Workaround:
18.69 - None.
18.70 -
18.71 ---------------------------------
18.72 -Symptoms:
18.73 - uClibc fails to build under Cygwin.
18.74 -
18.75 -Explanations:
18.76 - With uClibc, it is possible to build a cross-ldd. Unfortunately, it is
18.77 - not (currently) possible to build this cross-ldd under Cygwin.
18.78 -
18.79 -Fix:
18.80 - None so far.
18.81 -
18.82 -Workaround:
18.83 - Disable the cross-ldd build.
18.84 -
18.85 ---------------------------------
18.86 -Symptoms:
18.87 - On 64-bit build systems, the glibc (possibly eglibc too) build fails for
18.88 - 64-bit targets, because it can not find libgcc.
18.89 -
18.90 -Explanations:
18.91 - This issue has been observed when the companion libraries are built
18.92 - statically. For an unknown reason, in this case, the libgcc built by the
18.93 - core gcc is not located in the same place it is located when building
18.94 - with shared companion libraries.
18.95 -
18.96 -Fix:
18.97 - None so far.
18.98 -
18.99 -Workaround:
18.100 - Build shared companion libraries.
18.101 -
18.102 ---------------------------------
18.103 -Symptoms:
18.104 - While building the final gcc, I get an error message that ends with:
18.105 - libtool.m4: error: problem compiling FC test program
18.106 -
18.107 -Explanations:
18.108 - The gcc build procedure tries to run a Fortran test to see if it has a
18.109 - working native fortran compiler installed on the build machine, and it
18.110 - can't find one. A native Fortran compiler is needed (seems to be neede)
18.111 - to build the Fortran frontend of the cross-compiler.
18.112 - Even if you don't want to build the Fortran frontend, gcc tries to see
18.113 - if it has one, but fails. This is no problem, as the Fortran frontend
18.114 - will not be built. There is nothing to be worry about (unless you do
18.115 - want to build the Fortran frontend, of course).
18.116 -
18.117 -Fix:
18.118 - None so far. It's a spurious error, so there will probably never be
18.119 - a fix for this issue.
18.120 -
18.121 -Workaround:
18.122 - None needed, it's a spurious error.
18.123 -
18.124 ---------------------------------
18.125 -Symptoms:
18.126 - gcc barfs because it is "unable to detect the exception model".
18.127 -
18.128 -Explanations:
18.129 - On some architectures, proper stack unwinding (C++) requires that
18.130 - setjmp/longjmp (sjlj) be used, while on other architectures do not
18.131 - need sjlj. On some architectures, gcc is unable to determine whether
18.132 - sjlj are needed or not.
18.133 -
18.134 -Fix:
18.135 - None so far.
18.136 -
18.137 -Workaround:
18.138 - Trying setting use of sjlj to either 'Y' or 'N' (instead of the
18.139 - default 'M') in the menuconfig, option CT_CC_GCC_SJLJ_EXCEPTIONS
18.140 - labelled "Use sjlj for exceptions".
18.141 -
18.142 ---------------------------------
19.1 --- a/docs/overview.txt Tue Aug 10 13:25:52 2010 +0200
19.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
19.3 @@ -1,1172 +0,0 @@
19.4 -File.........: overview.txt
19.5 -Content......: Overview of how crosstool-NG works.
19.6 -Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
19.7 -License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
19.8 -
19.9 -____________________
19.10 - /
19.11 -Table Of Content /
19.12 -_________________/
19.13 -
19.14 -
19.15 -Introduction
19.16 -History
19.17 -Referring to crosstool-NG
19.18 -Installing crosstool-NG
19.19 - Install method
19.20 - The hacker's way
19.21 - Preparing for packaging
19.22 - Shell completion
19.23 - Contributed code
19.24 -Configuring crosstool-NG
19.25 - Interesting config options
19.26 - Re-building an existing toolchain
19.27 - Using as a backend for a build-system
19.28 -Running crosstool-NG
19.29 - Stopping and restarting a build
19.30 - Testing all toolchains at once
19.31 - Overriding the number of // jobs
19.32 - Note on // jobs
19.33 - Tools wrapper
19.34 -Using the toolchain
19.35 - The 'populate' script
19.36 -Toolchain types
19.37 - Seemingly-native toolchains
19.38 -Contributing
19.39 - Sending a bug report
19.40 - Sending patches
19.41 -Internals
19.42 - Makefile front-end
19.43 - Kconfig parser
19.44 - Architecture-specific
19.45 - Adding a new version of a component
19.46 - Build scripts
19.47 -
19.48 -
19.49 -________________
19.50 - /
19.51 -Introduction /
19.52 -_____________/
19.53 -
19.54 -crosstool-NG aims at building toolchains. Toolchains are an essential component
19.55 -in a software development project. It will compile, assemble and link the code
19.56 -that is being developed. Some pieces of the toolchain will eventually end up
19.57 -in the resulting binary/ies: static libraries are but an example.
19.58 -
19.59 -So, a toolchain is a very sensitive piece of software, as any bug in one of the
19.60 -components, or a poorly configured component, can lead to execution problems,
19.61 -ranging from poor performance, to applications ending unexpectedly, to
19.62 -mis-behaving software (which more than often is hard to detect), to hardware
19.63 -damage, or even to human risks (which is more than regrettable).
19.64 -
19.65 -Toolchains are made of different piece of software, each being quite complex
19.66 -and requiring specially crafted options to build and work seamlessly. This
19.67 -is usually not that easy, even in the not-so-trivial case of native toolchains.
19.68 -The work reaches a higher degree of complexity when it comes to cross-
19.69 -compilation, where it can become quite a nightmare...
19.70 -
19.71 -Some cross-toolchains exist on the internet, and can be used for general
19.72 -development, but they have a number of limitations:
19.73 - - they can be general purpose, in that they are configured for the majority:
19.74 - no optimisation for your specific target,
19.75 - - they can be prepared for a specific target and thus are not easy to use,
19.76 - nor optimised for, or even supporting your target,
19.77 - - they often are using aging components (compiler, C library, etc...) not
19.78 - supporting special features of your shiny new processor;
19.79 -On the other side, these toolchain offer some advantages:
19.80 - - they are ready to use and quite easy to install and setup,
19.81 - - they are proven if used by a wide community.
19.82 -
19.83 -But once you want to get all the juice out of your specific hardware, you will
19.84 -want to build your own toolchain. This is where crosstool-NG comes into play.
19.85 -
19.86 -There are also a number of tools that build toolchains for specific needs,
19.87 -which are not really scalable. Examples are:
19.88 - - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
19.89 - systems, hence the name. But once you have your toolchain with buildroot,
19.90 - part of it is installed in the root-to-be, so if you want to build a whole
19.91 - new root, you either have to save the existing one as a template and
19.92 - restore it later, or restart again from scratch. This is not convenient,
19.93 - - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
19.94 - similar to buildroot,
19.95 - - other projects (openembedded.org for example), which are again used to
19.96 - build root file systems.
19.97 -
19.98 -crosstool-NG is really targeted at building toolchains, and only toolchains.
19.99 -It is then up to you to use it the way you want.
19.100 -
19.101 -
19.102 -___________
19.103 - /
19.104 -History /
19.105 -________/
19.106 -
19.107 -crosstool was first 'conceived' by Dan Kegel, who offered it to the community
19.108 -as a set of scripts, a repository of patches, and some pre-configured, general
19.109 -purpose setup files to be used to configure crosstool. This is available at
19.110 -http://www.kegel.com/crosstool, and the subversion repository is hosted on
19.111 -google at http://code.google.com/p/crosstool/.
19.112 -
19.113 -I once managed to add support for uClibc-based toolchains, but it did not make
19.114 -into mainline, mostly because I didn't have time to port the patch forward to
19.115 -the new versions, due in part to the big effort it was taking.
19.116 -
19.117 -So I decided to clean up crosstool in the state it was, re-order the things
19.118 -in place, add appropriate support for what I needed, that is uClibc support
19.119 -and a menu-driven configuration, named the new implementation crosstool-NG,
19.120 -(standing for crosstool Next Generation, as many other comunity projects do,
19.121 -and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
19.122 -made it available to the community, in case it was of interest to any one.
19.123 -
19.124 -
19.125 -_____________________________
19.126 - /
19.127 -Referring to crosstool-NG /
19.128 -__________________________/
19.129 -
19.130 -
19.131 -The long name of the project is crosstool-NG:
19.132 - * no leading uppercase (except as first word in a sentence)
19.133 - * crosstool and NG separated with a hyphen (dash)
19.134 - * NG in uppercase
19.135 -
19.136 -Crosstool-NG can also be referred to by its short name CT-NG:
19.137 - * all in uppercase
19.138 - * CT and NG separated with a hyphen (dash)
19.139 -
19.140 -The long name is preferred over the short name, except in mail subjects, where
19.141 -the short name is a better fit.
19.142 -
19.143 -When referring to a specific version of crosstool-NG, append the version number
19.144 -either as:
19.145 - * crosstool-NG X.Y.Z
19.146 - - the long name, a space, and the version string
19.147 - * crosstool-ng-X.Y.Z
19.148 - - the long name in lowercase, a hyphen (dash), and the version string
19.149 - - this is used to name the release tarballs
19.150 - * crosstool-ng-X.Y.Z+hg_id
19.151 - - the long name in lowercase, a hyphen, the version string, and the Hg id
19.152 - (as returned by: ct-ng version)
19.153 - - this is used to differentiate between releases and snapshots
19.154 -
19.155 -The frontend to crosstool-NG is the command ct-ng:
19.156 - * all in lowercase
19.157 - * ct and ng separated by a hyphen (dash)
19.158 -
19.159 -
19.160 -___________________________
19.161 - /
19.162 -Installing crosstool-NG /
19.163 -________________________/
19.164 -
19.165 -There are two ways you can use crosstool-NG:
19.166 - - build and install it, then get rid of the sources like you'd do for most
19.167 - programs,
19.168 - - or only build it and run from the source directory.
19.169 -
19.170 -The former should be used if you got crosstool-NG from a packaged tarball, see
19.171 -"Install method", below, while the latter is most useful for developpers that
19.172 -use a clone of the repository, and want to submit patches, see "The Hacker's
19.173 -way", below.
19.174 -
19.175 -Install method |
19.176 ----------------+
19.177 -
19.178 -If you go for the install, then you just follow the classical, but yet easy
19.179 -./configure way:
19.180 - ./configure --prefix=/some/place
19.181 - make
19.182 - make install
19.183 - export PATH="${PATH}:/some/place/bin"
19.184 -
19.185 -You can then get rid of crosstool-NG source. Next create a directory to serve
19.186 -as a working place, cd in there and run:
19.187 - ct-ng help
19.188 -
19.189 -See below for complete usage.
19.190 -
19.191 -The Hacker's way |
19.192 ------------------+
19.193 -
19.194 -If you go the hacker's way, then the usage is a bit different, although very
19.195 -simple:
19.196 - ./configure --local
19.197 - make
19.198 -
19.199 -Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
19.200 -Stay in the directory holding the sources, and run:
19.201 - ./ct-ng help
19.202 -
19.203 -See below for complete usage.
19.204 -
19.205 -Now, provided you used a clone of the repository, you can send me your changes.
19.206 -See the section titled CONTRIBUTING, below, for how to submit changees.
19.207 -
19.208 -Preparing for packaging |
19.209 -------------------------+
19.210 -
19.211 -If you plan on packaging crosstool-NG, you surely don't want to install it
19.212 -in your root file system. The install procedure of crosstool-NG honors the
19.213 -DESTDIR variable:
19.214 -
19.215 - ./configure --prefix=/usr
19.216 - make
19.217 - make DESTDIR=/packaging/place install
19.218 -
19.219 -Shell completion |
19.220 ------------------+
19.221 -
19.222 -crosstool-NG comes with a shell script fragment that defines bash-compatible
19.223 -completion. That shell fragment is currently not installed automatically, but
19.224 -this is planned.
19.225 -
19.226 -To install the shell script fragment, you have two options:
19.227 - - install system-wide, most probably by copying ct-ng.comp into
19.228 - /etc/bash_completion.d/
19.229 - - install for a single user, by copying ct-ng.comp into ${HOME}/ and
19.230 - sourcing this file from your ${HOME}/.bashrc
19.231 -
19.232 -Contributed code |
19.233 ------------------+
19.234 -
19.235 -Some people contibuted code that couldn't get merged for various reasons. This
19.236 -code is available as lzma-compressed patches, in the contrib/ sub-directory.
19.237 -These patches are to be applied to the source of crosstool-NG, prior to
19.238 -installing, using something like the following:
19.239 - lzcat contrib/foobar.patch.lzma |patch -p1
19.240 -
19.241 -There is no guarantee that a particuliar contribution applies to the current
19.242 -version of crosstool-ng, or that it will work at all. Use contributions at
19.243 -your own risk.
19.244 -
19.245 -
19.246 -____________________________
19.247 - /
19.248 -Configuring crosstool-NG /
19.249 -_________________________/
19.250 -
19.251 -crosstool-NG is configured with a configurator presenting a menu-stuctured set
19.252 -of options. These options let you specify the way you want your toolchain
19.253 -built, where you want it installed, what architecture and specific processor it
19.254 -will support, the version of the components you want to use, etc... The
19.255 -value for those options are then stored in a configuration file.
19.256 -
19.257 -The configurator works the same way you configure your Linux kernel. It is
19.258 -assumed you now how to handle this.
19.259 -
19.260 -To enter the menu, type:
19.261 - ct-ng menuconfig
19.262 -
19.263 -Almost every config item has a help entry. Read them carefully.
19.264 -
19.265 -String and number options can refer to environment variables. In such a case,
19.266 -you must use the shell syntax: ${VAR}. You shall neither single- nor double-
19.267 -quote the string/number options.
19.268 -
19.269 -There are three environment variables that are computed by crosstool-NG, and
19.270 -that you can use:
19.271 -
19.272 -CT_TARGET:
19.273 - It represents the target tuple you are building for. You can use it for
19.274 - example in the installation/prefix directory, such as:
19.275 - /opt/x-tools/${CT_TARGET}
19.276 -
19.277 -CT_TOP_DIR:
19.278 - The top directory where crosstool-NG is running. You shouldn't need it in
19.279 - most cases. There is one case where you may need it: if you have local
19.280 - patches and you store them in your running directory, you can refer to them
19.281 - by using CT_TOP_DIR, such as:
19.282 - ${CT_TOP_DIR}/patches.myproject
19.283 -
19.284 -CT_VERSION:
19.285 - The version of crosstool-NG you are using. Not much use for you, but it's
19.286 - there if you need it.
19.287 -
19.288 -Interesting config options |
19.289 ----------------------------+
19.290 -
19.291 -CT_LOCAL_TARBALLS_DIR:
19.292 - If you already have some tarballs in a direcotry, enter it here. That will
19.293 - speed up the retrieving phase, where crosstool-NG would otherwise download
19.294 - those tarballs.
19.295 -
19.296 -CT_PREFIX_DIR:
19.297 - This is where the toolchain will be installed in (and for now, where it
19.298 - will run from). Common use is to add the target tuple in the directory
19.299 - path, such as (see above):
19.300 - /opt/x-tools/${CT_TARGET}
19.301 -
19.302 -CT_TARGET_VENDOR:
19.303 - An identifier for your toolchain, will take place in the vendor part of the
19.304 - target tuple. It shall *not* contain spaces or dashes. Usually, keep it
19.305 - to a one-word string, or use underscores to separate words if you need.
19.306 - Avoid dots, commas, and special characters.
19.307 -
19.308 -CT_TARGET_ALIAS:
19.309 - An alias for the toolchian. It will be used as a prefix to the toolchain
19.310 - tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
19.311 -
19.312 -Also, if you think you don't see enough versions, you can try to enable one of
19.313 -those:
19.314 -
19.315 -CT_OBSOLETE:
19.316 - Show obsolete versions or tools. Most of the time, you don't want to base
19.317 - your toolchain on too old a version (of gcc, for example). But at times, it
19.318 - can come handy to use such an old version for regression tests. Those old
19.319 - versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
19.320 - marked because maintaining support for those in crosstool-NG would be too
19.321 - costly, time-wise, and time is dear.
19.322 -
19.323 -CT_EXPERIMENTAL:
19.324 - Show experimental versions or tools. Again, you might not want to base your
19.325 - toolchain on too recent tools (eg. gcc) for production. But if you need a
19.326 - feature present only in a recent version, or a new tool, you can find them
19.327 - hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
19.328 - receive thorough testing in crosstool-NG, and/or are not mature enough to
19.329 - be blindly trusted.
19.330 -
19.331 -Re-building an existing toolchain |
19.332 -----------------------------------+
19.333 -
19.334 -If you have an existing toolchain, you can re-use the options used to build it
19.335 -to create a new toolchain. That needs a very little bit of effort on your side
19.336 -but is quite easy. The options to build a toolchain are saved with the
19.337 -toolchain, and you can retrieve this configuration by running:
19.338 - ${CT_TARGET}-ct-ng.config
19.339 -
19.340 -An alternate method is to extract the configuration from a build.log file.
19.341 -This will be necessary if your toolchain was build with crosstool-NG prior
19.342 -to 1.4.0, but can be used with build.log files from any version:
19.343 - ct-ng extractconfig <build.log >.config
19.344 -
19.345 -Or, if your build.log file is compressed (most probably!):
19.346 - bzcat build.log.bz2 |ct-ng extractconfig >.config
19.347 -
19.348 -The above commands will dump the configuration to stdout, so to rebuild a
19.349 -toolchain with this configuration, just redirect the output to the
19.350 -.config file:
19.351 - ${CT_TARGET}-ct-ng.config >.config
19.352 - ct-ng oldconfig
19.353 -
19.354 -Then, you can review and change the configuration by running:
19.355 - ct-ng menuconfig
19.356 -
19.357 -Using as a backend for a build-system |
19.358 ---------------------------------------+
19.359 -
19.360 -Crosstool-NG can be used as a backend for an automated build-system. In this
19.361 -case, some components that are expected to run on the target (eg. the native
19.362 -gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
19.363 -build either, as it is considered the responsibility of the build-system to
19.364 -build its own versions of those tools.
19.365 -
19.366 -If you want to use crosstool-NG as a backend to generate your toolchains for
19.367 -your build-system, you have to set and export this environment variable:
19.368 - CT_IS_A_BACKEND=y
19.369 -
19.370 -(case is not sensitive, you can say Y).
19.371 -
19.372 -
19.373 -________________________
19.374 - /
19.375 -Running crosstool-NG /
19.376 -_____________________/
19.377 -
19.378 -To build the toolchain, simply type:
19.379 - ct-ng build
19.380 -
19.381 -This will use the above configuration to retrieve, extract and patch the
19.382 -components, build, install and eventually test your newly built toolchain.
19.383 -
19.384 -You are then free to add the toolchain /bin directory in your PATH to use
19.385 -it at will.
19.386 -
19.387 -In any case, you can get some terse help. Just type:
19.388 - ct-ng help
19.389 -or:
19.390 - man 1 ct-ng
19.391 -
19.392 -Stopping and restarting a build |
19.393 ---------------------------------+
19.394 -
19.395 -If you want to stop the build after a step you are debugging, you can pass the
19.396 -variable STOP to make:
19.397 - ct-ng build STOP=some_step
19.398 -
19.399 -Conversely, if you want to restart a build at a specific step you are
19.400 -debugging, you can pass the RESTART variable to make:
19.401 - ct-ng build RESTART=some_step
19.402 -
19.403 -Alternatively, you can call make with the name of a step to just do that step:
19.404 - ct-ng libc_headers
19.405 -is equivalent to:
19.406 - ct-ng build RESTART=libc_headers STOP=libc_headers
19.407 -
19.408 -The shortcuts +step_name and step_name+ allow to respectively stop or restart
19.409 -at that step. Thus:
19.410 - ct-ng +libc_headers and: ct-ng libc_headers+
19.411 -are equivalent to:
19.412 - ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
19.413 -
19.414 -To obtain the list of acceptable steps, please call:
19.415 - ct-ng list-steps
19.416 -
19.417 -Note that in order to restart a build, you'll have to say 'Y' to the config
19.418 -option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
19.419 -that far.
19.420 -
19.421 -Building all toolchains at once |
19.422 ---------------------------------+
19.423 -
19.424 -You can build all samples; simply call:
19.425 - ct-ng build-all
19.426 -
19.427 -Overriding the number of // jobs |
19.428 ----------------------------------+
19.429 -
19.430 -If you want to override the number of jobs to run in // (the -j option to
19.431 -make), you can either re-enter the menuconfig, or simply add it on the command
19.432 -line, as such:
19.433 - ct-ng build.4
19.434 -
19.435 -which tells crosstool-NG to override the number of // jobs to 4.
19.436 -
19.437 -You can see the actions that support overriding the number of // jobs in
19.438 -the help menu. Those are the ones with [.#] after them (eg. build[.#] or
19.439 -build-all[.#], and so on...).
19.440 -
19.441 -Note on // jobs |
19.442 -----------------+
19.443 -
19.444 -The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
19.445 -in parallel (there is not much to gain). When speaking of // jobs, we are
19.446 -refering to the number of // jobs when making the *components*. That is, we
19.447 -speak of the number of // jobs used to build gcc, glibc, and so on...
19.448 -
19.449 -Tools wrapper |
19.450 ---------------+
19.451 -
19.452 -Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
19.453 -come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
19.454 -dependency on libelf. These are libraries that enable advanced features to
19.455 -gcc. Additionally, some of those libraries can be used by binutils and gdb.
19.456 -Unfortunately, not all systems on which crosstool-NG runs have all of those
19.457 -libraries. And for those that do, the versions of those libraries may be
19.458 -older than the version required by gcc (and binutils and gdb). To date,
19.459 -Debian stable (aka Lenny) is lagging behind on some, and is missing the
19.460 -others.
19.461 -
19.462 -This is why crosstool-NG builds its own set of libraries as part of the
19.463 -toolchain.
19.464 -
19.465 -The companion libraries can be built either as static libraries, or as shared
19.466 -libraries. The default is to build static libraries, and is the safe way.
19.467 -If you decide to use static companion libraries, then you can stop reading
19.468 -this section.
19.469 -
19.470 -But if you prefer to have shared libraries, then read on...
19.471 -
19.472 -Building shared companion libraries poses no problem at build time, as
19.473 -crosstool-NG correctly points gcc (and binutils and gdb) to the correct
19.474 -place where our own version of the libraries are installed. But it poses
19.475 -a problem when gcc et al. are run: the place where the libraries are is most
19.476 -probably not known to the host dynamic linker. Still worse, if the host system
19.477 -has its own versions, then ld.so would load the wrong libraries!
19.478 -
19.479 -So we have to force the dynamic linker to load the correct version. We do this
19.480 -by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
19.481 -to look for shared libraries prior to searching its standard places. But we
19.482 -can't impose that burden on all the system (because it'd be a nightmare to
19.483 -configure, and because two toolchains on the same system may use different
19.484 -versions of the libraries); so we have to do it on a per-toolchain basis.
19.485 -
19.486 -So we rename all binaries of the toolchain (by adding a dot '.' as their first
19.487 -character), and add a small program, the so-called "tools wrapper", that
19.488 -correctly sets LD_LIBRARY_PATH prior to running the real tool.
19.489 -
19.490 -First, the wrapper was written as a POSIX-compliant shell script. That shell
19.491 -script is very simple, if not trivial, and works great. The only drawback is
19.492 -that it does not work on host systems that lack a shell, for example the
19.493 -MingW32 environment. To solve the issue, the wrapper has been re-written in C,
19.494 -and compiled at build time. This C wrapper is much more complex than the shell
19.495 -script, and although it sems to be working, it's been only lightly tested.
19.496 -Some of the expected short-comings with this C wrapper are;
19.497 - - multi-byte file names may not be handled correctly
19.498 - - it's really big for what it does
19.499 -
19.500 -So, the default wrapper installed with your toolchain is the shell script.
19.501 -If you know that your system is missing a shell, then you shall use the C
19.502 -wrapper (and report back whether it works, or does not work, for you).
19.503 -
19.504 -A final word on the subject: do not build shared libraries. Build them
19.505 -static, and you'll be safe.
19.506 -
19.507 -
19.508 -_______________________
19.509 - /
19.510 -Using the toolchain /
19.511 -____________________/
19.512 -
19.513 -Using the toolchain is as simple as adding the toolchain's bin directory in
19.514 -your PATH, such as:
19.515 - export PATH="${PATH}:/your/toolchain/path/bin"
19.516 -
19.517 -and then using the target tuple to tell the build systems to use your
19.518 -toolchain:
19.519 - ./configure --target=your-target-tuple
19.520 -or
19.521 - make CC=your-target-tuple-gcc
19.522 -or
19.523 - make CROSS_COMPILE=your-target-tuple-
19.524 -and so on...
19.525 -
19.526 -It is strongly advised not to use the toolchain sys-root directory as an
19.527 -install directory for your programs/packages. If you do so, you will not be
19.528 -able to use your toolchain for another project. It is even strongly advised
19.529 -that your toolchain is chmod-ed to read-only once successfully build, so that
19.530 -you don't go polluting your toolchain with your programs/packages' files.
19.531 -
19.532 -Thus, when you build a program/package, install it in a separate directory,
19.533 -eg. /your/root. This directory is the /image/ of what would be in the root file
19.534 -system of your target, and will contain all that your programs/packages have
19.535 -installed.
19.536 -
19.537 -The 'populate' script |
19.538 -----------------------+
19.539 -
19.540 -When your root directory is ready, it is still missing some important bits: the
19.541 -toolchain's libraries. To populate your root directory with those libs, just
19.542 -run:
19.543 - your-target-tuple-populate -s /your/root -d /your/root-populated
19.544 -
19.545 -This will copy /your/root into /your/root-populated, and put the needed and only
19.546 -the needed libraries there. Thus you don't polute /your/root with any cruft that
19.547 -would no longer be needed should you have to remove stuff. /your/root always
19.548 -contains only those things you install in it.
19.549 -
19.550 -You can then use /your/root-populated to build up your file system image, a
19.551 -tarball, or to NFS-mount it from your target, or whatever you need.
19.552 -
19.553 -The populate script accepts the following options:
19.554 -
19.555 - -s src_dir
19.556 - Use 'src_dir' as the un-populated root directory.
19.557 -
19.558 - -d dst_dir
19.559 - Put the populated root directory in 'dst_dir'.
19.560 -
19.561 - -l lib1 [...]
19.562 - Always add specified libraries.
19.563 -
19.564 - -L file
19.565 - Always add libraries listed in 'file'.
19.566 -
19.567 - -f
19.568 - Remove 'dst_dir' if it previously existed; continue even if any library
19.569 - specified with -l or -L is missing.
19.570 -
19.571 - -v
19.572 - Be verbose, and tell what's going on (you can see exactly where libs are
19.573 - coming from).
19.574 -
19.575 - -h
19.576 - Print the help.
19.577 -
19.578 -See 'your-target-tuple-populate -h' for more information on the options.
19.579 -
19.580 -Here is how populate works:
19.581 -
19.582 - 1) performs some sanity checks:
19.583 - - src_dir and dst_dir are specified
19.584 - - src_dir exists
19.585 - - unless forced, dst_dir does not exist
19.586 - - src_dir != dst_dir
19.587 -
19.588 - 2) copy src_dir to dst_dir
19.589 -
19.590 - 3) add forced libraries to dst_dir
19.591 - - build the list from -l and -L options
19.592 - - get forced libraries from the sysroot (see below for heuristics)
19.593 - - abort on the first missing library, unless -f is specified
19.594 -
19.595 - 4) add all missing libraries to dst_dir
19.596 - - scan dst_dir for every ELF files that are 'executable' or
19.597 - 'shared object'
19.598 - - list the "NEEDED Shared library" fields
19.599 - - check if the library is already in dst_dir/lib or dst_dir/usr/lib
19.600 - - if not, get the library from the sysroot
19.601 - - if it's in sysroot/lib, copy it to dst_dir/lib
19.602 - - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
19.603 - - in both cases, use the SONAME of the library to create the file
19.604 - in dst_dir
19.605 - - if it was not found in the sysroot, this is an error.
19.606 -
19.607 -
19.608 -___________________
19.609 - /
19.610 -Toolchain types /
19.611 -________________/
19.612 -
19.613 -There are four kinds of toolchains you could encounter.
19.614 -
19.615 -First off, you must understand the following: when it comes to compilers there
19.616 -are up to four machines involved:
19.617 - 1) the machine configuring the toolchain components: the config machine
19.618 - 2) the machine building the toolchain components: the build machine
19.619 - 3) the machine running the toolchain: the host machine
19.620 - 4) the machine the toolchain is generating code for: the target machine
19.621 -
19.622 -We can most of the time assume that the config machine and the build machine
19.623 -are the same. Most of the time, this will be true. The only time it isn't
19.624 -is if you're using distributed compilation (such as distcc). Let's forget
19.625 -this for the sake of simplicity.
19.626 -
19.627 -So we're left with three machines:
19.628 - - build
19.629 - - host
19.630 - - target
19.631 -
19.632 -Any toolchain will involve those three machines. You can be as pretty sure of
19.633 -this as "2 and 2 are 4". Here is how they come into play:
19.634 -
19.635 -1) build == host == target
19.636 - This is a plain native toolchain, targetting the exact same machine as the
19.637 - one it is built on, and running again on this exact same machine. You have
19.638 - to build such a toolchain when you want to use an updated component, such
19.639 - as a newer gcc for example.
19.640 - crosstool-NG calls it "native".
19.641 -
19.642 -2) build == host != target
19.643 - This is a classic cross-toolchain, which is expected to be run on the same
19.644 - machine it is compiled on, and generate code to run on a second machine,
19.645 - the target.
19.646 - crosstool-NG calls it "cross".
19.647 -
19.648 -3) build != host == target
19.649 - Such a toolchain is also a native toolchain, as it targets the same machine
19.650 - as it runs on. But it is build on another machine. You want such a
19.651 - toolchain when porting to a new architecture, or if the build machine is
19.652 - much faster than the host machine.
19.653 - crosstool-NG calls it "cross-native".
19.654 -
19.655 -4) build != host != target
19.656 - This one is called a canadian-toolchain (*), and is tricky. The three
19.657 - machines in play are different. You might want such a toolchain if you
19.658 - have a fast build machine, but the users will use it on another machine,
19.659 - and will produce code to run on a third machine.
19.660 - crosstool-NG calls it "canadian".
19.661 -
19.662 -crosstool-NG can build all these kinds of toolchains (or is aiming at it,
19.663 -anyway!)
19.664 -
19.665 -(*) The term Canadian Cross came about because at the time that these issues
19.666 - were all being hashed out, Canada had three national political parties.
19.667 - http://en.wikipedia.org/wiki/Cross_compiler
19.668 -
19.669 -
19.670 -________________
19.671 - /
19.672 -Contributing /
19.673 -_____________/
19.674 -
19.675 -Sending a bug report |
19.676 ----------------------+
19.677 -
19.678 -If you need to send a bug report, please send a mail with subject
19.679 -prefixed with "[CT_NG]" with to following destinations:
19.680 - TO: yann.morin.1998 (at) anciens.enib.fr
19.681 - CC: crossgcc (at) sourceware.org
19.682 -
19.683 -Sending patches |
19.684 -----------------+
19.685 -
19.686 -If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
19.687 -
19.688 -Patches should come with the appropriate SoB line. A SoB line is typically
19.689 -something like:
19.690 - Signed-off-by: John DOE <john.doe@somewhere.net>
19.691 -
19.692 -The SoB line is clearly described in Documentation/SubmittingPatches , section
19.693 -12, of your favourite Linux kernel source tree.
19.694 -
19.695 -
19.696 -How to Use Mercurial |
19.697 ----------------------+
19.698 -
19.699 -For larger or more frequent contributions, mercurial should be used.
19.700 -
19.701 -PREREQUISITES:
19.702 -
19.703 -Configuring Mercurial:
19.704 - You need mercurial with the following extensions:
19.705 - - mq : http://mercurial.selenic.com/wiki/MqExtension
19.706 - - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
19.707 - Usually, these two extensions are already part of the installation package.
19.708 - The mq extension maintains a separate queue of your local changes
19.709 - that you can change at any later time.
19.710 - With the patchbomb extension you can email those patches directly
19.711 - from your local repo.
19.712 -
19.713 - Your configuration file for mercurial, e.g. ~/.hgrc should contain
19.714 - at least the following sections (but have a look at `man hgrc`):
19.715 - # ---
19.716 - [email]
19.717 - # configure sending patches directly via Mercurial
19.718 - from = "Your Name" <your@email.address>
19.719 - # How to send email:
19.720 - method = smtp
19.721 -
19.722 - [smtp]
19.723 - # SMTP configuration (only for method=smtp)
19.724 - host = localhost
19.725 - tls = true
19.726 - username =
19.727 - password =
19.728 -
19.729 - [extensions]
19.730 - # The following lines enable the two extensions:
19.731 - hgext.mq =
19.732 - hgext.patchbomb =
19.733 - # ----
19.734 -
19.735 -Create your local repository as a clone:
19.736 - hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
19.737 -
19.738 -Setting up the mq extension in your local copy:
19.739 - cd crosstool-ng
19.740 - hg qinit
19.741 -
19.742 -
19.743 -CREATING PATCHES:
19.744 -
19.745 -Recording your changes in the patch queue maintained by mq:
19.746 - # First, create a new patch entry in the patch queue:
19.747 - hg qnew -D -U -e short_patch_name1
19.748 - <edit patch description as commit message (see below for an example)>
19.749 -
19.750 - <now edit the ct-ng sources and check them>
19.751 -
19.752 - # if you execute `hg status` here, your modifications of the working
19.753 - # copy should show up.
19.754 -
19.755 - # Now the following command takes your modifications from the working copy
19.756 - # into the patch entry
19.757 - hg qrefresh -D [-e]
19.758 - <reedit patch description [-e] if desired>
19.759 -
19.760 - # Now your changes are recorded, and `hg status` should show a clean
19.761 - # working copy
19.762 -
19.763 -Repeat the above steps for all your modifications.
19.764 -The command `hg qseries` informs you about the content of your patch queue.
19.765 -
19.766 -
19.767 -CONTRIBUTING YOUR PATCHES:
19.768 -
19.769 -Once you are satisfied with your patch series, you can (you should!)
19.770 -contribute them back to upstream.
19.771 -This is easily done using the `hg email` command.
19.772 -
19.773 -`hg email` sends your new changesets to a specified list of recipients,
19.774 -each patch in its own email, all ordered in the way you entered them (oldest
19.775 -first). The command line flag --outgoing selects all changesets that are in
19.776 -your local but not yet in the upstream repository. Here, these are exactly
19.777 -the ones you entered into your local patch queue in the section above, so
19.778 ---outgoing is what you want.
19.779 -
19.780 -Each email gets the subject set to: "[PATCH x of n] <series summary>"
19.781 -where 'x' is the serial number in the email series, and 'n' is the total number
19.782 -of patches in the series. The body of the email is the complete patch, plus
19.783 -a handful of metadata, that helps properly apply the patch, keeping the log
19.784 -message, attribution and date, tracking file changes (move, delete, modes...)
19.785 -
19.786 -`hg email` also threads all outgoing patch emails below an introductory
19.787 -message. You should use the introductory message (command line flag --intro)
19.788 -to describe the scope and motivation for the whole patch series. The subject
19.789 -for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
19.790 -and you get the chance to set the <series summary>.
19.791 -
19.792 -Here is a sample `hg email` complete command line:
19.793 -Note: replace " (at) " with "@"
19.794 -
19.795 - hg email --outgoing --intro \
19.796 - --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
19.797 - --cc 'crossgcc (at) sourceware.org'
19.798 -
19.799 - # It then opens an editor and lets you enter the subject
19.800 - # and the body for the introductory message.
19.801 -
19.802 -Use `hg email` with the additional command line switch -n to
19.803 -first have a look at the email(s) without actually sending them.
19.804 -
19.805 -
19.806 -MAINTAINING YOUR PATCHES:
19.807 -
19.808 -When the patches are refined by discussing them on the mailing list,
19.809 -you may want to finalize and resend them.
19.810 -
19.811 -The mq extension has the idiosyncrasy of imposing a stack onto the queue:
19.812 -You can always reedit/refresh only the patch on top of stack.
19.813 -The queue consists of applied and unapplied patches
19.814 -(if you reached here via the above steps, all of your patches are applied),
19.815 -where the 'stack' consists of the applied patches, and 'top of stack'
19.816 -is the latest applied patch.
19.817 -
19.818 -The following output of `hg qseries` is now used as an example:
19.819 - 0 A short_patch_name1
19.820 - 1 A short_patch_name2
19.821 - 2 A short_patch_name3
19.822 - 3 A short_patch_name4
19.823 -
19.824 -You are now able to edit patch 'short_patch_name4' (which is top of stack):
19.825 - <Edit the sources>
19.826 - # and execute again
19.827 - hg qrefresh -D [-e]
19.828 - <and optionally [-e] reedit the commit message>
19.829 -
19.830 -If you want to edit e.g. patch short_patch_name2, you have to modify
19.831 -mq's stack so this patch gets top of stack.
19.832 -For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
19.833 -
19.834 - hg qgoto short_patch_name2
19.835 - # The patch queue should now look like
19.836 - hg qseries
19.837 - 0 A short_patch_name1
19.838 - 1 A short_patch_name2
19.839 - 2 U short_patch_name3
19.840 - 3 U short_patch_name4
19.841 - # so patch # 1 (short_patch_name2) is top of stack.
19.842 - <now reedit the sources for short_patch_name2>
19.843 - # and execute again
19.844 - hg qrefresh -D [-e]
19.845 - <and optionally [-e] reedit the commit message>
19.846 - # the following command reapplies the now unapplied two patches:
19.847 - hg qpush -a
19.848 - # you can also use `hg qgoto short_patch_name4` to get there again.
19.849 -
19.850 -
19.851 -RESENDING YOUR REEDITED PATCHES:
19.852 -
19.853 -By mailing list policy, please resend your complete patch series.
19.854 ---> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
19.855 -
19.856 -
19.857 -SYNCING WITH UPSTREAM AGAIN:
19.858 -
19.859 -You can sync your repo with upstream at any time by executing
19.860 - # first unapply all your patches:
19.861 - hg qpop -a
19.862 - # next fetch new changesets from upstream
19.863 - hg pull
19.864 - # then update your working copy
19.865 - hg up
19.866 - # optionally remove already upstream integrated patches (see below)
19.867 - hg qdelete <short_name_of_already_applied_patch>
19.868 - # and reapply your patches if any non upstream-integrated left (but see below)
19.869 - hg qpush -a
19.870 -
19.871 -Eventually, your patches get included into the upstream repository
19.872 -which you initially cloned.
19.873 -In this case, before executing the hg qpush -a from above
19.874 -you should manually "hg qdelete" the patches that are already integrated upstream.
19.875 -
19.876 -
19.877 -HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
19.878 -
19.879 -Commit messages should look like (without leading pipes):
19.880 - |component: short, one-line description
19.881 - |
19.882 - |optional longer description
19.883 - |on multiple lines if needed
19.884 -
19.885 -Here is an example commit message (see revision a53a5e1d61db):
19.886 - |comp-libs/cloog: fix building
19.887 - |
19.888 - |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
19.889 - |For any later versions, the directory name does have the version, such as
19.890 - |cloog-ppl-0.15.4.
19.891 -
19.892 -_____________
19.893 - /
19.894 -Internals /
19.895 -__________/
19.896 -
19.897 -Internally, crosstool-NG is script-based. To ease usage, the frontend is
19.898 -Makefile-based.
19.899 -
19.900 -Makefile front-end |
19.901 --------------------+
19.902 -
19.903 -The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
19.904 -script with an action will act exactly as if the Makefile was in the current
19.905 -working directory and make was called with the action as rule. Thus:
19.906 - ct-ng menuconfig
19.907 -
19.908 -is equivalent to having the Makefile in CWD, and calling:
19.909 - make menuconfig
19.910 -
19.911 -Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
19.912 -traditional command.
19.913 -
19.914 -ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
19.915 -at configuration time with ./configure.
19.916 -
19.917 -ct-ng also searches for config files, sub-tools, samples, scripts and patches in
19.918 -that library directory.
19.919 -
19.920 -Because of a stupid make behavior/bug I was unable to track down, implicit make
19.921 -rules are disabled: installing with --local would triger those rules, and mconf
19.922 -was unbuildable.
19.923 -
19.924 -Kconfig parser |
19.925 ----------------+
19.926 -
19.927 -The kconfig language is a hacked version, vampirised from the Linux kernel
19.928 -(http://www.kernel.org/), and (heavily) adapted to my needs.
19.929 -
19.930 -The list of the most notable changes (at least the ones I remember) follows:
19.931 -- the CONFIG_ prefix has been replaced with CT_
19.932 -- a leading | in prompts is skipped, and subsequent leading spaces are not
19.933 - trimmed; otherwise leading spaces are silently trimmed
19.934 -- removed the warning about undefined environment variable
19.935 -
19.936 -The kconfig parsers (conf and mconf) are not installed pre-built, but as
19.937 -source files. Thus you can have the directory where crosstool-NG is installed,
19.938 -exported (via NFS or whatever) and have clients with different architectures
19.939 -use the same crosstool-NG installation, and most notably, the same set of
19.940 -patches.
19.941 -
19.942 -Architecture-specific |
19.943 -----------------------+
19.944 -
19.945 -Note: this chapter is not really well written, and might thus be a little bit
19.946 -complex to understand. To get a better grasp of what an architecture is, the
19.947 -reader is kindly encouraged to look at the "arch/" sub-directory, and to the
19.948 -existing architectures to see how things are laid out.
19.949 -
19.950 -An architecture is defined by:
19.951 -
19.952 - - a human-readable name, in lower case letters, with numbers as appropriate.
19.953 - The underscore is allowed; space and special characters are not.
19.954 - Eg.: arm, x86_64
19.955 - - a file in "config/arch/", named after the architecture's name, and suffixed
19.956 - with ".in".
19.957 - Eg.: config/arch/arm.in
19.958 - - a file in "scripts/build/arch/", named after the architecture's name, and
19.959 - suffixed with ".sh".
19.960 - Eg.: scripts/build/arch/arm.sh
19.961 -
19.962 -The architecture's ".in" file API:
19.963 - > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
19.964 - actual architecture name).
19.965 - That config option must have *neither* a type, *nor* a prompt! Also, it can
19.966 - *not* depend on any other config option (EXPERIMENTAL is managed as above).
19.967 - Eg.:
19.968 - config ARCH_arm
19.969 - + mandatory:
19.970 - defines a (terse) help entry for this architecture:
19.971 - Eg.:
19.972 - config ARCH_arm
19.973 - help
19.974 - The ARM architecture.
19.975 - + optional:
19.976 - selects adequate associated config options.
19.977 - Note: 64-bit architectures *shall* select ARCH_64
19.978 - Eg.:
19.979 - config ARCH_arm
19.980 - select ARCH_SUPPORTS_BOTH_ENDIAN
19.981 - select ARCH_DEFAULT_LE
19.982 - help
19.983 - The ARM architecture.
19.984 - Eg.:
19.985 - config ARCH_x86_64
19.986 - select ARCH_64
19.987 - help
19.988 - The x86_64 architecture.
19.989 -
19.990 - > other target-specific options, at your discretion. Note however that to
19.991 - avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
19.992 - where %arch% is again replaced by the actual architecture name.
19.993 - (Note: due to historical reasons, and lack of time to clean up the code,
19.994 - I may have left some config options that do not completely conform to
19.995 - this, as the architecture name was written all upper case. However, the
19.996 - prefix is unique among architectures, and does not cause harm).
19.997 -
19.998 -The architecture's ".sh" file API:
19.999 - > the function "CT_DoArchTupleValues"
19.1000 - + parameters: none
19.1001 - + environment:
19.1002 - - all variables from the ".config" file,
19.1003 - - the two variables "target_endian_eb" and "target_endian_el" which are
19.1004 - the endianness suffixes
19.1005 - + return value: 0 upon success, !0 upon failure
19.1006 - + provides:
19.1007 - - mandatory
19.1008 - - the environment variable CT_TARGET_ARCH
19.1009 - - contains:
19.1010 - the architecture part of the target tuple.
19.1011 - Eg.: "armeb" for big endian ARM
19.1012 - "i386" for an i386
19.1013 - + provides:
19.1014 - - optional
19.1015 - - the environment variable CT_TARGET_SYS
19.1016 - - contains:
19.1017 - the sytem part of the target tuple.
19.1018 - Eg.: "gnu" for glibc on most architectures
19.1019 - "gnueabi" for glibc on an ARM EABI
19.1020 - - defaults to:
19.1021 - - for glibc-based toolchain: "gnu"
19.1022 - - for uClibc-based toolchain: "uclibc"
19.1023 - + provides:
19.1024 - - optional
19.1025 - - the environment variables to configure the cross-gcc (defaults)
19.1026 - - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
19.1027 - - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
19.1028 - - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
19.1029 - - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
19.1030 - - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
19.1031 - - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
19.1032 - + provides:
19.1033 - - optional
19.1034 - - the environment variables to pass to the cross-gcc to build target binaries (defaults)
19.1035 - - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
19.1036 - - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
19.1037 - - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
19.1038 - - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
19.1039 - - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
19.1040 - - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
19.1041 - - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
19.1042 - - default to:
19.1043 - see above.
19.1044 - + provides:
19.1045 - - optional
19.1046 - - the environement variables to configure the core and final compiler, specific to this architecture:
19.1047 - - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
19.1048 - - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
19.1049 - - default to:
19.1050 - - all empty
19.1051 - + provides:
19.1052 - - optional
19.1053 - - the architecture-specific CFLAGS and LDFLAGS:
19.1054 - - CT_ARCH_TARGET_CLFAGS
19.1055 - - CT_ARCH_TARGET_LDFLAGS
19.1056 - - default to:
19.1057 - - all empty
19.1058 -
19.1059 -You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
19.1060 -a quite complete example of what an actual architecture description looks like.
19.1061 -
19.1062 -Kernel specific |
19.1063 -----------------+
19.1064 -
19.1065 -A kernel is defined by:
19.1066 -
19.1067 - - a human-readable name, in lower case letters, with numbers as appropriate.
19.1068 - The underscore is allowed; space and special characters are not (although
19.1069 - they are internally replaced with underscores.
19.1070 - Eg.: linux, bare-metal
19.1071 - - a file in "config/kernel/", named after the kernel name, and suffixed with
19.1072 - ".in".
19.1073 - Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
19.1074 - - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
19.1075 - with ".sh".
19.1076 - Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
19.1077 -
19.1078 -The kernel's ".in" file must contain:
19.1079 - > an optional lines containing exactly "# EXPERIMENTAL", starting on the
19.1080 - first column, and without any following space or other character.
19.1081 - If this line is present, then this kernel is considered EXPERIMENTAL,
19.1082 - and correct dependency on EXPERIMENTAL will be set.
19.1083 -
19.1084 - > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
19.1085 - replaced with the actual kernel name, with all special characters and
19.1086 - spaces replaced by underscores).
19.1087 - That config option must have *neither* a type, *nor* a prompt! Also, it can
19.1088 - *not* depends on EXPERIMENTAL.
19.1089 - Eg.: KERNEL_linux, KERNEL_bare_metal
19.1090 - + mandatory:
19.1091 - defines a (terse) help entry for this kernel.
19.1092 - Eg.:
19.1093 - config KERNEL_bare_metal
19.1094 - help
19.1095 - Build a compiler for use without any kernel.
19.1096 - + optional:
19.1097 - selects adequate associated config options.
19.1098 - Eg.:
19.1099 - config KERNEL_bare_metal
19.1100 - select BARE_METAL
19.1101 - help
19.1102 - Build a compiler for use without any kernel.
19.1103 -
19.1104 - > other kernel specific options, at your discretion. Note however that, to
19.1105 - avoid name-clashing, such options should be prefixed with
19.1106 - "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
19.1107 - the actual kernel name.
19.1108 - (Note: due to historical reasons, and lack of time to clean up the code,
19.1109 - I may have left some config options that do not completely conform to
19.1110 - this, as the kernel name was written all upper case. However, the prefix
19.1111 - is unique among kernels, and does not cause harm).
19.1112 -
19.1113 -The kernel's ".sh" file API:
19.1114 - > is a bash script fragment
19.1115 -
19.1116 - > defines the function CT_DoKernelTupleValues
19.1117 - + see the architecture's CT_DoArchTupleValues, except for:
19.1118 - + set the environment variable CT_TARGET_KERNEL, the kernel part of the
19.1119 - target tuple
19.1120 - + return value: ignored
19.1121 -
19.1122 - > defines the function "do_kernel_get":
19.1123 - + parameters: none
19.1124 - + environment:
19.1125 - - all variables from the ".config" file.
19.1126 - + return value: 0 for success, !0 for failure.
19.1127 - + behavior: download the kernel's sources, and store the tarball into
19.1128 - "${CT_TARBALLS_DIR}". To this end, a functions is available, that
19.1129 - abstracts downloading tarballs:
19.1130 - - CT_DoGet <tarball_base_name> <URL1 [URL...]>
19.1131 - Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
19.1132 - Note: retrieving sources from svn, cvs, git and the likes is not supported
19.1133 - by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
19.1134 - "scripts/build/libc/eglibc.sh"
19.1135 -
19.1136 - > defines the function "do_kernel_extract":
19.1137 - + parameters: none
19.1138 - + environment:
19.1139 - - all variables from the ".config" file,
19.1140 - + return value: 0 for success, !0 for failure.
19.1141 - + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
19.1142 - required patches. To this end, a function is available, that abstracts
19.1143 - extracting tarballs:
19.1144 - - CT_ExtractAndPatch <tarball_base_name>
19.1145 - Eg.: CT_ExtractAndPatch linux-2.6.26.5
19.1146 -
19.1147 - > defines the function "do_kernel_headers":
19.1148 - + parameters: none
19.1149 - + environment:
19.1150 - - all variables from the ".config" file,
19.1151 - + return value: 0 for success, !0 for failure.
19.1152 - + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
19.1153 -
19.1154 - > defines any kernel-specific helper functions
19.1155 - These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
19.1156 - where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
19.1157 - any name-clashing.
19.1158 -
19.1159 -You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
19.1160 -as an example of what a complex kernel description looks like.
19.1161 -
19.1162 -Adding a new version of a component |
19.1163 -------------------------------------+
19.1164 -
19.1165 -When a new component, such as the Linux kernel, gcc or any other is released,
19.1166 -adding the new version to crosstool-NG is quite easy. There is a script that
19.1167 -will do all that for you:
19.1168 - scripts/addToolVersion.sh
19.1169 -
19.1170 -Run it with no option to get some help.
19.1171 -
19.1172 -Build scripts |
19.1173 ---------------+
19.1174 -
19.1175 -To Be Written later...