Changeset 5ba5405 in rtems-source-builder


Ignore:
Timestamp:
Feb 24, 2013, 9:07:47 AM (7 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.10, 4.11, 4.9, master
Children:
eef48f9
Parents:
77c68e8
Message:

Update documentation. Lots more is needed before it is finished.

Location:
source-builder/doc
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • source-builder/doc/source-builder.txt

    r77c68e8 r5ba5405  
    1 Source Builder
    2 ==============
    3 Chris Johns <chrisj@rtems.org>
    4 1.0, November 2012
     1RTEMS Source Builder
     2====================
    53:doctype: book
    6 :toc:
     4:toc2:
     5:toclevels: 5
    76:icons:
    87:numbered:
    98
    10 image:images/rtemswhitebg.jpg["RTEMS",width="20%"]
    11 
    12 Introduction
    13 ------------
    14 
    15 The Source Builder is a tool to aid building packages from source. It is not a
    16 package manager. It is just helps consolidate the details that you need to know
    17 to build a package from source. The tool is mainly aimed at those users who
    18 need to maintain tool sets for embedded type development, that is
    19 cross-compiled compiled tool chains, debuggers, and debugging aids. It is not
    20 limited to this role but designed to fit with-in that specific niche.
    21 
    22 The Source Builder attempts to support any host environment that runs Python
    23 and you can build the package on. It is not some sort of magic that can take
    24 any piece of source code and make it build. Someone at some point in time has
    25 figured out how to build that package from source and taught this tool.
    26 
    27 The Source Builder has two types configuration data. The first is configuration
    28 files and these are scripts based on the RPM spec file format that detail the
    29 steps needed to build a package. The steps are 'preparation', 'building', and
    30 'installing'. The second set of configuration files are 'build sets'. A build
    31 set describes a collection of packages you want built together. For example the
    32 GNU tool set is autoconf, automake, binutils, gcc, and gdb. This is the typical
    33 suite of tools you need for an embedded cross-development type project.
    34 
    35 The Source Builder does not interact with any host package management
     9image:images/rtemswhitebg.jpg["RTEMS",width="30%"]
     10
     11Chris Johns <chrisj@rtems.org>
     121.0, February 2013
     13
     14RTEMS Tools From Source
     15-----------------------
     16
     17The RTEMS Source Builder is a tool to aid building packages from source. It is
     18not a package manager. It helps consolidate the details you need to know to
     19build a package from source in a controlled and verifiable way. The tool is
     20mainly aimed at developers of software who use tool sets for embedded type
     21development. Embedded development typically uses cross-compiling tool chains,
     22debuggers, and debugging aids. Together we call these a tool set. The RTEMS
     23Source Builder is not limited to this role but designed to fit with-in this
     24specific niche. It can be used outside of the RTEMS project and we welcome this
     25happening in other open source or commercial projects.
     26
     27The RTEMS Source Builder is typically used to build a set of tools or a _build
     28set_. A _build set_ is a collection of packages and a package is a specific
     29tool, for example gcc or gdb. The RTEMS Source Builder attempts to support any
     30host environment that runs Python and you can build the package on. It is not
     31some sort of magic that can take any piece of source code and make it
     32build. Someone at some point in time has figured out how to build that package
     33from source and taught this tool. The RTEMS Source Builder has been tested on:
     34
     35. FreeBSD
     36. MacOS (Mountain Lion)
     37. Ubuntu
     38. Centos
     39. Fedora
     40. Raspbian
     41
     42Windows support is being added how-ever there are issues with the Python
     43threading used in the RTEMS Source Builder and the MinGW project's MSYS process
     44handling of make.
     45
     46The RTEMS Source Builder has two types configuration data. The first is the
     47_build set_. A _build set_ describes a collection of packages that define a set
     48of tools you would use when developing software for RTEMS. For example the
     49basic GNU tool set is binutils, gcc, and gdb and is the typical base suite of
     50tools you need for an embedded cross-development type project. The second type
     51of configuration data is the configuration files and they define how a package
     52is built. Configuration files are scripts based on the RPM spec file format
     53and detail the steps needed to build a package. The steps are 'preparation',
     54'building', and 'installing'. The script support macros, shell expansion,
     55logic, includes and many more featured need to build packages.
     56
     57The RTEMS Source Builder does not interact with any host package management
    3658system. There is no automatic dependence checking between various packages you
    37 build or your host system may have installed. We assume you know what are doing
    38 or the build sets and configuration files you are using have been created by
    39 developers who do. A buld set should provide a known working configuration.
    40 
    41 Why build from source ?
    42 ~~~~~~~~~~~~~~~~~~~~~~~
     59build or packages or software your host system may have installed. We assume
     60the build sets and configuration files you are using have been created by
     61developers who do.
     62
     63Quick Start
     64-----------
     65
     66The quick start will show you how to build a set of RTEMS tools for a supported
     67architecture.
     68
     69There is no need to become root or the administrator and we recommend you avoid
     70doing this. You can build and install the tools anywhere on the host's file
     71system you as a standard user have read and write access. I recommend you use
     72your home directory and work under the directory +~/development+. The
     73examples shown here will do this.
     74
     75You can use the build _prefix_ to install and maintain different versions of
     76the tools. Doing this lets you try a new set of tools while not touching your
     77proven working production set of tools. Once you have proven the new tools are
     78working rebuild with the _producion_ prefix switching your development to them.
     79
     80I also suggest you keep your environment to the bare minimum, particularly the
     81path variable. Using environment variables has been proven over the years to be
     82difficult to manage in production systems.
     83
     84Setup
     85~~~~~
     86
     87Setup a development work space:
     88
     89-------------------------------------------------------------
     90$ cd
     91$ mkdir -p development/rtems/src
     92$ cd development/rtems/src
     93-------------------------------------------------------------
     94
     95The RTEMS Source Builder is distributed as source. It is Python code so all you
     96need to do is head over to the RTEMS GIT repository and clone the code directly
     97from git:
     98
     99-------------------------------------------------------------
     100$ git clone git://git.rtems.org/chrisj/rtems-source-builder.git
     101$ cd rtems-source-builder
     102-------------------------------------------------------------
     103
     104Checking
     105~~~~~~~~
     106
     107The next step is to check if your host is set up correctly. The RTEMS Source
     108Builder provides a tool to help:
     109
     110-------------------------------------------------------------
     111$ source-builder/sb-check
     112warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
     113warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
     114error: exe: not found: (_xz) /usr/local/bin/xz <2>
     115RTEMS Source Builder environent is not correctly set up
     116$ source-builder/sb-check
     117RTEMS Source Builder environent is ok <3>
     118-------------------------------------------------------------
     119
     120<1> A tool is in the environment path but does not match the shown path.
     121<2> The executable 'xz' is not found.
     122<3> The host's environment is set up correct.
     123
     124The checking tool will output a list of executables not found if problems are
     125detected. Locate those executables and install them. You may also be given a
     126list of warnings about executables not in the expected location how-ever the
     127executable was located somewhere in your environment's path. You will need to
     128check each tool to determine if this is an issue. An executable not in the
     129standard location may indicate it is not the host operating system's standard
     130tool. It maybe ok or it could be buggy.
     131
     132The <<_host_setups,Host Setups>> section lists packages you should install for
     133common host operating systems. It maybe worth checking if you have those
     134installed.
     135
     136Build Sets
     137~~~~~~~~~~
     138
     139The RTEMS tools can be built within the RTEMS Source Builder's source tree. We
     140recommend you do this so lets change into the RTEMS directory in the RTEMS
     141Source Builder package:
     142
     143-------------------------------------------------------------
     144$ cd rtems
     145-------------------------------------------------------------
     146
     147If you are unsure how to specify the build set for the architecure you wish to
     148build ask the tool:
     149
     150-------------------------------------------------------------
     151$ ../source-builder/sb-set-builder --list-bsets <1>
     152RTEMS Source Builder - Set Builder, v0.1
     153Examining: config <2>
     154Examining: ../source-builder/config <2>
     155    4.11/rtems-all.bset <3>
     156    4.11/rtems-arm.bset <4>
     157    4.11/rtems-avr.bset
     158    4.11/rtems-bfin.bset
     159    4.11/rtems-h8300.bset
     160    4.11/rtems-m32c.bset
     161    4.11/rtems-m32r.bset
     162    4.11/rtems-m68k.bset
     163    4.11/rtems-microblaze.bset
     164    4.11/rtems-mips.bset
     165    4.11/rtems-moxie.bset
     166    4.11/rtems-nios2.bset
     167    4.11/rtems-powerpc.bset
     168    4.11/rtems-sh.bset
     169    4.11/rtems-sparc.bset
     170    gnu-tools-4.6.bset
     171    rtems-4.11-base.bset
     172    unstable/4.11/rtems-all.bset <5>
     173    unstable/4.11/rtems-arm.bset
     174    unstable/4.11/rtems-avr.bset
     175    unstable/4.11/rtems-bfin.bset
     176    unstable/4.11/rtems-h8300.bset
     177    unstable/4.11/rtems-m32c.bset
     178    unstable/4.11/rtems-m32r.bset
     179    unstable/4.11/rtems-m68k.bset
     180    unstable/4.11/rtems-microblaze.bset
     181    unstable/4.11/rtems-mips.bset
     182    unstable/4.11/rtems-moxie.bset
     183    unstable/4.11/rtems-powerpc.bset
     184    unstable/4.11/rtems-sh.bset
     185    unstable/4.11/rtems-sparc.bset
     186-------------------------------------------------------------
     187<1> Only option needed is +--list-bsets+
     188<2> The paths inspected. See <<X1,+_configdir+>> variable.
     189<3> Build all the architectures.
     190<4> The build set for the ARM architecture.
     191<5> Unstable tool sets are used by RTEMS developers to test new tool sets. You
     192    are welcome to try them but you must remember they are unstable, can change
     193    at point in time and your application may not work. If you have an issue
     194    with a production tool it may pay to try the unstable tool to see if it has
     195    been resolved.
     196
     197Building
     198~~~~~~~~
     199
     200In this quick start I will build an SPARC tool set.
     201
     202-------------------------------------------------------------
     203$ ../source-builder/sb-set-builder --log=l-sparc.txt <1> \
     204                --prefix=$HOME/development/rtems/4.11 <2> 4.11/rtems-sparc <3>
     205Source Builder - Set Builder, v0.1
     206Build Set: 4.11/rtems-sparc
     207config: expat-2.1.0-1.cfg <4>
     208package: expat-2.1.0-x86_64-freebsd9.1-1
     209building: expat-2.1.0-x86_64-freebsd9.1-1
     210installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <5>
     211config: tools/rtems-binutils-2.22-1.cfg <6>
     212package: sparc-rtems4.11-binutils-2.22-1
     213building: sparc-rtems4.11-binutils-2.22-1
     214installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     215config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg <7>
     216package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     217building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     218installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     219config: tools/rtems-gdb-7.5.1-1.cfg <8>
     220package: sparc-rtems4.11-gdb-7.5.1-1
     221building: sparc-rtems4.11-gdb-7.5.1-1
     222installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     223cleaning: expat-2.1.0-x86_64-freebsd9.1-1 <9>
     224cleaning: sparc-rtems4.11-binutils-2.22-1
     225cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     226cleaning: sparc-rtems4.11-gdb-7.5.1-1
     227Build Set: Time 0:13:43.616383 <10>
     228-------------------------------------------------------------
     229
     230<1> Providing a log file redirects the build output into a file. Logging the
     231    build output provides a simple way to report problems.
     232<2> The prefix is the location on your file system the tools are installed
     233    into. Provide a prefix to a location you have read and write access. You
     234    can use the prefix to install different version or builds of tools. Just
     235    use the path to the tools you want to use when building RTEMS.
     236<3> The build set. This is the SPARC build set.
     237<4> The SPARC build set build the expat library that is used in GDB. This is the
     238    expat configuration.
     239<5> Installing the expat package to the install prefix.
     240<6> The binutils build configuration.
     241<7> The GCC and Newlib build configuration.
     242<8> The GDB build configuration.
     243<9> All the packages built are cleaned at the end. If the build fails all the
     244    needed files are present. You may have to clean up by deleting the build
     245    directory.
     246<10> The time to build the package. This lets you see how different host
     247     hardware or configurations perform.
     248
     249Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and
     250RTEMS applications. When the build runs you will notice the tool fetch the
     251source code from the internet. These files are cached in a directory called
     252+source+. If you run the build again the cached files are used.
     253
     254-------------------------------------------------------------
     255$ ls $HOME/development/rtems/4.11
     256bin         include     lib         libexec     share       sparc-rtems4.11
     257$ ls $HOME/development/rtems/4.11/bin
     258sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
     259sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
     260sparc-rtems4.11-objdump         sparc-rtems4.11-size
     261sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
     262sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
     263sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
     264sparc-rtems4.11-as              sparc-rtems4.11-g++
     265sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
     266sparc-rtems4.11-readelf         sparc-rtems4.11-strip
     267sparc-rtems4.11-c++             sparc-rtems4.11-gcc
     268sparc-rtems4.11-gcov            sparc-rtems4.11-nm
     269sparc-rtems4.11-run             xmlwf
     270sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
     271sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
     272sparc-rtems4.11-sis
     273$ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
     274Using built-in specs.
     275COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
     276COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
     277libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
     278Target: sparc-rtems4.11
     279Configured with: ../gcc-4.7.2/configure
     280--prefix=/home/chris/development/rtems/4.11
     281--bindir=/home/chris/development/rtems/4.11/bin
     282--exec_prefix=/home/chris/development/rtems/4.11
     283--includedir=/home/chris/development/rtems/4.11/include
     284--libdir=/home/chris/development/rtems/4.11/lib
     285--libexecdir=/home/chris/development/rtems/4.11/libexec
     286--mandir=/home/chris/development/rtems/4.11/share/man
     287--infodir=/home/chris/development/rtems/4.11/share/info
     288--datadir=/home/chris/development/rtems/4.11/share
     289--build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
     290--disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
     291--with-system-zlib --disable-nls --without-included-gettext
     292--disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
     293--enable-threads --enable-plugin --enable-newlib-io-c99-formats
     294--enable-newlib-iconv --enable-languages=c,c++
     295Thread model: rtems
     296gcc version 4.7.2 20120920 (RTEMS) (GCC)
     297-------------------------------------------------------------
     298
     299Installing and Tar Files
     300~~~~~~~~~~~~~~~~~~~~~~~~
     301
     302The RTEMS Source Builder can install the built packages directly and optionally it can
     303create a build set tar file or a tar file per package built. The normal and
     304default behaviour is to let the RTEMS Source Builder install the tools. The
     305source will be downloaded, built, installed and cleaned up.
     306
     307The tar files are created with the full build prefix present. This can cause
     308problems if you are installing on a host you do not have super user or
     309administrator rights on if the prefix path references part you do not have
     310write access t0o. You can use the +--strip-components+ if you tar file has the
     311option to remove the parts you do not have write access too or you may need to
     312unpack the tar file somewhere and copy the file tree from the level you have
     313write access from. Embedding the full prefix path in the tar files lets you know
     314what the prefix is.
     315
     316A build set tar file can created by adding +--bset-tar-file+ option to the
     317+sb-set-builder+ command.
     318
     319-------------------------------------------------------------
     320$ ../source-builder/sb-set-builder --log=l-sparc.txt \
     321         --prefix=$HOME/development/rtems/4.11 \
     322         --bset-tar-file <1> 4.11/rtems-sparc
     323Source Builder - Set Builder, v0.1
     324Build Set: 4.11/rtems-sparc
     325config: expat-2.1.0-1.cfg
     326package: expat-2.1.0-x86_64-freebsd9.1-1
     327building: expat-2.1.0-x86_64-freebsd9.1-1
     328installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
     329config: tools/rtems-binutils-2.22-1.cfg
     330package: sparc-rtems4.11-binutils-2.22-1
     331building: sparc-rtems4.11-binutils-2.22-1
     332installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     333config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     334package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     335building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     336installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     337config: tools/rtems-gdb-7.5.1-1.cfg
     338package: sparc-rtems4.11-gdb-7.5.1-1
     339building: sparc-rtems4.11-gdb-7.5.1-1
     340installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
     341tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
     342cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     343cleaning: sparc-rtems4.11-binutils-2.22-1
     344cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     345cleaning: sparc-rtems4.11-gdb-7.5.1-1
     346Build Set: Time 0:15:25.92873
     347-------------------------------------------------------------
     348
     349<1> The option to create a build set tar file.
     350<2> The installation still happens.
     351<3> Creating the build set tar file.
     352
     353You can also suppress installing the files using the +--no-install+ option to
     354the +sb-set-builder+.
     355
     356-------------------------------------------------------------
     357$ ../source-builder/sb-set-builder --log=l-sparc.txt \
     358            --prefix=$HOME/development/rtems/4.11 \
     359            --bset-tar-file --no-install <1> 4.11/rtems-sparc
     360Source Builder - Set Builder, v0.1
     361Build Set: 4.11/rtems-sparc
     362config: expat-2.1.0-1.cfg
     363package: expat-2.1.0-x86_64-freebsd9.1-1
     364building: expat-2.1.0-x86_64-freebsd9.1-1
     365config: tools/rtems-binutils-2.22-1.cfg
     366package: sparc-rtems4.11-binutils-2.22-1
     367building: sparc-rtems4.11-binutils-2.22-1
     368config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     369package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     370building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     371config: tools/rtems-gdb-7.5.1-1.cfg
     372package: sparc-rtems4.11-gdb-7.5.1-1
     373building: sparc-rtems4.11-gdb-7.5.1-1
     374tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2>
     375cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     376cleaning: sparc-rtems4.11-binutils-2.22-1
     377cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     378cleaning: sparc-rtems4.11-gdb-7.5.1-1
     379Build Set: Time 0:14:11.721274
     380$ ls tar
     381rtems-4.11-sparc-rtems4.11-1.tar.bz2
     382-------------------------------------------------------------
     383
     384<1> The option to supressing installing the packages.
     385<2> Create the build set tar.
     386
     387A package tar file can be created by adding the +--pkg-tar-files+ to the
     388+sb-set-builder+ command. This creates a tar file per package built in the
     389build set.
     390
     391-------------------------------------------------------------
     392$ ../source-builder/sb-set-builder --log=l-sparc.txt \
     393            --prefix=$HOME/development/rtems/4.11 \
     394            --bset-tar-file --pkg-tar-files <1> --no-install 4.11/rtems-sparc
     395Source Builder - Set Builder, v0.1
     396Build Set: 4.11/rtems-sparc
     397config: expat-2.1.0-1.cfg
     398package: expat-2.1.0-x86_64-freebsd9.1-1
     399building: expat-2.1.0-x86_64-freebsd9.1-1
     400config: tools/rtems-binutils-2.22-1.cfg
     401package: sparc-rtems4.11-binutils-2.22-1
     402building: sparc-rtems4.11-binutils-2.22-1
     403config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
     404package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     405building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     406config: tools/rtems-gdb-7.5.1-1.cfg
     407package: sparc-rtems4.11-gdb-7.5.1-1
     408building: sparc-rtems4.11-gdb-7.5.1-1
     409tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
     410cleaning: expat-2.1.0-x86_64-freebsd9.1-1
     411cleaning: sparc-rtems4.11-binutils-2.22-1
     412cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
     413cleaning: sparc-rtems4.11-gdb-7.5.1-1
     414Build Set: Time 0:14:37.658460
     415$ ls tar
     416expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
     417sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
     418sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
     419-------------------------------------------------------------
     420
     421<1> The option to create packages tar files.
     422<2> The GDB package tar file.
     423<3> The build set tar file. All the others in a single tar file.
     424
     425Why Build from Source ?
     426-----------------------
     427
     428The RTEMS Source Builder is not a replacement for the binary install systems
     429you have with commercial operating systems or open source operating system
     430distributions. Those products and distributions are critically important and
     431are the base that allows the Source Builder to work. The RTEMS Source Builder
     432sits somewhere between you manually entering the commands to build a tool set
     433and a tool such as +yum+ or +apt-get+ to install binary packages made
     434specifically for your host operating system. Building manually or installing a
     435binary package from a remote repository are valid and real alternatives while
     436the Source Builder is attempting to provide a specific service of repeatably
     437being able to build tool sets from source code.
    43438
    44439If you are developing a system or product that has a long shelf life or is used
     
    49444flexibility open source gives you. Fast moving host environments are
    50445fantastic. We have powerful multi-core computers with huge amounts of memory
    51 and state of the art operating systems to running on them. The product or
     446and state of the art operating systems to run on them how-ever the product or
    52447project you are part of may need to be maintained well past the life time of
    53448these host. Being able to build from source an important and critical part of
     
    72467easier.
    73468
    74 History
    75 ~~~~~~~
    76 
    77 The Source Builder is a stand alone tool based on another tool called the
    78 'SpecBuilder'. The SpecBuilder was written for the RTEMS project too give me a
    79 way to build tools on hosts that did not support RPMs. At the time the RTEMS
    80 tools maintainer only used spec files to create various packages. This meant I
    81 had either spec files, RPM files or SRPM files. The RPM and SPRM files where
    82 useless because you needed an 'rpm' type tool to extract and manage them. There
    83 are versions of 'rpm' for a number of non-RPM hosts how-ever these proved to be
    84 in various broken states and randomally maintained. The solution I settled on
    85 was to use spec files so I wrote a Python based tool that parsed the spec file
    86 format and allowed me to create a shell script I could run to build the
    87 package. This approach proved successful and I was able to track the RPM
    88 version of the RTEMS tools on a non-RPM host over a number of years. How-ever
    89 the SpecBuilder tool did not help me build tools or other packages not related
    90 to the RTEMS project where there was no spec file I could use so I needed
    91 another tool. Rather than start again I decided to take the parsing code for
    92 the spec file format and build a new tool called the Source Builder.
    93 
    94 Quick Start
    95 -----------
    96 
    97 The quick start will show you how to build a generic unpatched GNU tool set for
    98 any support target.
    99 
    100 Check out the Source Builder tool from git:
    101 
    102 -------------------------------------------------------------
    103 $ git clone git://git.rtems.org/chrisj/rtems-source-builder.git
    104 -------------------------------------------------------------
    105 
    106 The first step is to check if your host is set up correctly:
    107 
    108 -------------------------------------------------------------
    109 $ rtems-source-builder/source-builder/sb-check
    110 warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
    111 warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
    112 error: exe: not found: (_xz) /usr/local/bin/xz <2>
    113 Source Builder environent is not correctly set up
    114 $ source-builder/sb-check
    115 Source Builder environent is ok <3>
    116 -------------------------------------------------------------
    117 
    118 <1> A tool is in the environment path but does not match the shown path.
    119 <2> The executable 'xz' is not found.
    120 <3> The host's environment is set up correct.
    121 
    122 If there are problems you are given a list of executables that cannot be
    123 found. You may also be given a list of warnings about executables not in the
    124 expected location how-ever the executable was located somewhere in your
    125 environment's path. You will need to check the specific host section to resolve
    126 these issues.
    127 
    128 Create a suitable build directory away from the Source Builder source change
    129 into that directory and build a GNU tool set:
    130 
    131 -------------------------------------------------------------
    132 $ mkdir gnu-tools <1>
    133 $ cd gnu-tools
    134 $ ../rtems-source-builder/source-builder/sb-set-builder <2> --log=l.txt <3> --force <4> \
    135         --prefix=$HOME/gnu-tools-1 <5> --target=arm-eabi <6> gnu-tools-4.6 <7>
    136 -------------------------------------------------------------
    137 
    138 <1> Make a build directory you can delete when finished.
    139 <2> The Source Builder command to build a set of tools.
    140 <3> Capture the output to a log file.
    141 <4> The force option will create any needed directories and allow the build to
    142 proceed if your host is not set up.
    143 <5> Give the tools a suitable prefix. This is the location you install the
    144 tools into once they have built.
    145 <6> The gnu-toolset requires you set a target. In this case the tool set will
    146 be a generic unpatched version of GCC 4.6 for a bare metal the ARM processor.
    147 <7> The build set.
    148 
    149 To view the build sets lets change to the RTEMS project's source builder
    150 configuration and then list the build sets:
    151 
    152 -------------------------------------------------------------
    153 $ cd ../rtems-source-builder/rtems
    154 $ ../source-builder/sb-set-builder --list-bsets
    155 Source Builder - Set Builder, v0.1
    156 Examining: /usr/home/chris/development/rtems/src/rtems-source-builder/config <1>
    157 Examining: /usr/home/chris/development/rtems/src/source-builder/config <2>
    158   gnu-tools-4.6 <3>
    159   rtems-tools-4.10 <4>
    160   rtems-tools-4.11 <5>
    161 -------------------------------------------------------------
    162 
    163 <1> The local RTEMS configuration directory. Searched first.
    164 <2> The Source Builder configuration directory.
    165 <3> The Source Builder provided GNU tools GCC 4.6 build set.
    166 <4> The RTEMS Source Builder provided RTEMS 4.10 build set.
    167 <5> The RTEMS Source Builder provided RTEMS 4.11 (gcc-4.6.3)  build set.
    168 
    169 And to view the configurations you can:
    170 
    171 -------------------------------------------------------------
    172 $ ../source-builder/sb-set-builder --list-configs
    173 Source Builder - Set Builder, v0.1
    174 Examining: /usr/home/chris/development/rtems/src/rtems-source-builder/config
    175 Examining: /usr/home/chris/development/rtems/src/source-builder/config
    176   autoconf-2-1 <1>
    177   autoconf-2.68-1
    178   autoconf-2.69-1
    179   autoconf-internal-2.68-1
    180   automake-1-1
    181   automake-1.12-1
    182   automake-internal-1.12-1
    183   base
    184   binutils-2-1
    185   binutils-2.22-1
    186   checks
    187   expat-2-1
    188   expat-2.1.0-1
    189   gcc-4.4-1
    190   gcc-4.6-1
    191   gcc-4.6-newlib-1.20-1
    192   gdb-7-1
    193   gdb-7.5-1
    194   libusb-1-1
    195   libusb-1.0.9-1
    196   m4-1-1
    197   m4-1.4.16-1
    198   texane-stlink-1
    199   rtems-binutils-2.20.1-1
    200   rtems-binutils-2.22-1
    201   rtems-gcc-4.4.7-newlib-1.18.0-1
    202   rtems-gcc-4.6.3-newlib-1.20.0-1
    203   rtems-gdb-7.3.1-1
    204   rtems-gdb-7.5-1
    205 -------------------------------------------------------------
    206 
    207 <1> Configurations are built by using the builder. This creates a stand alone
    208 package.
    209 
    210 The Source Builder
    211 ------------------
    212 
    213 The Source Builder provides a few generic build sets and the configuration
    214 support to build a number of packages. A project that uses the Source Builder
    215 can create a specialised set of configuration files that provides the specific
    216 configurations a project uses.
    217 
    218 For example the RTEMS project provides its own set of configuration files
    219 inside the Source Builder. They do not have to be here. In the build set list
    220 in the 'Quick Start' section you can see the build sets +rtems-tools-4.10+ and
    221 +rtems-tools-4.11+. These build set defines the extact configration to use for
    222 the RTEMS releases.
    223 
    224 The Source Builder has been tested on:
    225 
    226 . FreeBSD
    227 . MacOS (Mountain Lion)
    228 . Ubuntu
    229 . Fedora
    230 
    231 Windows will be support how-ever there are issues with the Python threading
    232 used in the Source Builder and the MinGW project's MSYS process handling of make.
     469The RTEMS Source Builder is designed to be audited and incorporated into a
     470project's verifcation and validation process. If your project is developing
     471critical applications that needs to be traced from source to executable code in
     472the target, you need to also consiser the tools and how to track them.
     473
     474If your IT department maintains all your computers and you do not have suitable
     475rights to install binary packages, building from source lets you create your
     476own tool set that you install under your home directory. Avoiding installing
     477any extra packages as a super user is always helpful in maintaining a secure
     478computing environment.
     479
     480Configuration
     481-------------
     482
     483The RTEMS Source Builder has two types of configuration data:
     484
     485. Build Sets
     486. Package Build Configurations
     487
     488By default these files can be located in two separate directories and
     489searched. The first directory is +config+ in your current working directory
     490(+_topdir+) and the second is +config+ located in the base directory the RTEMS
     491Source Builder command you run (+_sbdir+). The RTEMS directory +rtems+ located
     492at the top of the RTEMS Source Builder source code is an example of a specific
     493build configuration directory. You cane create custom or private build
     494configurations and if you run the RTEMS Source Builder command from that
     495directory your configurations will be used.
     496
     497[[X1]] The configuration search path is the macro variable and is reference as
     498+%\{_configdir\}+. It's default is defined as:
     499
     500-------------------------------------------------------------
     501_configdir          : dir      optional   %{_topdir}/config:%{_sbdir}/config <1>
     502-------------------------------------------------------------
     503
     504<1> The +_topdir+ is the directory  you run the command from and +_sbdir+ is
     505the location of the RTEMS Source Builder command.
     506
     507Build set files have the file extension +.bset+ and the package build
     508configuration files have the file extension of +.cfg+. The +sb-set-builder+
     509command will search for _build sets_ and the +sb-builder+ commands works with
     510package build configuration files.
     511
     512Both types of configuration files use the \'#' character as a comment
     513character. Anything after this character on the line is ignored. There is no
     514block comment.
     515
     516Macros and Defaults
     517~~~~~~~~~~~~~~~~~~~
     518
     519The RTEMS Source Builder uses a table of _macros_ called the _defaults_. The
     520values the _defaults_ are initialised to are dependent on your host. This lets
     521the Source Builder handle differences in the hosts. Build set and configuration
     522files can define new values extending the defaults. For example builds are
     523given a release number. This is typically a single number at the end of the
     524package name. For RTEMS this is set in the top level build set configuration
     525file with:
     526
     527-------------------------------------------------------------
     528%define release 1
     529-------------------------------------------------------------
     530
     531Once defined if can be accessed in a build set or package configuration file
     532with:
     533
     534-------------------------------------------------------------
     535%{release}
     536-------------------------------------------------------------
     537
     538The +sb-defaults+ command lists the defaults for your host. I will not include
     539the output of this command beause of its size.
     540
     541-------------------------------------------------------------
     542$ ../source-builder/sb-defaults
     543-------------------------------------------------------------
     544
     545Build Set Files
     546~~~~~~~~~~~~~~~
     547
     548Build set files lets you list the packages in the build set you are defining
     549and have a file extension of +.bset+. Build sets can define macro variables,
     550inline include other files and reference other build set or package
     551configuration files.
     552
     553Defining macros is performed with the +%define+ directive:
     554
     555-------------------------------------------------------------
     556%define _target m32r-rtems4.11
     557-------------------------------------------------------------
     558
     559The top level RTEMS build set files specify the target. This is used by other
     560referenced files or an undefined macro error is reported.
     561
     562Inline including another file with the +%include+ directive continues
     563processing with the specified file returning to carry on from just after the
     564include point.
     565
     566-------------------------------------------------------------
     567%include rtems-4.11-base.bset
     568-------------------------------------------------------------
     569
     570This includes the RTEMS 4.11 base set of defines and checks. The configuration
     571paths as defined by +_configdir+ are scanned. The file extension is optional.
     572
     573You reference build set or package configuration files by placing the file name
     574on a single line.
     575
     576-------------------------------------------------------------
     577tools/rtems-binutils-2.22-1
     578-------------------------------------------------------------
     579
     580The +_configdir+ path is scanned for +tools/rtems-binutils-2.22-1.bset+ or
     581+tools/rtems-binutils-2.22-1.cfg+. Build set files take precedent over package
     582configuration files. If +tools/rtems-binutils-2.22-1+ is a build set a new
     583instance of the build set processor is created and if the file is a package
     584configuration the package is built. This all happens once the build set file
     585has finished being scanned.
     586
     587Configuration Files
     588~~~~~~~~~~~~~~~~~~~
     589
     590Configuration files specify how to build a package. Configuration files are
     591scripts and have a +.cfg+ file extension. The script format is based loosely on
     592the RPM spec file format how-ever the use and purpose in this tool does not
     593compare with the functionality and therefore the important features of the spec
     594format RPM needs and uses.
     595
     596Script Language
     597~~~~~~~~~~~~~~~
     598
     599The script language is implemented in terms of directives. The directive list is:
     600
     601[horizontal]
     602+%prep+:: The source preparation shell commands.
     603+%build+:: The build shell commands.
     604+%install+:: The package install shell commands.
     605+%clean+:: The package clean shell commands.
     606+%include+:: Inline include another configuration file.
     607+%package+:: The package being built.
     608+%name+:: The name of the package.
     609+%description+:: A package description. Useful when reporting about a build.
     610+%release+:: The package release. A number that is the release as built by this tool.
     611+%version+:: The package's verison string.
     612+%buildarch+:: The build architecture.
     613+%setup+:: Setup a source package.
     614+%source+:: Define a source code package. This directive is number.
     615+%patch+:: Define a patch. This directive is number.
     616+%warning+:: Print the following string as a warning and continue.
     617+%error+:: Print the following string as an error and exit.
     618+%define+:: Define a macro. Macros cannot be redefined, you must first undefine it.
     619+%undefine+:: Undefine a macro.
     620+%if+:: Start a conditional logic block that ends with a +%endif+.
     621+%ifn+:: Inverted start of a conditional logic block.
     622+%ifarch+:: Test the architecture against the following string.
     623+%ifnarch+:: Inverted test of the architecture
     624+%ifos+:: Test the host operating system.
     625+%else+:: Start the _else_ conditional logic block.
     626+%endfi+:: End the conditional logic block.
     627+%bconf_with+:: Test the build condition _with_ setting. This is the +--with-*+
     628command line option.
     629+%bconf_without+:: Test the build condition _without_ setting. This is the
     630+--without-*+ command line option.
     631
     632%prep
     633^^^^^
     634
     635The +%prep+ directive starts a block that continues until the next block
     636directive. The _prep_ or preparation block defines the setup of the package's
     637source and is a mix of RTEMS Source Builder directives and shell scripting. The
     638sequence is typically +%setup+ directives for source, +%patch+ directives to
     639patch the source mixed with some shell commands to correct any source issues.
     640A +%prep+ section starts with a +%setup+ command. This creates the package
     641source top level directory then is followed by the first source file.
     642
     643-------------------------------------------------------------
     644                     <1>       <2>
     645%setup -q -c -T -n %{name}-%{version}
     646%setup -q -T -D -n %{name}-%{version} -a0
     647-------------------------------------------------------------
     648
     649<1> The package's name.
     650<2> The version of the package.
     651
     652The source for a package is declared with the +%source*+ directive where +*+ is
     653a number. For example +%source0+ is the source 0 tar file and is defined with
     654something similar to this:
     655
     656-------------------------------------------------------------
     657Source0: http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
     658-------------------------------------------------------------
     659
     660This URL is the primary location of the GNU GCC source code and the RTEMS
     661Source Builder can download the file from this location and by inspecting the
     662file extension use +bzip2+ decompression. When the +%prep+ section is processed
     663a check of the local +source+ directory is made to see if the file has already
     664been downloaded. If not found in the source cache directory the package is
     665downloaded from the URL. You can append other base URLs via the command line
     666option +--url+. This option accepts a comma delimited list of sites to try.
     667
     668You can combine the source directive with connditional logic to implement a
     669default that can be overriden in the top level files. This lets you reuse a
     670generic build script with different sources. This happens if you have a private
     671source package with local modifications. The following example is taken from
     672the +gcc-4.8-1.cfg+ build script.
     673
     674-------------------------------------------------------------
     675%ifn %{defined Source0}
     676 Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
     677 VersionContro0: git clone git://gcc.gnu.org/git/gcc.git <1>
     678%endif
     679-------------------------------------------------------------
     680
     681<1> The version control directive is currently not implemented.
     682
     683You could optionally have a few source files that make up the package. For
     684example GNU's GCC was a few tar files for a while and it is now a single tar
     685file. Support for multiple source files can be conditionally implemented with
     686the following scripting:
     687
     688-------------------------------------------------------------
     689%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
     690-------------------------------------------------------------
     691
     692The +source1+ macro value is checked and if present the command string after
     693the +:+ is executed. It is common to see a number of these present allowing top
     694level configuration files including a base configuration the ability to define
     695a number of source packages.
     696
     697-------------------------------------------------------------
     698%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
     699%{?source2:%setup -q -T -D -n %{name}-%{version} -a2}
     700%{?source3:%setup -q -T -D -n %{name}-%{version} -a3}
     701-------------------------------------------------------------
     702
     703Patching also occurs during the preparation stage. Patches are handled in a
     704similar way to the source packages. Most patches are based around the top of
     705the source tree. This is an example of the patch scripting for the GCC 4.8
     706series of compilers:
     707
     708-------------------------------------------------------------
     709cd gcc-%{gcc_version} <1>
     710%{?patch0:%patch0 -p1} <2>
     711%{?patch1:%patch1 -p1}
     712%{?patch2:%patch2 -p1}
     713%{?patch3:%patch3 -p1}
     714%{?patch4:%patch4 -p1}
     715%{?patch5:%patch5 -p1}
     716%{?patch6:%patch6 -p1}
     717%{?patch7:%patch7 -p1}
     718%{?patch8:%patch8 -p1}
     719%{?patch9:%patch9 -p1}
     720cd .. <3>
     721-------------------------------------------------------------
     722
     723<1> Change from the top of the source tree into the package being patched's top
     724    directory.
     725<2> The conditional macro expansion checks if +%patch0+ is defined and if
     726    defined issues the +%patch0" directive giving +-p1+ to the patch command.
     727<3> Return back to the top of the source tree.
     728
     729%build
     730^^^^^^
     731
     732The +%build+ directive starts a block that continues until the next block
     733directive. The build block is a series of shell commands that execute to build
     734the package. It assumes all source code has been unpacked, patch and adjusted
     735so the build will succeed.
     736
     737The following is an example take from the GutHub STLink project [footnote:
     738STLink is a JTAG debugging device for the ST ARM family of processors.]:
     739
     740-------------------------------------------------------------
     741%build
     742  export PATH="%{_bindir}:${PATH}" <1>
     743
     744  cd texane-stlink-%{stlink_version} <2>
     745
     746  ./autogen.sh <3>
     747
     748%if "%{_build}" != "%{_host}"
     749  CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
     750%endif
     751  CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
     752  CFLAGS="$SB_OPT_FLAGS" \
     753  LDFLAGS="-L $SB_TMPPREFIX/lib" \
     754  ./configure \ <6>
     755    --build=%{_build} --host=%{_host} \
     756    --verbose \
     757    --prefix=%{_prefix} --bindir=%{_bindir} \
     758    --exec-prefix=%{_exec_prefix} \
     759    --includedir=%{_includedir} --libdir=%{_libdir} \
     760    --mandir=%{_mandir} --infodir=%{_infodir}
     761
     762  %{__make} %{?_smp_mflags} all <7>
     763
     764  cd ..
     765-------------------------------------------------------------
     766
     767<1> Setup the PATH environment variable. This is not always needed.
     768<2> This package builds in the source tree so enter it.
     769<3> The package is actually checked directly out from the github project and so
     770    it needs its autoconf and automake files generated.
     771<4> Flags for a crosscompiled build.
     772<5> Various settings passed to configure to customise the build. In this
     773    example an include path is being set to the install point of _libusb_. This
     774    package requires _libusb_ is build before it.
     775<6> The +configure+ command. The RTEMS Source Builder provides all the needed
     776    paths as macro variables. You just need to provide them to +configure+.
     777<7> Running make. Do not use +make+ directly, use the RTEMS Source Builder's
     778    defined value. This value is specific to the host. A large number of
     779    packages need GNU make and on BSD systems this is +gmake+. You can
     780    optionally add the SMP flags if the packages build system can handle
     781    parallel building with multiple jobs. The +_smp_mflags+ value is
     782    automatically setup for SMP hosts to match the number of cores the host has.
     783
     784%install
     785^^^^^^^^
     786
     787The +%install+ directive starts a block that continues until the next block
     788directive. The install block is a series of shell commands that execute to
     789install the package. You can assumes the package has build correctly when this
     790shell script executes.
     791
     792Never install the package to the actual _prefix_ the package was built
     793with. Always install to the RTEMS Source Builder's temporary path defined in
     794the macro variable +__tmpdir+. The RTEMS Source Builder sets up a shell
     795environment variable called +SB_BUILD_ROOT+ as the standard install point. Most
     796packages support adding +DESTDIR=+ to the _make install_ command.
     797
     798Looking at the same example as in <<_build, %build>>:
     799
     800-------------------------------------------------------------
     801%install
     802  export PATH="%{_bindir}:${PATH}" <1>
     803  rm -rf $SB_BUILD_ROOT <2>
     804
     805  cd texane-stlink-%{stlink_version} <3>
     806  %{__make} DESTDIR=$SB_BUILD_ROOT install <4>
     807
     808  cd ..
     809-------------------------------------------------------------
     810
     811<1> Setup the PATH environment variable. This is not always needed.
     812<2> Clean any installed files. This make sure the install is just what
     813    the package installs and not any left over files from a broken build or
     814    install.
     815<3> Enter the build directory. In this example it just happens to be the source
     816    directory.
     817<4> Run +make install_ to install the package overriding the +DESTDIR+ make
     818    variable.
     819
     820%clean
     821^^^^^^
     822
     823%include
     824^^^^^^^^
     825
     826%package
     827^^^^^^^^
     828
     829%name
     830^^^^^
     831
     832%description
     833^^^^^^^^^^^^
     834
     835%release
     836^^^^^^^^
     837
     838%version
     839^^^^^^^^
     840
     841%buildarch
     842^^^^^^^^^^
     843
     844%setup
     845^^^^^^
     846
     847%source
     848^^^^^^^
     849
     850%patch
     851^^^^^^
     852
     853%warning
     854^^^^^^^^
     855
     856%error
     857^^^^^^
     858
     859%define
     860^^^^^^^
     861
     862%undefine
     863^^^^^^^^^
     864
     865%if
     866^^^
     867
     868%ifn
     869^^^^
     870
     871%ifarch
     872^^^^^^^
     873
     874%ifnarch
     875^^^^^^^^
     876
     877%ifos
     878^^^^^
     879
     880%else
     881^^^^^
     882
     883%endfi
     884^^^^^^
     885
     886%bconf_with
     887^^^^^^^^^^^
     888
     889%bconf_without
     890^^^^^^^^^^^^^^
     891
     892
     893RTEMS Build Sets
     894----------------
     895
     896Configuration files are typically structured as outer files that are specific
     897to a version of the package being built and become more generic as you move
     898deeper. The outter layers are required to define various macro.
     899
    233900
    234901Set Builder and the Builder
    235902~~~~~~~~~~~~~~~~~~~~~~~~~~~
    236903
    237 The Source Builder provides two commands, the +sb-set-builder+ to build sets of
     904The RTEMS Source Builder provides two commands, the +sb-set-builder+ to build sets of
    238905packages and the +sb-builder+ to build a specific package. The set builder uses
    239906the builder to build a set of packages. You could write a shell script that did
    240 th same thing so the set builder is a convenience command that allows you to
     907the same thing so the set builder is a convenience command that allows you to
    241908define and control specific features of the packages you are building. The set
    242909builder looks for files with the +.bset" extension in the +config+
    243 directories. The builder command uses the configuration files have the +.cfg+
    244 file extension. They also live in the +config+ directories.
    245 
    246 The build set file for the RTEMS 4.10 tool set +rtems/rtems-tools-4.10.bset+
    247 shows a typical build set file structure:
     910directories. The builder command uses configuration files which have the +.cfg+
     911file extension to control the build. The configuration files are written in a
     912script language based on the _spec_ format the RPM builder uses. They also
     913live in the +config+ directories.
     914
     915The build set files for the RTEMS 4.11 can be found in +rtems/4.11/+. There is
     916one per architecture RTEMS supports. This allows variation between
     917architectures is bugs or patches are needed. Sometimes a specific version of a
     918tool may needed to resolve an issue in an architecture, how-ever that version
     919may have a bug in another architecture. We also want to limit architecture
     920specific patches to the architecture it relates to. This avoids any crosstalk a
     921patch may have with another architecture. An example of this is the NIOS2
     922tools. They are built using a version of GCC released by Altera currently not
     923in the Free Software Foundation's GCC project.
     924
     925This is the build set for the Blackfin processor or +bfin+.
    248926
    249927-------------------------------------------------------------
     
    5141192~~~~~~~~~~~~~~~~~~~~~
    5151193
    516 The Source Builder has a +config+ and +patches+ directory that contain some
     1194The RTEMS Source Builder has a +config+ and +patches+ directory that contain some
    5171195useful and often needed configurations and patches. You do not need to add your
    518 project specific configurations into the Source Builder. You can create a
    519 private set and then use the Source Builder to build your packages.
     1196project specific configurations into the RTEMS Source Builder. You can create a
     1197private set and then use the RTEMS Source Builder to build your packages.
    5201198
    5211199Create a +config+ directory and place your build sets and configuration in
    5221200them. If you have private patches add them to a +patches+ directory next to the
    523 +config+ directiory. When you run a Source Builder command it will first search
     1201+config+ directiory. When you run a RTEMS Source Builder command it will first search
    5241202the for the specific file then the local +config+ directoy then the Source
    5251203Builder's +config+ directory. The same goes for +patches+.
     
    5291207RTEMS project.
    5301208
    531 If you are an open source project and you find the Source Builder useful and
    532 would like your configuration held in the Source Builder's repository please
     1209If you are an open source project and you find the RTEMS Source Builder useful and
     1210would like your configuration held in the RTEMS Source Builder's repository please
    5331211contact me directly.
    5341212
    535 Using the Builder
    536 ~~~~~~~~~~~~~~~~~
     1213The Builder
     1214~~~~~~~~~~~
    5371215
    5381216TBD
    5391217
    540 RTEMS Build Sets
    541 ----------------
    542 
    543 The Source Builder package comes with the RTEMS project's build sets and
    544 configurations. These let you build tools for RTEMS. To use clone the Source
    545 Builder repository and change into the +rtems+ directory:
    546 
    547 -------------------------------------------------------------
    548 $ git clone git://git.rtems.org/chrisj/rtems-source-builder.git
    549 $ cd rtems
    550 -------------------------------------------------------------
    551 
    552 To build all the available architectures you can run the provided script giving
    553 it a prefix:
    554 
    555 -------------------------------------------------------------
    556 $ ./build-4.10-targets.sh $HOME/development/rtems/4.10 <1>
    557 -------------------------------------------------------------
    558 
    559 <1> This is a local user path and does not need root to install.
    560 
    561 To build a tool set for a specific architecture you enter:
    562 
    563 -------------------------------------------------------------
    564 $ ../source-builder/sb-set-builder --log=l-arm.txt \
    565              --prefix=$HOME/development/rtems/4.10 \
    566              --target=arm-rtems4.10 rtems-tools-4.10
    567 -------------------------------------------------------------
    568 
    569 The results of the build are found in the +tar+ directory. The packages that
    570 make the build set are available as packages as well as the combined package
    571 for the whole build set:
    572 
    573 -------------------------------------------------------------
    574 $ ls -1 tar
    575 arm-rtems4.10-binutils-2.20.1-1.tar.bz2 <1>
    576 arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.tar.bz2
    577 arm-rtems4.10-gdb-7.3.1-1.tar.bz2
    578 rtems-4.10-arm-rtems4.10-1.tar.bz2 <2>
    579 -------------------------------------------------------------
    580 
    581 <1> The bintuls part of the build set as a separate tar file.
    582 <2> The RTEMS ARM tool set. This is various packages combined.
    583 
    584 The tar files are constructed from the top of the prefix you provide. If you
    585 provide a relative prefix the installation will be relative. How well this
    586 works depends on the specifics of the application being packaged. Some such as
    587 binutils and gcc can be relocated without any issues how-ever other such as
    588 autoconf and automake cannot be relocated. Those packages contain absolute file
    589 names. In the example above the prefix was +$HOME/development/rtems/4.10+ so
    590 the contents of the tar file is:
    591 
    592 -------------------------------------------------------------
    593 tar jtf tar/rtems-4.10-arm-rtems4.10-1.tar.bz2
    594 ./
    595 ./home/
    596 ./home/chris/
    597 ./home/chris/development/
    598 ./home/chris/development/rtems/
    599 ./home/chris/development/rtems/4.10/
    600 ./home/chris/development/rtems/4.10/arm-rtems4.10/
    601 ./home/chris/development/rtems/4.10/bin/
    602 ./home/chris/development/rtems/4.10/include/
    603 ./home/chris/development/rtems/4.10/lib/
    604 ./home/chris/development/rtems/4.10/libexec/
    605   ....
    606 ./home/chris/development/rtems/4.10/lib/gcc/arm-rtems4.10/4.4.7/fpu/libsupc++.la
    607 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-addr2line
    608 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-ar
    609 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-as
    610 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-c++
    611 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-c++filt
    612 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-cpp
    613 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-g++
    614 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gcc
    615 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gcc-4.4.7
    616 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gccbug
    617 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gcov
    618 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gdb
    619 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gdbtui
    620 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-gprof
    621 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-ld
    622 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-nm
    623 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-objcopy
    624 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-objdump
    625 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-ranlib
    626 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-readelf
    627 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-run
    628 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-size
    629 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-strings
    630 ./home/chris/development/rtems/4.10/bin/arm-rtems4.10-strip
    631 ./home/chris/development/rtems/4.10/arm-rtems4.10/bin/
    632 ./home/chris/development/rtems/4.10/arm-rtems4.10/include/
    633  ....
    634 -------------------------------------------------------------
    635 
    636 Because the path is absolute and references directories that +root+ owns +root+
    637 access would normally be needed. This can be avoided if your tar supports the
    638 +--strip-components=+ option. To install this package without becoming +root+:
    639 
    640 -------------------------------------------------------------
    641 $ cd
    642 $ tar --strip-components=3 -jxf \
    643  development/rtems/build/rtems-source-builder/rtems/tar/tar/rtems-4.10-arm-rtems4.10-1.tar.bz2
    644 -------------------------------------------------------------
    645 
    646 Source Builder Commands
    647 -----------------------
     1218Commands
     1219--------
    6481220
    6491221Checker (sb-check)
     
    6551227$ ./source-builder/sb-check --help
    6561228sb-check: [options] [args]
    657 Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     1229RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
    6581230Options and arguments:
    6591231--force                : Create directories that are not present
     
    6921264$ ./source-builder/sb-set-builder --help
    6931265sb-set-builder: [options] [args]
    694 Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     1266RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
    6951267Options and arguments:
    6961268--force                : Create directories that are not present
     
    7311303$ ./source-builder/sb-builder --help
    7321304sb-builder: [options] [args]
    733 Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     1305RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
    7341306Options and arguments:
    7351307--force                : Create directories that are not present
     
    7631335-----------
    7641336
     1337MacOS X
     1338~~~~~~~
     1339
     1340The RTEMS Source Builder has been tested on Mountain Lion. You will need to
     1341install the Xcode app using the _App Store_ tool, run Xcode and instal the
     1342Developers Tools package within Xcode.
     1343
    7651344Ubuntu
    7661345~~~~~~
    7671346
    768 -------------------------------------------------------------
    769 $ sudo apt-get build-dep binutils gcc g++ gdb
    770 -------------------------------------------------------------
     1347The latest testing was with 12.10. A minimal installation was used and the
     1348following packages installed.
     1349
     1350-------------------------------------------------------------
     1351$ sudo apt-get build-dep binutils gcc g++ gdb unzip git
     1352-------------------------------------------------------------
     1353
     1354Raspbian
     1355~~~~~~~~
     1356
     1357The is the Debian distribution for the Raspberry Pi. The following packages are
     1358required.
     1359
     1360-------------------------------------------------------------
     1361$ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
     1362texinfo unzip ncurses-dev python-dev
     1363-------------------------------------------------------------
     1364
     1365It is recommended you get Model B of the Pi with 512M of memory and to mount a
     1366remote disk over the network. The tools can be build with a prefix under your
     1367home directory as recommended and end up on the SD card.
    7711368
    7721369CentOS 6
     
    7761373
    7771374-------------------------------------------------------------
    778 # yum install autoconf automake binutils gcc gcc-c++ gdb make patch flex xz
    779 unzip ncurses-devel texinfo zlib-devel python-devel
     1375# yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
     1376bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
    7801377-------------------------------------------------------------
    7811378
     
    7831380system. If you use a full system some of these packages may have been
    7841381installed.
     1382
     1383History
     1384-------
     1385
     1386The RTEMS Source Builder is a stand alone tool based on another tool called the
     1387'SpecBuilder'. The SpecBuilder was written for the RTEMS project too give me a
     1388way to build tools on hosts that did not support RPMs. At the time the RTEMS
     1389tools maintainer only used spec files to create various packages. This meant I
     1390had either spec files, RPM files or SRPM files. The RPM and SPRM files where
     1391useless because you needed an 'rpm' type tool to extract and manage them. There
     1392are versions of 'rpm' for a number of non-RPM hosts how-ever these proved to be
     1393in various broken states and randomally maintained. The solution I settled on
     1394was to use spec files so I wrote a Python based tool that parsed the spec file
     1395format and allowed me to create a shell script I could run to build the
     1396package. This approach proved successful and I was able to track the RPM
     1397version of the RTEMS tools on a non-RPM host over a number of years. How-ever
     1398the SpecBuilder tool did not help me build tools or other packages not related
     1399to the RTEMS project where there was no spec file I could use so I needed
     1400another tool. Rather than start again I decided to take the parsing code for
     1401the spec file format and build a new tool called the RTEMS Source Builder.
  • source-builder/doc/wscript

    r77c68e8 r5ba5405  
    77def configure(ctx):
    88    ctx.env.ASCIIDOC = ctx.find_program(['asciidoc.py'], mandatory = True)
    9     ctx.env.ASCIIDOC_FLAGS = ['-b', 'html', '-a', 'data-uri', '-a', 'icons', '-a', 'max-width=55em-a']
     9    ctx.env.ASCIIDOC_FLAGS = ['-b', 'html5', '-a', 'data-uri', '-a', 'icons', '-a', 'max-width=55em-a']
    1010
    1111def build(ctx):
Note: See TracChangeset for help on using the changeset viewer.