[PATCH 1/1] user/rsb/configuration.rst: Complete review on the text
Gedare Bloom
gedare at rtems.org
Fri Apr 17 04:45:37 UTC 2020
It would be great to get the DTC corrections also, to close the ticket.
On Wed, Apr 8, 2020 at 10:56 AM <clrrm at isep.ipp.pt> wrote:
>
> From: Cláudio Maia <clrrm at isep.ipp.pt>
>
> ---
> user/rsb/configuration.rst | 424 +++++++++++++++++++------------------
> 1 file changed, 215 insertions(+), 209 deletions(-)
>
> diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst
> index 4b21dee..561ae60 100644
> --- a/user/rsb/configuration.rst
> +++ b/user/rsb/configuration.rst
> @@ -8,23 +8,25 @@
> Configuration
> -------------
>
> -The RTEMS Source Builder has two types of configuration data:
> +The RTEMS Source Builder (RSB) has two types of configuration data:
>
> -- Build Sets
> +- Build Sets (see :ref:`bsets` for more info)
>
> - Package Build Configurations
>
> -By default these files can be located in two separate directories and
> -searched. The first directory is ``config`` in your current working directory
> -(``_topdir``) and the second is ``config`` located in the base directory of the
> -RTEMS Source Builder command you run (``_sbdir``). The RTEMS directory
> -``rtems``` located at the top of the RTEMS Source Builder source code is an
> -example of a specific build configuration directory. You can create custom or
> -private build configurations and if you run the RTEMS Source Builder command
> -from that directory your configurations will be used.
> +By default this type of files can be located and searched in two separate
Use "this type of file" (or "these types of files")
> +directories. The first directory is the ``config`` directory existing inside
> +your current working directory (``_topdir``) and the second is the ``config``
> +directory located inside the base directory of the RTEMS Source Builder command
> +you run (``_sbdir``).
>
> -The configuration search path is a macro variable and is reference as
> -``%{_configdir}``. It's default is defined as:
> +The ``rtems`` directory located at the top of the RTEMS Source Builder source
> +code is an example of a specific build configuration directory. You can create
> +custom or private build configurations and if you run the RTEMS Source Builder
> +command from that directory your configurations will be used.
> +
> +The configuration search path is a macro variable and is referenced as
> +``%{_configdir}``. Its default is defined as:
>
> .. code-block:: spec
>
> @@ -39,8 +41,8 @@ The configuration search path is a macro variable and is reference as
> constraint and the definition.
>
> 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
> +configuration files have the file extension ``.cfg``. The ``sb-set-builder``
> +command will search for *build sets* and the ``sb-builder`` command works with
> package build configuration files.
>
> Both types of configuration files use the ``#`` character as a comment
> @@ -50,13 +52,13 @@ block comment.
> Source and Patches
> ^^^^^^^^^^^^^^^^^^
>
> -The RTEMS Source Builder provides a flexible way to manage source. Source and
> -patches are declare in configurations file using the ``source`` and ``patch``
> -directives. These are a single line containing a Universal Resource Location or
> -URL and can contain macros and shell expansions. The :ref:`prep` section
> -details the *source* and *patch* directives
> +The RTEMS Source Builder provides a flexible way to manage the files source.
Replace "the files source." with "source and patch files."
> +Source and patches are declared in configuration files using the ``source`` and
> +``patch`` directives. These are defined in a single line containing a Uniform
> +Resource Locator (URL) and can contain macros and shell expansions. The
> +:ref:`prep` section details the ``source`` and ``patch`` directives.
>
> -The URL can reference remote and local source and patch resources. The
> +The URL can reference remote and local sources and patch resources. The
> following schemes are provided:
>
> ``http``:
> @@ -75,21 +77,22 @@ following schemes are provided:
> Remote access to a patch management repository.
>
> ``file``:
> - Local access to an existing source directory.
> + Local access to an existing source directory.
>
> HTTP, HTTPS, and FTP
> ~~~~~~~~~~~~~~~~~~~~
>
> -Remote access to TAR or ZIP files is provided using HTTP, HTTPS and FTP
> +Remote access to TAR or ZIP files is provided using HTTP, HTTPS or FTP
> protocols. The full URL provided is used to access the remote file including
> any query components. The URL is parsed to extract the file component and the
> -local source directory is checked for that file. If the file is located locally
> -the remote file is not downloaded. Currently no other checks are made. If a
> -download fails you need to manually remove the file from the source directory
> +local source directory is checked for that file. If the file exists locally
> +then the remote file is not downloaded. Currently, no other checks are made. If
> +a download fails you need to manually remove the file from the source directory
I'm not sure this is correct, although I don't know for certain the
behavior after a failed download.
> and start the build process again.
>
> The URL can contain macros. These are expanded before issuing the request to
> -download the file. The standard GNU GCC compiler source URL is:
> +download the file. As an example of the ``source`` directive, the standard GNU
> +GCC compiler source URL is defined as follows:
>
> .. code-block:: spec
>
> @@ -97,11 +100,28 @@ download the file. The standard GNU GCC compiler source URL is:
>
> .. topic:: Items:
>
> - 1. The ``%source`` command's ``set`` command sets the source. The
> - first is set and following sets are ignored.
> + 1. The ``%source`` command's ``set`` command sets the source. The first is
> + set and following sets are ignored.
>
> 2. The source package is part of the ``gcc`` group.
>
> +The ``%source`` directive typically supports a single source file tar or zip
replace "file tar or zip file" with "tar or zip file" or "tar file or zip file"
> +file. The ``set`` command is used to set the URL for a specific source group.
> +The first set command encountered is registered and any further set commands
> +are ignored. This allows you to define a base standard source location and
> +override it in build and architecture specific files. You can also add extra
> +source files to a group. This is typically done when a collection of source
> +is broken down into a number of smaller files and you require the full package.
> +
> +If the source URL references a GitHub API server https://api.github.com/, a
> +tarball of the specified version is downloaded. For example, the URL for the
> +STLINK project on GitHub and version is:
> +
> +.. code-block:: spec
> +
> + %define stlink_version 3494c11
> + %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
> +
> The type of compression is automatically detected from the file extension. The
> supported compression formats are:
>
> @@ -119,33 +139,14 @@ supported compression formats are:
>
> 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
> -the decompression tool and all other files must be in the tar file format.
> -
> -The ``%source`` directive typically supports a single source file tar or zip
> -file. The ``set`` command is used to set the URL for a specific source
> -group. The first set command encountered is registered and any further set
> -commands are ignored. This allows you to define a base standard source location
> -and override it in build and architecture specific files. You can also add
> -extra source files to a group. This is typically done when a collection of
> -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:
> -
> -.. code-block:: spec
> -
> - %define stlink_version 3494c11
> - %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz
> +the decompression tool. All other files must be in the tar file format.
>
> GIT
> ~~~
>
> A GIT repository can be cloned and used as source. The GIT repository resides
> in the 'source' directory under the ``git`` directory. You can edit, update and
> -use the repository as you normally do and the results will used to build the
> +use the repository as you normally do and the results will be used to build the
> tools. This allows you to prepare and test patches in the build environment the
> tools are built in. The GIT URL only supports the GIT protocol. You can control
> the repository via the URL by appending options and arguments to the GIT
> @@ -188,7 +189,7 @@ 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
> +because of the modules support. This can affect 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
> @@ -215,34 +216,35 @@ The following is an example of checking out from a CVS repository:
> Macros and Defaults
> ^^^^^^^^^^^^^^^^^^^
>
> -The RTEMS Source Builder uses tables of *macros* read in when the tool
> -runs. The initial global set of macros is called the *defaults*. These values
> -are read from a file called ``defaults.mc`` and modified to suite your
> -host. This host specific adaption lets the Source Builder handle differences in
> -the build hosts.
> +The RTEMS Source Builder uses tables of *macros* read in when the tool runs. The
> +initial global set of macros is called the *defaults*. These values are read
> +from a file called ``defaults.mc`` and modified to suite your host. This host
s/suite/suit
> +specific adaption lets the Source Builder handle differences in the build hosts.
s/adaption/adaptation
>
> -Build set and configuration files can define new values updating and extending
> -the global macro table. For example builds are given a release number. This is
> +Build set and configuration files can define new values, updating and extending
This is a comma splice. I guess you could make it "values, which
updates and extends"
> +the global macro table. For example, builds are given a release number. This is
> typically a single number at the end of the package name. For example:
>
> .. code-block:: spec
>
> %define release 1
>
> -Once defined if can be accessed in a build set or package configuration file
> +Once defined it can be accessed in a build set or package configuration file
> with:
>
> .. code-block:: spec
>
> %{release}
>
> -The ``sb-defaults`` command lists the defaults for your host. I will not include
> -the output of this command because of its size:
> +The ``sb-defaults`` command lists the defaults for your host.
>
> .. code-block:: none
>
> $ ../source-builder/sb-defaults
>
> +Due to the amount of output produced by this command, its output is omitted
> +from this documentation page.
> +
> A nested build set is given a separate copy of the global macro maps. Changes
> in one change set are not seen in other build sets. That same happens with
> configuration files unless inline includes are used. Inline includes are seen
> @@ -280,7 +282,7 @@ where ``Name`` is a case insensitive macro name, the ``Type`` field is:
> the ``Attribute`` field is:
>
> ``none``:
> - Nothing, ignore
> + Nothing, ignore.
>
> ``required``:
> The host check must find the executable or path.
> @@ -298,8 +300,10 @@ the ``Attribute`` field is:
> map's macro is not visible but still exists.
>
> and the ``String`` field is a single or tripled multiline quoted string. The
> -'String' can contain references to other macros. Macro that loop are not
> -currently detected and will cause the tool to lock up.
> +'String' can contain references to other macros.
> +
> +**IMPORTANT: Macros that loop are not currently detected and will cause the
> +tool to lock up**.
>
> Maps are declared anywhere in the map using the map directive:
>
> @@ -316,18 +320,18 @@ Maps are declared anywhere in the map using the map directive:
>
> 1. The map is set to ``my-special-map``.
>
> -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
> +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:
>
> .. code-block:: spec
>
> %select my-special-map
>
> -Selecting a map means all requests for a macro first check the selected map and
> -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.
> +Selecting a map means all requests for a macro first check the selected map,
> +and if present, the requested value is returned, otherwise the ``global`` map
> +is used. Any new macros or changes only update the ``global`` map. This may
> +change in future releases so please make sure you use the ``override`` attribute.
>
> The macro files specified on the command line are looked for in the
> ``_configdir`` paths. See the definition of ``_configdir`` in
> @@ -336,7 +340,7 @@ The macro files specified on the command line are looked for in the
>
> Macro map files can include other macro map files using the ``%include``
> directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and
> -RTEMS from version control heads is:
> +RTEMS from version control head is:
heads is correct (albeit awkward). It refers to the heads of the five
listed projects.
>
> .. code-block:: spec
>
> @@ -350,7 +354,8 @@ RTEMS from version control heads is:
>
> .. topic:: Items:
>
> - 1. The file is ``config/snapshots/binutils-gcc-newlib-gdb-head.mc``.
> + 1. The code above can be found in the file
> + ``config/snapshots/binutils-gcc-newlib-gdb-head.mc``.
>
> The macro map defaults to ``global`` at the start of each included file and the
> map setting of the macro file including the other macro files does not change.
> @@ -359,12 +364,11 @@ Personal Macros
> ~~~~~~~~~~~~~~~
>
> When the tools start to run they will load personal macros. Personal macros are
> -in the standard format for macros in a file. There are two places personal
> -macros can be configured. The first is the environment variable
> -``RSB_MACROS``. If present the macros from the file the environment variable
> -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.
> +in the standard format for macros in a file. There are two places where personal
> +macros can be configured. The first is the environment variable ``RSB_MACROS``.
> +If present, the macros from the file the environment variable 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 to work.
>
> Configuration Reports
> ^^^^^^^^^^^^^^^^^^^^^
> @@ -384,8 +388,8 @@ Report Mailing
> ~~~~~~~~~~~~~~
>
> 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:
> +for logging and monitoring purposes. Mailing requires a number of parameters to
> +function properly. These are:
>
> - To mail address
>
> @@ -410,10 +414,10 @@ The ``from`` mail address is taken from:
>
> - Command line
>
> -If you have configured an email and name in git it will be used used. If you do
> -not a check is made for a ``.mailrc`` file. The environment variable ``MAILRC``
> -is used if present else your home directory is check. If found the file is
> -scanned for the ``from`` setting:
> +If you have configured an email and name in git these will be used. Otherwise,
> +a check is made for a ``.mailrc`` file. The environment variable ``MAILRC``
> +is used if present, otherwise the home directory is checked. If the file is
> +found, then it is scanned for the ``from`` setting:
>
> .. code-block:: shell
>
> @@ -426,10 +430,12 @@ The SMTP host is taken from the macro ``%{_mail_smtp_host}`` and the
> default is ``localhost``. You can override the default with a personal
> or user macro file or via the command line option ``--smtp-host``.
>
> +.. _bsets:
> +
> Build Set Files
> ^^^^^^^^^^^^^^^
>
> -Build set files lets you list the packages in the build set you are defining
> +Build set files let you list the packages in the build set you are defining
> and have a file extension of ``.bset``. Build sets can define macro variables,
> inline include other files and reference other build set or package
> configuration files.
> @@ -459,7 +465,7 @@ on a single line:
> tools/rtems-binutils-2.22-1
>
> The ``_configdir`` path is scanned for ``tools/rtems-binutils-2.22-1.bset`` or
> -``tools/rtems-binutils-2.22-1.cfg``. Build set files take precedent over
> +``tools/rtems-binutils-2.22-1.cfg``. Build set files take precedence over
> package configuration files. If ``tools/rtems-binutils-2.22-1`` is a build set
> a new instance of the build set processor is created and if the file is a
> package configuration the package is built with the package builder. This all
> @@ -468,7 +474,7 @@ happens once the build set file has finished being scanned.
> Configuration Control
> ^^^^^^^^^^^^^^^^^^^^^
>
> -The RTEMS Souce Builder is designed to fit within most verification and
> +The RTEMS Source Builder is designed to fit within most verification and
> validation processes. All of the RTEMS Source Builder is source code. The
> Python code is source and comes with a commercial friendly license. All
> configuration data is text and can be read or parsed with standard text based
> @@ -478,9 +484,9 @@ 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``
> +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
> +Newlib version is 2.0.0, plus any RTEMS specific patches that relate to this
> version. The configuration defines the version numbers of the various parts
> that make up this package:
>
> @@ -501,7 +507,7 @@ The package build options, if there are any are also defined:
> %define with_iconv 1
>
> The generic configuration may provide defaults in case options are not
> -specified. The patches this specific version of the package requires can be
> +specified. The patches required by this specific version of the package can be
> included:
>
> .. code-block:: spec
> @@ -519,9 +525,9 @@ Newlib. It is not specific to RTEMS. A bare no operating system tool set can be
> built with this file.
>
> The ``-1`` part of the file names is a revision. The GCC 4.7 script maybe
> -revised to fix a problem and if this fix effects an existing script the file is
> +revised to fix a problem and if this fix affects an existing script the file is
> copied and given a ``-2`` revision number. Any dependent scripts referencing
> -the earlier revision number will not be effected by the change. This locks down
> +the earlier revision number will not be affected by the change. This locks down
> a specific configuration over time.
>
> Personal Configurations
> @@ -533,7 +539,7 @@ source. There is also the ``bare`` set of configurations. You can create your
> own configurations away from the RSB source tree yet use all that the RSB
> provides.
>
> -To create a private configuration change to a suitable directory:
> +To create a private configuration change to a suitable directory, for instance:
>
> .. code-block:: none
>
> @@ -543,8 +549,10 @@ To create a private configuration change to a suitable directory:
> $ mkdir config
>
> and create a ``config`` directory. Here you can add a new configuration or
> -build set file. The section 'Adding New Configurations' details how to add a
> -new confguration.
> +build set file. The section :ref:`new-configs` details how to add a
> +new configuration.
> +
> +.. _new-configs:
>
> New Configurations
> ^^^^^^^^^^^^^^^^^^
> @@ -564,9 +572,9 @@ Layering by Including
>
> Configurations can be layered using the ``%include`` directive. The user
> invokes the outer layers which include inner layers until all the required
> -configuration is present and the package can be built. The outer layers can
> -provide high level details such as the version and the release and the inner
> -layers provide generic configuration details that do not change from one
> +configurations are present and the package can be built. The outer layers can
> +provide high level details such as the version and the release, and the inner
> +layers can provide generic configuration details that do not change from one
> release to another. Macro variables are used to provide the specific
> configuration details.
>
> @@ -575,15 +583,15 @@ Configuration File Numbering
>
> Configuration files have a number at the end. This is a release number for that
> configuration and it gives us the ability to track a specific configuration for
> -a specific version. For example lets say the developers of the DTC package
> +a specific version. For example, let us assume the developers of the DTC package
> change the build system from a single makefile to autoconf and automake between
> version 1.3.0 and version 1.4.0. The configuration file used to build the
> -package would change have to change. If we did not number the configuration
> -files the ability to build 1.1.0, 1.2.0 or 1.3.0 would be lost if we update a
> -common configuration file to build an autoconf and automake version. For
> -version 1.2.0 the same build script can be used so we can share the same
> -configuration file between version 1.1.0 and version 1.2.0. An update to any
> -previous release lets us still build the package.
> +package would have to change. If we did not number the configuration files the
> +ability to build 1.1.0, 1.2.0 or 1.3.0 would be lost if we update a common
> +configuration file to build an autoconf and automake version. For version 1.2.0
> +the same build script can be used so we can share the same configuration file
> +between version 1.1.0 and version 1.2.0. An update to any previous release lets
> +us still build the package.
>
> Common Configuration Scripts
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -592,9 +600,9 @@ Common configuration scripts that are independent of version, platform and
> architecture are useful to everyone. These live in the Source Builder's
> configuration directory. Currently there are scripts to build binutils, expat,
> DTC, GCC, GDB and libusb. These files contain the recipes to build these
> -package without the specific details of the versions or patches being
> -built. They expect to be wrapped by a configuration file that ties the package
> -to a specific version and optionally specific patches.
> +packages without the specific details of the versions or patches being built.
> +They expect to be wrapped by a configuration file that ties the package to a
> +specific version and optionally specific patches.
>
> DTC Example
> ~~~~~~~~~~~
> @@ -607,23 +615,23 @@ this is a configuration file. The first ``1`` says this is for the major
> release 1 of the package and the last ``1`` is the build configuration version.
>
> The file starts with some comments that detail the configuration. If there is
> -anything unusual about the configuration it is a good idea to add something in
> -the comments here. The comments are followed by a check for the release. In
> -this case if a release is not provided a default of 1 is used:
> +anything unusual about the configuration it is a good idea to add a comment.
> +The comments are followed by a check for the release. In this case if a release
> +is not provided a default of 1 is used:
>
> .. code-block:: spec
>
> #
> # DTC 1.x.x Version 1.
> #
> - # This configuration file configure's, make's and install's DTC.
> + # This configuration file configures, makes and installs the DTC.
> #
>
> %if %{release} == %{nil}
> %define release 1
> %endif
>
> -The next section defines some information about the package. It does not effect
> +The next section defines some information about the package. It does not affect
> the build and is used to annotate the reports. It is recommended this
> information is kept updated and accurate:
>
> @@ -638,7 +646,7 @@ information is kept updated and accurate:
>
> 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
> +knows this is a GZip'ped tar file. If more than one package is needed, add
> them increasing the index. The ``gcc-4.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:
> @@ -650,7 +658,7 @@ source packages based on the outer configuration options:
> #
> %source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz
>
> -The remainder of the script is broken in to the various phases of a build. They
> +The remainder of the script is broken into the various phases of a build. They
> are:
>
> . Preparation
> @@ -660,17 +668,17 @@ are:
>
> Preparation is the unpacking of the source, applying any patches as well as any
> package specific set ups. This part of the script is a standard Unix shell
> -script. Be careful with the use of ``%`` and ``$``. The RSB uses ``%`` while
> -the shell scripts use ``$``.
> -
> -A standard pattern you will observe is the saving of the build's top
> -directory. This is used instead of changing into a subdirectory and then
> -changing to the parent when finished. Some hosts will change in a subdirectory
> -that is a link however changing to the parent does not change back to the
> -parent of the link rather it changes to the parent of the target of the link
> -and that is something the RSB nor you can track easily. The RSB configuration
> -script's are a collection of various subtle issues so please ask if you are
> -unsure why something is being done a particular way.
> +script. **Be careful with the use of ``%`` and ``$``. The RSB uses ``%`` while
> +the shell scripts use ``$``.**
> +
> +A standard pattern you will observe is the saving of the build's top directory.
> +This is used instead of changing into a subdirectory and then changing to the
> +parent when finished. Some hosts will change in a subdirectory that is a link
> +however changing to the parent does not change back to the parent of the link,
> +rather it changes to the parent of the target of the link and that is something
> +the RSB nor you can track easily. The RSB configuration scripts are a
> +collection of various subtle issues so please ask if you are unsure why
> +something is being done a particular way.
>
> The preparation phase will often include source and patch setup commands. Outer
> layers can set the source package and add patches as needed while being able to
> @@ -694,12 +702,12 @@ The configuration file ``gcc-common-1.cfg`` is a complex example of source
> preparation. It contains a number of source packages and patches and it
> combines these into a single source tree for building. It uses links to map
> source into the GCC source tree so GCC can be built using the *single source
> -tree* method. It also shows how to fetch source code from version
> -control. Newlib is taken directly from its CVS repository.
> +tree* method. It also shows how to fetch source code from version control.
> +Newlib is taken directly from its CVS repository.
> Next is the building phase and for the DTC example this is simply a matter of
> running ``make``. Note the use of the RSB macros for commands. In the case of
> -``%{__make}`` it maps to the correct make for your host. In the case of BSD
> +``%{__make}`` it maps to the correct make on your host. In the case of BSD
> systems we need to use the BSD make and not the GNU make.
>
> If your package requires a configuration stage you need to run this before the
> @@ -718,33 +726,33 @@ make stage. Again the GCC common configuration file provides a detailed example:
>
> cd ${build_top}
>
> -You can invoke make with the macro ``%{?_smp_flags}`` as a command line
> +You can invoke ``make`` with the macro ``%{?_smp_flags}`` as a command line
> argument. This macro is controlled by the ``--jobs`` command line option and
> the host CPU detection support in the RSB. If you are on a multicore host you
> -can increase the build speed using this macro. It also lets you disabled
> +can increase the build speed using this macro. It also lets you disable
> building on multicores to aid debugging when testing.
>
> Next is the install phase. This phase is a little more complex because you may
> -be building a tar file and the end result of the build is never actually
> -installed into the prefix on the build host and you may not even have
> +be building a tar file and the end result of the build may never actually be
> +installed into the prefix on the build host or 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
> -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
> -shell variable called ``SB_BUILD_ROOT`` you can use. In a build set where you
> -are building a number of packages you can collect all the built packages in a
> -single tree that is captured in the tar file.
> +which is typically supplied via the command to the RSB, otherwise 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 variables and you can
> +typically specify it on the command line to make when invoking the install
``make``
> +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 shell variable called
> +``SB_BUILD_ROOT`` you can use. In a build set where you are building a number
> +of packages you can collect all the built packages in a single tree that is
> +captured in the tar file. The code below shows the use of these variables.
>
> Also note the use of the macro ``%{__rmdir}``. The use of these macros allow
> the RSB to vary specific commands based on the host. This can help on hosts
> -like Windows where bugs can effect the standard commands such as ``rm``. There
> -are many many macros to help you. You can find these listed in the
> -``defaults.mc`` file and in the trace output. If you are new to creating and
> -editing configurations learning these can take a little time:
> +like Windows where bugs can affect standard commands such as ``rm``. There
> +are many macros to help you. You can find these listed in the ``defaults.mc``
> +file and in the trace output. If you are new to creating and editing
> +configurations learning these can take time:
>
> .. code-block:: spec
>
> @@ -759,8 +767,8 @@ editing configurations learning these can take a little time:
> cd ${build_top}
>
> 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.
> +``--no-clean`` has not been provided on the command line. The RSB does the
> +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
> @@ -780,10 +788,10 @@ in the ``tar`` directory:
>
> 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.
> +at once to create a single package. For example, the GNU tools package 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:
>
> @@ -814,31 +822,29 @@ To build this you can use something similar to:
> $ ls tar
> dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2 x86_64-freebsd9.1-dtc-set.tar.bz2
>
> -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 privileges so a build set or bset tar
> -file is created. This can then be installed using root privileges.
> +The build is for a FreeBSD host and the prefix is for user installed packages.
> +In this example, the source builder creates a build set or bset tar file which
> +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.
> +The command also supplies the ``--trace`` option which outputs in the log file
> +all the macros.
>
> Debugging
> ~~~~~~~~~
>
> -New configuration files require debugging. There are two types of
> -debugging. The first is debugging RSB script bugs. The ``--dry-run`` option is
> -used here. Suppling this option will result in most of the RSB processing to be
> -performed and suitable output placed in the log file. This with the ``--trace``
> -option should help you resolve any issues.
> -
> -The second type of bug to fix are related to the execution of one of
> -phases. These are usually a mix of shell script bugs or package set up or
> -configuration bugs. Here you can use any normal shell script type debug
> -technique such as ``set +x`` to output the commands or ``echo``
> -statements. Debugging package related issues may require you start a build with
> -the RSB and supply ``--no-clean`` option and then locate the build directories
> -and change directory into them and manually run commands until to figure what
> -the package requires.
> +New configuration files require debugging. There are two types of debugging.
> +The first is debugging RSB script bugs. The ``--dry-run`` option is used here.
> +Supplying this option will result in most of the RSB processing to be performed
> +and suitable output placed in the log file. This option in conjunction with the
> +``--trace`` option should help you resolve any issues.
> +
> +The second type of bugs to fix are related to the execution of one of phases.
> +These are usually a mix of shell script bugs or package set up or configuration
> +bugs. Here you can use any normal shell script type debug technique such as
> +``set +x`` to output the commands or ``echo`` statements. Debugging package
> +related issues may require you start a build with the RSB and supply
> +``--no-clean`` option and then locate the build directories and change directory
> +into them and manually run commands until to figure what the package requires.
delete until
>
> Scripting
> ^^^^^^^^^
> @@ -924,7 +930,7 @@ The script language is implemented in terms of macros. The built-in list is:
> Test the architecture against the following string.
>
> ``%ifnarch``:
> - Inverted test of the architecture
> + Inverted test of the architecture.
>
> ``%ifos``:
> Test the host operating system.
> @@ -932,7 +938,7 @@ The script language is implemented in terms of macros. The built-in list is:
> ``%else``:
> Start the *else* conditional logic block.
>
> -``%endfi``:
> +``%endif``:
> End the conditional logic block.
>
> ``%bconf_with``:
> @@ -946,12 +952,12 @@ The script language is implemented in terms of macros. The built-in list is:
> Expanding
> ~~~~~~~~~
>
> -A macro can be ``%{string}`` or the equivalent of ``%string``. The following macro
> -expansions supported are:
> +A macro can be ``%{string}`` or the equivalent of ``%string``. The macro
> +expansions supported are the following:
>
> ``%{string}``:
> Expand the 'string' replacing the entire macro text with the text in the
> - table for the entry 'string . For example if 'var' is 'foo' then ``${var}``
> + table for the entry 'string'. For example if 'var' is 'foo' then ``${var}``
> would become ``foo``.
>
> ``%{expand: string}``:
> @@ -962,12 +968,12 @@ expansions supported are:
>
> ``%{with string}``:
> Expand the macro to ``1`` if the macro ``with_string`` is defined else expand
> - to ``0``. Macros with the name ``with_string`` can be define with command
> + to ``0``. Macros with the name ``with_string`` can be defined with command
> line arguments to the RTEMS Source Builder commands.
>
> ``%{defined string}``:
> Expand the macro to ``1`` if a macro of name ``string`` is defined else
> - expand to '0'.
> + expand to ``0``.
>
> ``%{?string: expression}``:
> Expand the macro to ``expression`` if a macro of name ``string`` is defined
> @@ -975,7 +981,7 @@ expansions supported are:
>
> ``%{!?string: expression}``:
> Expand the macro to ``expression`` if a macro of name ``string`` is not
> - defined. If the macro is define expand to ``%{nil}``.
> + defined. If the macro is defined expand to ``%{nil}``.
>
> ``%(expression)``:
> Expand the macro to the result of running the ``expression`` in a host
> @@ -1006,7 +1012,7 @@ mixed with some shell commands to correct any source issues:
>
> 3. The version of the source is the macro ``%{version}``.
>
> -The source set up are declared with the source ``set`` and ``add`` commands. For
> +The source set up is declared with the source ``set`` and ``add`` commands. For
> example:
>
> .. code-block:: spec
> @@ -1058,7 +1064,7 @@ 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
> 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 use the `setup` default.
>
> .. code-block:: spec
>
> @@ -1086,10 +1092,10 @@ To apply these patches:
>
> The ``%build`` macro starts a block that continues until the next block
> macro. The build block is a series of shell commands that execute to build the
> -package. It assumes all source code has been unpacked, patch and adjusted so
> +package. It assumes all source code has been unpacked, patched and adjusted so
> the build will succeed.
>
> -The following is an example take from the GitHub STLink project. The STLink is
> +The following is an example taken from the GitHub STLink project. The STLink is
> a JTAG debugging device for the ST ARM family of processors:
>
> .. code-block:: spec
> @@ -1197,13 +1203,13 @@ Looking at the same example as in :ref:`build`:
>
> The ``%clean`` macro starts a block that continues until the next block
> macro. The clean block is a series of shell commands that execute to clean up
> -after a package has been built and install. This macro is currenly not been
> +after a package has been built and install. This macro is currently not been
> used because the RTEMS Source Builder automatically cleans up.
>
> %include
> ~~~~~~~~
>
> -The ``%include`` macro inline includes the specific file. The ``__confdir``
> +The ``%include`` macro "inline includes" the specific file. The ``__confdir``
> path is searched. Any relative path component of the include file is appended
> to each part of the ``__configdir``. Adding an extension is optional as files
> with ``.bset`` and ``.cfg`` are automatically searched for.
> @@ -1214,7 +1220,7 @@ configuration file that contains the ``%include`` macro.
>
> Including files allow a kind of configuration file reuse. The outer
> configuration files provide specific information such as package version
> -numbers and patches and then include a generic configuration script which
> +numbers and patches, and then include a generic configuration script which
> builds the package:
>
> .. code-block:: spec
> @@ -1234,7 +1240,7 @@ with Newlib configuration the name is typically::
> ~~~~~~~~
>
> The ``%summary`` is a brief description of the package. It is useful when
> -reporting. This information is not capture in the package anywhere. For the GCC
> +reporting. This information is not captured in the package anywhere. For the GCC
> with Newlib configuration the summary is typically:
>
> .. code-block:: spec
> @@ -1245,7 +1251,7 @@ with Newlib configuration the summary is typically:
> ~~~~~~~~
>
> The ``%release`` is a packaging number that allows revisions of a package to
> -happen where no package versions change. This value typically increases when
> +happen when no package versions change. This value typically increases when
> the configuration building the package changes:
>
> .. code-block:: spec
> @@ -1255,11 +1261,11 @@ the configuration building the package changes:
> %version
> ~~~~~~~~
>
> -The ``%version`` macro sets the version the package. If the package is a single
> -component it tracks that component's version number. For example in the
> +The ``%version`` macro sets the version of the package. If the package is a
> +single component it tracks that component's version number. For example in the
> ``libusb`` configuration the ``%version`` is the same as ``%libusb_version``,
> -however in a GCC with Newlib configuration there is no single version
> -number. In this case the GCC version is used:
> +however in a GCC with Newlib configuration there is no single version number.
> +In this case the GCC version is used:
>
> .. code-block:: spec
>
> @@ -1270,19 +1276,19 @@ number. In this case the GCC version is used:
>
> The ``%buildarch`` macro is set to the architecture the package contains. This
> is currently not used in the RTEMS Source Builder and may go away. This macro
> -is more important in a real packaging system where the package could end up on
> +is more important in a real packaging system where the package could end up in
> the wrong architecture.
>
> %source
> ~~~~~~~
>
> -The ``%source`` macro has 3 commands that controls what it does. You can
> -``set`` the source files, ``add`` source files to a source group, and ``setup``
> -the source file group getting it ready to be used.
> +The ``%source`` macro has 3 commands that control what it does. You can ``set``
> +the source files, ``add`` source files to a source group, and ``setup`` the
> +source file group getting it ready to be used.
>
> Source files are source code files in tar or zip files that are unpacked,
> copied or symbolically linked into the package's build tree. Building a package
> -requires one or more dependent packages. These are typically the packages
> +requires one or more dependent packages. These are typically the packages'
> source code plus dependent libraries or modules. You can create any number of
> these source groups and set each of them up with a separate source group for
> each needed library or module. Each source group normally has a single tar, zip
> @@ -1336,22 +1342,22 @@ Accepted options are:
>
> ``-T``:
> The ``-T`` option is used to direct %setup to not perform the default
> - unpacking of the source archive specified by the first ``Source:`` macro. It
> + unpacking of the source archive specified by the first ``source:`` macro. It
> is used with the ``-a`` or ``-b`` options.
>
> ``-b <n>``:
> The ``-b`` option is used to direct ``%setup`` to unpack the source archive
> - specified on the nth ``Source:`` macro line before changing directory into
> + specified on the nth ``source:`` macro line before changing directory into
> the build directory.
>
> %patch
> ~~~~~~
>
> -The ``%patch`` macro has the same 3 command as the ``%source`` command however
> +The ``%patch`` macro has the same 3 commands as the ``%source`` command however
> the ``set`` commands is not really that useful with the ``%patch`` command. You
> add patches with the ``add`` command and ``setup`` applies the patches. Patch
> options can be added to each patch by placing them before the patch URL. If no
> -patch option is provided the default options passed to the ``setup`` command
> +patch option is provided, the default options passed to the ``setup`` command
> are used. An option starts with a ``-``. The ``setup`` command must reside
> inside the ``%prep`` section.
>
> @@ -1371,7 +1377,7 @@ To add a patch:
>
> 1. The patch group is ``gcc``.
>
> - 2. Option ``-p0`` is this specific to this patch.
> + 2. Option ``-p0`` is specific to this patch.
>
> Placing ``%patch setup`` in the ``%prep`` section will apply the groups
> patches::
> @@ -1395,7 +1401,7 @@ generates a warning.
> A file to be checksummed must be unique in the source and patch directories.
> The basename of the file is used as the key for the hash.
>
> -The hash algorthim can be ``md5``, ``sha1``, ``sha224``, ``sha256``,
> +The hash algorithm can be ``md5``, ``sha1``, ``sha224``, ``sha256``,
> ``sha384``, and ``sha512`` and we typically use ``md5``.
>
> To add a hash:
> @@ -1408,15 +1414,15 @@ To add a hash:
>
> 1. The type of checksum.
>
> - 2. The file to checksum. It can contain macros that are expanded for you.
> + 2. The file to checksum. It can contain macros that are expanded.
>
> 3. The MD5 hash for the Net-SNMP file ``net-snmp-5.7.2.1.tar.gz``.
>
> Do not include a path with the file name. Only the basename is required. Files
> -can be searched for from a number of places and having a path conponent would
> +can be searched for from a number of places and having a path component would
> create confusion. This does mean files with hashes must be unique.
>
> -Downloading off repositories such as git and cvs cannot be checksummed. It is
> +Downloading off repositories such as git and CVS cannot be checksummed. It is
I think "off" should be "of", or maybe "from" or "off of"
> assumed those protocols and tools manage the state of the files.
>
> %echo
> @@ -1561,7 +1567,7 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
> * - **>**
> - The left hand side is numerically greater than the right hand side.
>
> - * - **>**
> + * - **>=**
> - The left hand side is numerically greater than or equal to the
> right hand side.
>
> @@ -1608,7 +1614,7 @@ packages.
>
> The ``%else`` macro starts the conditional *else* block.
>
> -%endfi
> +%endif
> ~~~~~~
>
> The ``%endif`` macro ends a conditional logic block.
> --
> 2.17.1
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list