1 File.........: 8 - Internals.txt
2 Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
3 License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
10 Internally, crosstool-NG is script-based. To ease usage, the frontend is
17 The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
18 script with an action will act exactly as if the Makefile was in the current
19 working directory and make was called with the action as rule. Thus:
22 is equivalent to having the Makefile in CWD, and calling:
25 Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
28 ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
29 at configuration time with ./configure.
31 ct-ng also searches for config files, sub-tools, samples, scripts and patches in
32 that library directory.
34 Because of a stupid make behavior/bug I was unable to track down, implicit make
35 rules are disabled: installing with --local would triger those rules, and mconf
42 The kconfig language is a hacked version, vampirised from the Linux kernel
43 (http://www.kernel.org/), and (heavily) adapted to my needs.
45 The list of the most notable changes (at least the ones I remember) follows:
46 - the CONFIG_ prefix has been replaced with CT_
47 - a leading | in prompts is skipped, and subsequent leading spaces are not
48 trimmed; otherwise leading spaces are silently trimmed
49 - removed the warning about undefined environment variable
51 The kconfig parsers (conf and mconf) are not installed pre-built, but as
52 source files. Thus you can have the directory where crosstool-NG is installed,
53 exported (via NFS or whatever) and have clients with different architectures
54 use the same crosstool-NG installation, and most notably, the same set of
58 Architecture-specific |
59 ----------------------+
61 Note: this chapter is not really well written, and might thus be a little bit
62 complex to understand. To get a better grasp of what an architecture is, the
63 reader is kindly encouraged to look at the "arch/" sub-directory, and to the
64 existing architectures to see how things are laid out.
66 An architecture is defined by:
68 - a human-readable name, in lower case letters, with numbers as appropriate.
69 The underscore is allowed; space and special characters are not.
71 - a file in "config/arch/", named after the architecture's name, and suffixed
73 Eg.: config/arch/arm.in
74 - a file in "scripts/build/arch/", named after the architecture's name, and
76 Eg.: scripts/build/arch/arm.sh
78 The architecture's ".in" file API:
79 > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
80 actual architecture name).
81 That config option must have *neither* a type, *nor* a prompt! Also, it can
82 *not* depend on any other config option (EXPERIMENTAL is managed as above).
86 defines a (terse) help entry for this architecture:
92 selects adequate associated config options.
93 Note: 64-bit architectures *shall* select ARCH_64
96 select ARCH_SUPPORTS_BOTH_ENDIAN
97 select ARCH_DEFAULT_LE
104 The x86_64 architecture.
106 > other target-specific options, at your discretion. Note however that to
107 avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
108 where %arch% is again replaced by the actual architecture name.
109 (Note: due to historical reasons, and lack of time to clean up the code,
110 I may have left some config options that do not completely conform to
111 this, as the architecture name was written all upper case. However, the
112 prefix is unique among architectures, and does not cause harm).
114 The architecture's ".sh" file API:
115 > the function "CT_DoArchTupleValues"
118 - all variables from the ".config" file,
119 - the two variables "target_endian_eb" and "target_endian_el" which are
120 the endianness suffixes
121 + return value: 0 upon success, !0 upon failure
124 - the environment variable CT_TARGET_ARCH
126 the architecture part of the target tuple.
127 Eg.: "armeb" for big endian ARM
131 - the environment variable CT_TARGET_SYS
133 the sytem part of the target tuple.
134 Eg.: "gnu" for glibc on most architectures
135 "gnueabi" for glibc on an ARM EABI
137 - for glibc-based toolchain: "gnu"
138 - for uClibc-based toolchain: "uclibc"
141 - the environment variables to configure the cross-gcc (defaults)
142 - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
143 - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
144 - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
145 - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
146 - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
147 - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
150 - the environment variables to pass to the cross-gcc to build target binaries (defaults)
151 - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
152 - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
153 - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
154 - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
155 - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
156 - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
157 - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
162 - the environement variables to configure the core and final compiler, specific to this architecture:
163 - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
164 - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
169 - the architecture-specific CFLAGS and LDFLAGS:
170 - CT_ARCH_TARGET_CLFAGS
171 - CT_ARCH_TARGET_LDFLAGS
175 You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
176 a quite complete example of what an actual architecture description looks like.
182 A kernel is defined by:
184 - a human-readable name, in lower case letters, with numbers as appropriate.
185 The underscore is allowed; space and special characters are not (although
186 they are internally replaced with underscores.
187 Eg.: linux, bare-metal
188 - a file in "config/kernel/", named after the kernel name, and suffixed with
190 Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
191 - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
193 Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
195 The kernel's ".in" file must contain:
196 > an optional lines containing exactly "# EXPERIMENTAL", starting on the
197 first column, and without any following space or other character.
198 If this line is present, then this kernel is considered EXPERIMENTAL,
199 and correct dependency on EXPERIMENTAL will be set.
201 > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
202 replaced with the actual kernel name, with all special characters and
203 spaces replaced by underscores).
204 That config option must have *neither* a type, *nor* a prompt! Also, it can
205 *not* depends on EXPERIMENTAL.
206 Eg.: KERNEL_linux, KERNEL_bare_metal
208 defines a (terse) help entry for this kernel.
210 config KERNEL_bare_metal
212 Build a compiler for use without any kernel.
214 selects adequate associated config options.
216 config KERNEL_bare_metal
219 Build a compiler for use without any kernel.
221 > other kernel specific options, at your discretion. Note however that, to
222 avoid name-clashing, such options should be prefixed with
223 "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
224 the actual kernel name.
225 (Note: due to historical reasons, and lack of time to clean up the code,
226 I may have left some config options that do not completely conform to
227 this, as the kernel name was written all upper case. However, the prefix
228 is unique among kernels, and does not cause harm).
230 The kernel's ".sh" file API:
231 > is a bash script fragment
233 > defines the function CT_DoKernelTupleValues
234 + see the architecture's CT_DoArchTupleValues, except for:
235 + set the environment variable CT_TARGET_KERNEL, the kernel part of the
237 + return value: ignored
239 > defines the function "do_kernel_get":
242 - all variables from the ".config" file.
243 + return value: 0 for success, !0 for failure.
244 + behavior: download the kernel's sources, and store the tarball into
245 "${CT_TARBALLS_DIR}". To this end, a functions is available, that
246 abstracts downloading tarballs:
247 - CT_DoGet <tarball_base_name> <URL1 [URL...]>
248 Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
249 Note: retrieving sources from svn, cvs, git and the likes is not supported
250 by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
251 "scripts/build/libc/eglibc.sh"
253 > defines the function "do_kernel_extract":
256 - all variables from the ".config" file,
257 + return value: 0 for success, !0 for failure.
258 + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
259 required patches. To this end, a function is available, that abstracts
261 - CT_ExtractAndPatch <tarball_base_name>
262 Eg.: CT_ExtractAndPatch linux-2.6.26.5
264 > defines the function "do_kernel_headers":
267 - all variables from the ".config" file,
268 + return value: 0 for success, !0 for failure.
269 + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
271 > defines any kernel-specific helper functions
272 These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
273 where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
276 You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
277 as an example of what a complex kernel description looks like.
280 Adding a new version of a component |
281 ------------------------------------+
283 When a new component, such as the Linux kernel, gcc or any other is released,
284 adding the new version to crosstool-NG is quite easy. There is a script that
285 will do all that for you:
286 scripts/addToolVersion.sh
288 Run it with no option to get some help.
294 To Be Written later...