path: root/README.md

# RTEMS Deployment

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.

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.

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.

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 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

- Please follow the RTEMS User Guide's Quick Start and Host section to
  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. You provide the path to the source tree.

## Instructions

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.

### Help

The `waf` build system provides help:

```
./waf --help
```

**Configuration**:

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 `--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
   builds do not install any output. Use this option with the `--prefix` option
   if you want to use the tools directly.

3. The `--rtems-version` options lets you specify the version of the
   RSB to test.

**Build**:

1. The `list` command will list the build targets.

2. The build `--targets` options lets you specific a build set
   configuration to run. This helps target or select a specific build
   set from the group of builds provided.

### Build All

Configure the build with the RSB you wish to use. Please sure the RSB
is the right version for the version configured:

```
./waf configure --rsb=../rtems-source-builder
```

Build:

```
./waf
```

### Dry Run

A dry-run is useful to check the RSB configurations are usable. Using
the Build All configuration:

```
./waf dry-run
```

### Show

Show the RSB commands for the build sets:

```
./waf show
```

### Prefix

The configure `--prefix` option lets you specify a deployment prefix
for your team or organization:

```
./waf configure --rsb=../rtems-source-builder --prefix=/opt/project
```

All built sets built will use this prefix and the tar files create in
the build will use this path. Run the builds:

```
./waf
```

Use the `--targets=` option to select a specific build.Installing

### Installing

To install the output provide a prefix to a writable location on your disk:

```
./waf configure --rsb=../rtems-source-builder --prefix=/opt/project --install
```

Each build set will install to the prefix path. Run the builds:

```
./waf
```

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.