[rtems-docs commit] user: Add deployment section

Chris Johns chrisj at rtems.org
Mon Sep 12 21:38:21 UTC 2022


Module:    rtems-docs
Branch:    master
Commit:    2a2d33ccfcaacbb1b2e98a200078b4d882175415
Changeset: http://git.rtems.org/rtems-docs/commit/?id=2a2d33ccfcaacbb1b2e98a200078b4d882175415

Author:    Chris Johns <chrisj at rtems.org>
Date:      Sat Sep 10 07:38:15 2022 +1000

user: Add deployment section

---

 user/deployment/index.rst | 426 ++++++++++++++++++++++++++++++++++++++++++++++
 user/index.rst            |   3 +-
 2 files changed, 428 insertions(+), 1 deletion(-)

diff --git a/user/deployment/index.rst b/user/deployment/index.rst
new file mode 100644
index 0000000..d1315af
--- /dev/null
+++ b/user/deployment/index.rst
@@ -0,0 +1,426 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2022 Chris Johns
+
+.. _BSPs:
+
+Deployment
+**********
+.. index:: Deployment
+.. index:: packages
+
+Deployment is a process companies, organizations or teams use to
+control and manage delivery of RTEMS tools, kernels and third party
+libraries. Deployed tools, kernels and libraries are packaged and
+controlled so the same tools and libraries are used in all phases of a
+project.
+
+The Quick Start guide details how tools are built using the RSB. The
+tools are installed on your development computer and available for you
+to build applications. That build can be viewed as the simplest form
+of deployment because it is simple and easy however it does not
+scale. Building the tools and kernel on each development machine in a
+project or company is time consuming, difficult to get right and
+costly to audit.
+
+This section covers the building of tools, kernels and third party
+libraries using the RSB for deployment. Custom RSB buildset files are
+supported across releases giving you an easy update path. The RSB can
+generate a single tarfile for any prefix without needing to install
+the pieces built helping ease integration with packaging systems and
+continuous integration (CI) for automated workflows.
+
+RSB Deployment
+--------------
+
+The RSB provides support for deployment using custom buildset files. A
+custom buildset file resides outside the RSB and can build tools for a
+number of architectures and kernels for BSPs. Deployment can include
+third party libraries if a single BSP is being built.
+
+The RSB ``--no-install`` option builds the tools and kernel without
+the final installation phase. A prefix that is not accessible when
+running the RSB can be used. This is important if a CI flow is being
+used.
+
+The buildset tar file option ``--bset-tar-file`` packages the build's
+staging directory tree into a single tar file. The tar file can be
+used as the input source to a packaging system.
+
+Buildset configuration files can be tested by adding the ``--dry-run``
+option to the ``sb-set-builder`` command line.
+
+The buildset examples that follow assume the prefix path used does not
+exist or is not writable and the environment path does not include any
+RTEMS tools.
+
+Deployment Repository
+^^^^^^^^^^^^^^^^^^^^^
+
+Create a repository to hold a project's buildset configuration
+files:
+
+.. code-block:: none
+
+    $ mkdir a-project
+    $ cd a-project
+    $ git init
+
+Add the RSB as a sub-module:
+
+.. code-block:: none
+
+    $ git submodule add git://git.rtems.org/rtems-source-builder.git
+
+Create a configuration directory:
+
+.. code-block:: none
+
+    $ mkdir config
+    $ git add config
+
+Tools Configuration
+^^^^^^^^^^^^^^^^^^^
+
+This example will build a single tool set with a local configuration
+file.
+
+Create a configuration file for the ``project``:
+
+.. code-block:: none
+
+    $ vi config/project-tools.bset
+
+Add the following to the buildset configuration file:
+
+.. code-block:: none
+
+    #
+    # Project Tools
+    #
+    @rtems-ver-major@/rtems-aarch64
+
+Commit the changes to the repository:
+
+.. code-block:: none
+
+   $ git add config/project-tools.bset
+   $ git commit -m "Add project aarch64 tools buildset"
+
+Build a tarfile containing the tools using the RSB submodule:
+
+.. code-block:: none
+
+   $ ./rtems-source-builder/source-builder/sb-set-builder \
+       --prefix=/opt/project --log=project.txt \
+       --bset-tar-file --no-install \
+       project-tools
+
+Once the build has finished the ``tar`` directory will contain the
+``project`` tools in a tarfile:
+
+.. code-block:: none
+
+   $ ls tar
+   project-tools.tar.bz2
+
+Inspect the tarfile to check the path matches the prefix used to build
+the tools (sizes may vary):
+
+.. code-block:: none
+
+   $ tar Jtvf tar/project-tools.tar.bz2 | less
+   drwxr-xr-x  0 chris  eng        0 Sep  6 14:27 opt/project/bin/
+   -rwxr-xr-x  0 chris  eng  1320888 Sep  6 14:20 opt/project/bin/aarch64-rtems at rtems-ver-major@-addr2line
+   -rwxr-xr-x  0 chris  eng  1358688 Sep  6 14:20 opt/project/bin/aarch64-rtems at rtems-ver-major@-ar
+   -rwxr-xr-x  0 chris  eng  2381976 Sep  6 14:20 opt/project/bin/aarch64-rtems at rtems-ver-major@-as
+   -rwxr-xr-x  0 chris  eng  1328440 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-c++
+   -rwxr-xr-x  0 chris  eng  1316240 Sep  6 14:20 opt/project/bin/aarch64-rtems at rtems-ver-major@-c++filt
+   -rwxr-xr-x  0 chris  eng  1328440 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-cpp
+   -rwxr-xr-x  0 chris  eng    60792 Sep  6 14:20 opt/project/bin/aarch64-rtems at rtems-ver-major@-elfedit
+   -rwxr-xr-x  0 chris  eng  1328440 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-g++
+   -rwxr-xr-x  0 chris  eng  1328440 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-gcc
+   -rwxr-xr-x  0 chris  eng  1328440 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-gcc-12.1.1
+   -rwxr-xr-x  0 chris  eng    48568 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-gcc-ar
+   -rwxr-xr-x  0 chris  eng    48568 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-gcc-nm
+   -rwxr-xr-x  0 chris  eng    48576 Sep  6 14:27 opt/project/bin/aarch64-rtems at rtems-ver-major@-gcc-ranlib
+   .....
+
+Tools and Kernel
+^^^^^^^^^^^^^^^^
+
+This example builds a single tool set and an RTEMS kernel for a BSP
+using a buildset defined BSP settings.
+
+We use the same ``a-project`` repository from the previous example and
+add a new configuration. Add a configuration file to build the tools
+and a BSP:
+
+.. code-block:: none
+
+   $ vi config/project-tools-bsp.bset
+
+Add the following to the buildset configuration file and save:
+
+.. code-block:: none
+
+   #
+   # Project Tools and BSP
+   #
+   %define with_rtems_bsp     aarch64/xilinx_versal_aiedge
+   %define with_rtems_bspopts BSP_XILINX_VERSAL_NOCACHE_LENGTH=0x4000000 \
+                              BSP_XILINX_VERSAL_RAM_LENGTH=0x200000000
+   @rtems-ver-major@/rtems-aarch64
+   @rtems-ver-major@/rtems-kernel
+
+The configuration provides BSP options. Commit the changes to the
+repository:
+
+.. code-block:: none
+
+   $ git add config/project-tools-bsp.bset
+   $ git commit -m "Add project tools and BSP buildset"
+
+Build a tarfile of the tools and BSP using the RSB submodule:
+
+.. code-block:: none
+
+   $ ./rtems-source-builder/source-builder/sb-set-builder \
+       --prefix=/opt/project --log=project.txt \
+       --bset-tar-file --no-install \
+       project-tools-bsp
+
+A buildset configuration file that uses buildset BSP defines is
+limited to a single architecture and the tools built need to match the
+architecture of the BSP.
+
+You can specify more than one BSP to be built. An updated
+configuration could be:
+
+.. code-block:: none
+
+   %define with_rtems_bsp     aarch64/xilinx_versal_aiedge \
+                              aarch64/xilinx_zynqmp_lp64_zu3eg
+
+This is useful when deploying more than one BSP. If you need multiple
+architectures and BSPs consider the Tools and Kernel With Config
+example.
+
+Buildset BSP options are applied to all BSPs in the BSP list. If they
+are specific to a BSP only specify a single BSP in the BSP define.
+
+RTEMS 5 supports this type of buildset file.
+
+Tools and Kernel with Config
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example builds tool sets for different architectures and multiple
+BSPs for the architectures using a kernel configuration INI file.
+
+Tools for the ``arch64`` and ``arm`` architectures are built and three
+BSPs each with different options.
+
+We use the same ``a-project`` repository from the previous example and
+add the new configurations. Add a configuration file to build the
+tools and BSPs:
+
+.. code-block:: none
+
+   $ vi config/project-tools-bsp-config.bset
+
+Add the following to the buildset configuration file and save:
+
+.. code-block:: none
+
+   #
+   # Project Tools and BSPs
+   #
+   %define with_rtems_bsp_config config/project-bsps.ini
+   @rtems-ver-major@/rtems-aarch64
+   @rtems-ver-major@/rtems-arm
+   @rtems-ver-major@/rtems-kernel
+
+Add a kernel configuration INI file:
+
+.. code-block:: none
+
+   $ vi config/project-bsps.bset
+
+Add the following to the kernel configuration INI file and save:
+
+.. code-block:: none
+
+   #
+   # Project BSPs
+   #
+   [DEFAULT]
+   RTEMS_POSIX_API = True
+   BUILD_SAMPLES = True
+   BUILD_TESTS = False
+
+   [aarch64/xilinx_versal_aiedge]
+   BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000
+   BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000
+
+   [aarch64/xilinx_zynqmp_lp64_zu3eg]
+   RTEMS_SMP = True
+
+   [arm/xilinx_zynq_zc706]
+   RTEMS_SMP = True
+   BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000
+   BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000
+
+Commit the changes to the repository:
+
+.. code-block:: none
+
+   $ git add config/project-tools-bsp-config.bset
+   $ git add config/project-bsps.ini
+   $ git commit -m "Add project tools and BSPs buildset and kernel config"
+
+Build a tarfile of the tools and BSPs using the RSB submodule:
+
+.. code-block:: none
+
+   $ ./rtems-source-builder/source-builder/sb-set-builder \
+       --prefix=/opt/project --log=project.txt \
+       --bset-tar-file --no-install \
+       project-tools-bsp-config
+
+Tools, Kernel and Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Third party libraries can be built as part of a single RSB
+configuration if only one BSP is built at a time. The RSB support for
+building packages does not support building for multiple BSPs.
+
+We use the same ``a-project`` repository from the previous example and
+add a new configuration. Add a configuration file to build the tools,
+BSPs and LibBSD:
+
+.. code-block:: none
+
+   $ vi config/project-aarch64-tools-bsp-libbsd.bset
+
+Add the following to the buildset configuration file and save:
+
+.. code-block:: none
+
+   #
+   # Project Tools, BSP and LibBSD
+   #
+   %define with_rtems_bsp     aarch64/xilinx_versal_aiedge
+   %define with_rtems_bspopts BSP_XILINX_VERSAL_NOCACHE_LENGTH=0x4000000 \
+                              BSP_XILINX_VERSAL_RAM_LENGTH=0x200000000
+   6/rtems-aarch64
+   6/rtems-kernel
+   6/rtems-libbsd
+
+Commit the changes to the repository:
+
+.. code-block:: none
+
+   $ git add config/project-aarch64-tools-bsp-libbsd.bset
+   $ git commit -m "Add project aarch64 tools, BSP and libbsd"
+
+Build a tarfile of the tools, BSP and LibBSD using the RSB
+submodule:
+
+.. code-block:: none
+
+   $ ./rtems-source-builder/source-builder/sb-set-builder \
+       --prefix=/opt/project --log=project.txt \
+       --bset-tar-file --no-install \
+       project-aarch64-tools-bsp-libbsd
+
+The tarfile can be reviewed to see the BSP libraries built (sizes may vary):
+
+.. code-block:: none
+
+   $ tar jtvf tar/project-aarch64-tools-bsp-libbsd.tar.bz2 | \
+              grep -e '\.a$' | grep -e 'xilinx_versal_aiedge'
+   -rw-r--r--  0 chris  eng 138936312 Sep  7 14:58 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libbsd.a
+   -rw-r--r--  0 chris  eng    686190 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libdebugger.a
+   -rw-r--r--  0 chris  eng    164086 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libftpd.a
+   -rw-r--r--  0 chris  eng    107560 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libftpfs.a
+   -rw-r--r--  0 chris  eng    978812 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libjffs2.a
+   -rw-r--r--  0 chris  eng    412354 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libmghttpd.a
+   -rw-r--r--  0 chris  eng   2099962 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/librtemsbsp.a
+   -rw-r--r--  0 chris  eng  29693496 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/librtemscpu.a
+   -rw-r--r--  0 chris  eng    435236 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/librtemscxx.a
+   -rw-r--r--  0 chris  eng    141234 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/librtemsdefaultconfig.a
+   -rw-r--r--  0 chris  eng    856514 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/librtemstest.a
+   -rw-r--r--  0 chris  eng    159004 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libtelnetd.a
+   -rw-r--r--  0 chris  eng    137386 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libtftpfs.a
+   -rw-r--r--  0 chris  eng    476692 Sep  7 14:56 opt/project/aarch64-rtems at rtems-ver-major@/xilinx_versal_aiedge/lib/libz.a
+
+Tools, Kernel with Config and Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example builds the tools, kernel and LibBSD using an RSB
+configuration file and a kernel configuration file. The kernel
+configuration provides easier kernel and BSP option management.
+
+Third party libraries can be built as part of a single RSB
+configuration if only one BSP is built at a time. The RSB support for
+building packages does not support building for multiple BSPs.
+
+We use the same ``a-project`` repository from the previous example and
+add a new configuration. Add a configuration file to build the tools,
+BSPs and LibBSD:
+
+.. code-block:: none
+
+   $ vi config/project-aarch-tools-bsp-libbsd-config.bset
+
+Add the following to the buildset configuration file and save:
+
+.. code-block:: none
+
+   #
+   # Project Tools, BSP and LibBSD
+   #
+   %define with_rtems_bsp_config config/project-aarch64-bsp.ini
+   6/rtems-aarch64
+   6/rtems-kernel
+   6/rtems-libbsd
+
+Add a kernel configuration INI file:
+
+.. code-block:: none
+
+   $ vi config/project-aarch64-bsp.bset
+
+Add the following kernel configuration INI file and save:
+
+.. code-block:: none
+
+   #
+   # Project Versal AI Edge BSP
+   #
+   [DEFAULT]
+   RTEMS_POSIX_API = True
+   BUILD_SAMPLES = True
+   BUILD_TESTS = False
+
+   [aarch64/xilinx_versal_aiedge]
+   BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000
+   BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000
+
+Commit the changes to the repository:
+
+.. code-block:: none
+
+   $ git add config/project-aarch64-tools-bsp-libbsd-config.bset
+   $ git add config/project-aarch64-bsp.ini
+   $ git commit -m "Add project aarch64 tools, BSP (with config) and libbsd"
+
+Build the tarfile of the tools, BSP and LibBSD using the RSB
+submodule:
+
+.. code-block:: none
+
+   $ ./rtems-source-builder/source-builder/sb-set-builder \
+       --prefix=/opt/project --log=project.txt \
+       --bset-tar-file --no-install \
+       project-aarch64-tools-bsp-libbsd-config
diff --git a/user/index.rst b/user/index.rst
index a91aa55..38ade81 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -20,7 +20,7 @@ RTEMS User Manual (|version|).
     | |copy| 2017 Tanu Hari Dixit
     | |copy| 2016, 2019 embedded brains GmbH
     | |copy| 2016, 2019 Sebastian Huber
-    | |copy| 2012, 2020 Chris Johns
+    | |copy| 2012, 2022 Chris Johns
     | |copy| 2012, 2020 Gedare Bloom
     | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR)
 
@@ -37,6 +37,7 @@ RTEMS User Manual (|version|).
     support/index
     hosts/index
     installation/index
+    deployment/index
 
     hardware/index
     bld/index



More information about the vc mailing list