diff options
Diffstat (limited to 'user/rsb')
| -rw-r--r-- | user/rsb/commands.rst | 121 | ||||
| -rw-r--r-- | user/rsb/configuration.rst | 154 | ||||
| -rw-r--r-- | user/rsb/cross-canadian-cross.rst | 2 | ||||
| -rw-r--r-- | user/rsb/index.rst | 2 | ||||
| -rw-r--r-- | user/rsb/project-sets.rst | 11 | ||||
| -rw-r--r-- | user/rsb/third-party-packages.rst | 2 |
6 files changed, 156 insertions, 136 deletions
diff --git a/user/rsb/commands.rst b/user/rsb/commands.rst index b85692d..4048568 100644 --- a/user/rsb/commands.rst +++ b/user/rsb/commands.rst @@ -199,22 +199,22 @@ The ``arguments`` are a list of build sets to build. Path to the configuration directory. This overrides the built in defaults. ``--builddir path``: - Path to the build directory. This overrides the default of +build+. + Path to the build directory. This overrides the default of `build`. ``--sourcedir path``: - Path to the source directory. This overrides the default of +source+. + Path to the source directory. This overrides the default of `source`. ``--patchdir path``: - Path to the patches directory. This overrides the default of +patches+. + Path to the patches directory. This overrides the default of `patches`. ``--tmppath path``: - Path to the temporary directory. This overrides the default of +tmp+. + Path to the temporary directory. This overrides the default of `tmp`. ``--macros files``: Macro files to load. The configuration directory path is searched. ``--log file``: - Log all the output from the build process. The output is directed to +stdout+ + Log all the output from the build process. The output is directed to `stdout` if no log file is provided. ``--url url``: @@ -296,42 +296,83 @@ The ``arguments`` are a list of build sets to build. Print a list of dependent files used by a build set. Dependent files have a ``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically. -Set Builder (sb-builder) -^^^^^^^^^^^^^^^^^^^^^^^^ +Track (sb-track) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This command checks build sets and configurations reporting any errors, the +dependencies and which files are referenced. The command can list all the +configuration files not referenced. If this option is used when checking all +build set files a list of all configuration files not referenced can be +found. The list can be used to purge the RSB of old and unused configurations. -This command builds a configuration as described in a configuration -file. Configuration files have the extension of ``.cfg``: +The check runs a build set through a number of host configurations. This +checks any logic that is specific to a host. + +The command reports a dependency tree for a build set in the output +report. For example the dependency tree for the ``database/sqlite`` build set +is: .. code-block:: none - $ ./source-builder/sb-builder --help - sb-builder: [options] [args] - RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns - Options and arguments: - --force : Force the build to proceed - --quiet : Quiet output (not used) - --trace : Trace the execution - --dry-run : Do everything but actually run the build - --warn-all : Generate warnings - --no-clean : Do not clean up the build tree - --always-clean : Always clean the build tree, even with an error - --jobs : Run with specified number of jobs, default: num CPUs. - --host : Set the host triplet - --build : Set the build triplet - --target : Set the target triplet - --prefix path : Tools build prefix, ie where they are installed - --topdir path : Top of the build tree, default is $PWD - --configdir path : Path to the configuration directory, default: ./config - --builddir path : Path to the build directory, default: ./build - --sourcedir path : Path to the source directory, default: ./source - --patchdir path : Path to the patches directory, default: ./patches - --tmppath path : Path to the temp directory, default: ./tmp - --macros file[,[file] : Macro format files to load after the defaults - --log file : Log file where all build out is written too - --url url[,url] : URL to look for source - --targetcflags flags : List of C flags for the target code - --targetcxxflags flags : List of C++ flags for the target code - --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code - --with-<label> : Add the --with-<label> to the build - --without-<label> : Add the --without-<label> to the build - --list-configs : List available configurations + +-- rtems/config/databases/sqlite.bset + +-- rtems/config/databases/sqlite-3.31.1-1.cfg + +-- rtems/config/rtems-bsp.cfg + +-- source-builder/config/sqlite-3-1.cfg + +-- rtems/config/rtems-package.bset + +-- rtems/config/rtems-urls.bset + +-- rtems/config/rtems-version.bset + +The comnmand is: + +.. code-block:: none + + $ ../source-builder/sb-track --help + usage: sb-dep-check [-h] [--rtems-version RTEMS_VERSION] [--list-hosts] + [--list-bsets] [--output OUTPUT] [--log LOG] [--trace] + [--not-referenced] + [bsets [bsets ...]] + + RTEMS Track Dependencies a build set has for all hosts. + + positional arguments: + bsets Build sets. + + optional arguments: + -h, --help show this help message and exit + --rtems-version RTEMS_VERSION + Set the RTEMS version. + --list-hosts List the hosts. + --list-bsets List the hosts. + --output OUTPUT Output file. + --log LOG Log file. + --trace Enable trace logging for debugging. + --not-referenced Write out the list of config files not referenced. + +The ``bsets`` are a list of build sets to check. If none are provided all +build sets are checked. + +**Options**: + +``-h, --help``: + The command's help. + +``--rtems-version``: + Set the RTEMS version number. + +``--list-hosts``: + List the hosts each build set of check against. + +``--list-bsets``: + List all the build set files. + +``--output``: + Write the report to the output file. + +``--log``: + The log file the build set check processing is written too. + +``--trace``: + Enable trace debugging. + +``--not-referenced``: + List the configration files not referenced by a build set in the output. diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst index fc387a1..1403c4f 100644 --- a/user/rsb/configuration.rst +++ b/user/rsb/configuration.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 Gedare Bloom <gedare@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. _Configuration: @@ -39,8 +40,7 @@ The configuration search path is a macro variable and is reference as Build set files have the file extension ``.bset`` and the package build configuration files have the file extension of ``.cfg``. The ``sb-set-builder`` -command will search for *build sets* and the ``sb-builder`` commands works with -package build configuration files. +command will search for *build sets*. Both types of configuration files use the ``#`` character as a comment character. Anything after this character on the line is ignored. There is no @@ -113,8 +113,8 @@ supported compression formats are: ``zip``: ZIP -``xy``: - XY +``xz``: + XZ The output of the decompression tool is fed to the standard ``tar`` utility if not a ZIP file and unpacked into the build directory. ZIP files are unpacked by @@ -130,14 +130,16 @@ source is broken down in a number of smaller files and you require the full package. The source's ``setup`` command must reside in the ``%prep:`` section and it unpacks the source code ready to be built. -If the source URL references the GitHub API server https://api.github.com/ a -tarball of the specified version is download. For example the URL for the -STLINK project on GitHub and version is: +If the source URL references the GitHub API server a tarball of the specified +version is download. For example the URL for a Newlib snapshot GitHub is: .. code-block:: spec - %define stlink_version 3494c11 - %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz + %define newlib_version 08eab6396f678cf5e5968acaed0bae9fd129983b + %define newlib_external 1 + %define newlib_expand_name sourceware-mirror-newlib-cygwin-%{newlib_version} + %source set newlib --rsb-file=newlib-%{newlib_version}.tar.gz \ + https://codeload.github.com/RTEMS/sourceware-mirror-newlib-cygwin/tar.gz/%{newlib_version} GIT ~~~ @@ -181,35 +183,7 @@ errors that can arise. The protocol option lets you set a specific protocol. The ``git://`` prefix used by the RSB to select a git repository can be removed using *none* or -replaced with one of the standard git protcols. - -CVS -~~~ - -A CVS repository can be checked out. CVS is more complex than GIT to handle -because of the modules support. This can effect the paths the source ends up -in. The CVS URL only supports the CVS protocol. You can control the repository -via the URL by appending options and arguments to the CVS path. The options are -delimited by ``?`` and option arguments are delimited from the options with -``=``. The options are: - -``module``: - The module to checkout. - -``src-prefix``: - The path into the source where the module starts. - -``tag``: - The CVS tag to checkout. - -``date``: - The CVS date to checkout. - -The following is an example of checking out from a CVS repository: - -.. code-block:: spec - - %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src +replaced with one of the standard git protocols. Macros and Defaults ^^^^^^^^^^^^^^^^^^^ @@ -315,7 +289,7 @@ Maps are declared anywhere in the map using the map directive: 1. The map is set to ``my-special-map``. -Any macro defintions following a map declaration are placed in that map and the +Any macro definitions following a map declaration are placed in that map and the default map is ``global`` when loading a file. Maps are selected in configuration files by using the ``%select`` directive: @@ -328,9 +302,10 @@ if present return that value else the ``global`` map is used. Any new macros or changes update only the ``global`` map. This may change in future releases so please make sure you use the ``override`` attribute. -The macro files specificed on the command line are looked for in the -``_configdir`` paths. See <<X1,``_configdir``>> variable for details. Included -files need to add the ``%{_configdir}`` macro to the start of the file. +The macro files specified on the command line are looked for in the +``_configdir`` paths. See the definition of ``_configdir`` in +:ref:`Configuration` for details. Included files need to add the +``%{_configdir}`` macro to the start of the file. Macro map files can include other macro map files using the ``%include`` directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and @@ -364,11 +339,26 @@ points to are loaded. The second is a file called ``.rsb_macros`` in your home directory. You need to have the environment variable ``HOME`` defined for this work. +Configuration Reports +^^^^^^^^^^^^^^^^^^^^^ + +A configuration report detailing a build configuration is generated by the +``sb-set-builder`` command. The report can also be generated separately from +the build process by invoking the ``sb-report`` command on the build set used +for the build, for example: + +.. code-block:: shell + + cd rtems + ../source-builder/sb-reports 5/rtems-sparc + less 5-rtems-sparc.txt + Report Mailing -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ -The build reports can be mailed to a specific email address to logging and -monitoring. Mailing requires a number of parameters to function. These are: +Configuration reports from a build can be mailed to a specific email address +for logging and monitoring. Mailing requires a number of parameters to +function. These are: - To mail address @@ -459,13 +449,12 @@ tools. File naming provides configuration management. A specific version of a package is captured in a specific set of configuration files. The top level -configuration file referenced in a *build set* or passed to the ``sb-builder`` -command relates to a specific configuration of the package being built. For -example the RTEMS configuration file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg`` -creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the -Newlib version is 2.0.0, plus any RTEMS specific patches that related to this -version. The configuration defines the version numbers of the various parts -that make up this package: +configuration file referenced in a *build set* relates to a specific +configuration of the package being built. For example the RTEMS configuration +file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg`` creates an RTEMS GCC and Newlib +package where the GCC version is 4.7.2, the Newlib version is 2.0.0, plus any +RTEMS specific patches that related to this version. The configuration defines +the version numbers of the various parts that make up this package: .. code-block:: spec @@ -616,13 +605,13 @@ information is kept updated and accurate: Summary: Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host} Version: %{dtc_version} Release: %{release} - URL: http://www.jdl.com/software/ + URL: https://www.devicetree.org/ BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n) The next section defines the source and any patches. In this case there is a single source package and it can be downloaded using the HTTP protocol. The RSB knows this is GZip'ped tar file. If more than one package is needed, add -them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains +them increasing the index. The ``gcc-8-1.cfg`` configuration contains examples of more than one source package as well as conditionally including source packages based on the outer configuration options: @@ -631,13 +620,13 @@ source packages based on the outer configuration options: # # Source # - %source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz + %source set dtc https://www.kernel.org/pub/software/utils/dtc/dtc-%{dtc_version}.tar.gz The remainder of the script is broken in to the various phases of a build. They are: -. Preperation -. Bulding +. Preparation +. Building . Installing, and . Cleaning @@ -713,8 +702,8 @@ installed into the prefix on the build host and you may not even have permissions to perform a real install. Most packages install to the ``prefix`` and the prefix is typically supplied via the command to the RSB or the package's default is used. The default can vary depending on the host's -operating system. To install to a path that is not the prefix the ``DESTDIR`` -make variable is used. Most packages should honour the ``DISTDIR`` make +operating system. To install to a path that is not the prefix the ``DESTDIR`` +make variable is used. Most packages should honour the ``DESTDIR`` make variables and you can typically specify it on the command line to make when invoking the install target. This results in the package being installed to a location that is not the prefix but one you can control. The RSB provides a @@ -745,28 +734,11 @@ Finally there is an optional clean section. The RSB will run this section if ``--no-clean`` has not been provided on the command line. The RSB does clean up for you. -Once we have the configuration files we can execute the build using the -``sb-builder`` command. The command will perform the build and create a tar file -in the ``tar`` directory: - -.. code-block:: none - - $ ../source-builder/sb-builder --prefix=/usr/local \ - --log=log_dtc devel/dtc-1.2.0 - RTEMS Source Builder, Package Builder v0.2.0 - config: devel/dtc-1.2.0 - package: dtc-1.2.0-x86_64-freebsd9.1-1 - download: http://www.jdl.com/software/dtc-v1.2.0.tgz -> sources/dtc-v1.2.0.tgz - building: dtc-1.2.0-x86_64-freebsd9.1-1 - $ ls tar - dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2 - -If you want to have the package installed automatically you need to create a -build set. A build set can build one or more packages from their configurations -at once to create a single package. For example the GNU tools is typically seen -as binutils, GCC and GDB and a build set will build each of these packages and -create a single build set tar file or install the tools on the host into the -prefix path. +To have a package installed automatically create a build set. A build set can +build one or more packages from their configurations at once to create a +single package. For example the GNU tools is typically seen as binutils, GCC +and GDB and a build set will build each of these packages and create a single +build set tar file or install the tools on the host into the prefix path. The DTC build set file is called ``dtc.bset`` and contains: @@ -799,8 +771,8 @@ To build this you can use something similar to: The build is for a FreeBSD host and the prefix is for user installed packages. In this example I cannot let the source builder perform the install -because I never run the RSB with root priviledges so a build set or bset tar -file is created. This can then be installed using root priviledges. +because I never run the RSB with root privileges so a build set or bset tar +file is created. This can then be installed using root privileges. The command also supplies the ``--trace`` option. The output in the log file will contain all the macros. @@ -971,10 +943,10 @@ expansions supported are: %prep ~~~~~ -The +%prep+ macro starts a block that continues until the next block macro. The +The `%prep` macro starts a block that continues until the next block macro. The *prep* or preparation block defines the setup of the package's source and is a mix of RTEMS Source Builder macros and shell scripting. The sequence is -typically +%source+ macros for source, +%patch+ macros to patch the source +typically `%source` macros for source, `%patch` macros to patch the source mixed with some shell commands to correct any source issues: .. code-block:: spec @@ -998,7 +970,7 @@ example: This URL is the primary location of the GNU GDB source code and the RTEMS Source Builder can download the file from this location and by inspecting the -file extension use ``bzip2`` decompression with +tar+. When the ``%prep`` +file extension use ``bzip2`` decompression with `tar`. When the ``%prep`` section is processed a check of the local ``source`` directory is made to see if the file has already been downloaded. If not found in the source cache directory the package is downloaded from the URL. You can append other base @@ -1039,9 +1011,9 @@ and set up with: Patching also occurs during the preparation stage. Patches are handled in a similar way to the source packages except you only ``add`` patches. Patches are -applied using the +setup+ command. The +setup+ command takes the default patch +applied using the `setup` command. The `setup` command takes the default patch option. You can provide options with each patch by adding them as arguments -before the patch URL. Patches with no options uses the +setup+ default. +before the patch URL. Patches with no options uses the `setup` default. .. code-block:: spec @@ -1600,12 +1572,10 @@ The ``%endif`` macro ends a conditional logic block. ~~~~~~~~~~~ The ``%bconf_with`` macro provides a way to test if the user has passed a -specific option on the command line with the ``--with-<label>`` option. This -option is only available with the ``sb-builder`` command. +specific option on the command line with the ``--with-<label>`` option. %bconf_without ~~~~~~~~~~~~~~ The ``%bconf_without`` macro provides a way to test if the user has passed a -specific option on the command line with the ``--without-<label>`` option. This -option is only available with the ``sb-builder`` command. +specific option on the command line with the ``--without-<label>`` option. diff --git a/user/rsb/cross-canadian-cross.rst b/user/rsb/cross-canadian-cross.rst index 8eceed3..7ccd6c3 100644 --- a/user/rsb/cross-canadian-cross.rst +++ b/user/rsb/cross-canadian-cross.rst @@ -37,7 +37,7 @@ To build the Curl package for RTEMS you enter the RSB command: 2. The ``--host`` command is the RTEMS architecture and version. - 3. The BSP is built and installed in the prefix. The arhcitecture must match + 3. The BSP is built and installed in the prefix. The architecture must match the ``--host`` architecture. .. note: Installing Into Different Directories diff --git a/user/rsb/index.rst b/user/rsb/index.rst index c307ebe..9bbc2e1 100644 --- a/user/rsb/index.rst +++ b/user/rsb/index.rst @@ -44,7 +44,7 @@ how to build that package from source and taught this tool. .. sidebar:: Setting up your Host - See :ref:`QuickStartHost` for details on setting up hosts. + See :ref:`QuickStartPreparation` for details on setting up hosts. The RTEMS Source Builder is known to work on: diff --git a/user/rsb/project-sets.rst b/user/rsb/project-sets.rst index 6eb8729..ce839c5 100644 --- a/user/rsb/project-sets.rst +++ b/user/rsb/project-sets.rst @@ -116,6 +116,15 @@ build sets: ``--with-objc`` Attempt to build a C++ compiler. +``--with-newlib-tls`` or ``--without-newlib-tls`` + Enable or disable the ``--enable-newlib-reent-thread-local`` Newlib + configuration option. This option is enabled by default on the aarch64, arm, + nios2, powerpc, riscv, and sparc targets. If this option is enabled, then + each member of the Newlib struct _reent is replaced by a dedicated + thread-local object. The thread-local objects are defined in translation + units which use the corresponding object so that only objects used by the + application are linked in. + The RSB provides build sets for some BSPs. These build sets will build: - Compiler, linker, debugger and RTEMS Tools. @@ -154,7 +163,7 @@ Patches are added to a component's name and in the ``%prep:`` section the patches can be set up, meaning they are applied to source. The patches are applied in the order they are added. If there is a dependency make sure you order the patches correctly when you add them. You can add any number of -patches and the RSB will handle them efficently. +patches and the RSB will handle them efficiently. Patches can have options. These are added before the patch URL. If no options are provided the patch's setup default options are used. diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst index 0d9fa81..8610650 100644 --- a/user/rsb/third-party-packages.rst +++ b/user/rsb/third-party-packages.rst @@ -133,7 +133,7 @@ A custom RTEMS patch to an executate's source code 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 with them to provide a way for the code to +community and see if you can work with 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 |