From 8b643359868d044ef0f1f3432dd49594aae6c6a2 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 2 Nov 2016 12:09:54 +1100 Subject: RSB: Finish reformatting after moving from asciidocs. --- rsb/third-party-packages.rst | 314 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 rsb/third-party-packages.rst (limited to 'rsb/third-party-packages.rst') diff --git a/rsb/third-party-packages.rst b/rsb/third-party-packages.rst new file mode 100644 index 0000000..cda7183 --- /dev/null +++ b/rsb/third-party-packages.rst @@ -0,0 +1,314 @@ +.. 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. -- cgit v1.2.3