Update the README.md

1 files changed, 177 insertions, 19 deletions

diff --git a/README.md b/README.md
index 50d139a..690eb83 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,121 @@
-# RTEMS RSB Deployment Tests
+# RTEMS Deployment
 
-This project provides buildset configuration scripts to test the
-RSB. It provides:
+Deployment is the process a team or organization uses to provide
+configuration controlled tools and libraries that are used to build
+RTEMS applications. An RTEMS application can be viewed as a vertical
+software stack and deployment of RTEMS is a way to manage this
+complexity across a team.
 
-1. Regression tests for the RSB
+Deployment using this tool is based on building vertical stacks using
+the RSB. The project provides buildset configurations that contain
+the buildsets a team or organization needs to build configuration
+managed RTEMS applications.
 
-2. Examples of buildset configuration files for deployment
+A deployment of RTEMS can be based on a tar file or a package for a
+supported operating system, for example RPM. This repo is organized to
+integrate with Constant Integration (CI) workflows by providing a
+common interface to the management of specific configurations across
+different operating systems and deployment options.
 
-3. Waf build script as a template that can be used to create
-   deplayment workflows for teams and organisations.
+The output of this project normally forms part of a wider deployment
+model a team or organization uses. An example is containers on
+Linux. A container can contain the RPM built by this tool and the
+container can be used as a base for application development. For
+example the Gemini project uses GitLab CI workflows to automatically
+build Docker containers that have the RPM output from this tool
+installed.
 
+The deployment project provides:
+
+1. Buildset configurations for users, organization and commonly used
+   builds.
+
+2. Host operating system specific packaging if supported.
+
+3. Regression tests build configurations for the RSB.
+
+4. Examples of buildset configuration files for deployment.
+
+5. Waf based build scripts that are used to create custom deployment
+   workflows for teams and organizations.
+
+The repo is open and anyone can add a buildset configuration so please
+ask.
+
+The repo uses waf but you do not need to learn or understand waf to
+use it.
+
+## Deployable Packages
+
+Deployment is based on the system level requirements a project or
+organization has.
+
+### Single Package
+
+The single package deployment model has a top level buildset
+configuration file that builds a single output package containing all
+the packages a projects needs.
+
+An organization can have more than one single package, for example
+different versions of RTEMS. If more than one package is to be
+installed use the prefix to make sure there are not conflicts.
+
+A single package is easier to configuration manage because the output
+package contains all the pieces in the vertical software
+stack. Installing the output package installs all the vertical stack
+layers at the same time.
+
+### Multiple Packages
+
+Multiple packages means each part in a vertical stack is built
+separately and managed externally. Correct management requires extra
+tools or logic to make sure all the pieces are built vertically
+against the lower layers. Packaging and installation needs to account
+for the dependencies between the packages.
+
+Packaging systems provide support for multiple packages and can be
+used if supported. Multiple packages support a common install path
+because the common pieces need to be handled when packaging.
+
+Supporting multiple packages is more complex because each layer built
+needs to be packaged and installed so it can be used to build higher
+layers. Packaging needs to understand the common pieces in each
+package and those need to be packaged in common packages other
+packages depend on. This can become complex if the vertical stack is
+not fully defined.
+
+Multiple packages is not supported by this repo.
+
+## Host Support
+
+You can build a deployment package for the host packaging formats
+listed in the section. The package built is a deployment snapshot of
+the tools, libraries and headers files. The package should not be
+viewed the same as packages your host provides. There is no sharing of
+common files between packages this tool builds. You should consider
+the deployment as the super set of what your team or organization
+needs.
+
+A host packaging system provides you with the ability to query what is
+installed as well being able to verify what is installed against what
+was built.
+
+### RPM
+
+An RPM package can be built. This has been tested on Rocky
+distributions. The `configure` option provdes support to customise the
+RPM information to capture site specific details.
 
 ## RTEMS Source Builder
 
 The RTEMS Source Builder or RSB is a package that builds tools, board
 support packages (BSP) and third party libraries for RTEMS. The RSB is
-a tool that can be embedded into custom workflows to provide a base
-for deployment of tools, BSPs and libraries for users, teams and
-organisations.
-
-Deplopyment of tools, BSPs and libraries provides a stable common base
-for all uses in project. Stable and controlled delivery can be
-achieved when combined with a host's package management system.
+a tool that can be embedded into custom workflows to support
+deployment.
 
+The RSB provides a stable interface across releases of RTEMS. Using it
+to deploy RTEMS packages lets a deployment workflow work across
+different releases of RTEMS.
 
 ## Requirements
 
@@ -30,12 +123,11 @@ achieved when combined with a host's package management system.
   get a properly configured host that can build RTEMS tools.
 
 - A copy of the RSB in source. It can be a released tar file or a
-  cloned git repo.
-
+  cloned git repo. You provide the path to the source tree.
 
 ## Instructions
 
-The default configuration does not install the built output and to
+The default configuration does not install the built output. A  and to
 create a tar file. This is the RSB deployment mode. You can optionally
 configure a prefix if you wish to install the built output or use the
 build set tar file created by the builds.
@@ -55,7 +147,7 @@ To run a test build you must first run `configure`. Valid configure options are:
 1. The `--rsb` option provides the path to the RSB to use when
    running the build set commands.
 
-2. The optional `--prefx` option lets you set an install path for the
+2. The optional `--prefix` option lets you set an install path for the
    build if the install mode is `install`.
 
 3. The `--install` option enable the install mode. By default the
@@ -108,7 +200,7 @@ Show the RSB commands for the build sets:
 ### Prefix
 
 The configure `--prefix` option lets you specify a deployment prefix
-for your team or organisation:
+for your team or organization:
 
 ```
 ./waf configure --rsb=../rtems-source-builder --prefix=/opt/project
@@ -138,3 +230,69 @@ Each build set will install to the prefix path. Run the builds:
 ```
 
 Use the `--targets=` option to select a specific build.
+
+### RPM
+
+Generate RPM spec files using:
+
+```
+./waf rpmspec
+```
+
+Build the RPM using the RPM build tool:
+
+```
+rpmbuild -bb out/gemini/gemini-powerpc-net-legacy-bsps.spec
+```
+
+You can use `configure` to provide an RPM configuration INI file to
+override specific fields in the RPM spec file. The INI format is:
+
+```
+[DEFAULT]
+
+[<configuration>]
+<key> = <value>
+```
+
+where:
+
+`<configuration>` is a configuration being built
+
+`<key>` is a key. The keys are:
+
+- `rpm_name` : The name of the RPM
+
+- `rpm_version` : Site specific version of the RPM
+
+- `rpm_summary` : The RPM Summary
+
+- `rpm_description` : The RPM description
+
+An example for Gemini the INI called `gemini.ini` is:
+
+```
+[DEFAULT]
+
+[gemini/gemini-powerpc-legacy-bsps]
+rpm_name = rtems-gemini-powerpc-legacy
+rpm_version = %{rsb_version}.%{rsb_revision}
+rpm_revision = %{gemini_version}%{?dist}
+
+[gemini/gemini-powerpc-net-legacy-bsps]
+rpm_name = rtems-gemini-powerpc-net-legacy
+rpm_version = %{rsb_version}.%{rsb_revision}
+rpm_revision = %{gemini_version}%{?dist}
+```
+
+RPM configuration values can also be supplied on the `configure`
+command line as options. For example the following command line can be
+used with the `gemini.ini` configuration:
+
+```
+--rpm-config-value=gemini_version=123456
+```
+
+A site configuration INI file and the `configure` command line options
+provides a simple way to integrate site information needed to
+deployment configuration control and auditing into a CI process.