Changeset 069c7de in rtems-source-builder


Ignore:
Timestamp:
Nov 10, 2012, 5:19:15 AM (7 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.10, 4.11, 4.9, master
Children:
9215db1
Parents:
6e10a49
Message:

More documentation added.

File:
1 edited

Legend:

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

    r6e10a49 r069c7de  
    9595-----------
    9696
     97The quick start will show you how to build a generic unpatched GNU tool set for
     98any support target.
     99
    97100Check out the Source Builder tool from git:
    98101
     
    155158  gnu-tools-4.6 <3>
    156159  rtems-tools-4.10 <4>
     160  rtems-tools-4.11 <5>
    157161-------------------------------------------------------------
    158162
     
    161165<3> The Source Builder provided GNU tools GCC 4.6 build set.
    162166<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.
    163168
    164169And to view the configurations you can:
     
    193198  texane-stlink-1
    194199  rtems-binutils-2.20.1-1
     200  rtems-binutils-2.22-1
    195201  rtems-gcc-4.4.7-newlib-1.18.0-1
     202  rtems-gcc-4.6.3-newlib-1.20.0-1
    196203  rtems-gdb-7.3.1-1
     204  rtems-gdb-7.5-1
    197205-------------------------------------------------------------
    198206
     
    206214support to build a number of packages. A project that uses the Source Builder
    207215can create a specialised set of configuration files that provides the specific
    208 configurations thet project uses.
    209 
    210 For example the RTEMS project provides its own set of configuration files. In
    211 the build set list in the 'Quick Start' section you can see a build set
    212 +rtems-tools-4.10+. This build set defines the extact configration to use for
    213 the RTEMS 4.10 release.
    214 
     216configurations a project uses.
     217
     218For example the RTEMS project provides its own set of configuration files
     219inside the Source Builder. They do not have to be here. In the build set list
     220in 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
     222the RTEMS releases.
     223
     224The Source Builder has been tested on:
     225
     226. FreeBSD
     227. MacOS (Mountain Lion)
     228. Ubuntu
     229. Fedora
     230
     231Windows will be support how-ever there are issues with the Python threading
     232used in the Source Builder and the MinGW project's MSYS process handling of make.
     233
     234Set Builder and the Builder
     235~~~~~~~~~~~~~~~~~~~~~~~~~~~
     236
     237The Source Builder provides two commands, the +sb-set-builder+ to build sets of
     238packages and the +sb-builder+ to build a specific package. The set builder uses
     239the builder to build a set of packages. You could write a shell script that did
     240th same thing so the set builder is a convenience command that allows you to
     241define and control specific features of the packages you are building. The set
     242builder looks for files with the +.bset" extension in the +config+
     243directories. The builder command uses the configuration files have the +.cfg+
     244file extension. They also live in the +config+ directories.
     245
     246The build set file for the RTEMS 4.10 tool set +rtems/rtems-tools-4.10.bset+
     247shows a typical build set file structure:
     248
     249-------------------------------------------------------------
     250#
     251# Tools Set for RTEMS 4.10
     252#
     253
     254%define rtems_version 4.10 <1>
     255
     256%define release 1 <2>
     257
     258package: rtems-%{rtems_version}-%{_target}-%{release} <3>
     259
     260#
     261# Project custom message
     262#
     263%define gcc_version_message RTEMS %{rtems_version}-%{release},gcc-%{gcc_version}/newlib-%{newlib_version} <4>
     264
     265#
     266# Tools configuration.
     267#
     268rtems-binutils-2.20.1-1 <5>
     269rtems-gcc-4.4.7-newlib-1.18.0-1
     270rtems-gdb-7.3.1-1
     271-------------------------------------------------------------
     272
     273<1> Define the version of RTEMS.
     274<2> Define the release. This allows us to number the tool releases.
     275<3> The top level name of the package. The finaly tar file name.
     276<4> The GCC configuration allow a custom message to be embedded into GCC.
     277<5> The list of packages this build set contains.
     278
     279Currently the syntax of the set builder scripts is limited. It support
     280comments, the package command, macros (the +%{}+), and defining macros
     281(+%define+). It is planned to allow more of the configuration file syntax in
     282the future.
     283
     284The builder uses configuration files that allow the full range of the
     285configuration script syntax. Configuration files follow most of the RPM spec
     286file format. They support macros and logic as well as the ability to include
     287other configuration files. The ability to include other configuration files
     288allow a simple way to configuration control the builds. Configuration files
     289have four main areas:
     290
     291. Descriptions and definitions.
     292+
     293The description lists various useful pieces of information about the
     294package. None of this is currently enforced how-ever it is good practice to
     295provide it. The definitions are the sources and the patches.
     296. Preparation
     297+
     298The preparation is the set up of the source code ready for building. The set up
     299follows the unusual command structure used by RPM. The follwing macro
     300trickshows how to conditional patch the source if a patch has been declared.
     301+
     302-------------------------------------------------------------
     303cd expat-%{expat_version}
     304%{?patch0:%patch0 -p1}
     305cd ..
     306-------------------------------------------------------------
     307+
     308. Build
     309+
     310The build phase. This is a fragment of shell script that can be mixed with
     311conditional configuration scripting to create the list of build commands.
     312+
     313. Install
     314+
     315The install phase. Again this is a fragment of shell script.
     316
     317This is a configuration script to build gdb:
     318
     319-------------------------------------------------------------
     320#
     321# GDB 7.xx Version 1.
     322#
     323# This configuration file configure's, make's and install's gdb.
     324#
     325
     326%include %{_configdir}/checks.cfg <1>
     327
     328Name:      %{_target}-gdb-%{gdb_version}-%{release} <2>
     329Summary:   GDB v%{gdb_version} for target %{_target} on host %{_host}
     330Version:   %{gdb_version}
     331Release:   %{release}
     332URL:       http://www.gnu.org/software/gdb/
     333BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n)
     334
     335#
     336# Source
     337#
     338Source0: http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2 <3>
     339VersionControl0 git clone git://sourceware.org/git/gdb.git
     340
     341#
     342# Prepare the source code.
     343#
     344%prep <4>
     345%setup -q -c -T -n %{name}-%{version}
     346cd gdb-%{gdb_version}
     347%{?patch0:%patch0 -p1}
     348cd ..
     349
     350%build <5>
     351  export PATH="%{_bindir}:${PATH}"
     352  mkdir -p build
     353  cd build
     354%if "%{_build}" != "%{_host}"
     355  CFLAGS_FOR_BUILD="-g -O2 -Wall" \
     356%endif
     357  CFLAGS="$SB_OPT_FLAGS" \
     358  ../gdb-%{gdb_version}/configure \
     359    --build=%{_build} --host=%{_host} \
     360    --target=%{_target} \
     361    --verbose --disable-nls \
     362    --without-included-gettext \
     363    --disable-win32-registry \
     364    --disable-werror \
     365    --enable-sim \
     366    --with-expat \
     367    --with-python \
     368    --prefix=%{_prefix} --bindir=%{_bindir} \
     369    --exec-prefix=%{_exec_prefix} \
     370    --includedir=%{_includedir} --libdir=%{_libdir} \
     371    --mandir=%{_mandir} --infodir=%{_infodir}
     372
     373  %{__make} %{?_smp_mflags} all
     374  cd ..
     375
     376%install <6>
     377  export PATH="%{_bindir}:${PATH}"
     378  rm -rf $SB_BUILD_ROOT
     379
     380  cd build
     381  %{__make} DESTDIR=$SB_BUILD_ROOT install
     382
     383  # Dropped in FSF-binutils-2.9.5, but Cygwin still ships it.
     384  rm -rf $SB_BUILD_ROOT%{_infodir}/configure.info*
     385
     386  rm -f $SB_BUILD_ROOT%{_infodir}/dir
     387  touch $SB_BUILD_ROOT%{_infodir}/dir
     388
     389  cd ..
     390-------------------------------------------------------------
     391
     392<1> Including a file. The +_configdir+ macro searchs a list of paths.
     393<2> The description section.
     394<3> The source file as a URL. If not found in the +sources+ directories it is
     395downloaded.
     396<4> Preparing the source code.
     397<5> The commands to build +gdb+.
     398<6> The installation phase. Notice the +DESTDIR=+ feature is used.
     399
     400Controlling Configurations
     401~~~~~~~~~~~~~~~~~~~~~~~~~~
     402
     403This is a simple process of including the specific pieces you need. There
     404typically is three layers where the top level is specific and each sub-layer is
     405more generic configured by the layer above it. The typical layering is:
     406
     407. Build Set
     408. Package definition
     409. Package configuration
     410
     411The build set defines the packages to be built plus any specific configuration
     412needed. Some packages default to standard values if the build set does not
     413provide any specific configuration and some configurations raise an error
     414indicating a required configuration is missing.
     415
     416Using the RTEMS 4.10 Tools Set build as an example the build set configuration
     417is:
     418
     419-------------------------------------------------------------
     420#
     421# Tools Set for RTEMS 4.10
     422#
     423
     424%define rtems_version 4.10
     425
     426%define release 1 <1>
     427
     428package: rtems-%{rtems_version}-%{_target}-%{release}
     429
     430#
     431# Project custom message
     432#
     433%define gcc_version_message RTEMS %{rtems_version}-%{release},gcc-%{gcc_version}/newlib-%{newlib_version}
     434
     435#
     436# Tools configuration.
     437#
     438rtems-binutils-2.20.1-1 <2>
     439rtems-gcc-4.4.7-newlib-1.18.0-1
     440rtems-gdb-7.3.1-1
     441-------------------------------------------------------------
     442
     443<1> The release of the RTEMS 4.10 tools package.
     444<2> The build configurations. These reference the specific version of the tools
     445including the related patches. You should note the configurations referenced
     446are RTEMS specific, that is prefixed with +rtems-+.
     447
     448The GCC and Newlib file +rtems-gcc-4.4.7-newlib-1.18.0-1+ is:
     449
     450-------------------------------------------------------------
     451#
     452# GCC 4.4.7, Newlib 1.18.0
     453#
     454
     455%include %{_configdir}/checks.cfg <1>
     456%include %{_configdir}/base.cfg <2>
     457
     458%define gcc_version    4.4.7 <3>
     459%define newlib_version 1.18.0
     460%define mpfr_version   2.4.1
     461%define mpc_version    0.8.2
     462%define gmp_version    5.0.5
     463
     464%define with_threads 1 <4>
     465%define with_plugin  0
     466%define with_iconv   1
     467
     468#
     469# AVR C++ does not work.
     470#   configure: error: unable to detect exception model
     471#
     472%if %{_target} == avr-rtems4.10 <5>
     473%define enable_cxx 0
     474%endif
     475
     476#
     477# M32C C++ does not work.
     478#   gcc-4.4.7/libstdc++-v3/src/mt_allocator.cc:76: error: cast from 'void*' to 'size_t' loses precision
     479#
     480%if %{_target} == m32c-rtems4.10
     481%define enable_cxx 0
     482%endif
     483
     484%ifn %{defined enable_cxx} <6>
     485%define enable_cxx 1
     486%endif
     487
     488#
     489# The RTEMS 4.10 patches
     490#
     491Patch0:  gcc-core-4.4.7-rtems4.10-20120314.diff <7>
     492%if %{enable_cxx}
     493Patch1:  gcc-g++-4.4.7-rtems4.10-20120314.diff
     494%endif
     495Patch10: newlib-1.18.0-rtems4.10-20110518.diff
     496
     497#
     498# The gcc/newlib build instructions. We use 4.4 Release 1.
     499#
     500%include %{_configdir}/gcc-4.4-1.cfg <8>
     501-------------------------------------------------------------
     502
     503<1> Perform some standard checks such as the release being set.
     504<2> Set up some standard macros needed by most configure type packages.
     505<3> The specific versions of the various parts that make a GCC embedded
     506cross-compiler.
     507<4> Configure some specific parts of GCC and Newlib for RTEMS.
     508<5> Disable C++ for the AVR target because it does not build for RTEMS.
     509<6> Default is to build C++.
     510<7> The various patches. This file's revision increases with each patch change.
     511<8> The generic GCC/Newlib build configuration for gcc-4.4.x.
     512
     513Project Configuration
     514~~~~~~~~~~~~~~~~~~~~~
     515
     516The Source Builder has a +config+ and +patches+ directory that contain some
     517useful and often needed configurations and patches. You do not need to add your
     518project specific configurations into the Source Builder. You can create a
     519private set and then use the Source Builder to build your packages.
     520
     521Create a +config+ directory and place your build sets and configuration in
     522them. 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
     524the for the specific file then the local +config+ directoy then the Source
     525Builder's +config+ directory. The same goes for +patches+.
     526
     527For example of this set up look in the +rtems+ directory in the Source
     528Builder. It is actually a standard alone project configuration private to the
     529RTEMS project.
     530
     531If you are an open source project and you find the Source Builder useful and
     532would like your configuration held in the Source Builder's repository please
     533contact me directly.
     534
     535Using the Builder
     536~~~~~~~~~~~~~~~~~
     537
     538TBD
     539
     540RTEMS Build Sets
     541----------------
     542
     543The Source Builder package comes with the RTEMS project's build sets and
     544configurations. These let you build tools for RTEMS. To use clone the Source
     545Builder 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
     552To build all the available architectures you can run the provided script giving
     553it 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
     561To 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
     569The results of the build are found in the +tar+ directory. The packages that
     570make the build set are available as packages as well as the combined package
     571for the whole build set:
     572
     573-------------------------------------------------------------
     574$ ls -1 tar
     575arm-rtems4.10-binutils-2.20.1-1.tar.bz2 <1>
     576arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.tar.bz2
     577arm-rtems4.10-gdb-7.3.1-1.tar.bz2
     578rtems-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
     584The tar files are constructed from the top of the prefix you provide. If you
     585provide a relative prefix the installation will be relative. How well this
     586works depends on the specifics of the application being packaged. Some such as
     587binutils and gcc can be relocated without any issues how-ever other such as
     588autoconf and automake cannot be relocated. Those packages contain absolute file
     589names. In the example above the prefix was +$HOME/development/rtems/4.10+ so
     590the contents of the tar file is:
     591
     592-------------------------------------------------------------
     593tar 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
     636Because the path is absolute and references directories that +root+ owns +root+
     637access 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
     646Source Builder Commands
     647-----------------------
     648
     649Checker (sb-check)
     650~~~~~~~~~~~~~~~~~~
     651
     652This commands checks your system is set up correctly.
     653
     654-------------------------------------------------------------
     655$ ./source-builder/sb-check --help
     656sb-check: [options] [args]
     657Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     658Options and arguments:
     659--force                : Create directories that are not present
     660--trace                : Trace the execution (not current used)
     661--dry-run              : Do everything but actually run the build
     662--warn-all             : Generate warnings
     663--no-clean             : Do not clean up the build tree
     664--no-smp               : Run with 1 job and not as many as CPUs
     665--rebuild              : Rebuild (not used)
     666--host                 : Set the host triplet
     667--build                : Set the build triplet
     668--target               : Set the target triplet
     669--prefix path          : Tools build prefix, ie where they are installed
     670--prefixbase path      :
     671--topdir path          : Top of the build tree, default is $PWD
     672--configdir path       : Path to the configuration directory, default: ./config
     673--builddir path        : Path to the build directory, default: ./build
     674--sourcedir path       : Path to the source directory, default: ./source
     675--tmppath path         : Path to the temp directory, default: ./tmp
     676--log file             : Log file where all build out is written too
     677--url url              : URL to look for source
     678--targetcflags flags   : List of C flags for the target code
     679--targetcxxflags flags : List of C++ flags for the target code
     680--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
     681--with-<label>         : Add the --with-<label> to the build
     682--without-<label>      : Add the --without-<label> to the build
     683-------------------------------------------------------------
     684
     685Set Builder (sb-set-builder)
     686~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     687
     688This command builds a set as described in a build set. Build set files have the
     689extension of +.bset+.
     690
     691-------------------------------------------------------------
     692$ ./source-builder/sb-set-builder --help
     693sb-set-builder: [options] [args]
     694Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     695Options and arguments:
     696--force                : Create directories that are not present
     697--trace                : Trace the execution (not current used)
     698--dry-run              : Do everything but actually run the build
     699--warn-all             : Generate warnings
     700--no-clean             : Do not clean up the build tree
     701--no-smp               : Run with 1 job and not as many as CPUs
     702--rebuild              : Rebuild (not used)
     703--host                 : Set the host triplet
     704--build                : Set the build triplet
     705--target               : Set the target triplet
     706--prefix path          : Tools build prefix, ie where they are installed
     707--prefixbase path      :
     708--topdir path          : Top of the build tree, default is $PWD
     709--configdir path       : Path to the configuration directory, default: ./config
     710--builddir path        : Path to the build directory, default: ./build
     711--sourcedir path       : Path to the source directory, default: ./source
     712--tmppath path         : Path to the temp directory, default: ./tmp
     713--log file             : Log file where all build out is written too
     714--url url              : URL to look for source
     715--targetcflags flags   : List of C flags for the target code
     716--targetcxxflags flags : List of C++ flags for the target code
     717--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
     718--with-<label>         : Add the --with-<label> to the build
     719--without-<label>      : Add the --without-<label> to the build
     720--list-configs         : List available configurations
     721--list-bsets           : List available build sets
     722-------------------------------------------------------------
     723
     724Set Builder (sb-builder)
     725~~~~~~~~~~~~~~~~~~~~~~~~
     726
     727This command builds a configuration as described in a configuration
     728file. Configuration files have the extension of +.cfg+.
     729
     730-------------------------------------------------------------
     731$ ./source-builder/sb-builder --help
     732sb-builder: [options] [args]
     733Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
     734Options and arguments:
     735--force                : Create directories that are not present
     736--trace                : Trace the execution (not current used)
     737--dry-run              : Do everything but actually run the build
     738--warn-all             : Generate warnings
     739--no-clean             : Do not clean up the build tree
     740--no-smp               : Run with 1 job and not as many as CPUs
     741--rebuild              : Rebuild (not used)
     742--host                 : Set the host triplet
     743--build                : Set the build triplet
     744--target               : Set the target triplet
     745--prefix path          : Tools build prefix, ie where they are installed
     746--prefixbase path      :
     747--topdir path          : Top of the build tree, default is $PWD
     748--configdir path       : Path to the configuration directory, default: ./config
     749--builddir path        : Path to the build directory, default: ./build
     750--sourcedir path       : Path to the source directory, default: ./source
     751--tmppath path         : Path to the temp directory, default: ./tmp
     752--log file             : Log file where all build out is written too
     753--url url              : URL to look for source
     754--targetcflags flags   : List of C flags for the target code
     755--targetcxxflags flags : List of C++ flags for the target code
     756--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
     757--with-<label>         : Add the --with-<label> to the build
     758--without-<label>      : Add the --without-<label> to the build
     759--list-configs         : List available configurations
     760-------------------------------------------------------------
     761
     762Host Setups
     763-----------
     764
     765Ubuntu
     766~~~~~~
     767
     768-------------------------------------------------------------
     769sudo apt-get build-dep binutils gcc g++ gdb
     770-------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.