1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | Third-Party Packages |
---|
6 | -------------------- |
---|
7 | |
---|
8 | This section describes how to build and add an RTEMS third-party package to the |
---|
9 | RSB. |
---|
10 | |
---|
11 | A third-party package is a library or software package built to run on RTEMS, |
---|
12 | examples are Curl, NTP, Net-Snmp, libjpeg and more. These pieces of software |
---|
13 | can be used to help build RTEMS applications. The package is built for a |
---|
14 | specific BSP and so requires a working RTEMS tool chain, an installed RTEMS |
---|
15 | Board Support Package (BSP), and a network stack if the package uses |
---|
16 | networking resources. |
---|
17 | |
---|
18 | .. sidebar:: Help |
---|
19 | |
---|
20 | If you have any issues using, building or adding third party packages please |
---|
21 | ask on the RTEMS users mailing list. |
---|
22 | |
---|
23 | |
---|
24 | The RSB support for building third-party packages is based around the |
---|
25 | *pkconfig* files (PC) installed with the BSP. The pkgconfig support in RTEMS is |
---|
26 | considered experimental and can have some issues for some BSPs. This issue is |
---|
27 | rooted deep in the RTEMS build system. |
---|
28 | |
---|
29 | Vertical Integration |
---|
30 | ^^^^^^^^^^^^^^^^^^^^ |
---|
31 | |
---|
32 | The RSB supports horizontal integration with support for multiple |
---|
33 | architectures. Adding packages to the RSB as libraries is vertical |
---|
34 | integration. Building the GCC tool chain requires you build an assembler |
---|
35 | before you build a compiler. The same can be done for third-party libraries, |
---|
36 | you can create build sets that stack library dependences vertically to create |
---|
37 | a *stack*. |
---|
38 | |
---|
39 | Building |
---|
40 | ^^^^^^^^ |
---|
41 | |
---|
42 | To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP |
---|
43 | installed. The set builder command line requires you provide the tools path, |
---|
44 | the RTEMS architecture (host), the BSP, and the prefix path used to the |
---|
45 | install RTEMS BSP. |
---|
46 | |
---|
47 | The RSB prefix option (``--prefix``) provided when building a package is the |
---|
48 | path to: |
---|
49 | |
---|
50 | #. The tools, RTEMS kernel and any dependent libraries such as LibBSD. The |
---|
51 | package will be installed into the prefix path. This build configuration can |
---|
52 | be used to make a complete set of development tools and libraries for a |
---|
53 | project or product under a single path. |
---|
54 | |
---|
55 | #. The RTEMS kernel and any dependent libraries such as LibBSD. The tools path |
---|
56 | needs to be in the environment path (not recommended) or provided to the set |
---|
57 | builder command by the ``--with-tools`` option. The package will be |
---|
58 | installed into the prefix path. This build configuration can be used when |
---|
59 | you have a set of tools used with a number of RTEMS BSPs. The tools can be |
---|
60 | shared between the different BSPs. |
---|
61 | |
---|
62 | #. The path the package is installed into. The tools path needs to be in the |
---|
63 | environment path (not recommended) or provided to the set builder command |
---|
64 | using the ``--with-tools`` option. The path to the RTEMS kernel and any |
---|
65 | dependent libraries such as LibBSD needs to be supplied to the set builder |
---|
66 | command using the ``--with-rtems`` option. This build configuration can be |
---|
67 | used when you have a set of libraries you are testing with a changing RTEMS |
---|
68 | kernel. Becareful using this configuration as changes in RTEMS interfaces |
---|
69 | may require rebuilding these packages. |
---|
70 | |
---|
71 | The set builder command option ``--host`` is used to provide the RTEMS |
---|
72 | architecture the package is being built for. For example ``--host=arm-rtems5`` |
---|
73 | is used for any ARM BSP. |
---|
74 | |
---|
75 | The set builder command option ``--with-rtems-bsp`` is the RTEMS BSP the |
---|
76 | package is being built for. The BSP is searched for under the path provided by |
---|
77 | the command option ``--with-rtems`` and if this option is not provided the |
---|
78 | provided prefix is searched. |
---|
79 | |
---|
80 | The following example builds and installs the Curl networking package for the |
---|
81 | ARM BeagleBone Black BSP installing it into the same path the tools, RTEMS |
---|
82 | kernel and LibBSD are installed in. |
---|
83 | |
---|
84 | .. code-block:: none |
---|
85 | |
---|
86 | $ ../source-builder/sb-set-builder --prefix=$HOME/development/cs/rtems/5 \ |
---|
87 | --log=curl.txt --host=arm-rtems5 --with-rtems-bsp=beagleboneblack ftp/curl |
---|
88 | RTEMS Source Builder - Set Builder, 5 (2bdae1f169e4) |
---|
89 | Build Set: ftp/curl |
---|
90 | config: ftp/curl-7.65.1-1.cfg |
---|
91 | package: curl-v7.65.1-arm-rtems5-1 |
---|
92 | download: https://curl.haxx.se/download/curl-7.65.1.tar.xz -> sources/curl-7.65.1.tar.xz |
---|
93 | downloading: sources/curl-7.65.1.tar.xz - 2.3MB of 2.3MB (100%) |
---|
94 | building: curl-v7.65.1-arm-rtems5-1 |
---|
95 | sizes: curl-v7.65.1-arm-rtems5-1: 87.055MB (installed: 2.238MB) |
---|
96 | cleaning: curl-v7.65.1-arm-rtems5-1 |
---|
97 | reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.txt |
---|
98 | reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.xml |
---|
99 | installing: curl-v7.65.1-arm-rtems5-1 -> /Users/chris/development/cs/rtems/5 |
---|
100 | cleaning: curl-v7.65.1-arm-rtems5-1 |
---|
101 | Build Set: Time 0:01:10.006872 |
---|
102 | |
---|
103 | Adding |
---|
104 | ^^^^^^ |
---|
105 | |
---|
106 | Adding a package requires you first build it manually by downloading the |
---|
107 | source for the package and building it for RTEMS using the command line of a |
---|
108 | standard shell. If the package has not been ported to RTEMS you will need to |
---|
109 | port it and this may require asking questions on the package's user or |
---|
110 | development support lists as well as RTEMS's developers list. Your porting |
---|
111 | effort may end up with a patch. RTEMS requires a patch be submitted upstream |
---|
112 | to the project's community as well as RTEMS. The RTEMS submission is best as a |
---|
113 | patch attached to ticket in Trac. A patch attached to a ticket can be |
---|
114 | referenced by an RSB configuration file and used in a build. |
---|
115 | |
---|
116 | .. sidebar:: Patches in Trac |
---|
117 | |
---|
118 | Attaching patches for packages to Trac tickets provides an easy to reference |
---|
119 | URL the RSB can fetch. The patch URL does not change across RTEMS versions |
---|
120 | and it does not depend on the state or layout of a git repo. |
---|
121 | |
---|
122 | |
---|
123 | A package may create executables, for example Curl normally creates an |
---|
124 | executable called ``curl`` how ever it will probailty not run because the |
---|
125 | needed RTEMS configuration is not suitable. If found the RSB automatically |
---|
126 | adds the RTEMS library ``librtemsdefaultconfig.a`` to the ``LIBS`` variable |
---|
127 | used to link executables. This library provides a limited configuraiton |
---|
128 | suitable for linking an executable however it is not a set up that allows the |
---|
129 | resulting executable to run correctly. As a result it is best not to install |
---|
130 | these executables. |
---|
131 | |
---|
132 | A custom RTEMS patch to an executate's source code can turn it into a function |
---|
133 | that can be called by the RTEMS shell. Users can call the function in their |
---|
134 | executables simulating the running of the package's command. If the package |
---|
135 | does not export the code in a suitable manner please contact the project's |
---|
136 | commuinity and see if you can work with them to provide a way for the code to |
---|
137 | be exported. This may be difficult because exporting internal headers and |
---|
138 | functions opens the project up to API compatibility issues they did not have |
---|
139 | before. In the simplest case attempting to get the code into a static library |
---|
140 | with a single call entry point exported in a header would give RTEMS user's |
---|
141 | access to the package's main functionality. |
---|
142 | |
---|
143 | A package requires at least three (3) files to be created: |
---|
144 | |
---|
145 | Published Package Name: |
---|
146 | The first file is the RTEMS build set file and it resides under the |
---|
147 | ``rtems/config`` path in a directory tree based on the FreeBSD ports |
---|
148 | collection. For the Curl package and RTEMS 5 this is |
---|
149 | ``rtems/config/ftp/curl.bset``. If you do not know the FreeBSD port path |
---|
150 | for the package you are adding please ask. The build set file references a |
---|
151 | specific configuration file therefore linking the RTEMS version to a |
---|
152 | specific version of the package you are adding. Updating the package to a |
---|
153 | new version requires changing the build set to the new configuration file. |
---|
154 | |
---|
155 | Package Version Configuration File: |
---|
156 | The second file is an RTEMS version specific configuration file and it |
---|
157 | includes the RSB RTEMS BSP support. These configuration files reside in |
---|
158 | the ``rtems/config`` tree and under the FreeBSD port's path name. For |
---|
159 | example the Curl package is found in the ``ftp`` directory of the FreeBSD |
---|
160 | ports tree so the Curl configuration path is |
---|
161 | ``rtems/config/ftp/curl-7.65.1-1.cfg`` for that specific version. The |
---|
162 | configuration file name typically provides version specific references and |
---|
163 | the RTEMS build set file references a specific version. This configuration |
---|
164 | file references the build configuration file held in the common |
---|
165 | configuration file tree. An SHA512 hash is required to verify the source |
---|
166 | package that is downloaded. |
---|
167 | |
---|
168 | Build Configuration File: |
---|
169 | The build configuration. This is a common script that builds the |
---|
170 | package. It resides in the ``source-builder/config`` directory and |
---|
171 | typically has the packages's name with the major version number. If the |
---|
172 | build script does not change for each major version number a *common* base |
---|
173 | script can be created and included by each major version configuration |
---|
174 | script. The *gcc* compiler configuration is an example. This approach lets |
---|
175 | you branch a version if something changes that is not backwards |
---|
176 | compatible. It is important to keep existing versions building. The build |
---|
177 | configuration should be able to build a package for the build host as well |
---|
178 | as RTEMS as the RSB abstracts the RTEMS specific parts. See |
---|
179 | :ref:`Configuration` for more details. |
---|
180 | |
---|
181 | Host and Build Flags |
---|
182 | ^^^^^^^^^^^^^^^^^^^^ |
---|
183 | |
---|
184 | A package's build is controlled by setting the compiler names and flags that |
---|
185 | are used when building. The RSB provides a macro called |
---|
186 | ``%{host_build_flags}`` to define these flags for you. Use this macro in the |
---|
187 | ```%build`` section of your config script file to define the set up needed to |
---|
188 | build a native package or to cross-compile to a specific host such as RTEMS |
---|
189 | . The typical ``%build`` section is: |
---|
190 | |
---|
191 | .. code-block:: spec |
---|
192 | |
---|
193 | %build |
---|
194 | build_top=$(pwd) |
---|
195 | |
---|
196 | %{build_directory} |
---|
197 | |
---|
198 | mkdir -p ${build_dir} |
---|
199 | cd ${build_dir} |
---|
200 | |
---|
201 | %{host_build_flags} |
---|
202 | |
---|
203 | ../${source_dir_curl}/configure \ |
---|
204 | --host=%{_host} \ |
---|
205 | --prefix=%{_prefix} \ |
---|
206 | --bindir=%{_bindir} \ |
---|
207 | --exec_prefix=%{_exec_prefix} \ |
---|
208 | --includedir=%{_includedir} \ |
---|
209 | --libdir=%{_libdir} \ |
---|
210 | --libexecdir=%{_libexecdir} \ |
---|
211 | --mandir=%{_mandir} \ |
---|
212 | --infodir=%{_infodir} \ |
---|
213 | --datadir=%{_datadir} |
---|
214 | |
---|
215 | %{__make} %{?_smp_mflags} all |
---|
216 | |
---|
217 | cd ${build_top} |
---|
218 | |
---|
219 | The ``%{host_build_flags}`` checks if the build is native for the development |
---|
220 | host or a cross-compile build. |
---|
221 | |
---|
222 | For a cross-complication build the flags are: |
---|
223 | |
---|
224 | ``CC``, ``CC_FOR_HOST``: |
---|
225 | The C compiler used to build the package. For an RTEMS build this is the |
---|
226 | RTEMS C compiler. For example the ARM architecture and RTEMS 5 the value is |
---|
227 | set to ``arm-rtems5-gcc``. |
---|
228 | |
---|
229 | ``CXX``, ``CXX_FOR_HOST``: |
---|
230 | The C++ compiler used to build the package. For an RTEMS build this is the |
---|
231 | RTEMS C++ compiler. For example the ARM architecture and RTEMS 5 the value is |
---|
232 | set to ``arm-rtems5-g++``. |
---|
233 | |
---|
234 | ``CPPFLAGS``, ``CPPFLAGS_FOR_HOST``: |
---|
235 | The C compiler preprocessor flags used to build the package. Set any include |
---|
236 | paths in this variable as some configure scripts will warns you if include |
---|
237 | paths are set in the ``CFLAGS``. |
---|
238 | |
---|
239 | ``CFLAGS``, ``CFLAGS_FOR_HOST``: |
---|
240 | The C compiler flags used when running the C compiler. Set any include paths |
---|
241 | in the ``CPPFLAGS`` variable as some configure scripts will warn you if |
---|
242 | include paths in this variable. |
---|
243 | |
---|
244 | ``CXXFLAGS``, ``CXXFLAGS_FOR_HOST``: |
---|
245 | The C++ compiler flags used when running the C++ compiler. Set any include |
---|
246 | paths in the ``CPPFLAGS`` variable as some configure scripts will warn you if |
---|
247 | include paths in this variable. |
---|
248 | |
---|
249 | ``LDFLAGS``, ``LDFLAGS_FOR_HOST``: |
---|
250 | The linker flags used whne link package executables. The C or C++ compiler |
---|
251 | is used to run the linker. |
---|
252 | |
---|
253 | ``LIBS``, ``LIBS_FOR_HOST``: |
---|
254 | A list of libraries passed to the linker when linking an executable. |
---|
255 | |
---|
256 | ``CC_FOR_BUILD``: |
---|
257 | The native C compiler. |
---|
258 | |
---|
259 | ``CXX_FOR_BUILD``: |
---|
260 | The native C++ compiler. |
---|
261 | |
---|
262 | ``CPPFLAGS_FOR_BUILD``: |
---|
263 | The C preprocessor flags used when preprocessoring a native C source file. |
---|
264 | |
---|
265 | ``CFLAGS_FOR_BUILD``: |
---|
266 | The native C compiler flags used when running the native C compiler. |
---|
267 | |
---|
268 | ``CXXFLAGS_FOR_BUILD``: |
---|
269 | The native C++ compiler flags used when running the native C++ compiler. |
---|
270 | |
---|
271 | ``LDFLAGS_FOR_BUILD``: |
---|
272 | The native linker flags used when linking a native executable. |
---|
273 | |
---|
274 | ``LIBS_FOR_BUILD``: |
---|
275 | The native libraries used to when linking a native executable. |
---|
276 | |
---|
277 | For a native build the flags are: |
---|
278 | |
---|
279 | ``CC``, ``CC_FOR_BUILD``: |
---|
280 | The native C compiler. |
---|
281 | |
---|
282 | ``CXX``, ``CXX_FOR_BUILD``: |
---|
283 | The native C++ compiler. |
---|
284 | |
---|
285 | ``CPPFLAGS``, ``CPPFLAGS_FOR_BUILD``: |
---|
286 | The C preprocessor flags used when preprocessoring a native C source file. |
---|
287 | |
---|
288 | ``CFLAGS``, ``CFLAGS_FOR_BUILD``: |
---|
289 | The native C compiler flags used when running the native C compiler. |
---|
290 | |
---|
291 | ``CXXFLAGS``, ``CXXFLAGS_FOR_BUILD``: |
---|
292 | The native C++ compiler flags used when running the native C++ compiler. |
---|
293 | |
---|
294 | ``LDFLAGS``, ``LDFLAGS_FOR_BUILD``: |
---|
295 | The native linker flags used when linking a native executable. |
---|
296 | |
---|
297 | ``LIBS``, ``LIBS_FOR_BUILD``: |
---|
298 | The native libraries used to when linking a native executable. |
---|
299 | |
---|
300 | BSP Support |
---|
301 | ^^^^^^^^^^^ |
---|
302 | |
---|
303 | The RSB provides support to build packages for RTEMS. RTEMS applications can |
---|
304 | be viewed as statically linked executables operating in a single address |
---|
305 | space. As a result only the static libraries a package builds are required and |
---|
306 | these libraries need to be ABI compatible with the RTEMS kernel and |
---|
307 | application code. This means the compiler ABI flags used to build all the code |
---|
308 | in the executable must be the same. A 3rd party package must use the same |
---|
309 | compiler flags as the BSP used to build RTEMS. |
---|
310 | |
---|
311 | .. note:: |
---|
312 | |
---|
313 | RTEMS's dynamic loading support does not use the standard shared library |
---|
314 | support found in Unix and the ELF standard. RTEMS's loader uses static |
---|
315 | libraries and the runtime link editor performs a similar function to a host |
---|
316 | based static linker. RTEMS will only reference static libraries even if |
---|
317 | dynamic libraries are created and installed. |
---|
318 | |
---|
319 | The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to |
---|
320 | support building third-party packages and you need to include this file in your |
---|
321 | RTEMS version specific configuration file. For example the Curl configuration |
---|
322 | file ``rtems/config/curl/curl-7.65.1-1.cfg``: |
---|
323 | |
---|
324 | .. code-block:: spec |
---|
325 | |
---|
326 | # |
---|
327 | # Curl 7.65.1 |
---|
328 | # |
---|
329 | |
---|
330 | %if %{release} == %{nil} |
---|
331 | %define release 1 <1> |
---|
332 | %endif |
---|
333 | |
---|
334 | %include %{_configdir}/rtems-bsp.cfg <2> |
---|
335 | |
---|
336 | # |
---|
337 | # Curl Version |
---|
338 | # |
---|
339 | %define curl_version 7.65.1 <3> |
---|
340 | |
---|
341 | %hash sha512 curl-%{curl_version}.tar.xz aba2d979a...72b6ac55df4 <4> |
---|
342 | |
---|
343 | # |
---|
344 | # Curl Build configuration |
---|
345 | # |
---|
346 | %include %{_configdir}/curl-1.cfg <5> |
---|
347 | |
---|
348 | .. topic:: Items: |
---|
349 | |
---|
350 | 1. The release number. |
---|
351 | |
---|
352 | 2. Include the RSB RTEMS BSP support. |
---|
353 | |
---|
354 | 3. The Curl package's version. |
---|
355 | |
---|
356 | 4. The SHA512 hash for the source file. The hash here has been shortened. |
---|
357 | |
---|
358 | 5. The Curl standard build configuration. |
---|
359 | |
---|
360 | The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make |
---|
361 | sure the required RSB command line options are provided. These include |
---|
362 | ``--host`` and ``--with-rtems-bsp``. If the ``--with-tools`` command line |
---|
363 | option is not given the ``${_prefix}`` is used as the path to the tools. If |
---|
364 | the ``--with-rtems`` command line option is not given the ``${_prefix}`` is |
---|
365 | used as the path to the installed RTEMS BSP. |
---|
366 | |
---|
367 | .. note:: |
---|
368 | |
---|
369 | The RTEMS BSP and any dependent 3rd party packages must be installed to be |
---|
370 | seen as available. A path to the location the BSP has been built will not |
---|
371 | work. |
---|
372 | |
---|
373 | The first check is to make sure a target is not specified. This is only used |
---|
374 | for Canadian cross-compilication builds and currently there is no support for |
---|
375 | RTEMS third party packages to build that way: |
---|
376 | |
---|
377 | .. code-block:: spec |
---|
378 | |
---|
379 | # |
---|
380 | # The target is used by compilers or Cxc builds. |
---|
381 | # |
---|
382 | %if %{_target} != %{nil} |
---|
383 | %error RTEMS BSP builds use --host and not --target |
---|
384 | %endif |
---|
385 | |
---|
386 | A host is required using the ``--host`` option: |
---|
387 | |
---|
388 | .. code-block:: spec |
---|
389 | |
---|
390 | # |
---|
391 | # We need a host from the user to specifiy the RTEMS architecture and major |
---|
392 | # version. |
---|
393 | # |
---|
394 | %if %{_host} == %{nil} && %{rtems_bsp_error} <1> |
---|
395 | %error No RTEMS host or BSP specified: --host=<arch>-rtems<ver> |
---|
396 | %endif |
---|
397 | |
---|
398 | An RTEMS BSP is required using the ``--with-bsp`` option: |
---|
399 | |
---|
400 | .. code-block:: spec |
---|
401 | |
---|
402 | # |
---|
403 | # We need a BSP from the user. |
---|
404 | # |
---|
405 | %ifn %{defined with_rtems_bsp} |
---|
406 | %if %{rtems_bsp_error} |
---|
407 | %error No RTEMS BSP specified: --rtems-bsp=arch/bsp (or --with-rtems-bsp=bsp) |
---|
408 | %endif |
---|
409 | %define with_rtems_bsp sparc/erc32 |
---|
410 | %endif |
---|
411 | |
---|
412 | Check if the ``--with-tools`` or ``--with-rtems`` options have been provided |
---|
413 | and if they are not provided use the ``--prefix`` path: |
---|
414 | |
---|
415 | .. code-block:: spec |
---|
416 | |
---|
417 | # |
---|
418 | # If no tools or RTEMS provided use the prefix. |
---|
419 | # |
---|
420 | %ifn %{defined with_tools} |
---|
421 | %define with_tools %{_prefix} |
---|
422 | %endif |
---|
423 | |
---|
424 | %ifn %{defined with_rtems} |
---|
425 | %define with_rtems %{_prefix} |
---|
426 | %endif |
---|
427 | |
---|
428 | Add the tools path to the envnironment path: |
---|
429 | |
---|
430 | .. code-block:: spec |
---|
431 | |
---|
432 | # |
---|
433 | # Set the path to the tools. |
---|
434 | # |
---|
435 | %{path prepend %{with_tools}/bin} |
---|
436 | |
---|
437 | RTEMS exports the build configuration in *pkgconfig* (.pc) files. The RSB can |
---|
438 | read these files even when there is no ``pkgconfig`` support installed on your |
---|
439 | development machine. The *pkgconfig* support provides a BSP's configuration and |
---|
440 | the RSB uses it to set the followng RSB macros variables: |
---|
441 | |
---|
442 | .. code-block:: spec |
---|
443 | |
---|
444 | %{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1> |
---|
445 | %{pkgconfig crosscompile yes} <2> |
---|
446 | %{pkgconfig filter-flags yes} <3> |
---|
447 | |
---|
448 | # |
---|
449 | # The RTEMS BSP Flags |
---|
450 | # |
---|
451 | %define rtems_bsp %{with_rtems_bsp} |
---|
452 | %define rtems_bsp_ccflags %{pkgconfig ccflags %{_host}-%{rtems_bsp}} <4> |
---|
453 | %define rtems_bsp_cflags %{pkgconfig cflags %{_host}-%{rtems_bsp}} |
---|
454 | %define rtems_bsp_ldflags %{pkgconfig ldflags %{_host}-%{rtems_bsp}} |
---|
455 | %define rtems_bsp_libs %{pkgconfig libs %{_host}-%{rtems_bsp}} |
---|
456 | |
---|
457 | .. topic:: Items: |
---|
458 | |
---|
459 | 1. Set the path to the BSP's pkgconfig file. |
---|
460 | |
---|
461 | 2. Let *pkgconfig* know this is a cross-compile build. |
---|
462 | |
---|
463 | 3. Filter flags such as warnings. Warning flags are specific to a package and |
---|
464 | RTEMS exports it's warnings flags in the BSP configuration settings. |
---|
465 | |
---|
466 | 4. Ask *pkgconfig* for the various settings we require. |
---|
467 | |
---|
468 | The flags obtained by *pkgconfig* and given a ``rtems_bsp`` prefix are used to |
---|
469 | set the RTEMS host variables ``CFLAGS``, ``LDFLAGS`` and ``LIBS``. When we |
---|
470 | build a third party library your host computer is the **build** machine and |
---|
471 | RTEMS is the **host** machine therefore we set the ``host`` variables: |
---|
472 | |
---|
473 | .. code-block:: spec |
---|
474 | |
---|
475 | %define host_cflags %{rtems_bsp_cflags} |
---|
476 | %define host_ldflags %{rtems_bsp_ldflags} |
---|
477 | %define host_libs %{rtems_bsp_libs} |
---|
478 | |
---|
479 | Finally we provide all the paths you may require when configuring a |
---|
480 | package. Packages by default consider the ``_prefix`` the base and install |
---|
481 | various files under this tree. The package you are building is specific to a |
---|
482 | BSP and needs to install it's files into the RTEMS specific BSP path under the |
---|
483 | ``_prefix``. This allows more than BSP build of this package to be installed |
---|
484 | under the same ``_prefix`` at the same time: |
---|
485 | |
---|
486 | .. code-block:: spec |
---|
487 | |
---|
488 | %define rtems_bsp_prefix %{_prefix}/%{_host}/%{rtems_bsp} <1> |
---|
489 | %define _exec_prefix %{rtems_bsp_prefix} |
---|
490 | %define _bindir %{_exec_prefix}/bin |
---|
491 | %define _sbindir %{_exec_prefix}/sbin |
---|
492 | %define _libexecdir %{_exec_prefix}/libexec |
---|
493 | %define _datarootdir %{_exec_prefix}/share |
---|
494 | %define _datadir %{_datarootdir} |
---|
495 | %define _sysconfdir %{_exec_prefix}/etc |
---|
496 | %define _sharedstatedir %{_exec_prefix}/com |
---|
497 | %define _localstatedir %{_exec_prefix}/var |
---|
498 | %define _includedir %{_libdir}/include |
---|
499 | %define _lib lib |
---|
500 | %define _libdir %{_exec_prefix}/%{_lib} |
---|
501 | %define _libexecdir %{_exec_prefix}/libexec |
---|
502 | %define _mandir %{_datarootdir}/man |
---|
503 | %define _infodir %{_datarootdir}/info |
---|
504 | %define _localedir %{_datarootdir}/locale |
---|
505 | %define _localedir %{_datadir}/locale |
---|
506 | %define _localstatedir %{_exec_prefix}/var |
---|
507 | |
---|
508 | .. topic:: Items: |
---|
509 | |
---|
510 | 1. The path to the installed BSP. |
---|
511 | |
---|
512 | When you configure a package you can reference these paths and the RSB will |
---|
513 | provide sensible default or in this case map them to the BSP: |
---|
514 | |
---|
515 | .. code-block:: spec |
---|
516 | |
---|
517 | ../${source_dir_curl}/configure \ <1> |
---|
518 | --host=%{_host} \ |
---|
519 | --prefix=%{_prefix} \ |
---|
520 | --bindir=%{_bindir} \ |
---|
521 | --exec_prefix=%{_exec_prefix} \ |
---|
522 | --includedir=%{_includedir} \ |
---|
523 | --libdir=%{_libdir} \ |
---|
524 | --libexecdir=%{_libexecdir} \ |
---|
525 | --mandir=%{_mandir} \ |
---|
526 | --infodir=%{_infodir} \ |
---|
527 | --datadir=%{_datadir} |
---|
528 | |
---|
529 | .. topic:: Items: |
---|
530 | |
---|
531 | 1. The configure command for Curl. |
---|
532 | |
---|
533 | |
---|
534 | BSP Configuration |
---|
535 | ^^^^^^^^^^^^^^^^^ |
---|
536 | |
---|
537 | The following RSB macros are defined when building a package for RTEMS: |
---|
538 | |
---|
539 | .. note:: |
---|
540 | |
---|
541 | A complete list can be obtained by building with the ``--trace`` flag. The |
---|
542 | log will contain a listing of all macros before and after the configuration |
---|
543 | is loaded. |
---|
544 | |
---|
545 | ``%{rtems_bsp}``: |
---|
546 | The name of the RTEMS BSP. |
---|
547 | |
---|
548 | ``%{rtems_bsp_cc}``: |
---|
549 | The C compiler name for the RTEMS BSP. |
---|
550 | |
---|
551 | ``%{rtems_bsp_cflags}``: |
---|
552 | The C compiler flags for the RTEMS BSP. |
---|
553 | |
---|
554 | ``%{rtems_bsp_ccflags}``: |
---|
555 | The C++ compiler flags for the RTEMS BSP. |
---|
556 | |
---|
557 | ``%{rtems_bsp_incpath}``: |
---|
558 | The include path to teh RTEMS BSP header files. |
---|
559 | |
---|
560 | ``%{rtems_bsp_ldflags}``: |
---|
561 | The linker flags for the RTEMS BSP. |
---|
562 | |
---|
563 | ``%{rtems_bsp_libs}``: |
---|
564 | The libraries used when linking an RTEMS BSP executable. |
---|
565 | |
---|
566 | ``%{rtems_bsp_prefix}``: |
---|
567 | The prefix for the RTEMS BSP. |
---|
568 | |
---|
569 | ``%{rtems-libbsd}``: |
---|
570 | The variable is set to ``found`` if LibBSD is available. |
---|
571 | |
---|
572 | ``%{rtems-defaultconfig}``: |
---|
573 | The path of the RSB helper script to locate find header files or libraries. |
---|
574 | |
---|
575 | ``%{_host}`` |
---|
576 | The host triplet passed on the command line to the set builder using the |
---|
577 | ``--host`` options. This is the RTEMS architecture and version. For example |
---|
578 | ``arm-rtems5``. |
---|
579 | |
---|
580 | ``%{host_cflags}``: |
---|
581 | The BSP ``CFLAGS`` returned by ``pkgconfig``. |
---|
582 | |
---|
583 | ``%{host_cxxflags}``: |
---|
584 | The BSP ``CXXFLAGS`` returned by ``pkgconfig``. |
---|
585 | |
---|
586 | ``%{host_includes}``: |
---|
587 | The BSP include paths returned by ``pkgconfig``. |
---|
588 | |
---|
589 | ``%{host_ldflags}``: |
---|
590 | The BSP ``LDFLAGS`` returned by ``pkgconfig``. |
---|
591 | |
---|
592 | ``%{host_libs}``: |
---|
593 | The libraries needed to be linked to create an executable. If LibBSD is |
---|
594 | installed the library ``-lbsd`` is added. If the BSP has installed the RTEMS |
---|
595 | default configuration library (``-lrtemsdefaultconfig``) it is added to the |
---|
596 | list of libraries. |
---|
597 | |
---|
598 | ``%{host_build_flags}``: |
---|
599 | This macro is defined in ``defaults.mc`` and is a series of shell commands |
---|
600 | that set up the environment to build an RTEMS package. If the host and the |
---|
601 | build triplets are the same it is a native build for your development host. If |
---|
602 | the host is not the build machine it is a cross-complitation build. For either |
---|
603 | case the following are defined. |
---|
604 | |
---|
605 | ``%{_host_os}``: |
---|
606 | The host operating system extracted from the ``--host`` command line |
---|
607 | option. For example the operating sstem for the host of ``arm-rtems5`` is |
---|
608 | ``rtems5``. |
---|
609 | |
---|
610 | ``%{_host_arch}``: |
---|
611 | The host architecture extracted from the ``--host`` command line option. For |
---|
612 | example the architecture for the host of ``arm-rtems5`` is ``arm``. |
---|
613 | |
---|
614 | ``%{_host_cpu}``: |
---|
615 | The host cpu extracted from the ``--host`` command line option. For |
---|
616 | example the cpu for the host of ``arm-rtems5`` is ``arm``. |
---|