[e52906b] | 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
[8b64335] | 2 | |
---|
[4886d60] | 3 | .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> |
---|
[8b64335] | 4 | |
---|
[63735bc] | 5 | RTEMS Third-Party Packages |
---|
[2674d6a] | 6 | -------------------------- |
---|
[8b64335] | 7 | |
---|
[63735bc] | 8 | This section describes how to build and add an RTEMS third-party package to the |
---|
[8b64335] | 9 | RSB. |
---|
| 10 | |
---|
[63735bc] | 11 | A third-party package is a library or software package built to run on RTEMS, |
---|
[8b64335] | 12 | examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be |
---|
| 13 | used to help build RTEMS applications. The package is built for a specific |
---|
| 14 | BSP and so requires a working RTEMS tool chain and an installed RTEMS Board |
---|
| 15 | Support Package (BSP). |
---|
| 16 | |
---|
[63735bc] | 17 | The RSB support for building third-party packages is based around the *pkconfig* |
---|
[8b64335] | 18 | files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered |
---|
| 19 | experimental and can have some issues for some BSPs. This issue is rooted deep |
---|
| 20 | in the RTEMS build system. If you have any issues with this support please ask |
---|
| 21 | on the RTEMS developers mailing list. |
---|
| 22 | |
---|
| 23 | Vertical Integration |
---|
[2674d6a] | 24 | ^^^^^^^^^^^^^^^^^^^^ |
---|
[8b64335] | 25 | |
---|
| 26 | The RSB supports horizontal integration with support for multiple |
---|
| 27 | architectures. Adding packages to the RSB as libraries is vertical |
---|
| 28 | integration. Building the GCC tool chain requires you build an assembler before |
---|
[63735bc] | 29 | you build a compiler. The same can be done for third-party libraries, you can |
---|
[8b64335] | 30 | crate build sets that stack library dependences vertically to create a *stack*. |
---|
| 31 | |
---|
| 32 | Building |
---|
[2674d6a] | 33 | ^^^^^^^^ |
---|
[8b64335] | 34 | |
---|
| 35 | To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP |
---|
| 36 | installed. The set builder command line requires you provide the tools path, |
---|
| 37 | the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix |
---|
| 38 | needs to be the same as the prefix used to build RTEMS. |
---|
| 39 | |
---|
| 40 | To build Net-SNMP the command is: |
---|
| 41 | |
---|
[d5b631f] | 42 | .. code-block:: none |
---|
[8b64335] | 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 \ |
---|
[d8beaab] | 48 | --host=sparc-rtems4.11 --with-rtems-bsp=erc32 4.11/net-mgmt/net-snmp |
---|
[8b64335] | 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 | |
---|
| 58 | Adding |
---|
[2674d6a] | 59 | ^^^^^^ |
---|
[8b64335] | 60 | |
---|
| 61 | Adding a package requires you first build it manually by downloading the source |
---|
| 62 | for the package and building it for RTEMS using the command line of a standard |
---|
| 63 | shell. If the package has not been ported to RTEMS you will need to port it and |
---|
| 64 | this may require you asking questions on the package's user or development |
---|
| 65 | support lists as well as RTEMS's developers list. Your porting effort may end |
---|
| 66 | up with a patch. RTEMS requires a patch be submitted upstream to the project's |
---|
| 67 | community as well as RTEMS so it can be added to the RTEMS Tools git |
---|
| 68 | repository. A patch in the RTEMS Tools git reposiitory can then be referenced |
---|
| 69 | by an RSB configuration file. |
---|
| 70 | |
---|
| 71 | A package may create executables, for example NTP normally creates executables |
---|
| 72 | such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These executables can be useful |
---|
| 73 | when testing the package however they are of limited use by RTEMS users because |
---|
| 74 | they cannot be directly linked into a user application. Users need to link to |
---|
| 75 | the functions in these executables or even the executable as a function placed |
---|
| 76 | in libraries. If the package does not export the code in a suitable manner |
---|
| 77 | please contact the project's commuinity and see if you can work them to provide |
---|
| 78 | a way for the code to be exported. This may be difficult because exporting |
---|
| 79 | internal headers and functions opens the project up to API compatibility issues |
---|
| 80 | they did not have before. In the simplest case attempting to get the code into |
---|
| 81 | a static library with a single call entry point exported in a header would give |
---|
| 82 | RTEMS user's access to the package's main functionality. |
---|
| 83 | |
---|
| 84 | A 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 | |
---|
| 116 | BSP Support |
---|
[2674d6a] | 117 | ^^^^^^^^^^^ |
---|
[8b64335] | 118 | |
---|
| 119 | The RSB provides support to help build packages for RTEMS. RTEMS applications |
---|
| 120 | can be viewed as statically linked executables operating in a single address |
---|
| 121 | space. As a result only the static libraries a package builds are required and |
---|
| 122 | these libraries need to be ABI compatible with the RTEMS kernel and application |
---|
| 123 | code meaning compiler ABI flags cannot be mixed when building code. The 3rd |
---|
| 124 | party package need to use the same compiler flags as the BSP used to build |
---|
| 125 | RTEMS. |
---|
| 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 | |
---|
| 135 | The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to |
---|
[63735bc] | 136 | support building third-party packages and you need to include this file in your |
---|
[8b64335] | 137 | RTEMS version specific configuration file. For example the Net-SNMP |
---|
[2674d6a] | 138 | configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``: |
---|
| 139 | |
---|
| 140 | .. code-block:: spec |
---|
[8b64335] | 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 | |
---|
[2674d6a] | 179 | 4. Add specific ``CFLAGS`` to the build process. See the |
---|
| 180 | ``net-snmp-5.7.2.1-1.cfg`` for details. |
---|
[8b64335] | 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 | |
---|
| 186 | The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make |
---|
| 187 | sure standard command line options are provided. These include ``--host`` and |
---|
| 188 | ``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given |
---|
[2674d6a] | 189 | the ``${_prefix}`` is used: |
---|
| 190 | |
---|
| 191 | .. code-block:: spec |
---|
[8b64335] | 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 | |
---|
| 221 | RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can |
---|
| 222 | read and manage them even when there is no pkgconfig support installed on your |
---|
| 223 | build machine. Using this support we can obtain a BSP's configuration and set |
---|
[2674d6a] | 224 | some standard macros variables (``rtems/config/rtems-bsp.cfg``): |
---|
| 225 | |
---|
| 226 | .. code-block:: spec |
---|
[8b64335] | 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 | |
---|
| 251 | The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these |
---|
| 252 | to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd |
---|
| 253 | party library your host computer is the _build_ machine and RTEMS is the _host_ |
---|
| 254 | machine therefore we set the ``host`` variables |
---|
[2674d6a] | 255 | (``rtems/config/rtems-bsp.cfg``): |
---|
| 256 | |
---|
| 257 | .. code-block:: spec |
---|
[8b64335] | 258 | |
---|
| 259 | %define host_cflags %{rtems_bsp_cflags} |
---|
| 260 | %define host_ldflags %{rtems_bsp_ldflags} |
---|
| 261 | %define host_libs %{rtems_bsp_libs} |
---|
| 262 | |
---|
| 263 | Finally we provide all the paths you may require when configuring a |
---|
| 264 | package. Packages by default consider the ``_prefix`` the base and install |
---|
| 265 | various files under this tree. The package you are building is specific to a |
---|
| 266 | BSP 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 |
---|
[2674d6a] | 268 | under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``): |
---|
| 269 | |
---|
| 270 | .. code-block:: spec |
---|
[8b64335] | 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 | |
---|
| 296 | When you configure a package you can reference these paths and the RSB will |
---|
| 297 | provide sensible default or in this case map them to the BSP |
---|
[2674d6a] | 298 | (``source-builder/config/ntp-4-1.cfg``): |
---|
| 299 | |
---|
| 300 | .. code-block:: spec |
---|
[8b64335] | 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 | |
---|
| 320 | RTEMS BSP Configuration |
---|
[2674d6a] | 321 | ^^^^^^^^^^^^^^^^^^^^^^^ |
---|
[8b64335] | 322 | |
---|
| 323 | To build a package for RTEMS you need to build it with the matching BSP |
---|
| 324 | configuration. A BSP can be built with specific flags that require all code |
---|
| 325 | being used needs to be built with the same flags. |
---|