1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | .. comment: All rights reserved. |
---|
5 | |
---|
6 | .. _ecosystem: |
---|
7 | |
---|
8 | Ecosystem |
---|
9 | ********* |
---|
10 | .. index:: Ecosystem |
---|
11 | |
---|
12 | The RTEMS Ecosystem is the collection of tools, packages, code, documentation |
---|
13 | and online content provided by the RTEMS Project. The ecosystem provides a way |
---|
14 | to develop, maintain, and use RTEMS. It's parts interact with the user, the |
---|
15 | host environment, and each other to make RTEMS accessable, useable and |
---|
16 | predicable. |
---|
17 | |
---|
18 | The ecosystem is for users, developers and maintainers and it is an on going |
---|
19 | effort that needs your help and support. The RTEMS project is always improving |
---|
20 | the way it delivers the kernel to you and your feedback is important so please |
---|
21 | join the mailing lists and contribute back comments, success stories, bugs and |
---|
22 | patches. |
---|
23 | |
---|
24 | What the RTEMS project describes here to develop, maintain and use RTEMS does |
---|
25 | not dictate what you need to use in your project. You can and should select the |
---|
26 | work-flow that best suites the demands of your project and what you are |
---|
27 | delivering. |
---|
28 | |
---|
29 | Rational |
---|
30 | ======== |
---|
31 | |
---|
32 | RTEMS is complex and the focus of the RTEMS Ecosystem is to simplify the |
---|
33 | complexity for users by providing a stable documented way to build, configure |
---|
34 | and run RTEMS. RTEMS is more than a kernel running real-time applications on |
---|
35 | target hardware, it is part of a project's and therefore team's workflow and |
---|
36 | every project and team is different. |
---|
37 | |
---|
38 | RTEMS's ecosystem does not mandate a way to work. It is a series of parts, |
---|
39 | components, and items that are used to create a suitable development |
---|
40 | environment to work with. The processes explained in this manual are the same |
---|
41 | things an RTEMS maintainer does to maintain the kernel or an experienced user |
---|
42 | does to build their production system. It is important to keep this in mind |
---|
43 | when working through this manual. We encourage users to explore what can be |
---|
44 | done and to discover ways to make it fit their needs. The ecosystem provided by |
---|
45 | the RTEMS Project will not install in a single click of a mouse because we want |
---|
46 | users to learn the parts they will come to depend on as their project's |
---|
47 | development matures. |
---|
48 | |
---|
49 | The RTEMS Ecosystem provides a standard interface that is the same on all |
---|
50 | supported host systems. Standardizing how a user interacts with RTEMS is |
---|
51 | important and making that experience portable is also important. As a result |
---|
52 | the ecosystem is documented at the command line level and we leave GUI and IDE |
---|
53 | integration for users and integrators. |
---|
54 | |
---|
55 | Standardizing the parts and how to use them lets users create processes and |
---|
56 | procedures that are stable over releases. The RTEMS Ecosystem generates data |
---|
57 | that can be used to audit the build process so their configuration can be |
---|
58 | documented. |
---|
59 | |
---|
60 | The ecosystem is based around the source code used in the various parts, |
---|
61 | compontents and items of the RTEMS development environment. A user can create |
---|
62 | an archive of the complete build process including all the source code for long |
---|
63 | term storage. This is important for projects with a long life cycle. |
---|
64 | |
---|
65 | Open Source |
---|
66 | =========== |
---|
67 | |
---|
68 | RTEMS is an open source operating system and an open source project and this |
---|
69 | extends to the ecosystem. We encourage users to integrate the processes to |
---|
70 | build tools, the kernel and any 3rd party libraries into their project's |
---|
71 | configuration management processes. |
---|
72 | |
---|
73 | All the parts that make up the ecosystem are open source. The ecosystem uses a |
---|
74 | package's source code to create an executable on a host so when an example |
---|
75 | RTEMS executable is created and run for the first time the user will have built |
---|
76 | every tool as well as the executable from source. The RTEMS Project believes |
---|
77 | the freedom this gives a user is as important as the freedom of having access |
---|
78 | to the source code for a package. |
---|
79 | |
---|
80 | Deployment |
---|
81 | ========== |
---|
82 | |
---|
83 | The RTEMS Project provides the ecosystem as source code that users can download |
---|
84 | to create personalised development environments. The RTEMS Project does not |
---|
85 | provide packaging and deployment for a specific host environment, target |
---|
86 | architecture or BSP. The RTEMS Project encourages users and organizations to |
---|
87 | fill this role for the community. |
---|
88 | |
---|
89 | Building and Deploying Tool Binaries |
---|
90 | ------------------------------------ |
---|
91 | |
---|
92 | If you wish to create and distribute your build or you want to archive a build |
---|
93 | you can create a tar file. We term this deploying a build. This is a more |
---|
94 | advanced method for binary packaging and installing of tools. |
---|
95 | |
---|
96 | By default the RTEMS Source Builder installs the built packages directly and |
---|
97 | optionally it can also create a *build set tar file* or a *package tar file* |
---|
98 | per package built. The normal and default behaviour is to let the RTEMS Source |
---|
99 | Builder install the tools. The source will be downloaded, built, installed and |
---|
100 | cleaned up. |
---|
101 | |
---|
102 | The tar files are created with the full build prefix present and if you follow |
---|
103 | the examples given in this documentation the path is absolute. This can cause |
---|
104 | problems if you are installing on a host you do not have super user or |
---|
105 | administrator rights on because the prefix path may references part you do not |
---|
106 | have write access too and tar will not extract the files. You can use the |
---|
107 | ``--strip-components`` option in tar if your host tar application supports it |
---|
108 | to remove the parts you do not have write access too or you may need to unpack |
---|
109 | the tar file somewhere and copy the file tree from the level you have write |
---|
110 | access from. Embedding the full prefix path in the tar files lets you know what |
---|
111 | the prefix is and is recommended. For example if |
---|
112 | ``/home/chris/development/rtems/4.11`` is the prefix used you cannot change |
---|
113 | directory to the root (``/``) and untar the file because the ``/home`` is root |
---|
114 | access only. To install a tar file you have downloaded into your new machine's |
---|
115 | ``Downloads`` directory in your home directoty you would enter: |
---|
116 | |
---|
117 | .. code-block:: shell |
---|
118 | |
---|
119 | $ cd /somewhere |
---|
120 | $ tar --strip-components=3 -xjf \ |
---|
121 | $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2 |
---|
122 | |
---|
123 | A build set tar file is created by adding ``--bset-tar-file`` option to the |
---|
124 | ``sb-set-builder`` command:: |
---|
125 | |
---|
126 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
127 | --prefix=$HOME/development/rtems/4.11 \ |
---|
128 | --bset-tar-file \ <1> |
---|
129 | 4.11/rtems-sparc |
---|
130 | Source Builder - Set Builder, v0.2.0 |
---|
131 | Build Set: 4.11/rtems-sparc |
---|
132 | config: expat-2.1.0-1.cfg |
---|
133 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
134 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
135 | config: tools/rtems-binutils-2.22-1.cfg |
---|
136 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
137 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
138 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
139 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
140 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
141 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
142 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
143 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
144 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2> |
---|
145 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
146 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
147 | installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 |
---|
148 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> |
---|
149 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
150 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
151 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
152 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
153 | Build Set: Time 0:15:25.92873 |
---|
154 | |
---|
155 | .. topic:: Items |
---|
156 | |
---|
157 | 1. The option to create a build set tar file. |
---|
158 | |
---|
159 | 2. The installation still happens unless you specify ``--no-install``. |
---|
160 | |
---|
161 | 3. Creating the build set tar file. |
---|
162 | |
---|
163 | You can also suppress installing the files using the ``--no-install`` |
---|
164 | option. This is useful if your prefix is not accessiable, for example when |
---|
165 | building Canadian cross compiled tool sets:: |
---|
166 | |
---|
167 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
168 | --prefix=$HOME/development/rtems/4.11 \ |
---|
169 | --bset-tar-file \ |
---|
170 | --no-install \ <1> |
---|
171 | 4.11/rtems-sparc |
---|
172 | Source Builder - Set Builder, v0.2.0 |
---|
173 | Build Set: 4.11/rtems-sparc |
---|
174 | config: expat-2.1.0-1.cfg |
---|
175 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
176 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
177 | config: tools/rtems-binutils-2.22-1.cfg |
---|
178 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
179 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
180 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
181 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
182 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
183 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
184 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
185 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
186 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 <2> |
---|
187 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
188 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
189 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
190 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
191 | Build Set: Time 0:14:11.721274 |
---|
192 | $ ls tar |
---|
193 | rtems-4.11-sparc-rtems4.11-1.tar.bz2 |
---|
194 | |
---|
195 | .. topic:: Items |
---|
196 | |
---|
197 | 1. The option to supressing installing the packages. |
---|
198 | |
---|
199 | 2. Create the build set tar. |
---|
200 | |
---|
201 | A package tar file can be created by adding the ``--pkg-tar-files`` to the |
---|
202 | ``sb-set-builder`` command. This creates a tar file per package built in the |
---|
203 | build set:: |
---|
204 | |
---|
205 | $ ../source-builder/sb-set-builder --log=l-sparc.txt \ |
---|
206 | --prefix=$HOME/development/rtems/4.11 \ |
---|
207 | --bset-tar-file \ |
---|
208 | --pkg-tar-files \ <1> |
---|
209 | --no-install 4.11/rtems-sparc |
---|
210 | Source Builder - Set Builder, v0.2.0 |
---|
211 | Build Set: 4.11/rtems-sparc |
---|
212 | config: expat-2.1.0-1.cfg |
---|
213 | package: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
214 | building: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
215 | config: tools/rtems-binutils-2.22-1.cfg |
---|
216 | package: sparc-rtems4.11-binutils-2.22-1 |
---|
217 | building: sparc-rtems4.11-binutils-2.22-1 |
---|
218 | config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg |
---|
219 | package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
220 | building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
221 | config: tools/rtems-gdb-7.5.1-1.cfg |
---|
222 | package: sparc-rtems4.11-gdb-7.5.1-1 |
---|
223 | building: sparc-rtems4.11-gdb-7.5.1-1 |
---|
224 | tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2 |
---|
225 | cleaning: expat-2.1.0-x86_64-freebsd9.1-1 |
---|
226 | cleaning: sparc-rtems4.11-binutils-2.22-1 |
---|
227 | cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1 |
---|
228 | cleaning: sparc-rtems4.11-gdb-7.5.1-1 |
---|
229 | Build Set: Time 0:14:37.658460 |
---|
230 | $ ls tar |
---|
231 | expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2 sparc-rtems4.11-binutils-2.22-1.tar.bz2 |
---|
232 | sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2> rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3> |
---|
233 | sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2 |
---|
234 | |
---|
235 | .. topic:: Items |
---|
236 | |
---|
237 | 1. The option to create packages tar files. |
---|
238 | |
---|
239 | 2. The GDB package tar file. |
---|
240 | |
---|
241 | 3. The build set tar file. All the others in a single tar file. |
---|