source: rtems-docs/rsb/third-party-packages.rst @ 42d50d7

5
Last change on this file since 42d50d7 was d8beaab, checked in by Joel Sherrill <joel@…>, on 11/15/16 at 23:54:47

Remove references to SPARC/SIS BSP. Also clean up old ERC32 references.

updates #2810.

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