[PATCH] user/rsb: Update 3rd party package build and add details.
chrisj at rtems.org
chrisj at rtems.org
Mon Jul 8 10:54:15 UTC 2019
From: Chris Johns <chrisj at rtems.org>
---
user/rsb/configuration.rst | 6 +-
user/rsb/index.rst | 51 +--
user/rsb/third-party-packages.rst | 545 ++++++++++++++++++++++--------
3 files changed, 439 insertions(+), 163 deletions(-)
diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst
index e9a6ad4..fc387a1 100644
--- a/user/rsb/configuration.rst
+++ b/user/rsb/configuration.rst
@@ -879,13 +879,13 @@ The script language is implemented in terms of macros. The built-in list is:
``%hash``:
Define a checksum for a source or patch file.
-``%echo``:
+``%{echo message}``:
Print the following string as a message.
-``%warning``:
+``%{warning message}``:
Print the following string as a warning and continue.
-``%error``:
+``%{error message}``:
Print the following string as an error and exit.
``%select``:
diff --git a/user/rsb/index.rst b/user/rsb/index.rst
index d499800..96fb5a8 100644
--- a/user/rsb/index.rst
+++ b/user/rsb/index.rst
@@ -6,28 +6,30 @@
.. _RSB:
-RTEMS Source Builder
-********************
+Source Builder
+**************
-The RTEMS Source Builder or RSB is a tool to build packages from source. It is
-used by the RTEMS project to build it's compilers and OS. The RSB helps
-consolidate the details you need to build a package from source in a controlled
-and verifiable way. The tool is aimed at developers of software who use tool
-sets for embedded development. The RSB is not limited to building tools just
-for RTEMS, you can build bare metal development environments.
+The RTEMS Source Builder or RSB is a tool to build packages from source. The
+RTEMS project uses it to build it's compilers, tools, kernel and 3rd party
+packages. The tool is aimed at developers of software who use tool sets for
+embedded development.
+
+The RSB consolidate the details you need to build a package from source in a
+controlled and verifiable way. The RSB is not limited to building tools for
+RTEMS, you can build bare metal development environments.
Embedded development typically uses cross-compiling tool chains, debuggers, and
debugging aids. Together we call these a **tool set**. The RTEMS Source Builder
is designed to fit this specific niche but is not limited to it. The RSB can be
used outside of the RTEMS project and we welcome this.
-The RTEMS Source Builder is typically used to build a set of tools or a **build
-set**. A **build set** is a collection of packages and a package is a specific
-tool, for example GCC or GDB, or library. The RTEMS Source Builder attempts to
-support any host environment that runs Python and you can build the package
-on. The RSB is not some sort of magic that can take any piece of source code
-and make it build. Someone at some point in time has figured out how to build
-that package from source and taught this tool.
+The RTEMS Source Builder is typically used to build a set of packages or a
+**build set**. A **build set** is a collection of packages and a package is a
+specific tool, for example GCC, GDB, or library. The RTEMS Source Builder
+attempts to support any host environment that runs Python and you can build the
+package on. The RSB is not some sort of magic that can take any piece of source
+code and make it build. Someone at some point in time has figured out how to
+build that package from source and taught this tool.
The RTEMS Source Builder has been tested on:
@@ -40,6 +42,7 @@ The RTEMS Source Builder has been tested on:
- openSUSE
- FreeBSD
- NetBSD
+- Solaris
- MacOS
- Windows
@@ -83,12 +86,12 @@ configuration can read the remaining sections.
.. toctree::
- why-build-from-source.rst
- project-sets
- cross-canadian-cross
- third-party-packages
- configuration
- commands
- deployment
- bug-reporting
- history
+ why-build-from-source.rst
+ project-sets
+ cross-canadian-cross
+ third-party-packages
+ configuration
+ commands
+ deployment
+ bug-reporting
+ history
diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst
index b8ca15a..2099f64 100644
--- a/user/rsb/third-party-packages.rst
+++ b/user/rsb/third-party-packages.rst
@@ -2,23 +2,29 @@
.. Copyright (C) 2012, 2016 Chris Johns <chrisj at rtems.org>
-RTEMS Third-Party Packages
---------------------------
+Third-Party Packages
+--------------------
This section describes how to build and add an RTEMS third-party package to the
RSB.
A third-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).
+examples are Curl, NTP, Net-Snmp, libjpeg and more. 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,an installed RTEMS
+Board Support Package (BSP), and if a network based packaged the networking
+stack.
-The RSB support for building third-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.
+.. sidebar:: Help
+
+ If you have any issues using, building or adding third party packages please
+ ask on the RTEMS users mailing list.
+
+
+The RSB support for building third-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.
Vertical Integration
^^^^^^^^^^^^^^^^^^^^
@@ -27,33 +33,70 @@ 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 third-party libraries, you can
-crate build sets that stack library dependences vertically to create a *stack*.
+create 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:
+the RTEMS host, and the prefix path to the installed RTEMS BSP.
+
+The RSB prefix option (``--prefix``) provided when building a package is the
+path to:
+
+#. The tools, RTEMS kernel and any dependent libraries such as LibBSD. The
+ package will be installed into the prefix path. This build configuration can
+ be used to make a complete set of development tools and libraries for a
+ project or product under a single path.
+
+#. The RTEMS kernel and any dependent libraries such as LibBSD. The tools path
+ needs to be in the environment path (not recommended) or provided to the set
+ builder command by the ``--with-tools`` option. The package will be
+ installed into the prefix path. This build configuration can be used when
+ you have a set of tools used with a number of RTEMS BSPs. The tools can be
+ shared between the different BSPs.
+
+#. The path the package is installed into. The tools path needs to be in the
+ environment path (not recommended) or provided to the set builder command
+ using the ``--with-tools`` option. The path to the RTEMS kernel and any
+ dependent libraries such as LibBSD needs to be supplied to the set builder
+ command using the ``--with-rtems`` option. This build configuration can be
+ used when you have a set of libraries you are testing with a changing RTEMS
+ kernel. Becareful using this configuration as changes in RTEMS interfaces
+ may require rebuilding these packages.
+
+The set builder command option ``--host`` is used to provide the RTEMS
+architecture the package is being built for. For example ``--host=arm-rtems5``
+is used for any ARM BSP.
+
+The set builder command option ``--with-rtems-bsp`` is the RTEMS BSP the
+package is being built for. The BSP is searched for under the path provided by
+the command option ``--with-rtems`` and if this option is not provided the
+provided prefix is searched.
+
+The following example builds and install the Curl networking package to the
+same path the tools, RTEMS kernel and LibBSD is installed for the ARM
+BeagleBone Black BSP:
.. code-block:: none
- $ 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=erc32 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
+ $ ../source-builder/sb-set-builder --prefix=$HOME/development/cs/rtems/5 \
+ --log=curl.txt --host=arm-rtems5 --with-rtems-bsp=beagleboneblack ftp/curl
+ RTEMS Source Builder - Set Builder, 5 (2bdae1f169e4)
+ Build Set: ftp/curl
+ config: ftp/curl-7.65.1-1.cfg
+ package: curl-v7.65.1-arm-rtems5-1
+ download: https://curl.haxx.se/download/curl-7.65.1.tar.xz -> sources/curl-7.65.1.tar.xz
+ downloading: sources/curl-7.65.1.tar.xz - 2.3MB of 2.3MB (100%)
+ building: curl-v7.65.1-arm-rtems5-1
+ sizes: curl-v7.65.1-arm-rtems5-1: 87.055MB (installed: 2.238MB)
+ cleaning: curl-v7.65.1-arm-rtems5-1
+ reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.txt
+ reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.xml
+ installing: curl-v7.65.1-arm-rtems5-1 -> /Users/chris/development/cs/rtems/5
+ cleaning: curl-v7.65.1-arm-rtems5-1
+ Build Set: Time 0:01:10.006872
Adding
^^^^^^
@@ -64,30 +107,43 @@ 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
+community as well as RTEMS. RTEMS submission and reference is best as a patch
+attached to ticket in Trac. An patch attached to a ticket can be referenced by
+an RSB configuration file and used in a build.
+
+.. sidebar:: Patches in Trac
+
+ Attaching patches for packages to Trac tickets provides an easy to reference
+ URL the RSB can fetch. The patch URL does not change across RTEMS versions
+ and it does not depend on the state or layout of a git repo.
+
+
+A package may create executables, for example Curl normally creates an
+executable called ``curl`` how ever it will probailty not run because the
+needed RTEMS configuration is not suitable. The RSB add the RTEMS library
+``librtemsdefaultconfig.a`` to the ``LIBS`` variable used to link executables
+if found. This library provides a limited configuraiton suitable for linking an
+executable however it is not a set up that allows the resulting executable to
+run correctly. As a result it is best not to install these executables.
+
+A custom RTEMS patch to an executate can turn it into a function that can be
+called by the RTEMS shell. Users can call the function in their executables
+simulating the running of the package's command. 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 at least three (3) files to be created:
+
+- The first file is the RTEMS build set file and it resides under the
+ ``rtems/config`` path in a directory tree based on the FreeBSD ports
+ collection. For the Curl package and RTEMS 5 this is
+ ``rtems/config/ftp/curl.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.
@@ -95,12 +151,13 @@ A package requires 3 files to be created:
- 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
+ the Curl package is found in the ``ftp`` directory of the FreeBSD ports tree
+ so the Curl configuration path is ``rtems/config/ftp/curl-7.65.1-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.
+ in the common configuration file tree. An SHA512 hash is required to verify
+ the source package that is downloaded.
- The build configuration. This is a common script that builds the package. It
resides in the ``source-builder/config`` directory and typically has the
@@ -113,6 +170,122 @@ A package requires 3 files to be created:
package for the build host as well as RTEMS as the RSB abstracts the RTEMS
specific parts. See :ref:`Configuration` for more details.
+Host and Build Flags
+^^^^^^^^^^^^^^^^^^^^
+
+A package's build is controlled by setting the compiler names and flags that
+are used when building. The RSB provides a macro called ``%{host_build_flags}``
+to define these flags for you. Use this macro in the ```%build`` section of
+your config script file to define the set up needed to build a native package
+or to cross-compile to a specific host. The typical ``%build`` section is:
+
+.. code-block:: spec
+
+ %build
+ build_top=$(pwd)
+
+ %{build_directory}
+
+ mkdir -p ${build_dir}
+ cd ${build_dir}
+
+ %{host_build_flags}
+
+ ../${source_dir_curl}/configure \
+ --host=%{_host} \
+ --prefix=%{_prefix} \
+ --bindir=%{_bindir} \
+ --exec_prefix=%{_exec_prefix} \
+ --includedir=%{_includedir} \
+ --libdir=%{_libdir} \
+ --libexecdir=%{_libexecdir} \
+ --mandir=%{_mandir} \
+ --infodir=%{_infodir} \
+ --datadir=%{_datadir}
+
+ %{__make} %{?_smp_mflags} all
+
+ cd ${build_top}
+
+The ``%{host_build_flags}`` checks if the build is native for the development
+host or a cross-compile build.
+
+For a cross-complication build the flags are:
+
+``CC``, ``CC_FOR_HOST``:
+ The C compiler used to build the package. For an RTEMS build this is the RTEMS
+ C compiler. For the ARM architecture it is set to ``arm-rtems5-gcc``.
+
+``CXX``, ``CXX_FOR_HOST``:
+ The C++ compiler used to build the package. For an RTEMS build this is the
+ RTEMS C++ compiler. For the ARM architecture it is set to ``arm-rtems5-g++``.
+
+``CPPFLAGS``, ``CPPFLAGS_FOR_HOST``:
+ The C compiler preprocessor flags used to build the packagw. Set any include
+ paths in this variable as some configure scripts will warns you if include
+ paths are set in the ``CFLAGS``.
+
+``CFLAGS``, ``CFLAGS_FOR_HOST``:
+ The C compiler flags used when running the C compiler. Set any include paths
+ in the ``CPPFLAGS`` variable as some configure scripts will warn you if
+ include paths in this variable.
+
+``CXXFLAGS``, ``CXXFLAGS_FOR_HOST``:
+ The C++ compiler flags used when running the C++ compiler. Set any include
+ paths in the ``CPPFLAGS`` variable as some configure scripts will warn you if
+ include paths in this variable.
+
+``LDFLAGS``, ``LDFLAGS_FOR_HOST``:
+ The linker flags used whne link package executables. The C or C++ compiler
+ is used to run the linker.
+
+``LIBS``, ``LIBS_FOR_HOST``:
+ A list of libraries passed to the linker when linking an executable.
+
+``CC_FOR_BUILD``:
+ The native C compiler.
+
+``CXX_FOR_BUILD``:
+ The native C++ compiler.
+
+``CPPFLAGS_FOR_BUILD``:
+ The C preprocessor flags used when preprocessoring a native C source file.
+
+``CFLAGS_FOR_BUILD``:
+ The native C compiler flags used when running the native C compiler.
+
+``CXXFLAGS_FOR_BUILD``:
+ The native C++ compiler flags used when running the native C++ compiler.
+
+``LDFLAGS_FOR_BUILD``:
+ The native linker flags used when linking a native executable.
+
+``LIBS_FOR_BUILD``:
+ The native libraries used to when linking a native executable.
+
+For a native build the flags are:
+
+``CC``, ``CC_FOR_BUILD``:
+ The native C compiler.
+
+``CXX``, ``CXX_FOR_BUILD``:
+ The native C++ compiler.
+
+``CPPFLAGS``, ``CPPFLAGS_FOR_BUILD``:
+ The C preprocessor flags used when preprocessoring a native C source file.
+
+``CFLAGS``, ``CFLAGS_FOR_BUILD``:
+ The native C compiler flags used when running the native C compiler.
+
+``CXXFLAGS``, ``CXXFLAGS_FOR_BUILD``:
+ The native C++ compiler flags used when running the native C++ compiler.
+
+``LDFLAGS``, ``LDFLAGS_FOR_BUILD``:
+ The native linker flags used when linking a native executable.
+
+``LIBS``, ``LIBS_FOR_BUILD``:
+ The native libraries used to when linking a native executable.
+
BSP Support
^^^^^^^^^^^
@@ -134,39 +307,32 @@ RTEMS.
The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
support building third-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``:
+RTEMS version specific configuration file. For example the Curl configuration
+file ``rtems/config/curl/curl-7.65.1-1.cfg``:
.. code-block:: spec
- #
- # NetSNMP 5.7.2.1
- #
- %if %{release} == %{nil}
- %define release 1 <1>
- %endif
+ #
+ # Curl 7.65.1
+ #
- %include %{_configdir}/rtems-bsp.cfg <2>
+ %if %{release} == %{nil}
+ %define release 1 <1>
+ %endif
- #
- # NetSNMP Version
- #
- %define net_snmp_version 5.7.2.1 <3>
+ %include %{_configdir}/rtems-bsp.cfg <2>
- #
- # 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
+ #
+ # Curl Version
+ #
+ %define curl_version 7.65.1 <3>
- #
- # Patch for RTEMS support.
- #
- %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
+ %hash sha512 curl-%{curl_version}.tar.xz aba2d979a...72b6ac55df4 <4>
- #
- # NetSNMP Build configuration
- #
- %include %{_configdir}/net-snmp-5-1.cfg <6>
+ #
+ # Curl Build configuration
+ #
+ %include %{_configdir}/curl-1.cfg <5>
.. topic:: Items:
@@ -174,54 +340,85 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
2. Include the RSB RTEMS BSP support.
- 3. The Net-SNMP package's version.
+ 3. The Curl package's version.
- 4. Add specific ``CFLAGS`` to the build process. See the
- ``net-snmp-5.7.2.1-1.cfg`` for details.
+ 4. The SHA512 hash for the source file. The hash here has been shortened.
- 5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
-
- 6. The Net-SNMP standard build configuration.
+ 5. The Curl 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:
+sure the required 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 as the path to the tools.
+
+The first check is to make sure a target is not specified. This is only used
+for Canadian cross-compilication builds and currently there is no support for
+RTEMS third party packages:
.. code-block:: spec
- %if %{_host} == %{nil} <1>
- %error No RTEMS target specified: --host=host
- %endif
+ #
+ # The target is used by compilers or Cxc builds.
+ #
+ %if %{_target} != %{nil}
+ %error RTEMS BSP builds use --host and not --target
+ %endif
- %ifn %{defined with_rtems_bsp} <2>
- %error No RTEMS BSP specified: --with-rtems-bsp=bsp
- %endif
+A host is required using the ``--host`` option:
- %ifn %{defined with_tools} <3>
- %define with_tools %{_prefix}
- %endif
+.. code-block:: spec
- #
- # Set the path to the tools.
- #
- %{path prepend %{with_tools}/bin} <4>
+ #
+ # We need a host from the user to specifiy the RTEMS architecture and major
+ # version.
+ #
+ %if %{_host} == %{nil} && %{rtems_bsp_error} <1>
+ %error No RTEMS host or BSP specified: --host=<arch>-rtems<ver>
+ %endif
-.. topic:: Items:
+An RTEMS BSP is required using the ``--with-bsp`` option:
+
+.. code-block:: spec
- 1. Check the host has been set.
+ #
+ # We need a BSP from the user.
+ #
+ %ifn %{defined with_rtems_bsp}
+ %if %{rtems_bsp_error}
+ %error No RTEMS BSP specified: --rtems-bsp=arch/bsp (or --with-rtems-bsp=bsp)
+ %endif
+ %define with_rtems_bsp sparc/erc32
+ %endif
- 2. Check a BSP has been specified.
+Check if the ``--with-tools`` or ``--with-rtems`` options have been provided
+and if they are not provided use the ``--prefix`` path:
- 3. If no tools path has been provided assume they are under the
- ``%{_prefix}``.
+.. code-block:: spec
+
+ #
+ # If no tools or RTEMS provided use the prefix.
+ #
+ %ifn %{defined with_tools}
+ %define with_tools %{_prefix}
+ %endif
- 4. Add the tools ``bin`` path to the system path.
+ %ifn %{defined with_rtems}
+ %define with_rtems %{_prefix}
+ %endif
-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``):
+Add the tools path to the envnironment path:
+
+.. code-block:: spec
+
+ #
+ # Set the path to the tools.
+ #
+ %{path prepend %{with_tools}/bin}
+
+RTEMS exports the build configuration in *pkgconfig* (.pc) files. The RSB can
+read these files even when there is no ``pkgconfig`` support installed on your
+development machine. The *pkgconfig* support provides a BSP's configuration and
+the RSB uses it to set the followng RSB macros variables:
.. code-block:: spec
@@ -242,17 +439,18 @@ some standard macros variables (``rtems/config/rtems-bsp.cfg``):
1. Set the path to the BSP's pkgconfig file.
- 2. Let pkgconfig know this is a cross-compile build.
+ 2. Let *pkgconfig* know this is a cross-compile build.
- 3. Filter flags such as warnings. Warning flags are specific to a package.
+ 3. Filter flags such as warnings. Warning flags are specific to a package and
+ RTEMS exports it's warnings flags in the BSP configuration settings.
- 4. Ask pkgconfig for the various items we require.
+ 4. Ask *pkgconfig* for the various settings 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``):
+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 third party library your host computer is the **build**
+machine and RTEMS is the **host** machine therefore we set the ``host``
+variables:
.. code-block:: spec
@@ -263,9 +461,9 @@ machine therefore we set the ``host`` variables
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``):
+BSP and needs to install it's files into the specific BSP path under the
+``_prefix``. This allows more than BSP build of this package to be installed
+under the same ``_prefix`` at the same time:
.. code-block:: spec
@@ -294,12 +492,11 @@ under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
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``):
+provide sensible default or in this case map them to the BSP:
.. code-block:: spec
- ../${source_dir_ntp}/configure \ <1>
+ ../${source_dir_curl}/configure \ <1>
--host=%{_host} \
--prefix=%{_prefix} \
--bindir=%{_bindir} \
@@ -309,17 +506,93 @@ provide sensible default or in this case map them to the BSP
--libexecdir=%{_libexecdir} \
--mandir=%{_mandir} \
--infodir=%{_infodir} \
- --datadir=%{_datadir} \
- --disable-ipv6 \
- --disable-HOPFPCI
+ --datadir=%{_datadir}
.. topic:: Items:
- 1. The configure command for NTP.
+ 1. The configure command for Curl.
+
+
+BSP Configuration
+^^^^^^^^^^^^^^^^^
+
+The following RSB macros are defined when build a package for RTEMS:
+
+.. note::
+
+ A complete list can be obtained by building with the ``--trace`` flag. The
+ log will contain a listing of all macros before and after the configuration
+ is loaded.
+
+``%{rtems_bsp}``:
+ The name of the RTEMS BSP.
+
+``%{rtems_bsp_cc}``:
+ The C compiler name for the RTEMS BSP.
+
+``%{rtems_bsp_cflags}``:
+ The C compiler flags for the RTEMS BSP.
+
+``%{rtems_bsp_ccflags}``:
+ The C++ compiler flags for the RTEMS BSP.
+
+``%{rtems_bsp_incpath}``:
+ The include path to teh RTEMS BSP header files.
+
+``%{rtems_bsp_ldflags}``:
+ The linker flags for the RTEMS BSP.
+
+``%{rtems_bsp_libs}``:
+ The libraries used when linking an RTEMS BSP executable.
+
+``%{rtems_bsp_prefix}``:
+ The prefix for the RTEMS BSP.
+
+``%{rtems-libbsd}``:
+ The variable is set to ``found`` if LibBSD is available.
+
+``%{rtems-defaultconfig}``:
+ The path of the RSB helper script to locate find header files or libraries.
+
+``%{_host}``
+ The host triplet passed on the command line to the set builder using the
+ ``--host`` options. This is the RTEMS architecture and version. For example
+ ``arm-rtems5``.
+
+``%{host_cflags}``:
+ The BSP ``CFLAGS`` returned by ``pkgconfig``.
+
+``%{host_cxxflags}``:
+ The BSP ``CXXFLAGS`` returned by ``pkgconfig``.
+
+``%{host_includes}``:
+ The BSP include paths returned by ``pkgconfig``.
+
+``%{host_ldflags}``:
+ The BSP ``LDFLAGS`` returned by ``pkgconfig``.
+
+``%{host_libs}``:
+ The libraries needed to be linked to create an executable. If LibBSD is
+ installed the library ``-lbsd`` is added. If the BSP has installed the RTEMS
+ default configuration library (``-lrtemsdefaultconfig``) it is added to the
+ list of libraries.
+
+``%{host_build_flags}``:
+ This macro is defined in ``defaults.mc`` and is a series of shell commands
+ that set up the environment to build an RTEMS package. If the host and the
+ build triplets are the same it is a native build for your development host. If
+ the host is not the build machine it is a cross-complitation build. For either
+ case the following are defined.
+
+``%{_host_os}``:
+ The host operating system extracted from the ``--host`` command line
+ option. For example the operating sstem for the host of ``arm-rtems5`` is
+ ``rtems5``.
-RTEMS BSP Configuration
-^^^^^^^^^^^^^^^^^^^^^^^
+``%{_host_arch}``:
+ The host architecture extracted from the ``--host`` command line option. For
+ example the architecture for the host of ``arm-rtems5`` is ``arm``.
-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.
+``%{_host_cpu}``:
+ The host cpu extracted from the ``--host`` command line option. For
+ example the cpu for the host of ``arm-rtems5`` is ``arm``.
--
2.20.1 (Apple Git-117)
More information about the devel
mailing list