diff options
Diffstat (limited to 'user/rsb/configuration.rst')
| -rw-r--r-- | user/rsb/configuration.rst | 154 |
1 files changed, 62 insertions, 92 deletions
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. |