source: rtems-docs/rsb/third-party-packages.rst @ 4886d60

.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>

RTEMS 3rd Party Packages
========================

This section describes how to build and add an RTEMS 3rd party package to the
RSB.

A 3rd party package is a library or software package built to run on RTEMS,
examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be
used to help build RTEMS applications. The package is built for a specific
BSP and so requires a working RTEMS tool chain and an installed RTEMS Board
Support Package (BSP).

The RSB support for building 3rd party packages is based around the *pkconfig*
files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered
experimental and can have some issues for some BSPs. This issue is rooted deep
in the RTEMS build system. If you have any issues with this support please ask
on the RTEMS developers mailing list.

Vertical Integration
--------------------

The RSB supports horizontal integration with support for multiple
architectures. Adding packages to the RSB as libraries is vertical
integration. Building the GCC tool chain requires you build an assembler before
you build a compiler. The same can be done for 3rd party libraries, you can
crate build sets that stack library dependences vertically to create a *stack*.

Building
--------

To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
installed. The set builder command line requires you provide the tools path,
the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix
needs to be the same as the prefix used to build RTEMS.

To build Net-SNMP the command is:

.. code-block:: shell

    $ cd rtems-source-builder/rtems
    $ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
        --prefix=$HOME/development/rtems/bsps/4.11 \
        --with-tools=$HOME/development/rtems/4.11 \
        --host=sparc-rtems4.11 --with-rtems-bsp=erc32 4.11/net-mgmt/net-snmp
    RTEMS Source Builder - Set Builder, v0.3.0
    Build Set: 4.11/net-mgmt/net-snmp
    config: net-mgmt/net-snmp-5.7.2.1-1.cfg
    package: net-snmp-5.7.2.1-sparc-rtems4.11-1
    building: net-snmp-5.7.2.1-sparc-rtems4.11-1
    installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
    cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
    Build Set: Time 0:01:10.651926

Adding
------

Adding a package requires you first build it manually by downloading the source
for the package and building it for RTEMS using the command line of a standard
shell. If the package has not been ported to RTEMS you will need to port it and
this may require you asking questions on the package's user or development
support lists as well as RTEMS's developers list. Your porting effort may end
up with a patch. RTEMS requires a patch be submitted upstream to the project's
community as well as RTEMS so it can be added to the RTEMS Tools git
repository. A patch in the RTEMS Tools git reposiitory can then be referenced
by an RSB configuration file.

A package may create executables, for example NTP normally creates executables
such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These executables can be useful
when testing the package however they are of limited use by RTEMS users because
they cannot be directly linked into a user application. Users need to link to
the functions in these executables or even the executable as a function placed
in libraries. If the package does not export the code in a suitable manner
please contact the project's commuinity and see if you can work them to provide
a way for the code to be exported. This may be difficult because exporting
internal headers and functions opens the project up to API compatibility issues
they did not have before. In the simplest case attempting to get the code into
a static library with a single call entry point exported in a header would give
RTEMS user's access to the package's main functionality.

A package requires 3 files to be created:

- The first file is the RTEMS build set file and it resides in the
  ``rtems/config/%{rtems_version}`` path in a directory tree based on the
  FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is
  ``rtems/config/4.11/net/ntp.bset``. If you do not know the FreeBSD port path
  for the package you are adding please ask. The build set file references a
  specific configuration file therefore linking the RTEMS version to a specific
  version of the package you are adding. Updating the package to a new version
  requires changing the build set to the new configuration file.

- The second file is an RTEMS version specific configuration file and it
  includes the RSB RTEMS BSP support. These configuration files reside in the
  ``rtems/config`` tree again under the FreeBSD port's path name. For example
  the NTP package is found in the ``net`` directory of the FreeBSD ports tree
  so the NTP configuration path is ``rtems/config/net/ntp-4.2.6p5-1.cfg`` for
  that specific version. The configuration file name typically provides version
  specific references and the RTEMS build set file references a specific
  version. This configuration file references the build configuration file held
  in the common configuration file tree.

- The build configuration. This is a common script that builds the package. It
  resides in the ``source-builder/config`` directory and typically has the
  packages's name with the major version number. If the build script does not
  change for each major version number a *common* base script can be created
  and included by each major version configuration script. The *gcc* compiler
  configuration is an example. This approach lets you branch a version if
  something changes that is not backwards compatible. It is important to keep
  existing versions building. The build configuration should be able to build a
  package for the build host as well as RTEMS as the RSB abstracts the RTEMS
  specific parts. See :ref:`Configuration` for more details.

BSP Support
-----------

The RSB provides support to help build packages for RTEMS. RTEMS applications
can be viewed as statically linked executables operating in a single address
space. As a result only the static libraries a package builds are required and
these libraries need to be ABI compatible with the RTEMS kernel and application
code meaning compiler ABI flags cannot be mixed when building code. The 3rd
party package need to use the same compiler flags as the BSP used to build
RTEMS.

.. note::

    RTEMS's dynamic loading support does not use the standard shared library
    support found in Unix and the ELF standard. RTEMS's loader uses static
    libraries and the runtime link editor performs a similar function to a host
    based static linker. RTEMS will only reference static libraries even if
    dynamic libraries are created and installed.

The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
support building 3rd party packages and you need to include this file in your
RTEMS version specific configuration file. For example the Net-SNMP
configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``::

    #
    # NetSNMP 5.7.2.1
    #
    %if %{release} == %{nil}
     %define release 1    <1>
    %endif

    %include %{_configdir}/rtems-bsp.cfg   <2>

    #
    # NetSNMP Version
    #
    %define net_snmp_version 5.7.2.1   <3>

    #
    # We need some special flags to build this version.
    #
    %define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0

    #
    # Patch for RTEMS support.
    #
    %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>

    #
    # NetSNMP Build configuration
    #
    %include %{_configdir}/net-snmp-5-1.cfg   <6>

.. topic:: Items:

  1. The release number.

  2. Include the RSB RTEMS BSP support.

  3. The Net-SNMP package's version.

  4. Add specific CFLAGS to the build process. See the
    ``net-snmp-5.7.2.1-1.cfg`` for details.

  5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.

  6. The Net-SNMP standard build configuration.

The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
sure standard command line options are provided. These include ``--host`` and
``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
the ``${_prefix}`` is used::

    %if %{_host} == %{nil} <1>
     %error No RTEMS target specified: --host=host
    %endif

    %ifn %{defined with_rtems_bsp} <2>
     %error No RTEMS BSP specified: --with-rtems-bsp=bsp
    %endif

    %ifn %{defined with_tools} <3>
     %define with_tools %{_prefix}
    %endif

    #
    # Set the path to the tools.
    #
    %{path prepend %{with_tools}/bin} <4>

.. topic:: Items:

  1. Check the host has been set.

  2. Check a BSP has been specified.

  3. If no tools path has been provided assume they are under the
     ``%{_prefix}``.

  4. Add the tools ``bin`` path to the system path.

RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
read and manage them even when there is no pkgconfig support installed on your
build machine. Using this support we can obtain a BSP's configuration and set
some standard macros variables (``rtems/config/rtems-bsp.cfg``)::

    %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
    %{pkgconfig crosscompile yes} <2>
    %{pkgconfig filter-flags yes} <3>

    #
    # The RTEMS BSP Flags
    #
    %define rtems_bsp           %{with_rtems_bsp}
    %define rtems_bsp_ccflags   %{pkgconfig ccflags %{_host}-%{rtems_bsp}} <4>
    %define rtems_bsp_cflags    %{pkgconfig cflags  %{_host}-%{rtems_bsp}}
    %define rtems_bsp_ldflags   %{pkgconfig ldflags %{_host}-%{rtems_bsp}}
    %define rtems_bsp_libs      %{pkgconfig libs    %{_host}-%{rtems_bsp}}

.. topic:: Items:

  1. Set the path to the BSP's pkgconfig file.

  2. Let pkgconfig know this is a cross-compile build.

  3. Filter flags such as warnings. Warning flags are specific to a package.

  4. Ask pkgconfig for the various items we require.

The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these
to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
party library your host computer is the _build_ machine and RTEMS is the _host_
machine therefore we set the ``host`` variables
(``rtems/config/rtems-bsp.cfg``)::

    %define host_cflags  %{rtems_bsp_cflags}
    %define host_ldflags %{rtems_bsp_ldflags}
    %define host_libs    %{rtems_bsp_libs}

Finally we provide all the paths you may require when configuring a
package. Packages by default consider the ``_prefix`` the base and install
various files under this tree. The package you are building is specific to a
BSP and so needs to install into the specific BSP path under the
``_prefix``. This allows more than BSP build of this package to be install
under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``)::

    %define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
    %define _exec_prefix      %{rtems_bsp_prefix}
    %define _bindir           %{_exec_prefix}/bin
    %define _sbindir          %{_exec_prefix}/sbin
    %define _libexecdir       %{_exec_prefix}/libexec
    %define _datarootdir      %{_exec_prefix}/share
    %define _datadir          %{_datarootdir}
    %define _sysconfdir       %{_exec_prefix}/etc
    %define _sharedstatedir   %{_exec_prefix}/com
    %define _localstatedir    %{_exec_prefix}/var
    %define _includedir       %{_libdir}/include
    %define _lib              lib
    %define _libdir           %{_exec_prefix}/%{_lib}
    %define _libexecdir       %{_exec_prefix}/libexec
    %define _mandir           %{_datarootdir}/man
    %define _infodir          %{_datarootdir}/info
    %define _localedir        %{_datarootdir}/locale
    %define _localedir        %{_datadir}/locale
    %define _localstatedir    %{_exec_prefix}/var

.. topic:: Items:

  1. The path to the BSP.

When you configure a package you can reference these paths and the RSB will
provide sensible default or in this case map them to the BSP
(``source-builder/config/ntp-4-1.cfg``)::

      ../${source_dir_ntp}/configure \ <1>
        --host=%{_host} \
        --prefix=%{_prefix} \
        --bindir=%{_bindir} \
        --exec_prefix=%{_exec_prefix} \
        --includedir=%{_includedir} \
        --libdir=%{_libdir} \
        --libexecdir=%{_libexecdir} \
        --mandir=%{_mandir} \
        --infodir=%{_infodir} \
        --datadir=%{_datadir} \
        --disable-ipv6 \
        --disable-HOPFPCI

.. topic:: Items:

  1. The configure command for NTP.

RTEMS BSP Configuration
-----------------------

To build a package for RTEMS you need to build it with the matching BSP
configuration. A BSP can be built with specific flags that require all code
being used needs to be built with the same flags.