Changeset 2674d6a in rtems-docs for user/rsb


Ignore:
Timestamp:
Feb 21, 2019, 2:06:58 AM (12 months ago)
Author:
Chris Johns <chrisj@…>
Branches:
master
Children:
921037f
Parents:
2e6f49f
git-author:
Chris Johns <chrisj@…> (02/21/19 02:06:58)
git-committer:
Chris Johns <chrisj@…> (02/27/19 23:22:54)
Message:

user: Remove nit-picky warnings.

Location:
user/rsb
Files:
10 edited

Legend:

Unmodified
Added
Removed
  • user/rsb/bug-reporting.rst

    r2e6f49f r2674d6a  
    66
    77Bugs, Crashes, and Build Failures
    8 =================================
     8---------------------------------
    99
    1010The RTEMS Source Builder is a Python program and every care is taken to test
  • user/rsb/commands.rst

    r2e6f49f r2674d6a  
    44
    55Commands
    6 ========
     6--------
    77
    88Checker (sb-check)
    9 ------------------
    10 
    11 This commands checks your system is set up correctly. Most options are ignored::
     9^^^^^^^^^^^^^^^^^^
     10
     11This commands checks your system is set up correctly. Most options are ignored:
     12
     13.. code-block:: shell
    1214
    1315    $ ../source-builder/sb-check --help
     
    4850
    4951Defaults (sb-defaults)
    50 ----------------------
     52^^^^^^^^^^^^^^^^^^^^^^
    5153
    5254This commands outputs and the default macros for your when given no
    53 arguments. Most options are ignored::
     55arguments. Most options are ignored:
     56
     57.. code-block:: shell
    5458
    5559    $ ../source-builder/sb-defaults --help
     
    8791
    8892Set Builder (sb-set-builder)
    89 ----------------------------
    90 
    91 This command builds a set::
     93^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     94
     95This command builds a set:
     96
     97.. code-block:: shell
    9298
    9399    $ ../source-builder/sb-set-builder --help
     
    292298
    293299Set Builder (sb-builder)
    294 ------------------------
     300^^^^^^^^^^^^^^^^^^^^^^^^
    295301
    296302This command builds a configuration as described in a configuration
    297 file. Configuration files have the extension of ``.cfg``::
     303file. Configuration files have the extension of ``.cfg``:
     304
     305.. code-block:: shell
    298306
    299307    $ ./source-builder/sb-builder --help
  • user/rsb/configuration.rst

    r2e6f49f r2674d6a  
    66
    77Configuration
    8 =============
     8-------------
    99
    1010The RTEMS Source Builder has two types of configuration data:
     
    2424
    2525The configuration search path is a macro variable and is reference as
    26 ``%{_configdir}``. It's default is defined as::
    27 
    28     _configdir   : dir  optional<2>  %{_topdir}/config:%{_sbdir}/config <1>
     26``%{_configdir}``. It's default is defined as:
     27
     28.. code-block:: spec
     29
     30    _configdir   : dir  optional  %{_topdir}/config:%{_sbdir}/config
    2931
    3032.. topic:: Items:
     
    4648
    4749Source and Patches
    48 ------------------
     50^^^^^^^^^^^^^^^^^^
    4951
    5052The RTEMS Source Builder provides a flexible way to manage source. Source and
     
    8991download the file. The standard GNU GCC compiler source URL is:
    9092
    91 .. code-block:: auto
    92 
    93     %source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
     93.. code-block:: spec
     94
     95    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
    9496
    9597.. topic:: Items:
    9698
    97   1. The ``%source`` command's set command sets the source. The first is set
    98      and following sets are ignored.
    99 
    100   2. The source is part of the ``gcc`` group.
     99  1. The ``%source`` command's ``set`` command sets the source. The
     100     first is set and following sets are ignored.
     101
     102  2. The source package is part of the ``gcc`` group.
    101103
    102104The type of compression is automatically detected from the file extension. The
     
    133135STLINK project on GitHub and version is:
    134136
    135 .. code-block:: auto
     137.. code-block:: spec
    136138
    137139    %define stlink_version 3494c11
     
    169171An example is:
    170172
    171 .. code-block:: auto
     173.. code-block:: spec
    172174
    173175    %source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
     
    206208The following is an example of checking out from a CVS repository:
    207209
    208 .. code-block:: auto
     210.. code-block:: spec
    209211
    210212    %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src
    211213
    212214Macros and Defaults
    213 -------------------
     215^^^^^^^^^^^^^^^^^^^
    214216
    215217The RTEMS Source Builder uses tables of *macros* read in when the tool
     
    221223Build set and configuration files can define new values updating and extending
    222224the global macro table. For example builds are given a release number. This is
    223 typically a single number at the end of the package name. For example::
     225typically a single number at the end of the package name. For example:
     226
     227.. code-block:: spec
    224228
    225229    %define release 1
    226230
    227231Once defined if can be accessed in a build set or package configuration file
    228 with::
     232with:
     233
     234.. code-block:: spec
    229235
    230236    %{release}
    231237
    232238The ``sb-defaults`` command lists the defaults for your host. I will not include
    233 the output of this command because of its size::
     239the output of this command because of its size:
     240
     241.. code-block:: shell
    234242
    235243    $ ../source-builder/sb-defaults
     
    249257start up by using the ``--macros`` command line option.
    250258
    251 The format for a macro in macro files is::
     259The format for a macro in macro files is:
     260
     261.. code-block:: ini
    252262
    253263  Name Type Attribute String
     
    291301currently detected and will cause the tool to lock up.
    292302
    293 Maps are declared anywhere in the map using the map directive::
     303Maps are declared anywhere in the map using the map directive:
     304
     305.. code-block:: ini
    294306
    295307    # Comments
     
    306318Any macro defintions following a map declaration are placed in that map and the
    307319default map is ``global`` when loading a file. Maps are selected in
    308 configuration files by using the ``%select`` directive::
     320configuration files by using the ``%select`` directive:
     321
     322.. code-block:: spec
    309323
    310324    %select my-special-map
     
    321335Macro map files can include other macro map files using the ``%include``
    322336directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
    323 RTEMS from version control heads is::
    324 
    325     # <1>
     337RTEMS from version control heads is:
     338
     339.. code-block:: spec
     340
     341    #
    326342    # Build all tool parts from version control head.
    327343    #
     
    350366
    351367Report Mailing
    352 --------------
     368^^^^^^^^^^^^^^
    353369
    354370The build reports can be mailed to a specific email address to logging and
     
    381397not a check is made for a ``.mailrc`` file. The environment variable ``MAILRC``
    382398is used if present else your home directory is check. If found the file is
    383 scanned for the ``from`` setting::
     399scanned for the ``from`` setting:
     400
     401.. code-block:: shell
    384402
    385403  set from="Foo Bar <foo@bar>"
     
    393411
    394412Build Set Files
    395 ---------------
     413^^^^^^^^^^^^^^^
    396414
    397415Build set files lets you list the packages in the build set you are defining
     
    400418configuration files.
    401419
    402 Defining macros is performed with the ``%define`` macro::
     420Defining macros is performed with the ``%define`` macro:
     421
     422.. code-block:: spec
    403423
    404424    %define _target m32r-rtems4.11
     
    406426Inline including another file with the ``%include`` macro continues processing
    407427with the specified file returning to carry on from just after the include
    408 point::
     428point:
     429
     430.. code-block:: spec
    409431
    410432    %include rtems-4.11-base.bset
     
    414436
    415437You reference build set or package configuration files by placing the file name
    416 on a single line::
     438on a single line:
     439
     440.. code-block:: spec
    417441
    418442    tools/rtems-binutils-2.22-1
     
    426450
    427451Configuration Control
    428 ---------------------
     452^^^^^^^^^^^^^^^^^^^^^
    429453
    430454The RTEMS Souce Builder is designed to fit within most verification and
     
    442466Newlib version is 2.0.0, plus any RTEMS specific patches that related to this
    443467version. The configuration defines the version numbers of the various parts
    444 that make up this package::
     468that make up this package:
     469
     470.. code-block:: spec
    445471
    446472    %define gcc_version    4.7.2
     
    450476    %define gmp_version    5.0.5
    451477
    452 The package build options, if there are any are also defined::
     478The package build options, if there are any are also defined:
     479
     480.. code-block:: spec
    453481
    454482    %define with_threads 1
     
    458486The generic configuration may provide defaults in case options are not
    459487specified. The patches this specific version of the package requires can be
    460 included::
     488included:
     489
     490.. code-block:: spec
    461491
    462492    Patch0: gcc-4.7.2-rtems4.11-20121026.diff
    463493
    464 Finally including the GCC 4.7 configuration script::
     494Finally including the GCC 4.7 configuration script:
     495
     496.. code-block:: spec
    465497
    466498    %include %{_configdir}/gcc-4.7-1.cfg
     
    477509
    478510Personal Configurations
    479 -----------------------
     511^^^^^^^^^^^^^^^^^^^^^^^
    480512
    481513The RSB supports personal configurations. You can view the RTEMS support in the
     
    485517provides.
    486518
    487 To create a private configuration change to a suitable directory::
     519To create a private configuration change to a suitable directory:
     520
     521.. code-block:: shell
    488522
    489523    $ cd ~/work
     
    497531
    498532New Configurations
    499 ------------------
     533^^^^^^^^^^^^^^^^^^
    500534
    501535This section describes how to add a new configuration to the RSB. We will add a
     
    559593anything unusual about the configuration it is a good idea to add something in
    560594the comments here. The comments are followed by a check for the release. In
    561 this case if a release is not provided a default of 1 is used::
     595this case if a release is not provided a default of 1 is used:
     596
     597.. code-block:: spec
    562598
    563599    #
     
    573609The next section defines some information about the package. It does not effect
    574610the build and is used to annotate the reports. It is recommended this
    575 information is kept updated and accurate::
     611information is kept updated and accurate:
     612
     613.. code-block:: spec
    576614
    577615    Name:      dtc-%{dtc_version}-%{_host}-%{release}
     
    587625them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains
    588626examples of more than one source package as well as conditionally including
    589 source packages based on the outer configuration options::
     627source packages based on the outer configuration options:
     628
     629.. code-block:: spec
    590630
    591631    #
     
    619659layers can set the source package and add patches as needed while being able to
    620660use a common recipe for the build. Users can override the standard build and
    621 supply a custom patch for testing using the user macro command line interface::
     661supply a custom patch for testing using the user macro command line interface:
     662
     663.. code-block:: spec
    622664
    623665    #
     
    645687
    646688If your package requires a configuration stage you need to run this before the
    647 make stage. Again the GCC common configuration file provides a detailed example::
     689make stage. Again the GCC common configuration file provides a detailed example:
     690
     691.. code-block:: spec
    648692
    649693    %build
     
    684728are many many macros to help you. You can find these listed in the
    685729``defaults.mc`` file and in the trace output. If you are new to creating and
    686 editing configurations learning these can take a little time::
     730editing configurations learning these can take a little time:
     731
     732.. code-block:: spec
    687733
    688734    %install
     
    702748Once we have the configuration files we can execute the build using the
    703749``sb-builder`` command. The command will perform the build and create a tar file
    704 in the ``tar`` directory::
     750in the ``tar`` directory:
     751
     752.. code-block:: shell
    705753
    706754    $  ../source-builder/sb-builder --prefix=/usr/local \
     
    721769prefix path.
    722770
    723 The DTC build set file is called ``dtc.bset`` and contains::
     771The DTC build set file is called ``dtc.bset`` and contains:
     772
     773.. code-block:: spec
    724774
    725775    #
     
    731781    devel/dtc-1.2.0.cfg
    732782
    733 To build this you can use something similar to::
     783To build this you can use something similar to:
     784
     785.. code-block:: shell
    734786
    735787    $ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
     
    773825
    774826Scripting
    775 ---------
     827^^^^^^^^^
    776828
    777829Configuration files specify how to build a package. Configuration files are
     
    924976mix of RTEMS Source Builder macros and shell scripting. The sequence is
    925977typically +%source+ macros for source, +%patch+ macros to patch the source
    926 mixed with some shell commands to correct any source issues::
    927 
    928                   <1>                <2>      <3>
     978mixed with some shell commands to correct any source issues:
     979
     980.. code-block:: spec
     981
    929982    %source setup gcc -q -c -T -n %{name}-%{version}
    930983
    931984.. topic:: Items:
    932985
    933   1. The source group to set up.
    934 
    935   2. The source's name.
    936 
    937   3. The version of the source.
     986  1. The source group to set up is ``gcc``.
     987
     988  2. The source's name is the macro ``%{name}``.
     989
     990  3. The version of the source is the macro ``%{version}``.
    938991
    939992The source set up are declared with the source ``set`` and ``add`` commands. For
    940993example:
    941994
    942 .. code-block:: auto
     995.. code-block:: spec
    943996
    944997    %source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2
     
    9581011the following scripting:
    9591012
    960 .. code-block:: auto
     1013.. code-block:: spec
    9611014
    9621015    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
     
    9671020uses Newlib, MPFR, MPC, and GMP source packages. You define the source with:
    9681021
    969 .. code-block:: auto
     1022.. code-block:: spec
    9701023
    9711024    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
     
    9771030and set up with:
    9781031
    979 .. code-block:: auto
     1032.. code-block:: spec
    9801033
    9811034    %source setup gcc -q -n gcc-%{gcc_version}
     
    9911044before the patch URL. Patches with no options uses the +setup+ default.
    9921045
    993 .. code-block:: auto
     1046.. code-block:: spec
    9941047
    9951048    %patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff
    996     %patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
     1049    %patch add gdb -p0 %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff
    9971050
    9981051.. topic:: Items:
    9991052
    1000   1. This patch has a custom option.
    1001 
    1002 To apply these patches::
    1003 
    1004     %patch setup gdb -p1 <1>
     1053  1. This patch has the custom option of ``-p0``.
     1054
     1055To apply these patches:
     1056
     1057.. code-block:: spec
     1058
     1059    %patch setup gdb -p1
    10051060
    10061061.. topic:: Items:
    10071062
    1008   1. The default options.
     1063  1. The default options for ``gdb`` set up.
    10091064
    10101065.. _build:
     
    10191074
    10201075The following is an example take from the GitHub STLink project. The STLink is
    1021 a JTAG debugging device for the ST ARM family of processors::
     1076a JTAG debugging device for the ST ARM family of processors:
     1077
     1078.. code-block:: spec
    10221079
    10231080    %build
    1024       export PATH="%{_bindir}:${PATH}" <1>
    1025 
    1026       cd texane-stlink-%{stlink_version} <2>
    1027 
    1028       ./autogen.sh <3>
     1081      export PATH="%{_bindir}:${PATH}"
     1082
     1083      cd texane-stlink-%{stlink_version}
     1084
     1085      ./autogen.sh
    10291086
    10301087    %if "%{_build}" != "%{_host}"
    1031       CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
     1088      CFLAGS_FOR_BUILD="-g -O2 -Wall" \
    10321089    %endif
    1033       CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
     1090      CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \
    10341091      CFLAGS="$SB_OPT_FLAGS" \
    10351092      LDFLAGS="-L $SB_TMPPREFIX/lib" \
    1036       ./configure \ <6>
     1093      ./configure \
    10371094        --build=%{_build} --host=%{_host} \
    10381095        --verbose \
     
    10421099        --mandir=%{_mandir} --infodir=%{_infodir}
    10431100
    1044       %{__make} %{?_smp_mflags} all <7>
     1101      %{__make} %{?_smp_mflags} all
    10451102
    10461103      cd ..
     
    10481105.. topic:: Items:
    10491106
    1050   1. Setup the PATH environment variable. This is not always needed.
    1051 
    1052   2. This package builds in the source tree so enter it.
     1107  1. Set up the PATH environment variable by setting the ``PATH`` environment
     1108     variable. This is not always needed.
     1109
     1110  2. This package builds in the source tree
     1111     ``texane-stlink-%{stlink_version}`` so enter it before building.
    10531112
    10541113  3. The package is actually checked directly out from the github project and
    1055      so it needs its autoconf and automake files generated.
    1056 
    1057   4. Flags for a cross-compiled build.
    1058 
    1059   5. Various settings passed to configure to customise the build. In this
    1060      example an include path is being set to the install point of
    1061      ``libusb``. This package requires ``libusb`` is built before it.
     1114     so it needs its ``autoconf`` and ``automake`` files generated. Invoke the
     1115     provided script ``autogen.sh``
     1116
     1117  4. If the build machine and host are not the same the build is a
     1118     cross-compile. Update the flags for a cross-compiled build.
     1119
     1120  5. The flags set in the environment before ``configure`` are various
     1121     settings that need to be passed to customise the build. In this example
     1122     an include path is being set to the install point of ``libusb``. This
     1123     package requires ``libusb`` is built before it.
    10621124
    10631125  6. The ``configure`` command. The RTEMS Source Builder provides all the
     
    10651127     ``configure``.
    10661128
    1067   7. Running make. Do not use ``make`` directly, use the RTEMS Source Builder's
    1068      defined value. This value is specific to the host. A large number of
    1069      packages need GNU make and on BSD systems this is ``gmake``. You can
    1070      optionally add the SMP flags if the packages build system can handle
    1071      parallel building with multiple jobs. The ``_smp_mflags`` value is
    1072      automatically setup for SMP hosts to match the number of cores the host
    1073      has.
     1129  7. Run ``make``. Do not use ``make`` directly, use the RTEMS Source
     1130     Builder's defined value. This value is specific to the host. A large
     1131     number of packages need GNU make and on BSD systems this is
     1132     ``gmake``. You can optionally add the SMP flags if the packages build
     1133     system can handle parallel building with multiple jobs. The
     1134     ``_smp_mflags`` value is automatically setup for SMP hosts to match the
     1135     number of cores the host has.
    10741136
    10751137%install
     
    10871149packages support adding ``DESTDIR=`` to the ``make install`` command.
    10881150
    1089 Looking at the same example as in :ref:`build`::
     1151Looking at the same example as in :ref:`build`:
     1152
     1153.. code-block:: spec
    10901154
    10911155    %install
     
    11351199configuration files provide specific information such as package version
    11361200numbers and patches and then include a generic configuration script which
    1137 builds the package::
     1201builds the package:
     1202
     1203.. code-block:: spec
    11381204
    11391205    %include %{_configdir}/gcc-4.7-1.cfg
     
    11531219The ``%summary`` is a brief description of the package. It is useful when
    11541220reporting. This information is not capture in the package anywhere. For the GCC
    1155 with Newlib configuration the summary is typically::
     1221with Newlib configuration the summary is typically:
     1222
     1223.. code-block:: spec
    11561224
    11571225    Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
     
    11621230The ``%release`` is a packaging number that allows revisions of a package to
    11631231happen where no package versions change. This value typically increases when
    1164 the configuration building the package changes::
     1232the configuration building the package changes:
     1233
     1234.. code-block:: spec
    11651235
    11661236    %define release 1
     
    11731243``libusb`` configuration the ``%version`` is the same as ``%libusb_version``,
    11741244however in a GCC with Newlib configuration there is no single version
    1175 number. In this case the GCC version is used::
     1245number. In this case the GCC version is used:
     1246
     1247.. code-block:: spec
    11761248
    11771249    Version: %{gcc_version}
     
    12071279them for specific releases or snapshots. To set a source file group:
    12081280
    1209 .. code-block:: auto
    1210 
    1211     %source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
     1281.. code-block:: spec
     1282
     1283    %source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
    12121284
    12131285.. topic:: Items:
     
    12181290the ``add`` command:
    12191291
    1220 .. code-block:: auto
     1292.. code-block:: spec
    12211293
    12221294    %source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2
    12231295
    12241296The source ``setup`` command can only be issued in the ``%prep:`` section. The
    1225 setup is::
     1297setup is:
     1298
     1299.. code-block:: spec
    12261300
    12271301    %source gcc setup -q -T -D -n %{name}-%{version}
     
    12701344The ``__patchdir`` path is searched.
    12711345
    1272 To add a patch::
    1273 
    1274     %patch add gcc <1>  gcc-4.7.2-rtems4.11-20121026.diff
    1275     %patch add gcc -p0 <2>  gcc-4.7.2-rtems4.11-20121101.diff
     1346To add a patch:
     1347
     1348.. code-block:: spec
     1349
     1350    %patch add gcc  gcc-4.7.2-rtems4.11-20121026.diff
     1351    %patch add gcc -p0  gcc-4.7.2-rtems4.11-20121101.diff
    12761352
    12771353.. topic:: Items:
     
    12791355  1. The patch group is ``gcc``.
    12801356
    1281   2. Option for this specific patch.
     1357  2. Option ``-p0`` is this specific to this patch.
    12821358
    12831359Placing ``%patch setup`` in the ``%prep`` section will apply the groups
    12841360patches::
    12851361
    1286     %patch setup gcc <1>  -p1 <2>
    1287 
    1288   1. The patch group.
    1289 
    1290   2. The default option used to apply the patch.
     1362.. code-block:: spec
     1363
     1364    %patch setup gcc  -p1
     1365
     1366  1. The patch group is ``gcc``.
     1367
     1368  2. The default option used to apply the patch is ``-p1``.
    12911369
    12921370%hash
     
    13041382``sha384``, and ``sha512`` and we typically use ``md5``.
    13051383
    1306 To add a hash::
     1384To add a hash:
     1385
     1386.. code-block:: spec
    13071387
    13081388    %hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>
     
    13521432package.
    13531433
    1354 The default map is ``global``::
     1434The default map is ``global``:
     1435
     1436.. code-block:: spec
    13551437
    13561438    %select gcc-4.8-snapshot <1>
     
    13681450
    13691451The ``%define`` macro defines a new macro or updates an existing one. If no
    1370 value is given it is assumed to be ``1``::
     1452value is given it is assumed to be ``1``:
     1453
     1454.. code-block:: spec
    13711455
    13721456    %define foo bar
     
    13931477
    13941478  * - **%{}**
    1395     - Check the macro is set or *true*, ie non-zero::
     1479    - Check the macro is set or *true*, ie non-zero:
     1480
     1481      .. code-block:: spec
    13961482
    13971483         %if ${foo}
     
    14021488
    14031489  * - **\!**
    1404     - The *not* operator inverts the test of the macro::
     1490    - The *not* operator inverts the test of the macro:
     1491
     1492      .. code-block:: spec
    14051493
    14061494         %if ! ${foo}
     
    14111499
    14121500  * - **==**
    1413     - The left hand size must equal the right hand side. For example::
     1501    - The left hand size must equal the right hand side. For example:
     1502
     1503      .. code-block:: spec
    14141504
    14151505         %define one 1
     
    14191509          %error The test fails
    14201510         %endif
    1421       You can also check to see if a macro is empty::
     1511
     1512      You can also check to see if a macro is empty:
     1513
     1514      .. code-block:: spec
    14221515
    14231516         %if ${nothing} == %{nil}
     
    14271520
    14281521  * - **!=**
    1429     - The left hand size does not equal the right hand side. For example::
     1522    - The left hand size does not equal the right hand side. For example:
     1523
     1524      .. code-block:: spec
    14301525
    14311526         #
     
    14661561The ``%ifn`` macro inverts the normal ``%if`` logic. It avoids needing to provide
    14671562empty *if* blocks followed by *else* blocks. It is useful when checking if a
    1468 macro is defined::
     1563macro is defined:
     1564
     1565.. code-block:: spec
    14691566
    14701567    %ifn %{defined foo}
  • user/rsb/cross-canadian-cross.rst

    r2e6f49f r2674d6a  
    44
    55Cross and Canadian Cross Building
    6 =================================
     6---------------------------------
    77
    88Cross building and Canadian Cross building is the process of building on one
     
    1414
    1515Cross Building
    16 --------------
     16^^^^^^^^^^^^^^
    1717
    1818Cross building is where the _build_ machine and _host_ are different. The
     
    2121development machine.
    2222
    23 To build the NTP package for RTEMS you enter the RSB command::
     23To build the NTP package for RTEMS you enter the RSB command:
     24
     25.. code-block:: shell
    2426
    2527    $ ../source-builder/sb-set-builder \
    2628       --log=log_ntp_arm.txt \
    27        --prefix=$HOME/development/rtems/4.11 \  <1>
    28        --host=arm-rtems4.11 \  <2>
     29       --prefix=$HOME/development/rtems/5 \  <1>
     30       --host=arm-rtems5 \  <2>
    2931       --with-rtems-bsp=xilinx_zynq_zc706 \  <3>
    30        4.11/net/ntp
     32       5/net/ntp
    3133
    3234.. topic:: Items:
     
    4648
    4749Canadian Cross Building
    48 -----------------------
     50^^^^^^^^^^^^^^^^^^^^^^^
    4951
    5052A Canadian cross builds are where the **build**, **host** and **target**
     
    8284To perform a cross build add ``--host=`` to the command line. For example
    8385to build a MinGW tool set on FreeBSD for Windows add ``--host=mingw32``
    84 if the cross compiler is ``mingw32-gcc``::
     86if the cross compiler is ``mingw32-gcc``:
     87
     88.. code-block:: shell
    8589
    8690    $ ../source-builder/sb-set-builder --host=mingw32 \
    8791       --log=l-mingw32-4.11-sparc.txt \
    88        --prefix=$HOME/development/rtems/4.11 \
    89        4.11/rtems-sparc
     92       --prefix=$HOME/development/rtems/5 \
     93       5/rtems-sparc
    9094
    9195If you are on a Linux Fedora build host with the MinGW packages installed the
    92 command line is::
     96command line is:
     97
     98.. code-block:: shell
    9399
    94100    $ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
    95101       --log=l-mingw32-4.11-sparc.txt \
    96        --prefix=$HOME/development/rtems/4.11 \
    97        4.11/rtems-sparc
     102       --prefix=$HOME/development/rtems/5 \
     103       5/rtems-sparc
  • user/rsb/deployment.rst

    r2e6f49f r2674d6a  
    66
    77Building and Deploying Tool Binaries
    8 ====================================
     8------------------------------------
    99
    1010If you wish to create and distribute your build or you want to archive a build
     
    4040
    4141A build set tar file is created by adding ``--bset-tar-file`` option to the
    42 ``sb-set-builder`` command::
     42``sb-set-builder`` command:
     43
     44.. code-block:: shell
    4345
    4446    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
     
    8183You can also suppress installing the files using the ``--no-install``
    8284option. This is useful if your prefix is not accessiable, for example when
    83 building Canadian cross compiled tool sets::
     85building Canadian cross compiled tool sets:
     86
     87.. code-block:: shell
    8488
    8589    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
     
    119123A package tar file can be created by adding the ``--pkg-tar-files`` to the
    120124``sb-set-builder`` command. This creates a tar file per package built in the
    121 build set::
     125build set:
     126
     127.. code-block:: shell
    122128
    123129    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
  • user/rsb/history.rst

    r2e6f49f r2674d6a  
    55
    66History
    7 =======
     7-------
    88
    99The RTEMS Source Builder is a stand alone tool based on another tool called the
  • user/rsb/index.rst

    r2e6f49f r2674d6a  
    88
    99RTEMS Source Builder
    10 ====================
     10********************
    1111
    1212The RTEMS Source Builder or RSB is a tool to build packages from source. It is
     
    4646.. topic:: Setting up your Host
    4747
    48    :ref:`Hosts` details setting up hosts.
     48   See :ref:`QuickStartHost` for details on setting up hosts.
    4949
    5050The RTEMS Source Builder has two types of configuration data. The first is the
     
    6363build or packages and software your host system you may have installed. We
    6464assume the build sets and configuration files you are using have been created
    65 by developers who do. Support is provided for package config or ``pkgconfg``
     65by developers who do. Support is provided for package config or ``pkgconfig``
    6666type files so you can check and use standard libraries if present. If you have
    6767a problem please ask on our :r:list:`devel`.
     
    8383
    8484.. toctree::
    85     :maxdepth: 5
    86     :numbered:
    8785
    8886    why-build-from-source.rst
  • user/rsb/project-sets.rst

    r2e6f49f r2674d6a  
    44
    55Project Sets
    6 ============
     6------------
    77
    88The RTEMS Source Builder supports project configurations. Project
     
    3737
    3838Bare Metal
    39 ----------
     39^^^^^^^^^^
    4040
    4141The RSB contains a 'bare' configuration tree and you can use this to add
     
    4848``lang/gcc491`` build set. You need to provide a target via the command line
    4949``--target`` option and this is in the standard 2 or 3 tuple form. For example
    50 for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf`, and for SPARC
    51 you would use `sparc-elf`::
     50for an ARM compiler you would use ``arm-eabi`` or ``arm-eabihf``, and for SPARC
     51you would use ``sparc-elf``:
     52
     53.. code-block:: shell
    5254
    5355    $ cd rtems-source-builder/bare
     
    7880
    7981RTEMS
    80 -----
     82^^^^^
    8183
    8284The RTEMS Configurations found in the ``rtems`` directory. The configurations
     
    106108packages only after they have been built so if you host does not have a
    107109recent enough version of ``autoconf`` and ``automake`` you first need to build them
    108 and install them then build your tool set. The commands are::
     110and install them then build your tool set. The commands are:
     111
     112.. code-block:: shell
    109113
    110114    $ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
     
    126130passing them on the command line using the ``--macros`` option. For RTEMS these
    127131are held in ``config/snapshots`` directory. The following builds *newlib* from
    128 CVS::
     132CVS:
     133
     134.. code-block:: shell
    129135
    130136    $ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
     
    134140
    135141and the following uses the version control heads for ``binutils``, ``gcc``,
    136 ``newlib``, ``gdb`` and *RTEMS*::
     142``newlib``, ``gdb`` and *RTEMS*:
     143
     144.. code-block:: shell
    137145
    138146    $ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
     
    160168
    161169Patches
    162 -------
     170^^^^^^^
    163171
    164172Packages being built by the RSB need patches from time to time and the RSB
     
    200208Patches can be declared in build set up files.
    201209
    202 This examples shows how to declare a patch for gdb in the ``lm32`` architecture::
     210This examples shows how to declare a patch for gdb in the ``lm32`` architecture:
     211
     212.. code-block:: spec
    203213
    204214    %patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>
     
    213223
    214224Patches require a checksum to avoid a warning. The ``%hash`` directive can be
    215 used to add a checksum for a patch that is used to verify the patch::
     225used to add a checksum for a patch that is used to verify the patch:
     226
     227.. code-block:: spec
    216228
    217229    %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
     
    227239The patches are applied when a patch ``setup`` command is issued in the
    228240``%prep:`` section. All patches in the group are applied. To apply the GDB
    229 patch above use::
     241patch above use:
     242
     243.. code-block:: spec
    230244
    231245    %patch setup <1> gdb <2> -p1 <3>
     
    252266``rtems/config/tools/`` that is included by the bset you use:
    253267
    254 .. code-block:: auto
     268.. code-block:: spec
    255269
    256270    %patch add newlib file://0001-this-is-a-newlib-patch.patch   <1>
  • user/rsb/third-party-packages.rst

    r2e6f49f r2674d6a  
    44
    55RTEMS Third-Party Packages
    6 ========================
     6--------------------------
    77
    88This section describes how to build and add an RTEMS third-party package to the
     
    2222
    2323Vertical Integration
    24 --------------------
     24^^^^^^^^^^^^^^^^^^^^
    2525
    2626The RSB supports horizontal integration with support for multiple
     
    3131
    3232Building
    33 --------
     33^^^^^^^^
    3434
    3535To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
     
    5757
    5858Adding
    59 ------
     59^^^^^^
    6060
    6161Adding a package requires you first build it manually by downloading the source
     
    115115
    116116BSP Support
    117 -----------
     117^^^^^^^^^^^
    118118
    119119The RSB provides support to help build packages for RTEMS. RTEMS applications
     
    136136support building third-party packages and you need to include this file in your
    137137RTEMS version specific configuration file. For example the Net-SNMP
    138 configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::
     138configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
     139
     140.. code-block:: spec
    139141
    140142    #
     
    175177  3. The Net-SNMP package's version.
    176178
    177   4. Add specific CFLAGS to the build process. See the
    178     ``net-snmp-5.7.2.1-1.cfg`` for details.
     179  4. Add specific ``CFLAGS`` to the build process. See the
     180     ``net-snmp-5.7.2.1-1.cfg`` for details.
    179181
    180182  5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
     
    185187sure standard command line options are provided. These include ``--host`` and
    186188``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
    187 the ``${_prefix}`` is used::
     189the ``${_prefix}`` is used:
     190
     191.. code-block:: spec
    188192
    189193    %if %{_host} == %{nil} <1>
     
    218222read and manage them even when there is no pkgconfig support installed on your
    219223build machine. Using this support we can obtain a BSP's configuration and set
    220 some standard macros variables (``rtems/config/rtems-bsp.cfg``)::
     224some standard macros variables (``rtems/config/rtems-bsp.cfg``):
     225
     226.. code-block:: spec
    221227
    222228    %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
     
    247253party library your host computer is the _build_ machine and RTEMS is the _host_
    248254machine therefore we set the ``host`` variables
    249 (``rtems/config/rtems-bsp.cfg``)::
     255(``rtems/config/rtems-bsp.cfg``):
     256
     257.. code-block:: spec
    250258
    251259    %define host_cflags  %{rtems_bsp_cflags}
     
    258266BSP and so needs to install into the specific BSP path under the
    259267``_prefix``. This allows more than BSP build of this package to be install
    260 under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::
     268under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
     269
     270.. code-block:: spec
    261271
    262272    %define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
     
    286296When you configure a package you can reference these paths and the RSB will
    287297provide sensible default or in this case map them to the BSP
    288 (``source-builder/config/ntp-4-1.cfg``)::
     298(``source-builder/config/ntp-4-1.cfg``):
     299
     300.. code-block:: spec
    289301
    290302      ../${source_dir_ntp}/configure \ <1>
     
    307319
    308320RTEMS BSP Configuration
    309 -----------------------
     321^^^^^^^^^^^^^^^^^^^^^^^
    310322
    311323To build a package for RTEMS you need to build it with the matching BSP
  • user/rsb/why-build-from-source.rst

    r2e6f49f r2674d6a  
    66
    77Why Build from Source?
    8 ======================
     8----------------------
    99
    1010The RTEMS Source Builder is not a replacement for the binary install systems
Note: See TracChangeset for help on using the changeset viewer.