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 ^^^^^^^^^^ +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. + %setup ^^^^^^ +The +%setup+ macro sets up the source code tree and is used in the +%prep+ +section of the script. The options are: + +[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 +-+. ++-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 +:: 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 +:: 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. + %source ^^^^^^^ +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: + +------------------------------------------------------------- +Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2 +------------------------------------------------------------- + +The setup script is: + +------------------------------------------------------------- +%setup -q -T -D -n %{name}-%{version} -a0 +------------------------------------------------------------- + +The +-a0+ means use +%source0+. + %patch ^^^^^^ +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 +------------------------------------------------------------- + +The +__patchdir+ path is search. + +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 +------------------------------------------------------------- + +You will typically see the patch conditionally used as: + +------------------------------------------------------------- +%{patch0:%patch0 -p1} +------------------------------------------------------------- + +In this case the patch will only be applied if it is defined. + %warning ^^^^^^^^ +The +%warning+ macro outputs the following string as a warning. + %error ^^^^^^ +The +%error+ macro outputs the follow string as an error and exits the RTEMS +Source Builder. + %define ^^^^^^^ +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. + +------------------------------------------------------------- +%define foo bar +%define one_plus_one 2 +%define one <1> +------------------------------------------------------------- + +<1> The macro _one_ is set to 1. + %undefine ^^^^^^^^^ +The +%undefine+ macro removes a macro if it exists. Any further references to +it will result in an undefine macro error. + %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. ++ +------------------------------------------------------------- +%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. ++ +------------------------------------------------------------- +%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: ++ +------------------------------------------------------------- +%define one 1 +%if ${one} == 1 + %warning The test passes +%else + %error The test fails +%endif +------------------------------------------------------------- ++ +You can also check to see if a macro is empty: ++ +------------------------------------------------------------- +%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: ++ +------------------------------------------------------------- +%define one 1 +%if ${one} != 2 + %warning The test passes +%else + %error The test fails +%endif +------------------------------------------------------------- ++ +You can also check to see if something is set: ++ +------------------------------------------------------------- +%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. + %ifn ^^^^ +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: + +------------------------------------------------------------- +%ifn %{defined foo} + %define foo bar +%endif +------------------------------------------------------------- + %ifarch ^^^^^^^ +The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used. + %ifnarch ^^^^^^^^ +The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not +used. + %ifos ^^^^^ +The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows +conditional support for various operating system differences when building +packages. + %else ^^^^^ +The +%else+ macro starts the conditional _else_ block. + %endfi ^^^^^^ +The +%endif+ macro ends a conditional logic block. + %bconf_with ^^^^^^^^^^^ +The +%bconf_with+ macro provides a way to test if the user has passed a +specific option on the command line with the +--with-