.. comment SPDX-License-Identifier: CC-BY-SA-4.0 .. comment COPYRIGHT (c) 2012 - 2016. .. comment Chris Johns 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=sis 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.