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 | |
---|
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. |
---|
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 |
---|
55 | *preparation*, *building*, and *installing*. Scripts support macros, shell |
---|
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 |
---|
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`. |
---|
65 | |
---|
66 | .. comment: TBD: The section "Installing and Tar Files" does not exist. |
---|
67 | |
---|
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 | |
---|
75 | .. topic:: Bug Reporting |
---|
76 | |
---|
77 | If you think you have found a problem please see :ref:`Bugs, Crashes, and |
---|
78 | Build Failures`. |
---|
79 | |
---|
80 | Why Build from Source? |
---|
81 | ---------------------- |
---|
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 |
---|
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 |
---|
89 | specifically for your host operating system. Building manually or installing a |
---|
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. |
---|
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 |
---|
121 | system. Given the stability of standards based libraries like ``libc`` and ever |
---|
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 | |
---|
136 | History |
---|
137 | ------- |
---|
138 | |
---|
139 | The RTEMS Source Builder is a stand alone tool based on another tool called the |
---|
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. The available SRPM and *spec* files by themselves |
---|
145 | where of little use because a suitable ``rpm`` tool was needed to use them. At |
---|
146 | the time the available versions of ``rpm`` for a number of non-RPM hosts were |
---|
147 | broken and randomly maintained. The solution Chris settled on was to use the |
---|
148 | *spec* files and to write a Python based tool that parsed the *spec* file |
---|
149 | format creating a shell script that could be run to build the package. The |
---|
150 | approach proved successful and Chris was able to track the RPM version of the |
---|
151 | RTEMS tools on a 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. |
---|