[cddb06c] | 1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
| 3 | .. comment COPYRIGHT (c) 2012 - 2016. |
---|
| 4 | .. comment Chris Johns <chrisj@rtems.org> |
---|
| 5 | |
---|
[8b64335] | 6 | RTEMS Source Builder |
---|
| 7 | #################### |
---|
| 8 | |
---|
| 9 | The RTEMS Source Builder or RSB is a tool to build packages from source. It is |
---|
| 10 | used by the RTEMS project to build it's compilers and OS. The RSB helps |
---|
| 11 | consolidate the details you need to build a package from source in a controlled |
---|
| 12 | and verifiable way. The tool is aimed at developers of software who use tool |
---|
| 13 | sets for embedded development. The RSB is not limited to building tools just |
---|
| 14 | for RTEMS, you can build bare metal development environments. |
---|
| 15 | |
---|
| 16 | Embedded development typically uses cross-compiling tool chains, debuggers, and |
---|
| 17 | debugging aids. Together we call these a **tool set**. The RTEMS Source Builder |
---|
| 18 | is designed to fit this specific niche but is not limited to it. The RSB can be |
---|
| 19 | used outside of the RTEMS project and we welcome this. |
---|
| 20 | |
---|
| 21 | The RTEMS Source Builder is typically used to build a set of tools or a **build |
---|
| 22 | set**. A **build set** is a collection of packages and a package is a specific |
---|
| 23 | tool, for example gcc or gdb, or library. The RTEMS Source Builder attempts to |
---|
| 24 | support any host environment that runs Python and you can build the package |
---|
| 25 | on. The RSB is not some sort of magic that can take any piece of source code |
---|
| 26 | and make it build. Someone at some point in time has figured out how to build |
---|
| 27 | that package from source and taught this tool. |
---|
| 28 | |
---|
| 29 | The RTEMS Source Builder has been tested on: |
---|
| 30 | |
---|
| 31 | - ArchLinux |
---|
| 32 | - CentOS |
---|
| 33 | - Fedora |
---|
| 34 | - Raspbian |
---|
| 35 | - Ubuntu (includes XUbuntu) |
---|
| 36 | - Linux Mint |
---|
| 37 | - openSUSE |
---|
| 38 | - FreeBSD |
---|
| 39 | - NetBSD |
---|
| 40 | - MacOS |
---|
| 41 | - Windows |
---|
| 42 | |
---|
| 43 | .. topic:: Setting up your Host |
---|
| 44 | |
---|
| 45 | :ref:`Hosts` details setting up hosts. |
---|
[cddb06c] | 46 | |
---|
| 47 | The RTEMS Source Builder has two types of configuration data. The first is the |
---|
| 48 | *build set*. A *build set* describes a collection of packages that define a set |
---|
| 49 | of tools you would use when developing software for RTEMS. For example the |
---|
| 50 | basic GNU tool set is binutils, gcc, and gdb and is the typical base suite of |
---|
| 51 | tools you need for an embedded cross-development type project. The second type |
---|
| 52 | of configuration data is the configuration files and they define how a package |
---|
| 53 | is built. Configuration files are scripts loosely based on the RPM spec file |
---|
| 54 | format and they detail the steps needed to build a package. The steps are |
---|
[8b64335] | 55 | *preparation*, *building*, and *installing*. Scripts support macros, shell |
---|
[cddb06c] | 56 | expansion, logic, includes plus many more features useful when build packages. |
---|
| 57 | |
---|
| 58 | The RTEMS Source Builder does not interact with any host package management |
---|
| 59 | systems. There is no automatic dependence checking between various packages you |
---|
| 60 | build or packages and software your host system you may have installed. We |
---|
| 61 | assume the build sets and configuration files you are using have been created |
---|
[8b64335] | 62 | by developers who do. Support is provided for package config or ``pkgconfg`` |
---|
| 63 | type files so you can check and use standard libraries if present. If you have |
---|
| 64 | a problem please ask on our :r:list:`devel`. |
---|
[cddb06c] | 65 | |
---|
[47aad7a] | 66 | .. comment: TBD: The section "Installing and Tar Files" does not exist. |
---|
| 67 | |
---|
[cddb06c] | 68 | This documentation caters for a range of users from new to experienced RTEMS |
---|
| 69 | developers. New users can follow the Quick Start section up to the "Installing |
---|
| 70 | and Tar Files" to get a working tools and RTEMS. Users building a binary tool |
---|
| 71 | set for release can read the "Installing and Tar Files". Users wanting to run |
---|
| 72 | and test bleeding edge tools or packages, or wanting update or extend the RSB's |
---|
| 73 | configuration can read the remaining sections. |
---|
| 74 | |
---|
[8b64335] | 75 | .. topic:: Bug Reporting |
---|
[cddb06c] | 76 | |
---|
[8b64335] | 77 | If you think you have found a problem please see :ref:`Bugs, Crashes, and |
---|
| 78 | Build Failures`. |
---|
[cddb06c] | 79 | |
---|
| 80 | Why Build from Source? |
---|
[8b64335] | 81 | ~~~~~~~~~~~~~~~~~~~~~~ |
---|
[cddb06c] | 82 | |
---|
| 83 | The RTEMS Source Builder is not a replacement for the binary install systems |
---|
| 84 | you have with commercial operating systems or open source operating system |
---|
| 85 | distributions. Those products and distributions are critically important and |
---|
[8b64335] | 86 | are the base that allows the RSB to work. The RTEMS Source Builder sits |
---|
| 87 | somewhere between you manually entering the commands to build a tool set and a |
---|
| 88 | tool such as ``yum`` or ``apt-get`` to install binary packages made |
---|
[cddb06c] | 89 | specifically for your host operating system. Building manually or installing a |
---|
[8b64335] | 90 | binary package from a remote repository are valid and real alternatives. The |
---|
| 91 | RSB provides the specific service of repeatably being able to build tool sets |
---|
| 92 | from source code. The process leaves you with the source code used to build |
---|
| 93 | the tools and the ability to rebuilt it. |
---|
[cddb06c] | 94 | |
---|
| 95 | If you are developing a system or product that has a long shelf life or is used |
---|
| 96 | in a critical piece of infrastructure that has a long life cycle being able to |
---|
| 97 | build from source is important. It insulates the project from the fast ever |
---|
| 98 | changing world of the host development machines. If your tool set is binary and |
---|
| 99 | you have lost the ability to build it you have lost a degree of control and |
---|
| 100 | flexibility open source gives you. Fast moving host environments are |
---|
| 101 | fantastic. We have powerful multi-core computers with huge amounts of memory |
---|
| 102 | and state of the art operating systems to run on them however the product or |
---|
| 103 | project you are part of may need to be maintained well past the life time of |
---|
| 104 | these host. Being able to build from source an important and critical part of |
---|
| 105 | this process because you can move to a newer host and create an equivalent tool |
---|
| 106 | set. |
---|
| 107 | |
---|
| 108 | Building from source provides you with control over the configuration of the |
---|
| 109 | package you are building. If all or the most important dependent parts are |
---|
| 110 | built from source you limit the exposure to host variations. For example the |
---|
| 111 | GNU C compiler (gcc) currently uses a number of 3rd party libraries internally |
---|
| 112 | (gmp, mpfr, etc). If your validated compiler generating code for your target |
---|
| 113 | processor is dynamically linked against the host's version of these libraries |
---|
| 114 | any change in the host's configuration may effect you. The changes the host's |
---|
| 115 | package management system makes may be perfectly reasonable in relation to the |
---|
| 116 | distribution being managed however this may not extend to you and your |
---|
| 117 | tools. Building your tools from source and controlling the specific version of |
---|
| 118 | these dependent parts means you are not exposing yourself to unexpected and |
---|
| 119 | often difficult to resolve problems. On the other side you need to make sure |
---|
| 120 | your tools build and work with newer versions of the host operating |
---|
[8b64335] | 121 | system. Given the stability of standards based libraries like ``libc`` and ever |
---|
[cddb06c] | 122 | improving support for standard header file locations this task is becoming |
---|
| 123 | easier. |
---|
| 124 | |
---|
| 125 | The RTEMS Source Builder is designed to be audited and incorporated into a |
---|
| 126 | project's verification and validation process. If your project is developing |
---|
| 127 | critical applications that needs to be traced from source to executable code in |
---|
| 128 | the target, you need to also consider the tools and how to track them. |
---|
| 129 | |
---|
| 130 | If your IT department maintains all your computers and you do not have suitable |
---|
| 131 | rights to install binary packages, building from source lets you create your |
---|
| 132 | own tool set that you install under your home directory. Avoiding installing |
---|
| 133 | any extra packages as a super user is always helpful in maintaining a secure |
---|
| 134 | computing environment. |
---|
| 135 | |
---|
[8b64335] | 136 | History |
---|
[cddb06c] | 137 | ~~~~~~~ |
---|
| 138 | |
---|
| 139 | The RTEMS Source Builder is a stand alone tool based on another tool called the |
---|
[8b64335] | 140 | *SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010 |
---|
| 141 | for the RTEMS project to provide Chris with a way to build tools on hosts that |
---|
| 142 | did not support RPMs. At the time the RTEMS tools maintainer only supported |
---|
| 143 | *spec* files and these files held all the vital configuration data needed to |
---|
| 144 | create suitable tool sets. Available SRPM and *spec* files by themselves where |
---|
| 145 | useless because a suitable ``rpm`` tool to use them was needed. At the time |
---|
| 146 | available versions of ``rpm`` for a number of non-RPM hosts were broken and |
---|
| 147 | randomly maintained. The solution Chris settled on was to use the *spec* files |
---|
| 148 | and write to a Python based tool that parsed the *spec* file format creating a |
---|
| 149 | shell script that could be run to build the package. The approach proved |
---|
| 150 | successful and Chris was able to track the RPM version of the RTEMS tools on a |
---|
| 151 | non-RPM host for a number of years. |
---|
| 152 | |
---|
| 153 | The *SpecBuilder* tool did not build tools or packages unrelated to the RTEMS |
---|
| 154 | project where no suitable *spec* file was available so another tool was |
---|
| 155 | needed. Rather than start again Chris decided to take the parsing code for the |
---|
| 156 | *spec* file format and build a new tool called the RTEMS Source Builder. |
---|