1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/8 - Internals.txt Sat Aug 14 16:37:11 2010 +0200
1.3 @@ -0,0 +1,294 @@
1.4 +File.........: 8 - Internals.txt
1.5 +Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
1.6 +License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
1.7 +
1.8 +
1.9 +Internals /
1.10 +__________/
1.11 +
1.12 +
1.13 +Internally, crosstool-NG is script-based. To ease usage, the frontend is
1.14 +Makefile-based.
1.15 +
1.16 +
1.17 +Makefile front-end |
1.18 +-------------------+
1.19 +
1.20 +The entry point to crosstool-NG is the Makefile script "ct-ng". Calling this
1.21 +script with an action will act exactly as if the Makefile was in the current
1.22 +working directory and make was called with the action as rule. Thus:
1.23 + ct-ng menuconfig
1.24 +
1.25 +is equivalent to having the Makefile in CWD, and calling:
1.26 + make menuconfig
1.27 +
1.28 +Having ct-ng as it is avoids copying the Makefile everywhere, and acts as a
1.29 +traditional command.
1.30 +
1.31 +ct-ng loads sub- Makefiles from the library directory $(CT_LIB_DIR), as set up
1.32 +at configuration time with ./configure.
1.33 +
1.34 +ct-ng also searches for config files, sub-tools, samples, scripts and patches in
1.35 +that library directory.
1.36 +
1.37 +Because of a stupid make behavior/bug I was unable to track down, implicit make
1.38 +rules are disabled: installing with --local would triger those rules, and mconf
1.39 +was unbuildable.
1.40 +
1.41 +
1.42 +Kconfig parser |
1.43 +---------------+
1.44 +
1.45 +The kconfig language is a hacked version, vampirised from the Linux kernel
1.46 +(http://www.kernel.org/), and (heavily) adapted to my needs.
1.47 +
1.48 +The list of the most notable changes (at least the ones I remember) follows:
1.49 +- the CONFIG_ prefix has been replaced with CT_
1.50 +- a leading | in prompts is skipped, and subsequent leading spaces are not
1.51 + trimmed; otherwise leading spaces are silently trimmed
1.52 +- removed the warning about undefined environment variable
1.53 +
1.54 +The kconfig parsers (conf and mconf) are not installed pre-built, but as
1.55 +source files. Thus you can have the directory where crosstool-NG is installed,
1.56 +exported (via NFS or whatever) and have clients with different architectures
1.57 +use the same crosstool-NG installation, and most notably, the same set of
1.58 +patches.
1.59 +
1.60 +
1.61 +Architecture-specific |
1.62 +----------------------+
1.63 +
1.64 +Note: this chapter is not really well written, and might thus be a little bit
1.65 +complex to understand. To get a better grasp of what an architecture is, the
1.66 +reader is kindly encouraged to look at the "arch/" sub-directory, and to the
1.67 +existing architectures to see how things are laid out.
1.68 +
1.69 +An architecture is defined by:
1.70 +
1.71 + - a human-readable name, in lower case letters, with numbers as appropriate.
1.72 + The underscore is allowed; space and special characters are not.
1.73 + Eg.: arm, x86_64
1.74 + - a file in "config/arch/", named after the architecture's name, and suffixed
1.75 + with ".in".
1.76 + Eg.: config/arch/arm.in
1.77 + - a file in "scripts/build/arch/", named after the architecture's name, and
1.78 + suffixed with ".sh".
1.79 + Eg.: scripts/build/arch/arm.sh
1.80 +
1.81 +The architecture's ".in" file API:
1.82 + > the config option "ARCH_%arch%" (where %arch% is to be replaced with the
1.83 + actual architecture name).
1.84 + That config option must have *neither* a type, *nor* a prompt! Also, it can
1.85 + *not* depend on any other config option (EXPERIMENTAL is managed as above).
1.86 + Eg.:
1.87 + config ARCH_arm
1.88 + + mandatory:
1.89 + defines a (terse) help entry for this architecture:
1.90 + Eg.:
1.91 + config ARCH_arm
1.92 + help
1.93 + The ARM architecture.
1.94 + + optional:
1.95 + selects adequate associated config options.
1.96 + Note: 64-bit architectures *shall* select ARCH_64
1.97 + Eg.:
1.98 + config ARCH_arm
1.99 + select ARCH_SUPPORTS_BOTH_ENDIAN
1.100 + select ARCH_DEFAULT_LE
1.101 + help
1.102 + The ARM architecture.
1.103 + Eg.:
1.104 + config ARCH_x86_64
1.105 + select ARCH_64
1.106 + help
1.107 + The x86_64 architecture.
1.108 +
1.109 + > other target-specific options, at your discretion. Note however that to
1.110 + avoid name-clashing, such options shall be prefixed with "ARCH_%arch%",
1.111 + where %arch% is again replaced by the actual architecture name.
1.112 + (Note: due to historical reasons, and lack of time to clean up the code,
1.113 + I may have left some config options that do not completely conform to
1.114 + this, as the architecture name was written all upper case. However, the
1.115 + prefix is unique among architectures, and does not cause harm).
1.116 +
1.117 +The architecture's ".sh" file API:
1.118 + > the function "CT_DoArchTupleValues"
1.119 + + parameters: none
1.120 + + environment:
1.121 + - all variables from the ".config" file,
1.122 + - the two variables "target_endian_eb" and "target_endian_el" which are
1.123 + the endianness suffixes
1.124 + + return value: 0 upon success, !0 upon failure
1.125 + + provides:
1.126 + - mandatory
1.127 + - the environment variable CT_TARGET_ARCH
1.128 + - contains:
1.129 + the architecture part of the target tuple.
1.130 + Eg.: "armeb" for big endian ARM
1.131 + "i386" for an i386
1.132 + + provides:
1.133 + - optional
1.134 + - the environment variable CT_TARGET_SYS
1.135 + - contains:
1.136 + the sytem part of the target tuple.
1.137 + Eg.: "gnu" for glibc on most architectures
1.138 + "gnueabi" for glibc on an ARM EABI
1.139 + - defaults to:
1.140 + - for glibc-based toolchain: "gnu"
1.141 + - for uClibc-based toolchain: "uclibc"
1.142 + + provides:
1.143 + - optional
1.144 + - the environment variables to configure the cross-gcc (defaults)
1.145 + - CT_ARCH_WITH_ARCH : the gcc ./configure switch to select architecture level ( "--with-arch=${CT_ARCH_ARCH}" )
1.146 + - CT_ARCH_WITH_ABI : the gcc ./configure switch to select ABI level ( "--with-abi=${CT_ARCH_ABI}" )
1.147 + - CT_ARCH_WITH_CPU : the gcc ./configure switch to select CPU instruction set ( "--with-cpu=${CT_ARCH_CPU}" )
1.148 + - CT_ARCH_WITH_TUNE : the gcc ./configure switch to select scheduling ( "--with-tune=${CT_ARCH_TUNE}" )
1.149 + - CT_ARCH_WITH_FPU : the gcc ./configure switch to select FPU type ( "--with-fpu=${CT_ARCH_FPU}" )
1.150 + - CT_ARCH_WITH_FLOAT : the gcc ./configure switch to select floating point arithmetics ( "--with-float=soft" or /empty/ )
1.151 + + provides:
1.152 + - optional
1.153 + - the environment variables to pass to the cross-gcc to build target binaries (defaults)
1.154 + - CT_ARCH_ARCH_CFLAG : the gcc switch to select architecture level ( "-march=${CT_ARCH_ARCH}" )
1.155 + - CT_ARCH_ABI_CFLAG : the gcc switch to select ABI level ( "-mabi=${CT_ARCH_ABI}" )
1.156 + - CT_ARCH_CPU_CFLAG : the gcc switch to select CPU instruction set ( "-mcpu=${CT_ARCH_CPU}" )
1.157 + - CT_ARCH_TUNE_CFLAG : the gcc switch to select scheduling ( "-mtune=${CT_ARCH_TUNE}" )
1.158 + - CT_ARCH_FPU_CFLAG : the gcc switch to select FPU type ( "-mfpu=${CT_ARCH_FPU}" )
1.159 + - CT_ARCH_FLOAT_CFLAG : the gcc switch to choose floating point arithmetics ( "-msoft-float" or /empty/ )
1.160 + - CT_ARCH_ENDIAN_CFLAG : the gcc switch to choose big or little endian ( "-mbig-endian" or "-mlittle-endian" )
1.161 + - default to:
1.162 + see above.
1.163 + + provides:
1.164 + - optional
1.165 + - the environement variables to configure the core and final compiler, specific to this architecture:
1.166 + - CT_ARCH_CC_CORE_EXTRA_CONFIG : additional, architecture specific core gcc ./configure flags
1.167 + - CT_ARCH_CC_EXTRA_CONFIG : additional, architecture specific final gcc ./configure flags
1.168 + - default to:
1.169 + - all empty
1.170 + + provides:
1.171 + - optional
1.172 + - the architecture-specific CFLAGS and LDFLAGS:
1.173 + - CT_ARCH_TARGET_CLFAGS
1.174 + - CT_ARCH_TARGET_LDFLAGS
1.175 + - default to:
1.176 + - all empty
1.177 +
1.178 +You can have a look at "config/arch/arm.in" and "scripts/build/arch/arm.sh" for
1.179 +a quite complete example of what an actual architecture description looks like.
1.180 +
1.181 +
1.182 +Kernel specific |
1.183 +----------------+
1.184 +
1.185 +A kernel is defined by:
1.186 +
1.187 + - a human-readable name, in lower case letters, with numbers as appropriate.
1.188 + The underscore is allowed; space and special characters are not (although
1.189 + they are internally replaced with underscores.
1.190 + Eg.: linux, bare-metal
1.191 + - a file in "config/kernel/", named after the kernel name, and suffixed with
1.192 + ".in".
1.193 + Eg.: config/kernel/linux.in, config/kernel/bare-metal.in
1.194 + - a file in "scripts/build/kernel/", named after the kernel name, and suffixed
1.195 + with ".sh".
1.196 + Eg.: scripts/build/kernel/linux.sh, scripts/build/kernel/bare-metal.sh
1.197 +
1.198 +The kernel's ".in" file must contain:
1.199 + > an optional lines containing exactly "# EXPERIMENTAL", starting on the
1.200 + first column, and without any following space or other character.
1.201 + If this line is present, then this kernel is considered EXPERIMENTAL,
1.202 + and correct dependency on EXPERIMENTAL will be set.
1.203 +
1.204 + > the config option "KERNEL_%kernel_name%" (where %kernel_name% is to be
1.205 + replaced with the actual kernel name, with all special characters and
1.206 + spaces replaced by underscores).
1.207 + That config option must have *neither* a type, *nor* a prompt! Also, it can
1.208 + *not* depends on EXPERIMENTAL.
1.209 + Eg.: KERNEL_linux, KERNEL_bare_metal
1.210 + + mandatory:
1.211 + defines a (terse) help entry for this kernel.
1.212 + Eg.:
1.213 + config KERNEL_bare_metal
1.214 + help
1.215 + Build a compiler for use without any kernel.
1.216 + + optional:
1.217 + selects adequate associated config options.
1.218 + Eg.:
1.219 + config KERNEL_bare_metal
1.220 + select BARE_METAL
1.221 + help
1.222 + Build a compiler for use without any kernel.
1.223 +
1.224 + > other kernel specific options, at your discretion. Note however that, to
1.225 + avoid name-clashing, such options should be prefixed with
1.226 + "KERNEL_%kernel_name%", where %kernel_name% is again tp be replaced with
1.227 + the actual kernel name.
1.228 + (Note: due to historical reasons, and lack of time to clean up the code,
1.229 + I may have left some config options that do not completely conform to
1.230 + this, as the kernel name was written all upper case. However, the prefix
1.231 + is unique among kernels, and does not cause harm).
1.232 +
1.233 +The kernel's ".sh" file API:
1.234 + > is a bash script fragment
1.235 +
1.236 + > defines the function CT_DoKernelTupleValues
1.237 + + see the architecture's CT_DoArchTupleValues, except for:
1.238 + + set the environment variable CT_TARGET_KERNEL, the kernel part of the
1.239 + target tuple
1.240 + + return value: ignored
1.241 +
1.242 + > defines the function "do_kernel_get":
1.243 + + parameters: none
1.244 + + environment:
1.245 + - all variables from the ".config" file.
1.246 + + return value: 0 for success, !0 for failure.
1.247 + + behavior: download the kernel's sources, and store the tarball into
1.248 + "${CT_TARBALLS_DIR}". To this end, a functions is available, that
1.249 + abstracts downloading tarballs:
1.250 + - CT_DoGet <tarball_base_name> <URL1 [URL...]>
1.251 + Eg.: CT_DoGet linux-2.6.26.5 ftp://ftp.kernel.org/pub/linux/kernel/v2.6
1.252 + Note: retrieving sources from svn, cvs, git and the likes is not supported
1.253 + by CT_DoGet. You'll have to do this by hand, as it is done for eglibc in
1.254 + "scripts/build/libc/eglibc.sh"
1.255 +
1.256 + > defines the function "do_kernel_extract":
1.257 + + parameters: none
1.258 + + environment:
1.259 + - all variables from the ".config" file,
1.260 + + return value: 0 for success, !0 for failure.
1.261 + + behavior: extract the kernel's tarball into "${CT_SRC_DIR}", and apply
1.262 + required patches. To this end, a function is available, that abstracts
1.263 + extracting tarballs:
1.264 + - CT_ExtractAndPatch <tarball_base_name>
1.265 + Eg.: CT_ExtractAndPatch linux-2.6.26.5
1.266 +
1.267 + > defines the function "do_kernel_headers":
1.268 + + parameters: none
1.269 + + environment:
1.270 + - all variables from the ".config" file,
1.271 + + return value: 0 for success, !0 for failure.
1.272 + + behavior: install the kernel headers (if any) in "${CT_SYSROOT_DIR}/usr/include"
1.273 +
1.274 + > defines any kernel-specific helper functions
1.275 + These functions, if any, must be prefixed with "do_kernel_%CT_KERNEL%_",
1.276 + where '%CT_KERNEL%' is to be replaced with the actual kernel name, to avoid
1.277 + any name-clashing.
1.278 +
1.279 +You can have a look at "config/kernel/linux.in" and "scripts/build/kernel/linux.sh"
1.280 +as an example of what a complex kernel description looks like.
1.281 +
1.282 +
1.283 +Adding a new version of a component |
1.284 +------------------------------------+
1.285 +
1.286 +When a new component, such as the Linux kernel, gcc or any other is released,
1.287 +adding the new version to crosstool-NG is quite easy. There is a script that
1.288 +will do all that for you:
1.289 + scripts/addToolVersion.sh
1.290 +
1.291 +Run it with no option to get some help.
1.292 +
1.293 +
1.294 +Build scripts |
1.295 +--------------+
1.296 +
1.297 +To Be Written later...