diff options
author | Chris Johns <chrisj@rtems.org> | 2013-02-26 17:55:39 +1100 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2013-02-26 17:55:39 +1100 |
commit | 6e4f5e705e4146b50d1684e6e54ad5f8d542254b (patch) | |
tree | 7536246354f95bd3e33ae08d867fcef63fef2f5e /doc | |
parent | Make the doco more visiable. (diff) | |
download | rtems-source-builder-6e4f5e705e4146b50d1684e6e54ad5f8d542254b.tar.bz2 |
Updated doco.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/source-builder.txt | 879 |
1 files changed, 514 insertions, 365 deletions
diff --git a/doc/source-builder.txt b/doc/source-builder.txt index a77c85f..caf4a34 100644 --- a/doc/source-builder.txt +++ b/doc/source-builder.txt @@ -197,7 +197,7 @@ Examining: ../source-builder/config <2> Building ~~~~~~~~ -In this quick start I will build an SPARC tool set. +In this quick start I will build a SPARC tool set. ------------------------------------------------------------- $ ../source-builder/sb-set-builder --log=l-sparc.txt <1> \ @@ -550,7 +550,7 @@ and have a file extension of +.bset+. Build sets can define macro variables, inline include other files and reference other build set or package configuration files. -Defining macros is performed with the +%define+ directive: +Defining macros is performed with the +%define+ macro: ------------------------------------------------------------- %define _target m32r-rtems4.11 @@ -559,9 +559,9 @@ Defining macros is performed with the +%define+ directive: The top level RTEMS build set files specify the target. This is used by other referenced files or an undefined macro error is reported. -Inline including another file with the +%include+ directive continues -processing with the specified file returning to carry on from just after the -include point. +Inline including another file with the +%include+ macro continues processing +with the specified file returning to carry on from just after the include +point. ------------------------------------------------------------- %include rtems-4.11-base.bset @@ -584,8 +584,67 @@ instance of the build set processor is created and if the file is a package configuration the package is built. This all happens once the build set file has finished being scanned. -Configuration Files -~~~~~~~~~~~~~~~~~~~ +Configuration Control +~~~~~~~~~~~~~~~~~~~~~ + +The RTEMS Souce Builder is designed to fit within most verification and +validation processes. All of the RTEMS Source Builder is source code. The +Python code is source and comes with a commercial friendly license. All +configuration data is text and can be read or parsed with standard text based +tools. + +File naming provides configuration management. A specific version of a package +is captured in a specific set of configuration files. The top level +configuration file referenced in a _build set_ or passed to the +sb-builder+ +command relates to a specific configuration of the package being built. For +example the RTEMS configuration file +rtems-gcc-4.7.2-newlib-2.0.0-1.cfg+ +creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the +Newlib version is 2.0.0, plus any RTEMS specific patches that related to this +version. The configuration defines the version numbers of the various parts +that make up this package: + +------------------------------------------------------------- +%define gcc_version 4.7.2 +%define newlib_version 2.0.0 +%define mpfr_version 3.0.1 +%define mpc_version 0.8.2 +%define gmp_version 5.0.5 +------------------------------------------------------------- + +The package build options, if there are any are also defined: + +------------------------------------------------------------- +%define with_threads 1 +%define with_plugin 0 +%define with_iconv 1 +------------------------------------------------------------- + +The generic configuration may provide defaults incase options are not +specified. The patches this specific version of the package requires can be +included: + +------------------------------------------------------------- +Patch0: gcc-4.7.2-rtems4.11-20121026.diff +------------------------------------------------------------- + +Finally including the GCC 4.7 configuration script: + +------------------------------------------------------------- +%include %{_configdir}/gcc-4.7-1.cfg +------------------------------------------------------------- + +The +gcc-4.7-1.cfg+ is a generic script to build a GCC 4.7 compiler with +Newlib. It is not specific to RTEMS. A bare no operating system tool set can be +built with this file. + +The +-1+ part of the file names is a revision. The GCC 4.7 script maybe revised +to fix a problem and if this fix effects an existing script the file is copied +and given a +-2+ revision number. Any dependent scripts referencing the earlier +revision number will not be effected by the change. This locks down a specific +configuration over time. + +Configuration Script Language +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Configuration files specify how to build a package. Configuration files are scripts and have a +.cfg+ file extension. The script format is based loosely on @@ -593,10 +652,7 @@ the RPM spec file format how-ever the use and purpose in this tool does not compare with the functionality and therefore the important features of the spec format RPM needs and uses. -Script Language -~~~~~~~~~~~~~~~ - -The script language is implemented in terms of directives. The directive list is: +The script language is implemented in terms of macross. The builtin list is: [horizontal] +%prep+:: The source preparation shell commands. @@ -604,15 +660,14 @@ The script language is implemented in terms of directives. The directive list is +%install+:: The package install shell commands. +%clean+:: The package clean shell commands. +%include+:: Inline include another configuration file. -+%package+:: The package being built. +%name+:: The name of the package. -+%description+:: A package description. Useful when reporting about a build. ++%summary+:: A brief package description. Useful when reporting about a build. +%release+:: The package release. A number that is the release as built by this tool. +%version+:: The package's verison string. +%buildarch+:: The build architecture. +%setup+:: Setup a source package. -+%source+:: Define a source code package. This directive is number. -+%patch+:: Define a patch. This directive is number. ++%source+:: Define a source code package. This macro has a number appended. ++%patch+:: Define a patch. This macro has a is number appended. +%warning+:: Print the following string as a warning and continue. +%error+:: Print the following string as an error and exit. +%define+:: Define a macro. Macros cannot be redefined, you must first undefine it. @@ -632,13 +687,13 @@ command line option. %prep ^^^^^ -The +%prep+ directive starts a block that continues until the next block -directive. The _prep_ or preparation block defines the setup of the package's -source and is a mix of RTEMS Source Builder directives and shell scripting. The -sequence is typically +%setup+ directives for source, +%patch+ directives to -patch the source mixed with some shell commands to correct any source issues. -A +%prep+ section starts with a +%setup+ command. This creates the package -source top level directory then is followed by the first source file. +The +%prep+ macro starts a block that continues until the next block macro. The +_prep_ or preparation block defines the setup of the package's source and is a +mix of RTEMS Source Builder macros and shell scripting. The sequence is +typically +%setup+ macros for source, +%patch+ macros to patch the source +mixed with some shell commands to correct any source issues. A +%prep+ section +starts with a +%setup+ command. This creates the package source top level +directory then is followed by the first source file. ------------------------------------------------------------- <1> <2> @@ -649,7 +704,7 @@ source top level directory then is followed by the first source file. <1> The package's name. <2> The version of the package. -The source for a package is declared with the +%source*+ directive where +*+ is +The source for a package is declared with the +%source*+ macro where +*+ is a number. For example +%source0+ is the source 0 tar file and is defined with something similar to this: @@ -665,11 +720,11 @@ been downloaded. If not found in the source cache directory the package is downloaded from the URL. You can append other base URLs via the command line option +--url+. This option accepts a comma delimited list of sites to try. -You can combine the source directive with connditional logic to implement a -default that can be overriden in the top level files. This lets you reuse a -generic build script with different sources. This happens if you have a private -source package with local modifications. The following example is taken from -the +gcc-4.8-1.cfg+ build script. +You can combine the source macro with connditional logic to implement a default +that can be overriden in the top level files. This lets you reuse a generic +build script with different sources. This happens if you have a private source +package with local modifications. The following example is taken from the ++gcc-4.8-1.cfg+ build script. ------------------------------------------------------------- %ifn %{defined Source0} @@ -678,7 +733,7 @@ the +gcc-4.8-1.cfg+ build script. %endif ------------------------------------------------------------- -<1> The version control directive is currently not implemented. +<1> The version control macro is currently not implemented. You could optionally have a few source files that make up the package. For example GNU's GCC was a few tar files for a while and it is now a single tar @@ -723,16 +778,16 @@ cd .. <3> <1> Change from the top of the source tree into the package being patched's top directory. <2> The conditional macro expansion checks if +%patch0+ is defined and if - defined issues the +%patch0" directive giving +-p1+ to the patch command. + defined issues the +%patch0" macro giving +-p1+ to the patch command. <3> Return back to the top of the source tree. %build ^^^^^^ -The +%build+ directive starts a block that continues until the next block -directive. The build block is a series of shell commands that execute to build -the package. It assumes all source code has been unpacked, patch and adjusted -so the build will succeed. +The +%build+ macro starts a block that continues until the next block +macro. The build block is a series of shell commands that execute to build the +package. It assumes all source code has been unpacked, patch and adjusted so +the build will succeed. The following is an example take from the GutHub STLink project [footnote: STLink is a JTAG debugging device for the ST ARM family of processors.]: @@ -771,7 +826,7 @@ STLink is a JTAG debugging device for the ST ARM family of processors.]: <4> Flags for a crosscompiled build. <5> Various settings passed to configure to customise the build. In this example an include path is being set to the install point of _libusb_. This - package requires _libusb_ is build before it. + package requires _libusb_ is built before it. <6> The +configure+ command. The RTEMS Source Builder provides all the needed paths as macro variables. You just need to provide them to +configure+. <7> Running make. Do not use +make+ directly, use the RTEMS Source Builder's @@ -784,14 +839,14 @@ STLink is a JTAG debugging device for the ST ARM family of processors.]: %install ^^^^^^^^ -The +%install+ directive starts a block that continues until the next block -directive. The install block is a series of shell commands that execute to -install the package. You can assumes the package has build correctly when this -shell script executes. +The +%install+ macro starts a block that continues until the next block +macro. The install block is a series of shell commands that execute to install +the package. You can assume the package has build correctly when this block +starts executing. Never install the package to the actual _prefix_ the package was built with. Always install to the RTEMS Source Builder's temporary path defined in -the macro variable +__tmpdir+. The RTEMS Source Builder sets up a shell +the macro variable +\__tmpdir+. The RTEMS Source Builder sets up a shell environment variable called +SB_BUILD_ROOT+ as the standard install point. Most packages support adding +DESTDIR=+ to the _make install_ command. @@ -814,406 +869,375 @@ Looking at the same example as in <<_build, %build>>: install. <3> Enter the build directory. In this example it just happens to be the source directory. -<4> Run +make install_ to install the package overriding the +DESTDIR+ make +<4> Run +make install+ to install the package overriding the +DESTDIR+ make variable. %clean ^^^^^^ +The +%clean+ macro starts a block that continues until the next block +macro. The clean block is a series of shell commands that execute to clean up +after a package has been built and install. This macro is currenly not been +used because the RTEMS Source Builder automatically cleans up. + %include ^^^^^^^^ -%package -^^^^^^^^ +The +%include+ macro inline includes the specific file. The +\__confdir+ +path is searched. Any relative path component of the include file is appended +to each part of the +\__configdir+. Adding an extension is optional as files +with +.bset+ and +.cfg+ are automatically searched for. + +Inline including means the file is processed as part of the configuration at +the point it is included. Parsing continues from the next line in the +configuration file that contains the +%include+ macro. + +Including files allow a kind of configuration file reuse. The outter +configuration files provide specific information such as package version +numbers and patches and then include a generic configuration script which +builds the package. + +------------------------------------------------------------- +%include %{_configdir}/gcc-4.7-1.cfg +------------------------------------------------------------- %name ^^^^^ -%description -^^^^^^^^^^^^ +The name of the package being built. The name typically contains the components +of the package and their version number plus a revision number. For the GCC +with Newlib configuration the name is typically: + +------------------------------------------------------------- +Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release} +------------------------------------------------------------- + +%summary +^^^^^^^^ + +The +%summary+ is a brief description of the package. It is useful when +reporting. This information is not capture in the package anywhere. For the GCC +with Newlib configuration the summary is typically: + +------------------------------------------------------------- +Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host} +------------------------------------------------------------- %release ^^^^^^^^ +The +%release+ is packaging number that allows revisions of a package to happen +where none package versions change. This value typically increases when the +configuration building the package changes. + +------------------------------------------------------------- +%define release 1 +------------------------------------------------------------- + %version ^^^^^^^^ +The +%version% macro sets the version the package. If the package is a single +component it tracks that component's version number. For example in the +_libusb_ configuration the +%version+ is the same as +%libusb_version+, +how-ever in a GCC with Newlib configuration there is no single version +number. In this case the GCC version is used. + +------------------------------------------------------------- +Version: %{gcc_version} +------------------------------------------------------------- + %buildarch ^^^^^^^^^^ -%setup -^^^^^^ - -%source -^^^^^^^ +The +%buildarch+ macro is set to the architecture the package contains. This is +currently not used in the RTEMS Source Builder and may go away. This macro is +more important in a real packaging system where the package could end up on the +wrong architecture. -%patch +%setup ^^^^^^ -%warning -^^^^^^^^ +The +%setup+ macro sets up the source code tree and is used in the +%prep+ +section of the script. The options are: -%error -^^^^^^ +[horizontal] +*Switch*:: *Description* ++-n+:: The -n option is used to set the name of the software's build +directory. This is necessary only when the source archive unpacks into a +directory named other than +<name>-<version>+. ++-c+:: The -c option is used to direct %setup to create the top-level build +directory before unpacking the sources. ++-D+:: The -D option is used to direct %setup to not delete the build directory +prior to unpacking the sources. This option is used when more than one source +archive is to be unpacked into the build directory, normally with the +-b+ or ++-a+ options. ++-T+:: The -T option is used to direct %setup to not perform the default +unpacking of the source archive specified by the first Source: macro. It is used +with the +-a+ or +-b+ options. ++-b <n>+:: The -b option is used to direct %setup to unpack the source archive +specified on the nth Source: macro line before changing directory into the build +directory. ++-a <n>+:: The -a option is used to direct %setup to unpack the source archive +specified on the nth Source: macro line after changing directory into the build +directory. -%define +%source ^^^^^^^ -%undefine -^^^^^^^^^ +The +%source+ macro is numbered and defines a source tar file used in the +package. The +%setup+ macro references the packages defined here. A macro is +defined as: -%if -^^^ - -%ifn -^^^^ - -%ifarch -^^^^^^^ +------------------------------------------------------------- +Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 +------------------------------------------------------------- -%ifnarch -^^^^^^^^ +The setup script is: -%ifos -^^^^^ +------------------------------------------------------------- +%setup -q -T -D -n %{name}-%{version} -a0 +------------------------------------------------------------- -%else -^^^^^ +The +-a0+ means use +%source0+. -%endfi +%patch ^^^^^^ -%bconf_with -^^^^^^^^^^^ - -%bconf_without -^^^^^^^^^^^^^^ +The +%patch+ macro is numbered and can define a patch and in the +%prep+ +section applies the patch. To define a patch append a +:+ followed by the patch +filename: +------------------------------------------------------------- +Patch0: gcc-4.7.2-rtems4.11-20121026.diff +------------------------------------------------------------- -RTEMS Build Sets ----------------- +The +__patchdir+ path is search. -Configuration files are typically structured as outer files that are specific -to a version of the package being built and become more generic as you move -deeper. The outter layers are required to define various macro. +Placing +%patch+ in the +%prep+ section will apply it with any trailing options +passed to the +patch+ command. This allows the +-p+ option to be passed to +strip any leading path components from the patch contents. +------------------------------------------------------------- +%patch0 -p1 +------------------------------------------------------------- -Set Builder and the Builder -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You will typically see the patch conditionally used as: -The RTEMS Source Builder provides two commands, the +sb-set-builder+ to build sets of -packages and the +sb-builder+ to build a specific package. The set builder uses -the builder to build a set of packages. You could write a shell script that did -the same thing so the set builder is a convenience command that allows you to -define and control specific features of the packages you are building. The set -builder looks for files with the +.bset" extension in the +config+ -directories. The builder command uses configuration files which have the +.cfg+ -file extension to control the build. The configuration files are written in a -script language based on the _spec_ format the RPM builder uses. They also -live in the +config+ directories. +------------------------------------------------------------- +%{patch0:%patch0 -p1} +------------------------------------------------------------- -The build set files for the RTEMS 4.11 can be found in +rtems/4.11/+. There is -one per architecture RTEMS supports. This allows variation between -architectures is bugs or patches are needed. Sometimes a specific version of a -tool may needed to resolve an issue in an architecture, how-ever that version -may have a bug in another architecture. We also want to limit architecture -specific patches to the architecture it relates to. This avoids any crosstalk a -patch may have with another architecture. An example of this is the NIOS2 -tools. They are built using a version of GCC released by Altera currently not -in the Free Software Foundation's GCC project. +In this case the patch will only be applied if it is defined. -This is the build set for the Blackfin processor or +bfin+. +%warning +^^^^^^^^ -------------------------------------------------------------- -# -# Tools Set for RTEMS 4.10 -# +The +%warning+ macro outputs the following string as a warning. -%define rtems_version 4.10 <1> +%error +^^^^^^ -%define release 1 <2> +The +%error+ macro outputs the follow string as an error and exits the RTEMS +Source Builder. -package: rtems-%{rtems_version}-%{_target}-%{release} <3> +%define +^^^^^^^ -# -# Project custom message -# -%define gcc_version_message RTEMS %{rtems_version}-%{release},gcc-%{gcc_version}/newlib-%{newlib_version} <4> +The +%define+ macro defines a new macro. If the macro being defined already +exists a warning is raised. If you value is given it is assumed to be 1. -# -# Tools configuration. -# -rtems-binutils-2.20.1-1 <5> -rtems-gcc-4.4.7-newlib-1.18.0-1 -rtems-gdb-7.3.1-1 +------------------------------------------------------------- +%define foo bar +%define one_plus_one 2 +%define one <1> ------------------------------------------------------------- -<1> Define the version of RTEMS. -<2> Define the release. This allows us to number the tool releases. -<3> The top level name of the package. The finaly tar file name. -<4> The GCC configuration allow a custom message to be embedded into GCC. -<5> The list of packages this build set contains. +<1> The macro _one_ is set to 1. -Currently the syntax of the set builder scripts is limited. It support -comments, the package command, macros (the +%{}+), and defining macros -(+%define+). It is planned to allow more of the configuration file syntax in -the future. +%undefine +^^^^^^^^^ -The builder uses configuration files that allow the full range of the -configuration script syntax. Configuration files follow most of the RPM spec -file format. They support macros and logic as well as the ability to include -other configuration files. The ability to include other configuration files -allow a simple way to configuration control the builds. Configuration files -have four main areas: +The +%undefine+ macro removes a macro if it exists. Any further references to +it will result in an undefine macro error. -. Descriptions and definitions. -+ -The description lists various useful pieces of information about the -package. None of this is currently enforced how-ever it is good practice to -provide it. The definitions are the sources and the patches. -. Preparation +%if +^^^ + +The +%if+ macro starts a conditional logic block that can optionally have a +_else_ section. A test follows this macro and can have the following operators: + +[horizontal] +*Operator*:: *Description* ++%{}+:: Check the macro is set or _true_, ie non-zero. + -The preparation is the set up of the source code ready for building. The set up -follows the unusual command structure used by RPM. The follwing macro -trickshows how to conditional patch the source if a patch has been declared. +------------------------------------------------------------- +%if ${foo} + %warning The test passes, must not be empty or is non-zero +%else + %error The test fails, must be empty or zero +%endif +------------------------------------------------------------- ++!+:: The _not_ operator inverts the test of the macro. + ------------------------------------------------------------- -cd expat-%{expat_version} -%{?patch0:%patch0 -p1} -cd .. +%if ! ${foo} + %warning The test passes, must be empty or zero +%else + %error The test fails, must not be empty or is non-zero +%endif ------------------------------------------------------------- ++==+:: The left hand size must equal the right hand side. For example: + -. Build +------------------------------------------------------------- +%define one 1 +%if ${one} == 1 + %warning The test passes +%else + %error The test fails +%endif +------------------------------------------------------------- + -The build phase. This is a fragment of shell script that can be mixed with -conditional configuration scripting to create the list of build commands. +You can also check to see if a macro is empty: + -. Install +------------------------------------------------------------- +%if ${nothing} == %{nil} + %warning The test passes +%else + %error The test fails +%endif +------------------------------------------------------------- ++!=+:: The left hand size does not equal the right hand side. For example: + -The install phase. Again this is a fragment of shell script. - -This is a configuration script to build gdb: - ------------------------------------------------------------- -# -# GDB 7.xx Version 1. -# -# This configuration file configure's, make's and install's gdb. -# - -%include %{_configdir}/checks.cfg <1> - -Name: %{_target}-gdb-%{gdb_version}-%{release} <2> -Summary: GDB v%{gdb_version} for target %{_target} on host %{_host} -Version: %{gdb_version} -Release: %{release} -URL: http://www.gnu.org/software/gdb/ -BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n) - -# -# Source -# -Source0: http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2 <3> -VersionControl0 git clone git://sourceware.org/git/gdb.git - -# -# Prepare the source code. -# -%prep <4> -%setup -q -c -T -n %{name}-%{version} -cd gdb-%{gdb_version} -%{?patch0:%patch0 -p1} -cd .. - -%build <5> - export PATH="%{_bindir}:${PATH}" - mkdir -p build - cd build -%if "%{_build}" != "%{_host}" - CFLAGS_FOR_BUILD="-g -O2 -Wall" \ +%define one 1 +%if ${one} != 2 + %warning The test passes +%else + %error The test fails %endif - CFLAGS="$SB_OPT_FLAGS" \ - ../gdb-%{gdb_version}/configure \ - --build=%{_build} --host=%{_host} \ - --target=%{_target} \ - --verbose --disable-nls \ - --without-included-gettext \ - --disable-win32-registry \ - --disable-werror \ - --enable-sim \ - --with-expat \ - --with-python \ - --prefix=%{_prefix} --bindir=%{_bindir} \ - --exec-prefix=%{_exec_prefix} \ - --includedir=%{_includedir} --libdir=%{_libdir} \ - --mandir=%{_mandir} --infodir=%{_infodir} - - %{__make} %{?_smp_mflags} all - cd .. - -%install <6> - export PATH="%{_bindir}:${PATH}" - rm -rf $SB_BUILD_ROOT - - cd build - %{__make} DESTDIR=$SB_BUILD_ROOT install - - # Dropped in FSF-binutils-2.9.5, but Cygwin still ships it. - rm -rf $SB_BUILD_ROOT%{_infodir}/configure.info* - - rm -f $SB_BUILD_ROOT%{_infodir}/dir - touch $SB_BUILD_ROOT%{_infodir}/dir - - cd .. ------------------------------------------------------------- - -<1> Including a file. The +_configdir+ macro searchs a list of paths. -<2> The description section. -<3> The source file as a URL. If not found in the +sources+ directories it is -downloaded. -<4> Preparing the source code. -<5> The commands to build +gdb+. -<6> The installation phase. Notice the +DESTDIR=+ feature is used. - -Controlling Configurations -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is a simple process of including the specific pieces you need. There -typically is three layers where the top level is specific and each sub-layer is -more generic configured by the layer above it. The typical layering is: - -. Build Set -. Package definition -. Package configuration - -The build set defines the packages to be built plus any specific configuration -needed. Some packages default to standard values if the build set does not -provide any specific configuration and some configurations raise an error -indicating a required configuration is missing. - -Using the RTEMS 4.10 Tools Set build as an example the build set configuration -is: - ++ +You can also check to see if something is set: ++ ------------------------------------------------------------- -# -# Tools Set for RTEMS 4.10 -# - -%define rtems_version 4.10 - -%define release 1 <1> - -package: rtems-%{rtems_version}-%{_target}-%{release} - -# -# Project custom message -# -%define gcc_version_message RTEMS %{rtems_version}-%{release},gcc-%{gcc_version}/newlib-%{newlib_version} - -# -# Tools configuration. -# -rtems-binutils-2.20.1-1 <2> -rtems-gcc-4.4.7-newlib-1.18.0-1 -rtems-gdb-7.3.1-1 +%if ${something} != %{nil} + %warning The test passes +%else + %error The test fails +%endif ------------------------------------------------------------- ++>+:: The left hand side is numerically greater than the right hand side. ++>=+:: The left hand side is numerically greater than or equal to the right +hand side. ++<+:: The left hand side is numerically less than the right hand side. ++\<=+:: The left hand side is numerically less than or equal to the right hand +side. -<1> The release of the RTEMS 4.10 tools package. -<2> The build configurations. These reference the specific version of the tools -including the related patches. You should note the configurations referenced -are RTEMS specific, that is prefixed with +rtems-+. +%ifn +^^^^ -The GCC and Newlib file +rtems-gcc-4.4.7-newlib-1.18.0-1+ is: +The +%ifn+ macro inverts the normal +%if+ logic. It avoids needing to provide +empty _if_ blocks followed by _else_ blocks. It is useful when checking if a +macro is defined: ------------------------------------------------------------- -# -# GCC 4.4.7, Newlib 1.18.0 -# - -%include %{_configdir}/checks.cfg <1> -%include %{_configdir}/base.cfg <2> - -%define gcc_version 4.4.7 <3> -%define newlib_version 1.18.0 -%define mpfr_version 2.4.1 -%define mpc_version 0.8.2 -%define gmp_version 5.0.5 +%ifn %{defined foo} + %define foo bar +%endif +------------------------------------------------------------- -%define with_threads 1 <4> -%define with_plugin 0 -%define with_iconv 1 +%ifarch +^^^^^^^ -# -# AVR C++ does not work. -# configure: error: unable to detect exception model -# -%if %{_target} == avr-rtems4.10 <5> -%define enable_cxx 0 -%endif +The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used. -# -# M32C C++ does not work. -# gcc-4.4.7/libstdc++-v3/src/mt_allocator.cc:76: error: cast from 'void*' to 'size_t' loses precision -# -%if %{_target} == m32c-rtems4.10 -%define enable_cxx 0 -%endif +%ifnarch +^^^^^^^^ -%ifn %{defined enable_cxx} <6> -%define enable_cxx 1 -%endif +The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not +used. -# -# The RTEMS 4.10 patches -# -Patch0: gcc-core-4.4.7-rtems4.10-20120314.diff <7> -%if %{enable_cxx} -Patch1: gcc-g++-4.4.7-rtems4.10-20120314.diff -%endif -Patch10: newlib-1.18.0-rtems4.10-20110518.diff +%ifos +^^^^^ -# -# The gcc/newlib build instructions. We use 4.4 Release 1. -# -%include %{_configdir}/gcc-4.4-1.cfg <8> -------------------------------------------------------------- +The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows +conditional support for various operating system differences when building +packages. -<1> Perform some standard checks such as the release being set. -<2> Set up some standard macros needed by most configure type packages. -<3> The specific versions of the various parts that make a GCC embedded -cross-compiler. -<4> Configure some specific parts of GCC and Newlib for RTEMS. -<5> Disable C++ for the AVR target because it does not build for RTEMS. -<6> Default is to build C++. -<7> The various patches. This file's revision increases with each patch change. -<8> The generic GCC/Newlib build configuration for gcc-4.4.x. +%else +^^^^^ -Project Configuration -~~~~~~~~~~~~~~~~~~~~~ +The +%else+ macro starts the conditional _else_ block. -The RTEMS Source Builder has a +config+ and +patches+ directory that contain some -useful and often needed configurations and patches. You do not need to add your -project specific configurations into the RTEMS Source Builder. You can create a -private set and then use the RTEMS Source Builder to build your packages. +%endfi +^^^^^^ -Create a +config+ directory and place your build sets and configuration in -them. If you have private patches add them to a +patches+ directory next to the -+config+ directiory. When you run a RTEMS Source Builder command it will first search -the for the specific file then the local +config+ directoy then the Source -Builder's +config+ directory. The same goes for +patches+. +The +%endif+ macro ends a conditional logic block. -For example of this set up look in the +rtems+ directory in the Source -Builder. It is actually a standard alone project configuration private to the -RTEMS project. +%bconf_with +^^^^^^^^^^^ -If you are an open source project and you find the RTEMS Source Builder useful and -would like your configuration held in the RTEMS Source Builder's repository please -contact me directly. +The +%bconf_with+ macro provides a way to test if the user has passed a +specific option on the command line with the +--with-<label>+ option. This +option is only available with the +sb-builder+ command. -The Builder -~~~~~~~~~~~ +%bconf_without +^^^^^^^^^^^^^^ -TBD +The +%bconf_without+ macro provides a way to test if the user has passed a +specific option on the command line with the +--without-<label>+ option. This +option is only available with the +sb-builder+ command. + + +Project Configuration Sets +-------------------------- + +The RTEMS Source Builder supports project configurations. Project +configurations can be public or private and can be contained in the RTEMS +Source Builder project if suitable, other projects they use the RTEM Source +Builder or privately on your local file system. + +The configuration file loader searches the macro +_configdir+ and by default +this is set to +%{\_topdir}/config:%{\_sbdir}/config+ where +_topdir+ is the +your current working direct, in other words the directory you invoke the RTEMS +Source Builder command in, and +_sbdir+ is the directory where the RTEMS Source +Builder command resides. Therefore the +config+ directory under each of these +is searched so all you need to do is create a +config+ in your project and add +your configuration files. They do not need to be under the RTEMS Source Builder +source tree. Public projects are included in the main RTEMS Source Builder such +as RTEMS. + +You can also add your own +patches+ directory next to your +config+ directort +as the +%patch+ command searches the +_patchdir+ macro variable and it is +by default set to +%{\_topdir}/patches:%{\_sbdir}/patches+. + +The +source-builder/config+ directory provides generic scripts for building +various tools. You can specialise these in your private configurations to make +use of them. If you add new generic configurations please contribute them back +to the project + +RTEMS Configurations +~~~~~~~~~~~~~~~~~~~~ + +The RTEMS Configurations are grouped by RTEMS version. In RTEMS the tools are +specific to a specific version because of variations between Newlib and +RTEMS. Restructuring in RTEMS and Newlib sometimes moves _libc_ functionality +between them and this makes existing tool incompatible with RTEMS. + +RTEMS allows architectures to have different tool versions and patches. The +large number of architectures RTEMS supports can make it difficult to get a +common stable version of all the packages. An architecture may require a recent +GCC because an existing bug has been fixed, how-ever the more recent verison +may have a bug in other architecture. Architecture specific patches should be +limited to the architecture it relates to. The patch may fix a problem on the +effect architecture how-ever it could introduce a problem in another +architecture. Limit exposure limits any possible crosstalk bewteen +architectures. + +RTEMS supports _stable_ and _unstable_ configuration of tools. The stable build sets +are referenced as +<version>/rtems-<arch>+ and the unstable build sets are +references as +<version>/unstable/rtems-<arch>+. Commands -------- @@ -1221,12 +1245,12 @@ Commands Checker (sb-check) ~~~~~~~~~~~~~~~~~~ -This commands checks your system is set up correctly. +This commands checks your system is set up correctly. Most options are ignored. ------------------------------------------------------------- -$ ./source-builder/sb-check --help +$ ../source-builder/sb-check --help sb-check: [options] [args] -RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns +RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns Options and arguments: --force : Create directories that are not present --trace : Trace the execution (not current used) @@ -1252,20 +1276,58 @@ Options and arguments: --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code --with-<label> : Add the --with-<label> to the build --without-<label> : Add the --without-<label> to the build +$ ../source-builder/sb-check +RTEMS Source Builder environent is ok +------------------------------------------------------------- + +Defaults (sb-defaults) +~~~~~~~~~~~~~~~~~~~~~~ + +This commands outputs and the default macros for your when given no +arguments. Most options are ignored. + +------------------------------------------------------------- +$ ../source-builder/sb-defaults --help +sb-defaults: [options] [args] +RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns +Options and arguments: +--force : Force the build to proceed +--trace : Trace the execution (not current used) +--dry-run : Do everything but actually run the build +--warn-all : Generate warnings +--no-clean : Do not clean up the build tree +--no-smp : Run with 1 job and not as many as CPUs +--rebuild : Rebuild (not used) +--host : Set the host triplet +--build : Set the build triplet +--target : Set the target triplet +--prefix path : Tools build prefix, ie where they are installed +--prefixbase path : +--topdir path : Top of the build tree, default is $PWD +--configdir path : Path to the configuration directory, default: ./config +--builddir path : Path to the build directory, default: ./build +--sourcedir path : Path to the source directory, default: ./source +--tmppath path : Path to the temp directory, default: ./tmp +--log file : Log file where all build out is written too +--url url : URL to look for source +--targetcflags flags : List of C flags for the target code +--targetcxxflags flags : List of C++ flags for the target code +--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code +--with-<label> : Add the --with-<label> to the build +--without-<label> : Add the --without-<label> to the build ------------------------------------------------------------- Set Builder (sb-set-builder) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This command builds a set as described in a build set. Build set files have the -extension of +.bset+. +This command builds a set. ------------------------------------------------------------- -$ ./source-builder/sb-set-builder --help +$ ../source-builder/sb-set-builder --help sb-set-builder: [options] [args] -RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns +RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns Options and arguments: ---force : Create directories that are not present +--force : Force the build to proceed --trace : Trace the execution (not current used) --dry-run : Do everything but actually run the build --warn-all : Generate warnings @@ -1289,9 +1351,96 @@ Options and arguments: --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code --with-<label> : Add the --with-<label> to the build --without-<label> : Add the --without-<label> to the build ---list-configs : List available configurations --list-bsets : List available build sets -------------------------------------------------------------- +--keep-going : Do not stop on error. +--no-install : Do not install the packages to the prefix. +--bset-tar-file : Create a build set tar file +--list-configs : List available configurations +--pkg-tar-files : Create package tar files +------------------------------------------------------------- + +.Arguments +The +[args]+ are a list build sets to build. + +.Options ++--force+;; +Force the build to proceed even if the host check fails. Typically this happens +if executables are found in the path at a different location to the host +defaults. ++--trace+;; +Trace enable printing of debug information to stdout. It is really only of use +to RTEMS Source Builder's developers. ++--dry-run+;; +Do everything but actually run the build commands. This is useful when checking +a new configuration parses cleanly. ++--warn-all+;; +Generate warnings. ++--no-clean+;; +Do not clean up the build tree during the cleaning phase of the build. This +leaves the source and the build output on disk so you can make changes, or +amend or generate new patches. It also allows you to review configure type +output such as +config.log+. ++--no-smp+;; +Run +make+ with 1 job and not as many as there are cores. This option can help +isolate parallel make type bugs or make the log file output +sequential. Parallel jobs can make the output confusing. ++--host+;; +Set the host triplet value. Becareful with this option. ++--build+;; +Set the build triplet. Becareful with this option. ++--target+;; +Set the target triplet. Becareful with this option. This is useful if you have +a generic configuration script that can work for a range of architectures. ++--prefix path+;; +Tools build prefix, ie where they are installed. ++--prefixbase path+;; +The prefix base is appended to the build root path. ++--topdir path+;; +Top of the build tree, that is the current directory you are in. ++--configdir path+;; +Path to the configuration directory. This overrides the built in defaults. ++--builddir path+;; +Path to the build directory. This overrides the default of +build+. ++--sourcedir path+;; +Path to the source directory. This overrides the default of +source+. ++--tmppath path+;; +Path to the temporary directory. This overrides the default of +tmp+. ++--log file+;; +Log all the output from the build process. The output is directed to +stdout+ +if no log file is provided. ++--url url+;; +URL to look for source when downloading. This is can be comma separate list. ++--targetcflags flags+;; +List of C flags for the target code. This allows for specific local +customisation when testing new variations. ++--targetcxxflags flags+;; +List of C++ flags for the target code. This allows for specific local +customisation when testing new variations. ++--libstdcxxflags flags+;; +List of C\++ flags to build the target libstdc++ code. This allows for specific +local customisation when testing new variations. ++--with-<label>+;; +Add the --with-<label> to the build. This can be tested for in a script with +the +%bconf_with+ macro. ++--without-<label>+;; +Add the --without-<label> to the build. This can be tested for in a script with +the +%bconf_without+ macro. ++--list-bsets+;; +List available build sets. ++--list-configs+;; +List available configurations. ++--keep-going+;; +Do not stop on error. This is useful if your build sets performs a large number +of testing related builds and there are errors. ++--no-install+;; +Do not install the packages to the prefix. Use this if you are only after the +tar files. ++--bset-tar-file+;; +Create a build set tar file. This is a single tar file of all the packages in +the build set. ++--pkg-tar-files+;; +Create package tar files. A tar file will be created for each package built in +a build set. Set Builder (sb-builder) ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1359,7 +1508,7 @@ required. ------------------------------------------------------------- $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \ -texinfo unzip ncurses-dev python-dev +texinfo unzip ncurses-dev python-dev git ------------------------------------------------------------- It is recommended you get Model B of the Pi with 512M of memory and to mount a |