1.1 --- a/docs/overview.txt Tue Aug 10 13:25:52 2010 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1172 +0,0 @@
1.4 -File.........: overview.txt
1.5 -Content......: Overview of how crosstool-NG works.
1.6 -Copyrigth....: (C) 2007 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
1.7 -License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
1.8 -
1.9 -____________________
1.10 - /
1.11 -Table Of Content /
1.12 -_________________/
1.13 -
1.14 -
1.15 -Introduction
1.16 -History
1.17 -Referring to crosstool-NG
1.18 -Installing crosstool-NG
1.19 - Install method
1.20 - The hacker's way
1.21 - Preparing for packaging
1.22 - Shell completion
1.23 - Contributed code
1.24 -Configuring crosstool-NG
1.25 - Interesting config options
1.26 - Re-building an existing toolchain
1.27 - Using as a backend for a build-system
1.28 -Running crosstool-NG
1.29 - Stopping and restarting a build
1.30 - Testing all toolchains at once
1.31 - Overriding the number of // jobs
1.32 - Note on // jobs
1.33 - Tools wrapper
1.34 -Using the toolchain
1.35 - The 'populate' script
1.36 -Toolchain types
1.37 - Seemingly-native toolchains
1.38 -Contributing
1.39 - Sending a bug report
1.40 - Sending patches
1.41 -Internals
1.42 - Makefile front-end
1.43 - Kconfig parser
1.44 - Architecture-specific
1.45 - Adding a new version of a component
1.46 - Build scripts
1.47 -
1.48 -
1.49 -________________
1.50 - /
1.51 -Introduction /
1.52 -_____________/
1.53 -
1.54 -crosstool-NG aims at building toolchains. Toolchains are an essential component
1.55 -in a software development project. It will compile, assemble and link the code
1.56 -that is being developed. Some pieces of the toolchain will eventually end up
1.57 -in the resulting binary/ies: static libraries are but an example.
1.58 -
1.59 -So, a toolchain is a very sensitive piece of software, as any bug in one of the
1.60 -components, or a poorly configured component, can lead to execution problems,
1.61 -ranging from poor performance, to applications ending unexpectedly, to
1.62 -mis-behaving software (which more than often is hard to detect), to hardware
1.63 -damage, or even to human risks (which is more than regrettable).
1.64 -
1.65 -Toolchains are made of different piece of software, each being quite complex
1.66 -and requiring specially crafted options to build and work seamlessly. This
1.67 -is usually not that easy, even in the not-so-trivial case of native toolchains.
1.68 -The work reaches a higher degree of complexity when it comes to cross-
1.69 -compilation, where it can become quite a nightmare...
1.70 -
1.71 -Some cross-toolchains exist on the internet, and can be used for general
1.72 -development, but they have a number of limitations:
1.73 - - they can be general purpose, in that they are configured for the majority:
1.74 - no optimisation for your specific target,
1.75 - - they can be prepared for a specific target and thus are not easy to use,
1.76 - nor optimised for, or even supporting your target,
1.77 - - they often are using aging components (compiler, C library, etc...) not
1.78 - supporting special features of your shiny new processor;
1.79 -On the other side, these toolchain offer some advantages:
1.80 - - they are ready to use and quite easy to install and setup,
1.81 - - they are proven if used by a wide community.
1.82 -
1.83 -But once you want to get all the juice out of your specific hardware, you will
1.84 -want to build your own toolchain. This is where crosstool-NG comes into play.
1.85 -
1.86 -There are also a number of tools that build toolchains for specific needs,
1.87 -which are not really scalable. Examples are:
1.88 - - buildroot (buildroot.uclibc.org) whose main purpose is to build root file
1.89 - systems, hence the name. But once you have your toolchain with buildroot,
1.90 - part of it is installed in the root-to-be, so if you want to build a whole
1.91 - new root, you either have to save the existing one as a template and
1.92 - restore it later, or restart again from scratch. This is not convenient,
1.93 - - ptxdist (www.pengutronix.de/software/ptxdist), whose purpose is very
1.94 - similar to buildroot,
1.95 - - other projects (openembedded.org for example), which are again used to
1.96 - build root file systems.
1.97 -
1.98 -crosstool-NG is really targeted at building toolchains, and only toolchains.
1.99 -It is then up to you to use it the way you want.
1.100 -
1.101 -
1.102 -___________
1.103 - /
1.104 -History /
1.105 -________/
1.106 -
1.107 -crosstool was first 'conceived' by Dan Kegel, who offered it to the community
1.108 -as a set of scripts, a repository of patches, and some pre-configured, general
1.109 -purpose setup files to be used to configure crosstool. This is available at
1.110 -http://www.kegel.com/crosstool, and the subversion repository is hosted on
1.111 -google at http://code.google.com/p/crosstool/.
1.112 -
1.113 -I once managed to add support for uClibc-based toolchains, but it did not make
1.114 -into mainline, mostly because I didn't have time to port the patch forward to
1.115 -the new versions, due in part to the big effort it was taking.
1.116 -
1.117 -So I decided to clean up crosstool in the state it was, re-order the things
1.118 -in place, add appropriate support for what I needed, that is uClibc support
1.119 -and a menu-driven configuration, named the new implementation crosstool-NG,
1.120 -(standing for crosstool Next Generation, as many other comunity projects do,
1.121 -and as a wink at the TV series "Star Trek: The Next Generation" ;-) ) and
1.122 -made it available to the community, in case it was of interest to any one.
1.123 -
1.124 -
1.125 -_____________________________
1.126 - /
1.127 -Referring to crosstool-NG /
1.128 -__________________________/
1.129 -
1.130 -
1.131 -The long name of the project is crosstool-NG:
1.132 - * no leading uppercase (except as first word in a sentence)
1.133 - * crosstool and NG separated with a hyphen (dash)
1.134 - * NG in uppercase
1.135 -
1.136 -Crosstool-NG can also be referred to by its short name CT-NG:
1.137 - * all in uppercase
1.138 - * CT and NG separated with a hyphen (dash)
1.139 -
1.140 -The long name is preferred over the short name, except in mail subjects, where
1.141 -the short name is a better fit.
1.142 -
1.143 -When referring to a specific version of crosstool-NG, append the version number
1.144 -either as:
1.145 - * crosstool-NG X.Y.Z
1.146 - - the long name, a space, and the version string
1.147 - * crosstool-ng-X.Y.Z
1.148 - - the long name in lowercase, a hyphen (dash), and the version string
1.149 - - this is used to name the release tarballs
1.150 - * crosstool-ng-X.Y.Z+hg_id
1.151 - - the long name in lowercase, a hyphen, the version string, and the Hg id
1.152 - (as returned by: ct-ng version)
1.153 - - this is used to differentiate between releases and snapshots
1.154 -
1.155 -The frontend to crosstool-NG is the command ct-ng:
1.156 - * all in lowercase
1.157 - * ct and ng separated by a hyphen (dash)
1.158 -
1.159 -
1.160 -___________________________
1.161 - /
1.162 -Installing crosstool-NG /
1.163 -________________________/
1.164 -
1.165 -There are two ways you can use crosstool-NG:
1.166 - - build and install it, then get rid of the sources like you'd do for most
1.167 - programs,
1.168 - - or only build it and run from the source directory.
1.169 -
1.170 -The former should be used if you got crosstool-NG from a packaged tarball, see
1.171 -"Install method", below, while the latter is most useful for developpers that
1.172 -use a clone of the repository, and want to submit patches, see "The Hacker's
1.173 -way", below.
1.174 -
1.175 -Install method |
1.176 ----------------+
1.177 -
1.178 -If you go for the install, then you just follow the classical, but yet easy
1.179 -./configure way:
1.180 - ./configure --prefix=/some/place
1.181 - make
1.182 - make install
1.183 - export PATH="${PATH}:/some/place/bin"
1.184 -
1.185 -You can then get rid of crosstool-NG source. Next create a directory to serve
1.186 -as a working place, cd in there and run:
1.187 - ct-ng help
1.188 -
1.189 -See below for complete usage.
1.190 -
1.191 -The Hacker's way |
1.192 ------------------+
1.193 -
1.194 -If you go the hacker's way, then the usage is a bit different, although very
1.195 -simple:
1.196 - ./configure --local
1.197 - make
1.198 -
1.199 -Now, *do not* remove crosstool-NG sources. They are needed to run crosstool-NG!
1.200 -Stay in the directory holding the sources, and run:
1.201 - ./ct-ng help
1.202 -
1.203 -See below for complete usage.
1.204 -
1.205 -Now, provided you used a clone of the repository, you can send me your changes.
1.206 -See the section titled CONTRIBUTING, below, for how to submit changees.
1.207 -
1.208 -Preparing for packaging |
1.209 -------------------------+
1.210 -
1.211 -If you plan on packaging crosstool-NG, you surely don't want to install it
1.212 -in your root file system. The install procedure of crosstool-NG honors the
1.213 -DESTDIR variable:
1.214 -
1.215 - ./configure --prefix=/usr
1.216 - make
1.217 - make DESTDIR=/packaging/place install
1.218 -
1.219 -Shell completion |
1.220 ------------------+
1.221 -
1.222 -crosstool-NG comes with a shell script fragment that defines bash-compatible
1.223 -completion. That shell fragment is currently not installed automatically, but
1.224 -this is planned.
1.225 -
1.226 -To install the shell script fragment, you have two options:
1.227 - - install system-wide, most probably by copying ct-ng.comp into
1.228 - /etc/bash_completion.d/
1.229 - - install for a single user, by copying ct-ng.comp into ${HOME}/ and
1.230 - sourcing this file from your ${HOME}/.bashrc
1.231 -
1.232 -Contributed code |
1.233 ------------------+
1.234 -
1.235 -Some people contibuted code that couldn't get merged for various reasons. This
1.236 -code is available as lzma-compressed patches, in the contrib/ sub-directory.
1.237 -These patches are to be applied to the source of crosstool-NG, prior to
1.238 -installing, using something like the following:
1.239 - lzcat contrib/foobar.patch.lzma |patch -p1
1.240 -
1.241 -There is no guarantee that a particuliar contribution applies to the current
1.242 -version of crosstool-ng, or that it will work at all. Use contributions at
1.243 -your own risk.
1.244 -
1.245 -
1.246 -____________________________
1.247 - /
1.248 -Configuring crosstool-NG /
1.249 -_________________________/
1.250 -
1.251 -crosstool-NG is configured with a configurator presenting a menu-stuctured set
1.252 -of options. These options let you specify the way you want your toolchain
1.253 -built, where you want it installed, what architecture and specific processor it
1.254 -will support, the version of the components you want to use, etc... The
1.255 -value for those options are then stored in a configuration file.
1.256 -
1.257 -The configurator works the same way you configure your Linux kernel. It is
1.258 -assumed you now how to handle this.
1.259 -
1.260 -To enter the menu, type:
1.261 - ct-ng menuconfig
1.262 -
1.263 -Almost every config item has a help entry. Read them carefully.
1.264 -
1.265 -String and number options can refer to environment variables. In such a case,
1.266 -you must use the shell syntax: ${VAR}. You shall neither single- nor double-
1.267 -quote the string/number options.
1.268 -
1.269 -There are three environment variables that are computed by crosstool-NG, and
1.270 -that you can use:
1.271 -
1.272 -CT_TARGET:
1.273 - It represents the target tuple you are building for. You can use it for
1.274 - example in the installation/prefix directory, such as:
1.275 - /opt/x-tools/${CT_TARGET}
1.276 -
1.277 -CT_TOP_DIR:
1.278 - The top directory where crosstool-NG is running. You shouldn't need it in
1.279 - most cases. There is one case where you may need it: if you have local
1.280 - patches and you store them in your running directory, you can refer to them
1.281 - by using CT_TOP_DIR, such as:
1.282 - ${CT_TOP_DIR}/patches.myproject
1.283 -
1.284 -CT_VERSION:
1.285 - The version of crosstool-NG you are using. Not much use for you, but it's
1.286 - there if you need it.
1.287 -
1.288 -Interesting config options |
1.289 ----------------------------+
1.290 -
1.291 -CT_LOCAL_TARBALLS_DIR:
1.292 - If you already have some tarballs in a direcotry, enter it here. That will
1.293 - speed up the retrieving phase, where crosstool-NG would otherwise download
1.294 - those tarballs.
1.295 -
1.296 -CT_PREFIX_DIR:
1.297 - This is where the toolchain will be installed in (and for now, where it
1.298 - will run from). Common use is to add the target tuple in the directory
1.299 - path, such as (see above):
1.300 - /opt/x-tools/${CT_TARGET}
1.301 -
1.302 -CT_TARGET_VENDOR:
1.303 - An identifier for your toolchain, will take place in the vendor part of the
1.304 - target tuple. It shall *not* contain spaces or dashes. Usually, keep it
1.305 - to a one-word string, or use underscores to separate words if you need.
1.306 - Avoid dots, commas, and special characters.
1.307 -
1.308 -CT_TARGET_ALIAS:
1.309 - An alias for the toolchian. It will be used as a prefix to the toolchain
1.310 - tools. For example, you will have ${CT_TARGET_ALIAS}-gcc
1.311 -
1.312 -Also, if you think you don't see enough versions, you can try to enable one of
1.313 -those:
1.314 -
1.315 -CT_OBSOLETE:
1.316 - Show obsolete versions or tools. Most of the time, you don't want to base
1.317 - your toolchain on too old a version (of gcc, for example). But at times, it
1.318 - can come handy to use such an old version for regression tests. Those old
1.319 - versions are hidden behind CT_OBSOLETE. Those versions (or features) are so
1.320 - marked because maintaining support for those in crosstool-NG would be too
1.321 - costly, time-wise, and time is dear.
1.322 -
1.323 -CT_EXPERIMENTAL:
1.324 - Show experimental versions or tools. Again, you might not want to base your
1.325 - toolchain on too recent tools (eg. gcc) for production. But if you need a
1.326 - feature present only in a recent version, or a new tool, you can find them
1.327 - hidden behind CT_EXPERIMENTAL. Those versions (or features) did not (yet)
1.328 - receive thorough testing in crosstool-NG, and/or are not mature enough to
1.329 - be blindly trusted.
1.330 -
1.331 -Re-building an existing toolchain |
1.332 -----------------------------------+
1.333 -
1.334 -If you have an existing toolchain, you can re-use the options used to build it
1.335 -to create a new toolchain. That needs a very little bit of effort on your side
1.336 -but is quite easy. The options to build a toolchain are saved with the
1.337 -toolchain, and you can retrieve this configuration by running:
1.338 - ${CT_TARGET}-ct-ng.config
1.339 -
1.340 -An alternate method is to extract the configuration from a build.log file.
1.341 -This will be necessary if your toolchain was build with crosstool-NG prior
1.342 -to 1.4.0, but can be used with build.log files from any version:
1.343 - ct-ng extractconfig <build.log >.config
1.344 -
1.345 -Or, if your build.log file is compressed (most probably!):
1.346 - bzcat build.log.bz2 |ct-ng extractconfig >.config
1.347 -
1.348 -The above commands will dump the configuration to stdout, so to rebuild a
1.349 -toolchain with this configuration, just redirect the output to the
1.350 -.config file:
1.351 - ${CT_TARGET}-ct-ng.config >.config
1.352 - ct-ng oldconfig
1.353 -
1.354 -Then, you can review and change the configuration by running:
1.355 - ct-ng menuconfig
1.356 -
1.357 -Using as a backend for a build-system |
1.358 ---------------------------------------+
1.359 -
1.360 -Crosstool-NG can be used as a backend for an automated build-system. In this
1.361 -case, some components that are expected to run on the target (eg. the native
1.362 -gdb, ltrace, DUMA...) are not available in the menuconfig, and they are not
1.363 -build either, as it is considered the responsibility of the build-system to
1.364 -build its own versions of those tools.
1.365 -
1.366 -If you want to use crosstool-NG as a backend to generate your toolchains for
1.367 -your build-system, you have to set and export this environment variable:
1.368 - CT_IS_A_BACKEND=y
1.369 -
1.370 -(case is not sensitive, you can say Y).
1.371 -
1.372 -
1.373 -________________________
1.374 - /
1.375 -Running crosstool-NG /
1.376 -_____________________/
1.377 -
1.378 -To build the toolchain, simply type:
1.379 - ct-ng build
1.380 -
1.381 -This will use the above configuration to retrieve, extract and patch the
1.382 -components, build, install and eventually test your newly built toolchain.
1.383 -
1.384 -You are then free to add the toolchain /bin directory in your PATH to use
1.385 -it at will.
1.386 -
1.387 -In any case, you can get some terse help. Just type:
1.388 - ct-ng help
1.389 -or:
1.390 - man 1 ct-ng
1.391 -
1.392 -Stopping and restarting a build |
1.393 ---------------------------------+
1.394 -
1.395 -If you want to stop the build after a step you are debugging, you can pass the
1.396 -variable STOP to make:
1.397 - ct-ng build STOP=some_step
1.398 -
1.399 -Conversely, if you want to restart a build at a specific step you are
1.400 -debugging, you can pass the RESTART variable to make:
1.401 - ct-ng build RESTART=some_step
1.402 -
1.403 -Alternatively, you can call make with the name of a step to just do that step:
1.404 - ct-ng libc_headers
1.405 -is equivalent to:
1.406 - ct-ng build RESTART=libc_headers STOP=libc_headers
1.407 -
1.408 -The shortcuts +step_name and step_name+ allow to respectively stop or restart
1.409 -at that step. Thus:
1.410 - ct-ng +libc_headers and: ct-ng libc_headers+
1.411 -are equivalent to:
1.412 - ct-ng build STOP=libc_headers and: ct-ng build RESTART=libc_headers
1.413 -
1.414 -To obtain the list of acceptable steps, please call:
1.415 - ct-ng list-steps
1.416 -
1.417 -Note that in order to restart a build, you'll have to say 'Y' to the config
1.418 -option CT_DEBUG_CT_SAVE_STEPS, and that the previous build effectively went
1.419 -that far.
1.420 -
1.421 -Building all toolchains at once |
1.422 ---------------------------------+
1.423 -
1.424 -You can build all samples; simply call:
1.425 - ct-ng build-all
1.426 -
1.427 -Overriding the number of // jobs |
1.428 ----------------------------------+
1.429 -
1.430 -If you want to override the number of jobs to run in // (the -j option to
1.431 -make), you can either re-enter the menuconfig, or simply add it on the command
1.432 -line, as such:
1.433 - ct-ng build.4
1.434 -
1.435 -which tells crosstool-NG to override the number of // jobs to 4.
1.436 -
1.437 -You can see the actions that support overriding the number of // jobs in
1.438 -the help menu. Those are the ones with [.#] after them (eg. build[.#] or
1.439 -build-all[.#], and so on...).
1.440 -
1.441 -Note on // jobs |
1.442 -----------------+
1.443 -
1.444 -The crosstool-NG script 'ct-ng' is a Makefile-script. It does *not* execute
1.445 -in parallel (there is not much to gain). When speaking of // jobs, we are
1.446 -refering to the number of // jobs when making the *components*. That is, we
1.447 -speak of the number of // jobs used to build gcc, glibc, and so on...
1.448 -
1.449 -Tools wrapper |
1.450 ---------------+
1.451 -
1.452 -Starting with gcc-4.3 come two new dependencies: GMP and MPFR. With gcc-4.4,
1.453 -come three new ones: PPL, CLooG/ppl and MPC. With gcc-4.5 again comes a new
1.454 -dependency on libelf. These are libraries that enable advanced features to
1.455 -gcc. Additionally, some of those libraries can be used by binutils and gdb.
1.456 -Unfortunately, not all systems on which crosstool-NG runs have all of those
1.457 -libraries. And for those that do, the versions of those libraries may be
1.458 -older than the version required by gcc (and binutils and gdb). To date,
1.459 -Debian stable (aka Lenny) is lagging behind on some, and is missing the
1.460 -others.
1.461 -
1.462 -This is why crosstool-NG builds its own set of libraries as part of the
1.463 -toolchain.
1.464 -
1.465 -The companion libraries can be built either as static libraries, or as shared
1.466 -libraries. The default is to build static libraries, and is the safe way.
1.467 -If you decide to use static companion libraries, then you can stop reading
1.468 -this section.
1.469 -
1.470 -But if you prefer to have shared libraries, then read on...
1.471 -
1.472 -Building shared companion libraries poses no problem at build time, as
1.473 -crosstool-NG correctly points gcc (and binutils and gdb) to the correct
1.474 -place where our own version of the libraries are installed. But it poses
1.475 -a problem when gcc et al. are run: the place where the libraries are is most
1.476 -probably not known to the host dynamic linker. Still worse, if the host system
1.477 -has its own versions, then ld.so would load the wrong libraries!
1.478 -
1.479 -So we have to force the dynamic linker to load the correct version. We do this
1.480 -by using the LD_LIBRARY_PATH variable, that informs the dynamic linker where
1.481 -to look for shared libraries prior to searching its standard places. But we
1.482 -can't impose that burden on all the system (because it'd be a nightmare to
1.483 -configure, and because two toolchains on the same system may use different
1.484 -versions of the libraries); so we have to do it on a per-toolchain basis.
1.485 -
1.486 -So we rename all binaries of the toolchain (by adding a dot '.' as their first
1.487 -character), and add a small program, the so-called "tools wrapper", that
1.488 -correctly sets LD_LIBRARY_PATH prior to running the real tool.
1.489 -
1.490 -First, the wrapper was written as a POSIX-compliant shell script. That shell
1.491 -script is very simple, if not trivial, and works great. The only drawback is
1.492 -that it does not work on host systems that lack a shell, for example the
1.493 -MingW32 environment. To solve the issue, the wrapper has been re-written in C,
1.494 -and compiled at build time. This C wrapper is much more complex than the shell
1.495 -script, and although it sems to be working, it's been only lightly tested.
1.496 -Some of the expected short-comings with this C wrapper are;
1.497 - - multi-byte file names may not be handled correctly
1.498 - - it's really big for what it does
1.499 -
1.500 -So, the default wrapper installed with your toolchain is the shell script.
1.501 -If you know that your system is missing a shell, then you shall use the C
1.502 -wrapper (and report back whether it works, or does not work, for you).
1.503 -
1.504 -A final word on the subject: do not build shared libraries. Build them
1.505 -static, and you'll be safe.
1.506 -
1.507 -
1.508 -_______________________
1.509 - /
1.510 -Using the toolchain /
1.511 -____________________/
1.512 -
1.513 -Using the toolchain is as simple as adding the toolchain's bin directory in
1.514 -your PATH, such as:
1.515 - export PATH="${PATH}:/your/toolchain/path/bin"
1.516 -
1.517 -and then using the target tuple to tell the build systems to use your
1.518 -toolchain:
1.519 - ./configure --target=your-target-tuple
1.520 -or
1.521 - make CC=your-target-tuple-gcc
1.522 -or
1.523 - make CROSS_COMPILE=your-target-tuple-
1.524 -and so on...
1.525 -
1.526 -It is strongly advised not to use the toolchain sys-root directory as an
1.527 -install directory for your programs/packages. If you do so, you will not be
1.528 -able to use your toolchain for another project. It is even strongly advised
1.529 -that your toolchain is chmod-ed to read-only once successfully build, so that
1.530 -you don't go polluting your toolchain with your programs/packages' files.
1.531 -
1.532 -Thus, when you build a program/package, install it in a separate directory,
1.533 -eg. /your/root. This directory is the /image/ of what would be in the root file
1.534 -system of your target, and will contain all that your programs/packages have
1.535 -installed.
1.536 -
1.537 -The 'populate' script |
1.538 -----------------------+
1.539 -
1.540 -When your root directory is ready, it is still missing some important bits: the
1.541 -toolchain's libraries. To populate your root directory with those libs, just
1.542 -run:
1.543 - your-target-tuple-populate -s /your/root -d /your/root-populated
1.544 -
1.545 -This will copy /your/root into /your/root-populated, and put the needed and only
1.546 -the needed libraries there. Thus you don't polute /your/root with any cruft that
1.547 -would no longer be needed should you have to remove stuff. /your/root always
1.548 -contains only those things you install in it.
1.549 -
1.550 -You can then use /your/root-populated to build up your file system image, a
1.551 -tarball, or to NFS-mount it from your target, or whatever you need.
1.552 -
1.553 -The populate script accepts the following options:
1.554 -
1.555 - -s src_dir
1.556 - Use 'src_dir' as the un-populated root directory.
1.557 -
1.558 - -d dst_dir
1.559 - Put the populated root directory in 'dst_dir'.
1.560 -
1.561 - -l lib1 [...]
1.562 - Always add specified libraries.
1.563 -
1.564 - -L file
1.565 - Always add libraries listed in 'file'.
1.566 -
1.567 - -f
1.568 - Remove 'dst_dir' if it previously existed; continue even if any library
1.569 - specified with -l or -L is missing.
1.570 -
1.571 - -v
1.572 - Be verbose, and tell what's going on (you can see exactly where libs are
1.573 - coming from).
1.574 -
1.575 - -h
1.576 - Print the help.
1.577 -
1.578 -See 'your-target-tuple-populate -h' for more information on the options.
1.579 -
1.580 -Here is how populate works:
1.581 -
1.582 - 1) performs some sanity checks:
1.583 - - src_dir and dst_dir are specified
1.584 - - src_dir exists
1.585 - - unless forced, dst_dir does not exist
1.586 - - src_dir != dst_dir
1.587 -
1.588 - 2) copy src_dir to dst_dir
1.589 -
1.590 - 3) add forced libraries to dst_dir
1.591 - - build the list from -l and -L options
1.592 - - get forced libraries from the sysroot (see below for heuristics)
1.593 - - abort on the first missing library, unless -f is specified
1.594 -
1.595 - 4) add all missing libraries to dst_dir
1.596 - - scan dst_dir for every ELF files that are 'executable' or
1.597 - 'shared object'
1.598 - - list the "NEEDED Shared library" fields
1.599 - - check if the library is already in dst_dir/lib or dst_dir/usr/lib
1.600 - - if not, get the library from the sysroot
1.601 - - if it's in sysroot/lib, copy it to dst_dir/lib
1.602 - - if it's in sysroot/usr/lib, copy it to dst_dir/usr/lib
1.603 - - in both cases, use the SONAME of the library to create the file
1.604 - in dst_dir
1.605 - - if it was not found in the sysroot, this is an error.
1.606 -
1.607 -
1.608 -___________________
1.609 - /
1.610 -Toolchain types /
1.611 -________________/
1.612 -
1.613 -There are four kinds of toolchains you could encounter.
1.614 -
1.615 -First off, you must understand the following: when it comes to compilers there
1.616 -are up to four machines involved:
1.617 - 1) the machine configuring the toolchain components: the config machine
1.618 - 2) the machine building the toolchain components: the build machine
1.619 - 3) the machine running the toolchain: the host machine
1.620 - 4) the machine the toolchain is generating code for: the target machine
1.621 -
1.622 -We can most of the time assume that the config machine and the build machine
1.623 -are the same. Most of the time, this will be true. The only time it isn't
1.624 -is if you're using distributed compilation (such as distcc). Let's forget
1.625 -this for the sake of simplicity.
1.626 -
1.627 -So we're left with three machines:
1.628 - - build
1.629 - - host
1.630 - - target
1.631 -
1.632 -Any toolchain will involve those three machines. You can be as pretty sure of
1.633 -this as "2 and 2 are 4". Here is how they come into play:
1.634 -
1.635 -1) build == host == target
1.636 - This is a plain native toolchain, targetting the exact same machine as the
1.637 - one it is built on, and running again on this exact same machine. You have
1.638 - to build such a toolchain when you want to use an updated component, such
1.639 - as a newer gcc for example.
1.640 - crosstool-NG calls it "native".
1.641 -
1.642 -2) build == host != target
1.643 - This is a classic cross-toolchain, which is expected to be run on the same
1.644 - machine it is compiled on, and generate code to run on a second machine,
1.645 - the target.
1.646 - crosstool-NG calls it "cross".
1.647 -
1.648 -3) build != host == target
1.649 - Such a toolchain is also a native toolchain, as it targets the same machine
1.650 - as it runs on. But it is build on another machine. You want such a
1.651 - toolchain when porting to a new architecture, or if the build machine is
1.652 - much faster than the host machine.
1.653 - crosstool-NG calls it "cross-native".
1.654 -
1.655 -4) build != host != target
1.656 - This one is called a canadian-toolchain (*), and is tricky. The three
1.657 - machines in play are different. You might want such a toolchain if you
1.658 - have a fast build machine, but the users will use it on another machine,
1.659 - and will produce code to run on a third machine.
1.660 - crosstool-NG calls it "canadian".
1.661 -
1.662 -crosstool-NG can build all these kinds of toolchains (or is aiming at it,
1.663 -anyway!)
1.664 -
1.665 -(*) The term Canadian Cross came about because at the time that these issues
1.666 - were all being hashed out, Canada had three national political parties.
1.667 - http://en.wikipedia.org/wiki/Cross_compiler
1.668 -
1.669 -
1.670 -________________
1.671 - /
1.672 -Contributing /
1.673 -_____________/
1.674 -
1.675 -Sending a bug report |
1.676 ----------------------+
1.677 -
1.678 -If you need to send a bug report, please send a mail with subject
1.679 -prefixed with "[CT_NG]" with to following destinations:
1.680 - TO: yann.morin.1998 (at) anciens.enib.fr
1.681 - CC: crossgcc (at) sourceware.org
1.682 -
1.683 -Sending patches |
1.684 -----------------+
1.685 -
1.686 -If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
1.687 -
1.688 -Patches should come with the appropriate SoB line. A SoB line is typically
1.689 -something like:
1.690 - Signed-off-by: John DOE <john.doe@somewhere.net>
1.691 -
1.692 -The SoB line is clearly described in Documentation/SubmittingPatches , section
1.693 -12, of your favourite Linux kernel source tree.
1.694 -
1.695 -
1.696 -How to Use Mercurial |
1.697 ----------------------+
1.698 -
1.699 -For larger or more frequent contributions, mercurial should be used.
1.700 -
1.701 -PREREQUISITES:
1.702 -
1.703 -Configuring Mercurial:
1.704 - You need mercurial with the following extensions:
1.705 - - mq : http://mercurial.selenic.com/wiki/MqExtension
1.706 - - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
1.707 - Usually, these two extensions are already part of the installation package.
1.708 - The mq extension maintains a separate queue of your local changes
1.709 - that you can change at any later time.
1.710 - With the patchbomb extension you can email those patches directly
1.711 - from your local repo.
1.712 -
1.713 - Your configuration file for mercurial, e.g. ~/.hgrc should contain
1.714 - at least the following sections (but have a look at `man hgrc`):
1.715 - # ---
1.716 - [email]
1.717 - # configure sending patches directly via Mercurial
1.718 - from = "Your Name" <your@email.address>
1.719 - # How to send email:
1.720 - method = smtp
1.721 -
1.722 - [smtp]
1.723 - # SMTP configuration (only for method=smtp)
1.724 - host = localhost
1.725 - tls = true
1.726 - username =
1.727 - password =
1.728 -
1.729 - [extensions]
1.730 - # The following lines enable the two extensions:
1.731 - hgext.mq =
1.732 - hgext.patchbomb =
1.733 - # ----
1.734 -
1.735 -Create your local repository as a clone:
1.736 - hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
1.737 -
1.738 -Setting up the mq extension in your local copy:
1.739 - cd crosstool-ng
1.740 - hg qinit
1.741 -
1.742 -
1.743 -CREATING PATCHES:
1.744 -
1.745 -Recording your changes in the patch queue maintained by mq:
1.746 - # First, create a new patch entry in the patch queue:
1.747 - hg qnew -D -U -e short_patch_name1
1.748 - <edit patch description as commit message (see below for an example)>
1.749 -
1.750 - <now edit the ct-ng sources and check them>
1.751 -
1.752 - # if you execute `hg status` here, your modifications of the working
1.753 - # copy should show up.
1.754 -
1.755 - # Now the following command takes your modifications from the working copy
1.756 - # into the patch entry
1.757 - hg qrefresh -D [-e]
1.758 - <reedit patch description [-e] if desired>
1.759 -
1.760 - # Now your changes are recorded, and `hg status` should show a clean
1.761 - # working copy
1.762 -
1.763 -Repeat the above steps for all your modifications.
1.764 -The command `hg qseries` informs you about the content of your patch queue.
1.765 -
1.766 -
1.767 -CONTRIBUTING YOUR PATCHES:
1.768 -
1.769 -Once you are satisfied with your patch series, you can (you should!)
1.770 -contribute them back to upstream.
1.771 -This is easily done using the `hg email` command.
1.772 -
1.773 -`hg email` sends your new changesets to a specified list of recipients,
1.774 -each patch in its own email, all ordered in the way you entered them (oldest
1.775 -first). The command line flag --outgoing selects all changesets that are in
1.776 -your local but not yet in the upstream repository. Here, these are exactly
1.777 -the ones you entered into your local patch queue in the section above, so
1.778 ---outgoing is what you want.
1.779 -
1.780 -Each email gets the subject set to: "[PATCH x of n] <series summary>"
1.781 -where 'x' is the serial number in the email series, and 'n' is the total number
1.782 -of patches in the series. The body of the email is the complete patch, plus
1.783 -a handful of metadata, that helps properly apply the patch, keeping the log
1.784 -message, attribution and date, tracking file changes (move, delete, modes...)
1.785 -
1.786 -`hg email` also threads all outgoing patch emails below an introductory
1.787 -message. You should use the introductory message (command line flag --intro)
1.788 -to describe the scope and motivation for the whole patch series. The subject
1.789 -for the introductory message gets set to: "[PATCH 0 of n] <series summary>"
1.790 -and you get the chance to set the <series summary>.
1.791 -
1.792 -Here is a sample `hg email` complete command line:
1.793 -Note: replace " (at) " with "@"
1.794 -
1.795 - hg email --outgoing --intro \
1.796 - --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
1.797 - --cc 'crossgcc (at) sourceware.org'
1.798 -
1.799 - # It then opens an editor and lets you enter the subject
1.800 - # and the body for the introductory message.
1.801 -
1.802 -Use `hg email` with the additional command line switch -n to
1.803 -first have a look at the email(s) without actually sending them.
1.804 -
1.805 -
1.806 -MAINTAINING YOUR PATCHES:
1.807 -
1.808 -When the patches are refined by discussing them on the mailing list,
1.809 -you may want to finalize and resend them.
1.810 -
1.811 -The mq extension has the idiosyncrasy of imposing a stack onto the queue:
1.812 -You can always reedit/refresh only the patch on top of stack.
1.813 -The queue consists of applied and unapplied patches
1.814 -(if you reached here via the above steps, all of your patches are applied),
1.815 -where the 'stack' consists of the applied patches, and 'top of stack'
1.816 -is the latest applied patch.
1.817 -
1.818 -The following output of `hg qseries` is now used as an example:
1.819 - 0 A short_patch_name1
1.820 - 1 A short_patch_name2
1.821 - 2 A short_patch_name3
1.822 - 3 A short_patch_name4
1.823 -
1.824 -You are now able to edit patch 'short_patch_name4' (which is top of stack):
1.825 - <Edit the sources>
1.826 - # and execute again
1.827 - hg qrefresh -D [-e]
1.828 - <and optionally [-e] reedit the commit message>
1.829 -
1.830 -If you want to edit e.g. patch short_patch_name2, you have to modify
1.831 -mq's stack so this patch gets top of stack.
1.832 -For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
1.833 -
1.834 - hg qgoto short_patch_name2
1.835 - # The patch queue should now look like
1.836 - hg qseries
1.837 - 0 A short_patch_name1
1.838 - 1 A short_patch_name2
1.839 - 2 U short_patch_name3
1.840 - 3 U short_patch_name4
1.841 - # so patch # 1 (short_patch_name2) is top of stack.
1.842 - <now reedit the sources for short_patch_name2>
1.843 - # and execute again
1.844 - hg qrefresh -D [-e]
1.845 - <and optionally [-e] reedit the commit message>
1.846 - # the following command reapplies the now unapplied two patches:
1.847 - hg qpush -a
1.848 - # you can also use `hg qgoto short_patch_name4` to get there again.
1.849 -
1.850 -
1.851 -RESENDING YOUR REEDITED PATCHES:
1.852 -
1.853 -By mailing list policy, please resend your complete patch series.
1.854 ---> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
1.855 -
1.856 -
1.857 -SYNCING WITH UPSTREAM AGAIN:
1.858 -
1.859 -You can sync your repo with upstream at any time by executing
1.860 - # first unapply all your patches:
1.861 - hg qpop -a
1.862 - # next fetch new changesets from upstream
1.863 - hg pull
1.864 - # then update your working copy
1.865 - hg up
1.866 - # optionally remove already upstream integrated patches (see below)
1.867 - hg qdelete <short_name_of_already_applied_patch>
1.868 - # and reapply your patches if any non upstream-integrated left (but see below)
1.869 - hg qpush -a
1.870 -
1.871 -Eventually, your patches get included into the upstream repository
1.872 -which you initially cloned.
1.873 -In this case, before executing the hg qpush -a from above
1.874 -you should manually "hg qdelete" the patches that are already integrated upstream.
1.875 -
1.876 -
1.877 -HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
1.878 -
1.879 -Commit messages should look like (without leading pipes):
1.880 - |component: short, one-line description
1.881 - |
1.882 - |optional longer description
1.883 - |on multiple lines if needed
1.884 -
1.885 -Here is an example commit message (see revision a53a5e1d61db):
1.886 - |comp-libs/cloog: fix building
1.887 - |
1.888 - |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
1.889 - |For any later versions, the directory name does have the version, such as
1.890 - |cloog-ppl-0.15.4.
1.891 -
1.892 -_____________
1.893 - /
1.894 -Internals /
1.895 -__________/
1.896 -
1.897 -Internally, crosstool-NG is script-based. To ease usage, the frontend is
1.898 -Makefile-based.
1.899 -
1.900 -Makefile front-end |
1.901 --------------------+
1.902 -
1.903 -The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
1.904 -script with an action will act exactly as if the Makefile was in the current
1.905 -working directory and make was called with the action as rule. Thus:
1.906 - ct-ng menuconfig
1.907 -
1.908 -is equivalent to having the Makefile in CWD, and calling:
1.909 - make menuconfig
1.910 -
1.911 -Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
1.912 -traditional command.
1.913 -
1.914 -ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
1.915 -at configuration time with ./configure.
1.916 -
1.917 -ct-ng also searches for config files, sub-tools, samples, scripts and patches in
1.918 -that library directory.
1.919 -
1.920 -Because of a stupid make behavior/bug I was unable to track down, implicit make
1.921 -rules are disabled: installing with --local would triger those rules, and mconf
1.922 -was unbuildable.
1.923 -
1.924 -Kconfig parser |
1.925 ----------------+
1.926 -
1.927 -The kconfig language is a hacked version, vampirised from the Linux kernel
1.928 -(http://www.kernel.org/), and (heavily) adapted to my needs.
1.929 -
1.930 -The list of the most notable changes (at least the ones I remember) follows:
1.931 -- the CONFIG_ prefix has been replaced with CT_
1.932 -- a leading | in prompts is skipped, and subsequent leading spaces are not
1.933 - trimmed; otherwise leading spaces are silently trimmed
1.934 -- removed the warning about undefined environment variable
1.935 -
1.936 -The kconfig parsers (conf and mconf) are not installed pre-built, but as
1.937 -source files. Thus you can have the directory where crosstool-NG is installed,
1.938 -exported (via NFS or whatever) and have clients with different architectures
1.939 -use the same crosstool-NG installation, and most notably, the same set of
1.940 -patches.
1.941 -
1.942 -Architecture-specific |
1.943 -----------------------+
1.944 -
1.945 -Note: this chapter is not really well written, and might thus be a little bit
1.946 -complex to understand. To get a better grasp of what an architecture is, the
1.947 -reader is kindly encouraged to look at the "arch/" sub-directory, and to the
1.948 -existing architectures to see how things are laid out.
1.949 -
1.950 -An architecture is defined by:
1.951 -
1.952 - - a human-readable name, in lower case letters, with numbers as appropriate.
1.953 - The underscore is allowed; space and special characters are not.
1.954 - Eg.: arm, x86_64
1.955 - - a file in "config/arch/", named after the architecture's name, and suffixed
1.956 - with ".in".
1.957 - Eg.: config/arch/arm.in
1.958 - - a file in "scripts/build/arch/", named after the architecture's name, and
1.959 - suffixed with ".sh".
1.960 - Eg.: scripts/build/arch/arm.sh
1.961 -
1.962 -The architecture's ".in" file API:
1.963 - > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
1.964 - actual architecture name).
1.965 - That config option must have *neither* a type, *nor* a prompt! Also, it can
1.966 - *not* depend on any other config option (EXPERIMENTAL is managed as above).
1.967 - Eg.:
1.968 - config ARCH_arm
1.969 - + mandatory:
1.970 - defines a (terse) help entry for this architecture:
1.971 - Eg.:
1.972 - config ARCH_arm
1.973 - help
1.974 - The ARM architecture.
1.975 - + optional:
1.976 - selects adequate associated config options.
1.977 - Note: 64-bit architectures *shall* select ARCH_64
1.978 - Eg.:
1.979 - config ARCH_arm
1.980 - select ARCH_SUPPORTS_BOTH_ENDIAN
1.981 - select ARCH_DEFAULT_LE
1.982 - help
1.983 - The ARM architecture.
1.984 - Eg.:
1.985 - config ARCH_x86_64
1.986 - select ARCH_64
1.987 - help
1.988 - The x86_64 architecture.
1.989 -
1.990 - > other target-specific options, at your discretion. Note however that to
1.991 - avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
1.992 - where %arch% is again replaced by the actual architecture name.
1.993 - (Note: due to historical reasons, and lack of time to clean up the code,
1.994 - I may have left some config options that do not completely conform to
1.995 - this, as the architecture name was written all upper case. However, the
1.996 - prefix is unique among architectures, and does not cause harm).
1.997 -
1.998 -The architecture's ".sh" file API:
1.999 - > the function "CT_DoArchTupleValues"
1.1000 - + parameters: none
1.1001 - + environment:
1.1002 - - all variables from the ".config" file,
1.1003 - - the two variables "target_endian_eb" and "target_endian_el" which are
1.1004 - the endianness suffixes
1.1005 - + return value: 0 upon success, !0 upon failure
1.1006 - + provides:
1.1007 - - mandatory
1.1008 - - the environment variable CT_TARGET_ARCH
1.1009 - - contains:
1.1010 - the architecture part of the target tuple.
1.1011 - Eg.: "armeb" for big endian ARM
1.1012 - "i386" for an i386
1.1013 - + provides:
1.1014 - - optional
1.1015 - - the environment variable CT_TARGET_SYS
1.1016 - - contains:
1.1017 - the sytem part of the target tuple.
1.1018 - Eg.: "gnu" for glibc on most architectures
1.1019 - "gnueabi" for glibc on an ARM EABI
1.1020 - - defaults to:
1.1021 - - for glibc-based toolchain: "gnu"
1.1022 - - for uClibc-based toolchain: "uclibc"
1.1023 - + provides:
1.1024 - - optional
1.1025 - - the environment variables to configure the cross-gcc (defaults)
1.1026 - - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
1.1027 - - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
1.1028 - - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
1.1029 - - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
1.1030 - - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
1.1031 - - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
1.1032 - + provides:
1.1033 - - optional
1.1034 - - the environment variables to pass to the cross-gcc to build target binaries (defaults)
1.1035 - - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
1.1036 - - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
1.1037 - - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
1.1038 - - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
1.1039 - - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
1.1040 - - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
1.1041 - - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
1.1042 - - default to:
1.1043 - see above.
1.1044 - + provides:
1.1045 - - optional
1.1046 - - the environement variables to configure the core and final compiler, specific to this architecture:
1.1047 - - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
1.1048 - - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
1.1049 - - default to:
1.1050 - - all empty
1.1051 - + provides:
1.1052 - - optional
1.1053 - - the architecture-specific CFLAGS and LDFLAGS:
1.1054 - - CT_ARCH_TARGET_CLFAGS
1.1055 - - CT_ARCH_TARGET_LDFLAGS
1.1056 - - default to:
1.1057 - - all empty
1.1058 -
1.1059 -You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
1.1060 -a quite complete example of what an actual architecture description looks like.
1.1061 -
1.1062 -Kernel specific |
1.1063 -----------------+
1.1064 -
1.1065 -A kernel is defined by:
1.1066 -
1.1067 - - a human-readable name, in lower case letters, with numbers as appropriate.
1.1068 - The underscore is allowed; space and special characters are not (although
1.1069 - they are internally replaced with underscores.
1.1070 - Eg.: linux, bare-metal
1.1071 - - a file in "config/kernel/", named after the kernel name, and suffixed with
1.1072 - ".in".
1.1073 - Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
1.1074 - - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
1.1075 - with ".sh".
1.1076 - Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
1.1077 -
1.1078 -The kernel's ".in" file must contain:
1.1079 - > an optional lines containing exactly "# EXPERIMENTAL", starting on the
1.1080 - first column, and without any following space or other character.
1.1081 - If this line is present, then this kernel is considered EXPERIMENTAL,
1.1082 - and correct dependency on EXPERIMENTAL will be set.
1.1083 -
1.1084 - > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
1.1085 - replaced with the actual kernel name, with all special characters and
1.1086 - spaces replaced by underscores).
1.1087 - That config option must have *neither* a type, *nor* a prompt! Also, it can
1.1088 - *not* depends on EXPERIMENTAL.
1.1089 - Eg.: KERNEL_linux, KERNEL_bare_metal
1.1090 - + mandatory:
1.1091 - defines a (terse) help entry for this kernel.
1.1092 - Eg.:
1.1093 - config KERNEL_bare_metal
1.1094 - help
1.1095 - Build a compiler for use without any kernel.
1.1096 - + optional:
1.1097 - selects adequate associated config options.
1.1098 - Eg.:
1.1099 - config KERNEL_bare_metal
1.1100 - select BARE_METAL
1.1101 - help
1.1102 - Build a compiler for use without any kernel.
1.1103 -
1.1104 - > other kernel specific options, at your discretion. Note however that, to
1.1105 - avoid name-clashing, such options should be prefixed with
1.1106 - "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
1.1107 - the actual kernel name.
1.1108 - (Note: due to historical reasons, and lack of time to clean up the code,
1.1109 - I may have left some config options that do not completely conform to
1.1110 - this, as the kernel name was written all upper case. However, the prefix
1.1111 - is unique among kernels, and does not cause harm).
1.1112 -
1.1113 -The kernel's ".sh" file API:
1.1114 - > is a bash script fragment
1.1115 -
1.1116 - > defines the function CT_DoKernelTupleValues
1.1117 - + see the architecture's CT_DoArchTupleValues, except for:
1.1118 - + set the environment variable CT_TARGET_KERNEL, the kernel part of the
1.1119 - target tuple
1.1120 - + return value: ignored
1.1121 -
1.1122 - > defines the function "do_kernel_get":
1.1123 - + parameters: none
1.1124 - + environment:
1.1125 - - all variables from the ".config" file.
1.1126 - + return value: 0 for success, !0 for failure.
1.1127 - + behavior: download the kernel's sources, and store the tarball into
1.1128 - "${CT_TARBALLS_DIR}". To this end, a functions is available, that
1.1129 - abstracts downloading tarballs:
1.1130 - - CT_DoGet <tarball_base_name> <URL1 [URL...]>
1.1131 - Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
1.1132 - Note: retrieving sources from svn, cvs, git and the likes is not supported
1.1133 - by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
1.1134 - "scripts/build/libc/eglibc.sh"
1.1135 -
1.1136 - > defines the function "do_kernel_extract":
1.1137 - + parameters: none
1.1138 - + environment:
1.1139 - - all variables from the ".config" file,
1.1140 - + return value: 0 for success, !0 for failure.
1.1141 - + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
1.1142 - required patches. To this end, a function is available, that abstracts
1.1143 - extracting tarballs:
1.1144 - - CT_ExtractAndPatch <tarball_base_name>
1.1145 - Eg.: CT_ExtractAndPatch linux-2.6.26.5
1.1146 -
1.1147 - > defines the function "do_kernel_headers":
1.1148 - + parameters: none
1.1149 - + environment:
1.1150 - - all variables from the ".config" file,
1.1151 - + return value: 0 for success, !0 for failure.
1.1152 - + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
1.1153 -
1.1154 - > defines any kernel-specific helper functions
1.1155 - These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
1.1156 - where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
1.1157 - any name-clashing.
1.1158 -
1.1159 -You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
1.1160 -as an example of what a complex kernel description looks like.
1.1161 -
1.1162 -Adding a new version of a component |
1.1163 -------------------------------------+
1.1164 -
1.1165 -When a new component, such as the Linux kernel, gcc or any other is released,
1.1166 -adding the new version to crosstool-NG is quite easy. There is a script that
1.1167 -will do all that for you:
1.1168 - scripts/addToolVersion.sh
1.1169 -
1.1170 -Run it with no option to get some help.
1.1171 -
1.1172 -Build scripts |
1.1173 ---------------+
1.1174 -
1.1175 -To Be Written later...