Changeset 2674d6a in rtems-docs


Ignore:
Timestamp:
Feb 21, 2019, 2:06:58 AM (11 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
Files:
34 edited

Legend:

Unmodified
Added
Removed
  • user/bsps/bsps-powerpc.rst

    r2e6f49f r2674d6a  
    9595image.  Use the following commands:
    9696
    97 ::
     97.. code-block:: shell
    9898
    9999    powerpc-rtems5-objcopy -O binary app.exe app.bin
     
    103103Use the following U-Boot commands to boot an application via TFTP download:
    104104
    105 ::
     105.. code-block:: shell
    106106
    107107    tftpboot ${loadaddr} app.img && run loadfdt && bootm ${loadaddr} - ${fdt_addr} ; reset
  • user/bsps/bsps-x86_64.rst

    r2e6f49f r2674d6a  
    5050Then edit ``Conf/target.txt`` to set:
    5151
    52 ::
     52.. code-block:: ini
    5353
    5454    ACTIVE_PLATFORM       = OvmfPkg/OvmfPkgX64.dsc
     
    6868    $ find . -name "*.fd"
    6969    ./Build/OvmfX64/DEBUG_GCC5/FV/MEMFD.fd
    70     ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd <-- the file we're looking for
     70    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd # the file we're looking for
    7171    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_CODE.fd
    7272    ./Build/OvmfX64/DEBUG_GCC5/FV/OVMF_VARS.fd
     
    8585.. code-block:: shell
    8686
    87    $ qemu-img create freebsd.img 8G
    88    $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
    89    $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
    90    $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
    91        -drive format=raw,file=freebsd.img \
    92        -drive format=raw,file=$FREEBSD_MEMSTICK
     87  $ qemu-img create freebsd.img 8G
     88  $ OVMF_LOCATION=/path/to/ovmf/OVMF.fd
     89  $ FREEBSD_MEMSTICK=/path/to/FreeBSD-11.2-amd64-memstick.img
     90  $ qemu-system-x86_64 -m 1024 -serial stdio --bios $OVMF_LOCATION \
     91      -drive format=raw,file=freebsd.img \
     92      -drive format=raw,file=$FREEBSD_MEMSTICK
    9393
    9494The first time you do this, continue through and install FreeBSD. `FreeBSD's
  • user/exe/debugging.rst

    r2e6f49f r2674d6a  
    9292#. Break and watch points
    9393
    94 .. _fig-exe-debug-qemu:
     94.. _fig-exe-debug-jtag:
    9595
    9696.. figure:: ../../images/user/exe-debug-jtag.png
  • user/exe/index.rst

    r2e6f49f r2674d6a  
    1515execiutable, and creating and dynamically loading code.
    1616
    17 .. include:: executables.rst
    18 .. include:: execution.rst
    19 .. include:: initialization.rst
    20 .. include:: debugging.rst
    21 .. include:: loader.rst
     17.. toctree::
     18
     19   executables
     20   execution
     21   initialization
     22   debugging
     23   loader
  • user/exe/initialization.rst

    r2e6f49f r2674d6a  
    8686sample application in the RTEMS kernel's testsuite::
    8787
     88.. code-block:: shell
     89
    8890 $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
    8991 RTEMS Executable Info 5.5416cfa39dd6
    90   rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
     92 $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
    9193 exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe
    9294
  • user/exe/loader.rst

    r2e6f49f r2674d6a  
    147147.. _dlopen:
    148148.. index:: dlopen
     149
    149150``void* dlopen(const char* path, int mode);``
    150151  The ``dlopen()`` function makes the symbols (function identifiers and data
     
    251252.. _dlclose:
    252253.. index:: dlclose
     254
    253255``int dlclose(void* handle);``
    254256  Releases a reference to the executable object file referenced by `handle`. If
     
    263265.. _dlsym:
    264266.. index:: dlsym
     267
    265268``void* dlsym(void* handle, const char* symbol);``
    266269 The ``dlsym()`` function obtains the address of a symbol (a function identifier
     
    289292.. _dlinfo:
    290293.. index:: dlinfo
     294
    291295``int dlinfo(void* handle, int request, void* args);``
    292296
     
    304308.. _dlerror:
    305309.. index:: dlerror
     310
    306311``const char *dlerror(void);``
    307312 The ``dlerror()`` function returns a null-terminated character string (with no
     
    691696
    692697 .. index:: RTEMS_RTL_ALLOC_OBJECT
     698
    693699 ``RTEMS_RTL_ALLOC_OBJECT``
    694700  Allocate a generic object. The link editor uses this memory for data
     
    697703
    698704 .. index:: RTEMS_RTL_ALLOC_SYMBOL
     705
    699706 ``RTEMS_RTL_ALLOC_SYMBOL``
    700707  Allocate memory to hold symbol data.
    701708
    702709 .. index:: RTEMS_RTL_ALLOC_EXTERNAL
     710
    703711 ``RTEMS_RTL_ALLOC_EXTERNAL``
    704712  Allocate memory for unresolved external symbols.
    705713
    706714 .. index:: RTEMS_RTL_ALLOC_READ
     715
    707716 ``RTEMS_RTL_ALLOC_READ``
    708717  Allocate memory for read-only data such as constants and exception tables.
    709718
    710719 .. index:: RTEMS_RTL_ALLOC_READ_WRITE
     720
    711721 ``RTEMS_RTL_ALLOC_READ_WRITE``
    712722  Allocate memory for read-write data such as a initialised, uninitialized and
     
    714724
    715725 .. index:: RTEMS_RTL_ALLOC_READ_EXEC
     726
    716727 ``RTEMS_RTL_ALLOC_READ_EXEC``
    717728  Allocate memory for code to be executed in. The address space is configure for
     
    725736
    726737 .. index:: RTEMS_RTL_ALLOC_NEW
     738
    727739 ``RTEMS_RTL_ALLOC_NEW``
    728740  Allocate memory of the ``tag`` type. Returns ``NULL`` if the allocation fails.
    729741
    730742 .. index:: RTEMS_RTL_ALLOC_DEL
     743
    731744 ``RTEMS_RTL_ALLOC_DEL``
    732745  Delete a previous allocation freeing the memory. The ``tag`` has to match
     
    734747
    735748 .. index:: RTEMS_RTL_ALLOC_WR_ENABLE
     749
    736750 ``RTEMS_RTL_ALLOC_WR_ENABLE``
    737751  Enable writes to a region of memory previously allocated. The ``tag`` has to
     
    740754
    741755 .. index:: RTEMS_RTL_ALLOC_WR_DISABLE
     756
    742757 ``RTEMS_RTL_ALLOC_WR_DISABLE``
    743758  Disable writes to a region of memory previously allocated. The ``tag`` has to
     
    764779
    765780``cmd``
    766  The command to action. See :ref:`_rtems_rtl_alloc_cmd`.
     781 The command to action. See `rtems_rtl_alloc_cmd <rtems_rtl_alloc_cmd_>`_.
    767782
    768783``tag``
    769  The type of memory the command is for. The ``tag`` must match the address for
    770  commands other than ``RTEMS_RTL_ALLOC_OBJECT``.
     784
     785 The type of memory the command is for. The ``tag`` must match the
     786 address for commands other than ``RTEMS_RTL_ALLOC_OBJECT``.  See
     787 `rtems_rtl_alloc_tags <rtems_rtl_alloc_tags_>`_.
    771788
    772789``address``
  • user/hosts/macos.rst

    r2e6f49f r2674d6a  
    33.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
    44
    5 .. _macos:
     5.. _MacOS:
    66
    77Apple MacOS
     
    2020:ref:`QuickStartPrefixes` details using Prefixes to manage the installation.
    2121
    22 MacOS
    2322.. _Mavericks:
    2423
     
    4443
    4544The RSB works on Sierra with the latest Xcode.
    46 
    47 
  • user/hosts/os.rst

    r2e6f49f r2674d6a  
    3939    The RSB assumes your host is set up and the needed packages are installed
    4040    and configured to work. If your host has not been set up please refer to
    41     :ref:`Hosts` and your host's section for packages you need to install.
     41    section that covers your host's packages you need to install.
    4242
    4343.. topic:: Path to use when building applications:
     
    8181
    8282    Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
    83 
  • user/hosts/posix.rst

    r2e6f49f r2674d6a  
    5454~~~~~~~~~
    5555
    56 The following packages are required on a fresh Archlinux 64bit installation::
    57 
    58     # pacman -S base-devel gdb xz unzip ncurses git zlib
     56The following packages are required on a fresh Archlinux 64bit installation:
     57
     58.. code-block:: shell
     59
     60  # pacman -S base-devel gdb xz unzip ncurses git zlib
    5961
    6062Archlinux, by default installs ``texinfo-5`` which is incompatible for building
    6163GCC 4.7 tree. You will have to obtain ``texinfo-legacy`` from ``AUR`` and
    62 provide a manual override::
    63 
    64     # pacman -R texinfo
    65     $ yaourt -S texinfo-legacy
    66     # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
     64provide a manual override:
     65
     66.. code-block:: shell
     67
     68  # pacman -R texinfo
     69  $ yaourt -S texinfo-legacy
     70  # ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo
    6771
    6872.. _CentOS:
     
    7175~~~~~~
    7276
    73 The following packages are required on a minimal CentOS 6.3 64bit installation::
    74 
    75     # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
    76     bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
     77The following packages are required on a minimal CentOS 6.3 64bit installation:
     78
     79.. code-block:: shell
     80
     81  # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
     82  bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git
    7783
    7884The minimal CentOS distribution is a specific DVD that installs a minimal
     
    8692
    8793The RTEMS Source Builder has been tested on Fedora 19 64bit with the following
    88 packages::
    89 
    90     # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
    91          flex texinfo patch perl-Text-ParseWords zlib-devel
     94packages:
     95
     96.. code-block:: shell
     97
     98  # yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
     99       flex texinfo patch perl-Text-ParseWords zlib-devel
    92100
    93101.. _Raspbian:
     
    97105
    98106The is the Debian distribution for the Raspberry Pi. The following packages are
    99 required::
    100 
    101     $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
    102     texinfo unzip ncurses-dev python-dev git
     107required:
     108
     109.. code-block:: shell
     110
     111  $ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
     112  texinfo unzip ncurses-dev python-dev git
    103113
    104114It is recommended you get Model B of the Pi with 512M of memory and to mount a
     
    113123
    114124The latest version is Ubuntu 18.04.1 LTS 64-bit. This section also includes
    115 Xubuntu. A minimal installation was used and the following packages installed::
    116 
    117     $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
    118            flex libpython-dev git libncurses5-dev zlib1g-dev
    119    
     125Xubuntu. A minimal installation was used and the following packages installed:
     126
     127.. code-block:: shell
     128
     129  $ sudu apt-get build-dep gcc-defaults g++ gdb git unzip pax bison \
     130         flex libpython-dev git libncurses5-dev zlib1g-dev
     131
    120132Note that in previous versions of Ubuntu, the package libpython-dev was
    121133python2.7-dev. The name of packages changes over time. You need the
     
    125137Users have suggested the following web pages which have instructions:
    126138
    127 * https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872 
     139* https://askubuntu.com/questions/158871/how-do-i-enable-the-source-code-repositories/158872
    128140* https://askubuntu.com/questions/496549/error-you-must-put-some-source-uris-in-your-sources-list
    129141
     
    134146
    135147zlib package is required on Linux Mint. It has a different name (other
    136 than the usual zlib-dev)::
    137 
    138     # sudo apt-get install zlib1g-dev
     148than the usual zlib-dev):
     149
     150.. code-block:: shell
     151
     152  # sudo apt-get install zlib1g-dev
    139153
    140154.. _openSUSE:
     
    152166
    153167The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit
    154 version. You need to install some ports. They are::
    155 
    156     # cd /usr/ports
    157     # portinstall --batch lang/python27
     168version. You need to install some ports. They are:
     169
     170.. code-block:: shell
     171
     172  # cd /usr/ports
     173  # portinstall --batch lang/python27
    158174
    159175If you wish to build Windows (mingw32) tools please install the following
    160 ports::
    161 
    162     # cd /usr/ports
    163     # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
    164     # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
     176ports:
     177
     178.. code-block:: shell
     179
     180  # cd /usr/ports
     181  # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
     182  # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads
    165183
    166184The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows
     
    176194
    177195The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
    178 are::
    179 
    180     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
    181     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
    182     # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
    183 
    184 .. _MacOS:
    185 
     196are:
     197
     198.. code-block:: shell
     199
     200  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
     201  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
     202  # pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz
  • user/hosts/windows.rst

    r2e6f49f r2674d6a  
    3939application development should be similar to other operating systems.
    4040
    41 Building is known to work on `Windows 7 64bit Professional` and `Windows 10`.
     41Building is known to work on `Windows 7 64bit Professional` and
     42`Windows 10 64bit`.
    4243
    4344.. _windows-path-length:
     
    223224cross-compiler is required to build the C runtime for the RTEMS target because
    224225we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set
    225 is::
    226 
    227     chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems
    228     $ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
    229     RTEMS Source Builder - Set Builder, v0.2
    230     Build Set: 4.10/rtems-arm
    231     config: expat-2.1.0-1.cfg
    232     package: expat-2.1.0-x86_64-w64-mingw32-1
    233     building: expat-2.1.0-x86_64-w64-mingw32-1
    234     reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
    235     config: tools/rtems-binutils-2.20.1-1.cfg
    236     package: arm-rtems4.10-binutils-2.20.1-1   <1>
    237     building: arm-rtems4.10-binutils-2.20.1-1
    238     package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
    239     building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
    240     reporting: tools/rtems-binutils-2.20.1-1.cfg ->
    241     arm-rtems4.10-binutils-2.20.1-1.html
    242     config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
    243     package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    244     building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    245     package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    246     building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    247     reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
    248     arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
    249     config: tools/rtems-gdb-7.3.1-1.cfg
    250     package: arm-rtems4.10-gdb-7.3.1-1
    251     building: arm-rtems4.10-gdb-7.3.1-1
    252     reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
    253     config: tools/rtems-kernel-4.10.2.cfg
    254     package: arm-rtems4.10-kernel-4.10.2-1
    255     building: arm-rtems4.10-kernel-4.10.2-1
    256     reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
    257     installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    258     installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
    259     installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    260     installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    261     installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
    262     cleaning: expat-2.1.0-x86_64-w64-mingw32-1
    263     cleaning: arm-rtems4.10-binutils-2.20.1-1
    264     cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
    265     cleaning: arm-rtems4.10-gdb-7.3.1-1
    266     cleaning: arm-rtems4.10-kernel-4.10.2-1
    267     Build Set: Time 10:09:42.810547   <4>
     226is:
     227
     228.. code-block:: shell
     229
     230  chris@cygwin ~/development/rtems/src/rtems-source-builder/rtems
     231  $ ../source-builder/sb-set-builder --log=l-arm.txt \
     232                --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
     233  RTEMS Source Builder - Set Builder, v0.2
     234  Build Set: 4.10/rtems-arm
     235  config: expat-2.1.0-1.cfg
     236  package: expat-2.1.0-x86_64-w64-mingw32-1
     237  building: expat-2.1.0-x86_64-w64-mingw32-1
     238  reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
     239  config: tools/rtems-binutils-2.20.1-1.cfg
     240  package: arm-rtems4.10-binutils-2.20.1-1   <1>
     241  building: arm-rtems4.10-binutils-2.20.1-1
     242  package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
     243  building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
     244  reporting: tools/rtems-binutils-2.20.1-1.cfg ->
     245  arm-rtems4.10-binutils-2.20.1-1.html
     246  config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
     247  package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
     248  building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
     249  package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
     250  building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
     251  reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
     252  arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
     253  config: tools/rtems-gdb-7.3.1-1.cfg
     254  package: arm-rtems4.10-gdb-7.3.1-1
     255  building: arm-rtems4.10-gdb-7.3.1-1
     256  reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
     257  config: tools/rtems-kernel-4.10.2.cfg
     258  package: arm-rtems4.10-kernel-4.10.2-1
     259  building: arm-rtems4.10-kernel-4.10.2-1
     260  reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
     261  installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
     262  installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
     263  installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
     264  installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
     265  installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
     266  cleaning: expat-2.1.0-x86_64-w64-mingw32-1
     267  cleaning: arm-rtems4.10-binutils-2.20.1-1
     268  cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
     269  cleaning: arm-rtems4.10-gdb-7.3.1-1
     270  cleaning: arm-rtems4.10-kernel-4.10.2-1
     271  Build Set: Time 10:09:42.810547   <4>
    268272
    269273.. topic:: Items:
     
    290294  pieces of software in a difficult environment. I have found building a single
    291295  tool tends to work, building all at once is harder.
    292 
  • user/installation/kernel.rst

    r2e6f49f r2674d6a  
    251251RTEMS with the following command:
    252252
    253 .. comment: CCJ - this code block for not parse and gives a warning in
    254             index.rst.
    255 
    256253.. code-block:: shell
    257254
     
    282279  make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
    283280  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
    284   make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu
    285    ......
     281  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
     282    ....
    286283  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c'
    287284  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
  • user/overview/index.rst

    r2e6f49f r2674d6a  
    55Introduction
    66************
     7
     8.. _Overview:
    79
    810Overview
  • 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
  • user/start/index.rst

    r2e6f49f r2674d6a  
    1414
    1515.. toctree::
    16     :maxdepth: 5
    17     :numbered:
    1816
    1917    host
  • user/testing/configuration.rst

    r2e6f49f r2674d6a  
    5858
    5959.. index:: BSP configuration, User configuration
     60
    6061BSP and User Configuration
    6162^^^^^^^^^^^^^^^^^^^^^^^^^^
     
    6667
    6768.. index:: bsp
     69
    6870``bsp``
    6971  The name of the BSP. The BSP name is used to create a macro map to hold the
     
    7274
    7375.. index:: arch
     76
    7477``arch``
    7578  The name of the BSP architecture. This is need for the GDB configuration
     
    7881
    7982.. index:: tester
     83
    8084``tester``
    8185  The tester or run configuration script. This is the name of the configuration
     
    8892
    8993.. index:: @ARCH@
     94
    9095``@ARCH@``
    9196  The BSP architecture.
    9297
    9398.. index:: @BSP@
     99
    94100``@BSP@``
    95101  The BSP's name set by the ``bsp`` value.
    96102
    97103.. index:: @EXE@
     104
    98105``@EXE@``
    99106  The executable name as an absolute path
    100107
    101108.. index:: @FEXE@
     109
    102110``@FEXE@``
    103111  The filtered executable if a ``target_exe_filter`` is provided else the
     
    108116
    109117.. index:: jobs
     118
    110119``jobs``
    111120  The jobs value sets the number of jobs that can be run at once. This setting
     
    117126
    118127.. index:: bsp_tty_dev
     128
    119129``bsp_tty_dev``
    120130  The BSP's tty device. This can be a real device on the host machine the
    121131  executable is being run from or it can be a telnet server and port defined
    122   using the stand host format. See :ref:`tester-consoles` for details.
     132  using the stand host format. See :ref:`TesterConsoles` for details.
    123133
    124134.. index:: target_pretest_command
     135
    125136``target_pretest_command``
    126137  The pre-test command is a host shell command that is called before each test
     
    130141
    131142 .. index:: target_posttest_command
     143
    132144``target_posttest_command``
    133145  The post-test command is a host shell command that is called after each test
     
    136148
    137149.. index:: target_exe_filter
     150
    138151``target_exe_filter``
    139152  The target executable filter transforms the executable name into a filtered
     
    148161
    149162.. index:: test_restarts
     163
    150164``test_restarts``
    151165  The number of restarts before the test is considered ``invalid``. Currently
     
    153167
    154168.. index:: target_reset_regex
     169
    155170``target_reset_regex``
    156171  The target reset regular expression. This is a `Python regular expression
     
    162177
    163178.. index:: target_start_regex
     179
    164180``target_start_regex``
    165181
     
    170186
    171187.. index:: target_on_command
     188
    172189``target_on_command``
    173190  The target on command is a host shell command that is called before the first
     
    179196
    180197.. index:: target_off_command
     198
    181199``target_off_command``
    182200  The target off command is a host shell command that is called after the last
     
    184202
    185203.. index:: target_reset_command
     204
    186205``target_reset_command``
    187206  The target reset command is a host shell command that is called when the
  • user/testing/consoles.rst

    r2e6f49f r2674d6a  
    33.. Copyright (C) 2018 Chris Johns <chrisj@rtems.org>
    44
    5 .. _tester-consoles:
     5.. _TesterConsoles:
    66
    77Consoles
  • user/testing/gdb-jtag.rst

    r2e6f49f r2674d6a  
    2121   RTEMS Tester using GDB and JTAG
    2222
    23 The :ref:`fig-tester-gdb-jtag` figure shows the structure of RTEMS Testing
     23The Figure :ref:`fig-tester-gdb-jtag` shows the structure of RTEMS Testing
    2424using GDB and JTAG. The executables are built and the ``rtems-test`` command is
    2525run from the top of the build directory. The RTEMS Tester executes the BSP
  • user/testing/index.rst

    r2e6f49f r2674d6a  
    4040extension.
    4141
    42 .. include:: tests.rst
    43 .. include:: configuration.rst
    44 .. include:: consoles.rst
    45 .. include:: simulation.rst
    46 .. include:: gdb-jtag.rst
    47 .. include:: tftp.rst
     42.. toctree::
     43
     44   tests
     45   configuration
     46   consoles
     47   simulation
     48   gdb-jtag
     49   tftp
  • user/testing/tests.rst

    r2e6f49f r2674d6a  
    7272
    7373.. index:: test state passed
     74
    7475``passed``
    7576  The test start and end banners have been sent to the console.
    7677
    7778.. index:: test state failure
     79
    7880``failure``
    7981  The test start banner has been sent to the console and no end banner has been
     
    8183
    8284.. index:: test state expected-fail
     85
    8386``excepted-fail``
    8487  The test is tagged as ``expected-fail`` in the RTEMS sources for this BSP and
     
    8992
    9093.. index:: test state indeterminate
     94
    9195``indeterminate``
    9296  The test is tagged as ``indeterminate`` in the RTEMS sources for this BSP and
     
    96100
    97101.. index:: test state user-input
     102
    98103``user-input``
    99104  The test is tagged as ``user-input`` in the RTEMS sources and outputs the
     
    102107
    103108.. index:: test state benchmark
     109
    104110``benchmark``
    105111  The test is tagged as ``benchmark`` in the RTEMS sources and outputs the
     
    109115
    110116.. index:: test state timeout
     117
    111118``timeout``
    112119  The test start banner has been sent to the console and no end banner is seen
     
    116123
    117124.. index:: test state invalid
     125
    118126``invalid``
    119127  The test did not output a start banner and the RTEMS Tester has detected the
     
    172180
    173181.. index:: build default
     182
    174183``default``
    175184  The build is the default. No RTEMS configure options have been used.
    176185
    177186.. index:: build posix
     187
    178188``posix``
    179189  The build includes the POSIX API. The RTEMS configure option
     
    182192
    183193.. index:: build smp
     194
    184195``smp``
    185196  The build is an SMP kernel. The RTEMS configure option ``--enable-smp`` has
     
    187198
    188199.. index:: build mp
     200
    189201``mp``
    190202  The build is an MP kernel. The RTEMS configure option
     
    193205
    194206.. index:: build paravirt
     207
    195208``paravirt``
    196209  The build is a paravirtualization kernel. The ``cpuopts.h`` define
     
    198211
    199212.. index:: build debug
     213
    200214``debug``
    201215  The build includes kernel debugging support. The RTEMS configure option
     
    204218
    205219.. index:: build profiling
     220
    206221``profiling``
    207222  The build include profiling support. The RTEMS configure option
  • user/testing/tftp.rst

    r2e6f49f r2674d6a  
    2323   RTEMS Tester using TFTP and U-Boot.
    2424
    25 The :ref:`fig-tester-tftp-u-boot` figure shows the structure and control flow
    26 of the RTEMS Tester using TFTP and U-boot. The executables are built and the
    27 ``rtems-test`` command is run from the top of the build directory.
     25The Figure :ref:`fig-tester-tftp-u-boot` figure shows the structure and
     26control flow of the RTEMS Tester using TFTP and U-boot. The executables are
     27built and the ``rtems-test`` command is run from the top of the build
     28directory.
    2829
    2930This test mode can only support a single test job running at once. You cannot
     
    4647#. Console interface cable that matches your target's console UART interface.
    4748
    48 #. Telnet terminal server. See :ref:`tester-consoles`.
     49#. Telnet terminal server. See :ref:`TesterConsoles`.
    4950
    5051The network power or IO switch is a device that can control power or an IO pin
     
    5960
    6061Configure U-Boot to network boot using the TFTP protocol. This is U-Boot script
    61 for a Zedboard::
     62for a Zedboard:
     63
     64.. code-block:: shell
    6265
    6366  loadaddr=0x02000000
     
    8790- ``tester`` - Set to ``%{_rtscripts}/tftp.cfg``
    8891
    89 For example the Zedboard's configuration is::
     92For example the Zedboard's configuration is:
     93
     94.. code-block:: ini
    9095
    9196  [xilinx_zynq_zedboard]
     
    160165
    161166Some of these field are normally provided by a user's configuration. To do this
    162 use::
     167use:
     168
     169.. code-block:: shell
    163170
    164171  requires = bsp_tty_dev, target_on_command, target_off_command, target_reset_command
     
    167174configuration file.
    168175
    169 The Zedboard's configuration file is::
     176The Zedboard's configuration file is:
     177
     178.. code-block:: ini
    170179
    171180  [xilinx_zynq_zedboard]
     
    187196U-Boot.
    188197
    189 An example of a user configuration for the Zedboard is::
     198An example of a user configuration for the Zedboard is:
     199
     200.. code-block:: ini
    190201
    191202  [xilinx_zynq_zedboard]
  • user/tracing/captureengine.rst

    r2e6f49f r2674d6a  
    9999number of context switches between tasks we are not interested in.
    100100
    101 .. code:: shell
     101.. code-block:: shell
    102102
    103103  *** BEGIN OF TEST CAPTURE ENGINE ***
  • user/tracing/examples.rst

    r2e6f49f r2674d6a  
    4747BSP is configured with the following command -
    4848
    49 .. code:: shell
     49.. code-block:: shell
    5050
    5151  ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \
     
    5959to your installation.
    6060
    61 .. code:: shell
     61.. code-block:: shell
    6262
    6363  sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \
     
    7373the wrapper c file.
    7474
    75 .. code:: shell
     75.. code-block:: shell
    7676
    7777  rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \
     
    8989with `rtrace`.
    9090
    91 .. code:: shell
     91.. code-block:: shell
    9292
    9393  sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/fileio.exe
     
    9595The output from the above commands will be as follows:
    9696
    97 .. code:: shell
     97.. code-block:: shell
    9898
    9999  *** BEGIN OF TEST FILE I/O ***
  • user/tracing/introduction.rst

    r2e6f49f r2674d6a  
    33.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
    44
    5 .. _introduction:
     5.. _IntroductionToTracing:
    66
    77Introduction to Tracing
  • user/tracing/tracelinker.rst

    r2e6f49f r2674d6a  
    9393files:
    9494
    95 .. code-block:: shell
     95.. code-block:: ini
    9696
    9797  include = rtems.ini, rtld-base.ini
     
    101101headers key that further references a section called `test-headers`:
    102102
    103 .. code-block:: shell
     103.. code-block:: ini
    104104
    105105  functions = test-trace-funcs, rtems-api
     
    144144comments.
    145145
    146 .. code-block:: shell
     146.. code-block:: ini
    147147
    148148  ;
     
    213213keys as shown below:
    214214
    215 .. code-block:: shell
     215.. code-block:: ini
    216216
    217217  ;
     
    251251sections to build on other trace sections.
    252252
    253 .. code:: shell
     253.. code-block:: ini
    254254
    255255  ; User application trace example.
     
    422422and is shown below:
    423423
    424 .. code:: shell
     424.. code:: ini
    425425
    426426  ;
  • user/wscript

    r2e6f49f r2674d6a  
    11from common.waf import cmd_configure as configure
    2 from common.waf import cmd_build as build
     2from common.waf import cmd_build as doc_build
    33from common.waf import cmd_options as options
    44from common.waf import spell
     
    66from common.waf import linkcheck
    77from common.waf import cmd_linkcheck
     8
     9def build(ctx):
     10    sources = {
     11        'exclude' : ['apps/index.rst']
     12    }
     13    doc_build(ctx, sources = sources)
Note: See TracChangeset for help on using the changeset viewer.