source: rtems-docs/user/rsb/third-party-packages.rst @ d5b631f

5
Last change on this file since d5b631f was d5b631f, checked in by Chris Johns <chrisj@…>, on 02/27/19 at 21:36:39

User: Change output block to type none.

  • Property mode set to 100644
File size: 12.8 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
4
5RTEMS Third-Party Packages
6--------------------------
7
8This section describes how to build and add an RTEMS third-party package to the
9RSB.
10
11A third-party package is a library or software package built to run on RTEMS,
12examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be
13used to help build RTEMS applications. The package is built for a specific
14BSP and so requires a working RTEMS tool chain and an installed RTEMS Board
15Support Package (BSP).
16
17The RSB support for building third-party packages is based around the *pkconfig*
18files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered
19experimental and can have some issues for some BSPs. This issue is rooted deep
20in the RTEMS build system. If you have any issues with this support please ask
21on the RTEMS developers mailing list.
22
23Vertical Integration
24^^^^^^^^^^^^^^^^^^^^
25
26The RSB supports horizontal integration with support for multiple
27architectures. Adding packages to the RSB as libraries is vertical
28integration. Building the GCC tool chain requires you build an assembler before
29you build a compiler. The same can be done for third-party libraries, you can
30crate build sets that stack library dependences vertically to create a *stack*.
31
32Building
33^^^^^^^^
34
35To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
36installed. The set builder command line requires you provide the tools path,
37the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix
38needs to be the same as the prefix used to build RTEMS.
39
40To build Net-SNMP the command is:
41
42.. code-block:: none
43
44    $ cd rtems-source-builder/rtems
45    $ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
46        --prefix=$HOME/development/rtems/bsps/4.11 \
47        --with-tools=$HOME/development/rtems/4.11 \
48        --host=sparc-rtems4.11 --with-rtems-bsp=erc32 4.11/net-mgmt/net-snmp
49    RTEMS Source Builder - Set Builder, v0.3.0
50    Build Set: 4.11/net-mgmt/net-snmp
51    config: net-mgmt/net-snmp-5.7.2.1-1.cfg
52    package: net-snmp-5.7.2.1-sparc-rtems4.11-1
53    building: net-snmp-5.7.2.1-sparc-rtems4.11-1
54    installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
55    cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
56    Build Set: Time 0:01:10.651926
57
58Adding
59^^^^^^
60
61Adding a package requires you first build it manually by downloading the source
62for the package and building it for RTEMS using the command line of a standard
63shell. If the package has not been ported to RTEMS you will need to port it and
64this may require you asking questions on the package's user or development
65support lists as well as RTEMS's developers list. Your porting effort may end
66up with a patch. RTEMS requires a patch be submitted upstream to the project's
67community as well as RTEMS so it can be added to the RTEMS Tools git
68repository. A patch in the RTEMS Tools git reposiitory can then be referenced
69by an RSB configuration file.
70
71A package may create executables, for example NTP normally creates executables
72such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These executables can be useful
73when testing the package however they are of limited use by RTEMS users because
74they cannot be directly linked into a user application. Users need to link to
75the functions in these executables or even the executable as a function placed
76in libraries. If the package does not export the code in a suitable manner
77please contact the project's commuinity and see if you can work them to provide
78a way for the code to be exported. This may be difficult because exporting
79internal headers and functions opens the project up to API compatibility issues
80they did not have before. In the simplest case attempting to get the code into
81a static library with a single call entry point exported in a header would give
82RTEMS user's access to the package's main functionality.
83
84A package requires 3 files to be created:
85
86- The first file is the RTEMS build set file and it resides in the
87  ``rtems/config/%{rtems_version}`` path in a directory tree based on the
88  FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is
89  ``rtems/config/4.11/net/ntp.bset``. If you do not know the FreeBSD port path
90  for the package you are adding please ask. The build set file references a
91  specific configuration file therefore linking the RTEMS version to a specific
92  version of the package you are adding. Updating the package to a new version
93  requires changing the build set to the new configuration file.
94
95- The second file is an RTEMS version specific configuration file and it
96  includes the RSB RTEMS BSP support. These configuration files reside in the
97  ``rtems/config`` tree again under the FreeBSD port's path name. For example
98  the NTP package is found in the ``net`` directory of the FreeBSD ports tree
99  so the NTP configuration path is ``rtems/config/net/ntp-4.2.6p5-1.cfg`` for
100  that specific version. The configuration file name typically provides version
101  specific references and the RTEMS build set file references a specific
102  version. This configuration file references the build configuration file held
103  in the common configuration file tree.
104
105- The build configuration. This is a common script that builds the package. It
106  resides in the ``source-builder/config`` directory and typically has the
107  packages's name with the major version number. If the build script does not
108  change for each major version number a *common* base script can be created
109  and included by each major version configuration script. The *gcc* compiler
110  configuration is an example. This approach lets you branch a version if
111  something changes that is not backwards compatible. It is important to keep
112  existing versions building. The build configuration should be able to build a
113  package for the build host as well as RTEMS as the RSB abstracts the RTEMS
114  specific parts. See :ref:`Configuration` for more details.
115
116BSP Support
117^^^^^^^^^^^
118
119The RSB provides support to help build packages for RTEMS. RTEMS applications
120can be viewed as statically linked executables operating in a single address
121space. As a result only the static libraries a package builds are required and
122these libraries need to be ABI compatible with the RTEMS kernel and application
123code meaning compiler ABI flags cannot be mixed when building code. The 3rd
124party package need to use the same compiler flags as the BSP used to build
125RTEMS.
126
127.. note::
128
129    RTEMS's dynamic loading support does not use the standard shared library
130    support found in Unix and the ELF standard. RTEMS's loader uses static
131    libraries and the runtime link editor performs a similar function to a host
132    based static linker. RTEMS will only reference static libraries even if
133    dynamic libraries are created and installed.
134
135The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
136support building third-party packages and you need to include this file in your
137RTEMS version specific configuration file. For example the Net-SNMP
138configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
139
140.. code-block:: spec
141
142    #
143    # NetSNMP 5.7.2.1
144    #
145    %if %{release} == %{nil}
146     %define release 1    <1>
147    %endif
148
149    %include %{_configdir}/rtems-bsp.cfg   <2>
150
151    #
152    # NetSNMP Version
153    #
154    %define net_snmp_version 5.7.2.1   <3>
155
156    #
157    # We need some special flags to build this version.
158    #
159    %define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0
160
161    #
162    # Patch for RTEMS support.
163    #
164    %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
165
166    #
167    # NetSNMP Build configuration
168    #
169    %include %{_configdir}/net-snmp-5-1.cfg   <6>
170
171.. topic:: Items:
172
173  1. The release number.
174
175  2. Include the RSB RTEMS BSP support.
176
177  3. The Net-SNMP package's version.
178
179  4. Add specific ``CFLAGS`` to the build process. See the
180     ``net-snmp-5.7.2.1-1.cfg`` for details.
181
182  5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
183
184  6. The Net-SNMP standard build configuration.
185
186The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
187sure standard command line options are provided. These include ``--host`` and
188``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
189the ``${_prefix}`` is used:
190
191.. code-block:: spec
192
193    %if %{_host} == %{nil} <1>
194     %error No RTEMS target specified: --host=host
195    %endif
196
197    %ifn %{defined with_rtems_bsp} <2>
198     %error No RTEMS BSP specified: --with-rtems-bsp=bsp
199    %endif
200
201    %ifn %{defined with_tools} <3>
202     %define with_tools %{_prefix}
203    %endif
204
205    #
206    # Set the path to the tools.
207    #
208    %{path prepend %{with_tools}/bin} <4>
209
210.. topic:: Items:
211
212  1. Check the host has been set.
213
214  2. Check a BSP has been specified.
215
216  3. If no tools path has been provided assume they are under the
217     ``%{_prefix}``.
218
219  4. Add the tools ``bin`` path to the system path.
220
221RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
222read and manage them even when there is no pkgconfig support installed on your
223build machine. Using this support we can obtain a BSP's configuration and set
224some standard macros variables (``rtems/config/rtems-bsp.cfg``):
225
226.. code-block:: spec
227
228    %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
229    %{pkgconfig crosscompile yes} <2>
230    %{pkgconfig filter-flags yes} <3>
231
232    #
233    # The RTEMS BSP Flags
234    #
235    %define rtems_bsp           %{with_rtems_bsp}
236    %define rtems_bsp_ccflags   %{pkgconfig ccflags %{_host}-%{rtems_bsp}} <4>
237    %define rtems_bsp_cflags    %{pkgconfig cflags  %{_host}-%{rtems_bsp}}
238    %define rtems_bsp_ldflags   %{pkgconfig ldflags %{_host}-%{rtems_bsp}}
239    %define rtems_bsp_libs      %{pkgconfig libs    %{_host}-%{rtems_bsp}}
240
241.. topic:: Items:
242
243  1. Set the path to the BSP's pkgconfig file.
244
245  2. Let pkgconfig know this is a cross-compile build.
246
247  3. Filter flags such as warnings. Warning flags are specific to a package.
248
249  4. Ask pkgconfig for the various items we require.
250
251The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these
252to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
253party library your host computer is the _build_ machine and RTEMS is the _host_
254machine therefore we set the ``host`` variables
255(``rtems/config/rtems-bsp.cfg``):
256
257.. code-block:: spec
258
259    %define host_cflags  %{rtems_bsp_cflags}
260    %define host_ldflags %{rtems_bsp_ldflags}
261    %define host_libs    %{rtems_bsp_libs}
262
263Finally we provide all the paths you may require when configuring a
264package. Packages by default consider the ``_prefix`` the base and install
265various files under this tree. The package you are building is specific to a
266BSP and so needs to install into the specific BSP path under the
267``_prefix``. This allows more than BSP build of this package to be install
268under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
269
270.. code-block:: spec
271
272    %define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
273    %define _exec_prefix      %{rtems_bsp_prefix}
274    %define _bindir           %{_exec_prefix}/bin
275    %define _sbindir          %{_exec_prefix}/sbin
276    %define _libexecdir       %{_exec_prefix}/libexec
277    %define _datarootdir      %{_exec_prefix}/share
278    %define _datadir          %{_datarootdir}
279    %define _sysconfdir       %{_exec_prefix}/etc
280    %define _sharedstatedir   %{_exec_prefix}/com
281    %define _localstatedir    %{_exec_prefix}/var
282    %define _includedir       %{_libdir}/include
283    %define _lib              lib
284    %define _libdir           %{_exec_prefix}/%{_lib}
285    %define _libexecdir       %{_exec_prefix}/libexec
286    %define _mandir           %{_datarootdir}/man
287    %define _infodir          %{_datarootdir}/info
288    %define _localedir        %{_datarootdir}/locale
289    %define _localedir        %{_datadir}/locale
290    %define _localstatedir    %{_exec_prefix}/var
291
292.. topic:: Items:
293
294  1. The path to the BSP.
295
296When you configure a package you can reference these paths and the RSB will
297provide sensible default or in this case map them to the BSP
298(``source-builder/config/ntp-4-1.cfg``):
299
300.. code-block:: spec
301
302      ../${source_dir_ntp}/configure \ <1>
303        --host=%{_host} \
304        --prefix=%{_prefix} \
305        --bindir=%{_bindir} \
306        --exec_prefix=%{_exec_prefix} \
307        --includedir=%{_includedir} \
308        --libdir=%{_libdir} \
309        --libexecdir=%{_libexecdir} \
310        --mandir=%{_mandir} \
311        --infodir=%{_infodir} \
312        --datadir=%{_datadir} \
313        --disable-ipv6 \
314        --disable-HOPFPCI
315
316.. topic:: Items:
317
318  1. The configure command for NTP.
319
320RTEMS BSP Configuration
321^^^^^^^^^^^^^^^^^^^^^^^
322
323To build a package for RTEMS you need to build it with the matching BSP
324configuration. A BSP can be built with specific flags that require all code
325being used needs to be built with the same flags.
Note: See TracBrowser for help on using the repository browser.