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 | .. _rtems-development: |
---|
7 | |
---|
8 | RTEMS Development |
---|
9 | ================= |
---|
10 | |
---|
11 | RTEMS can be developed using Eclipse. The RTEMS kernel is an `autotools` or |
---|
12 | `autoconf` and `automake` based package. You can create a project in Eclipse |
---|
13 | that lets you configure and build a BSP for an architecture. We assume you have |
---|
14 | already build and installed your tools using the RTEMS Source Builder. |
---|
15 | |
---|
16 | Kernel Source |
---|
17 | ------------- |
---|
18 | |
---|
19 | Download or clone the RTEMS Kernel source code. We will clone the source code: |
---|
20 | |
---|
21 | .. code-block:: shell |
---|
22 | |
---|
23 | $ git clone git://git.rtems.org/rtems.git rtems.master |
---|
24 | Cloning into 'rtems'... |
---|
25 | remote: Counting objects: 483342, done. |
---|
26 | remote: Compressing objects: 100% (88974/88974), done. |
---|
27 | remote: Total 483342 (delta 390053), reused 475669 (delta 383809) |
---|
28 | Receiving objects: 100% (483342/483342), 69.88 MiB | 1.37 MiB/s, done. |
---|
29 | Resolving deltas: 100% (390053/390053), done. |
---|
30 | Checking connectivity... done. |
---|
31 | |
---|
32 | We need to `bootstrap` the kernel source code. A `botostrap` invokes the |
---|
33 | various `autotools` commands need to generate build system files. First we need |
---|
34 | to the path to our tools: |
---|
35 | |
---|
36 | .. code-block:: shell |
---|
37 | |
---|
38 | $ export PATH=/opt/rtems/4.12/bin:$PATH |
---|
39 | |
---|
40 | Now run the `bootstrap` command: |
---|
41 | |
---|
42 | .. code-block:: shell |
---|
43 | |
---|
44 | $ cd rtems.master |
---|
45 | $ ./bootstrap |
---|
46 | |
---|
47 | Sit back, this can take a while. The Getting Started Guide talks about using |
---|
48 | the RSB's `sb-bootstrap` to run the bootstrap process in parallel on all |
---|
49 | available cores. The output of the bootstrap has not been copied into this |
---|
50 | documentment. |
---|
51 | |
---|
52 | The source code is now ready. |
---|
53 | |
---|
54 | Eclipse SDK Software |
---|
55 | -------------------- |
---|
56 | |
---|
57 | We need the following Eclipse SDK Software packages installed: |
---|
58 | |
---|
59 | - C/C++ Autotools support |
---|
60 | - C/C++ Development Tools |
---|
61 | - C/C++ GCC Cross Compiler Support |
---|
62 | |
---|
63 | Start Eclipse and check to see if you have the them installed via the **Help, |
---|
64 | Installation Details** menu item: |
---|
65 | |
---|
66 | .. figure:: ../images/eclipse/eclipse-help-installation.png |
---|
67 | :width: 50% |
---|
68 | :align: center |
---|
69 | :alt: Help, Installation Details |
---|
70 | |
---|
71 | The dialog box shows the installed software packages and you can see the |
---|
72 | **C/C++ Autotools support** and the **C/C++ Development Tools** are installed: |
---|
73 | |
---|
74 | .. figure:: ../images/eclipse/eclipse-sdk-details.png |
---|
75 | :align: center |
---|
76 | :alt: SDK Installation Details |
---|
77 | |
---|
78 | You can see some other software packages are installed in the figure. You can ignore those. |
---|
79 | |
---|
80 | If you do not have the listed software packages install select **Help, Install |
---|
81 | New Software** and in the **Work with:** list box select |
---|
82 | **http://download.eclipse.org/releases/mars**. |
---|
83 | |
---|
84 | .. figure:: ../images/eclipse/eclipse-install-new-software.png |
---|
85 | :width: 80% |
---|
86 | :align: center |
---|
87 | :alt: Help, Install New Software |
---|
88 | |
---|
89 | Afer a small period of time a list of available packages will populate and you |
---|
90 | can select the ones we are interested in. Enter ``autotools`` in the search |
---|
91 | box and select the package: |
---|
92 | |
---|
93 | .. figure:: ../images/eclipse/eclipse-autotools.png |
---|
94 | :width: 80% |
---|
95 | :align: center |
---|
96 | :alt: C/C++ Autotools support |
---|
97 | |
---|
98 | Clear the search line and enter ``development tools`` in the search box and |
---|
99 | then scroll down to find **C/C++ Development Tools**: |
---|
100 | |
---|
101 | .. figure:: ../images/eclipse/eclipse-cdt.png |
---|
102 | :width: 80% |
---|
103 | :align: center |
---|
104 | :alt: C/C++ Development Tools |
---|
105 | |
---|
106 | Again clear the search line and enter ``gcc cross`` in the search box and |
---|
107 | select the package: |
---|
108 | |
---|
109 | .. figure:: ../images/eclipse/eclipse-gcc-cross.png |
---|
110 | :width: 80% |
---|
111 | :align: center |
---|
112 | :alt: C/C++ GCC Cross Compiler Support |
---|
113 | |
---|
114 | Click **Next** and once the **Install Details** have determined what is needed |
---|
115 | select **Finish** to install the packages. |
---|
116 | |
---|
117 | Kernel Build Project |
---|
118 | -------------------- |
---|
119 | |
---|
120 | We create a project in Eclipse that can configure and build RTEMS for the |
---|
121 | ``pc686`` BSP. This BSP is based on the ``pc386`` BSP and is under the ``i386`` |
---|
122 | architecture. |
---|
123 | |
---|
124 | We assume you have built and installed the ``i386`` RTEMS Tools, obtained the |
---|
125 | RTEMS kernel code and ``bootstrapped`` it if a git clone, and installed the |
---|
126 | required Eclipse Software packages. |
---|
127 | |
---|
128 | The paths used in this project are: |
---|
129 | |
---|
130 | :file:`/opt/work/rtems/4.11` |
---|
131 | The RTEMS Tools prefix the tools are install under. |
---|
132 | |
---|
133 | :file:`/opt/work/chris/rtems/kernel/rtems.master` |
---|
134 | The RTEMS Kernel source code. |
---|
135 | |
---|
136 | :file:`/opt/work/chris/rtems/kernel/4.12` |
---|
137 | The RTEMS Kernel prefix. |
---|
138 | |
---|
139 | :file:`/opt/work/chris/rtems/kernel/bsp/pc` |
---|
140 | The RTEMS Kernel BSP build directory. |
---|
141 | |
---|
142 | The menus shown here may vary from those you have as Eclipse changes them based |
---|
143 | on what you do. |
---|
144 | |
---|
145 | Select **File, New, Project** : |
---|
146 | |
---|
147 | .. figure:: ../images/eclipse/eclipse-new-project.png |
---|
148 | :width: 100% |
---|
149 | :align: center |
---|
150 | :alt: File, New, Project... |
---|
151 | |
---|
152 | Click on **C/C++** and select **Makefile Project with Existing Code** then |
---|
153 | select **Next** : |
---|
154 | |
---|
155 | .. figure:: ../images/eclipse/eclipse-project-makefile-existing-code.png |
---|
156 | :width: 75% |
---|
157 | :align: center |
---|
158 | :alt: Makefile Project with Existing Code |
---|
159 | |
---|
160 | Enter the project name ``rtems-git`` into the **Project Name** field and select |
---|
161 | the **Browse...** button and the path to the RTEMS Kernel source code then |
---|
162 | click **Finish** : |
---|
163 | |
---|
164 | .. figure:: ../images/eclipse/eclipse-project-import-existing-code.png |
---|
165 | :width: 75% |
---|
166 | :align: center |
---|
167 | :alt: Import Existing Code |
---|
168 | |
---|
169 | Eclipse will show the RTEMS Kernel source code in the **Project Explorer** panel: |
---|
170 | |
---|
171 | .. figure:: ../images/eclipse/eclipse-rtems-git-files.png |
---|
172 | :width: 100% |
---|
173 | :align: center |
---|
174 | :alt: RTEMS GIT Project showing files |
---|
175 | |
---|
176 | We now convert the project to an Autotools project. Select **File, New, |
---|
177 | Convert to a C/C++ Autotools Project** : |
---|
178 | |
---|
179 | .. figure:: ../images/eclipse/eclipse-rtems-git-convert-autotools.png |
---|
180 | :width: 100% |
---|
181 | :align: center |
---|
182 | :alt: Convert the project to Autotools |
---|
183 | |
---|
184 | Select **C Project** then **Finish** : |
---|
185 | |
---|
186 | .. figure:: ../images/eclipse/eclipse-rtems-git-convert-autotools-dialog.png |
---|
187 | :width: 85% |
---|
188 | :align: center |
---|
189 | :alt: Convert the project to Autotools |
---|
190 | |
---|
191 | We now configure the project's properties by right clicking on the |
---|
192 | ``rtems-git`` project title and then **Properties** : |
---|
193 | |
---|
194 | .. figure:: ../images/eclipse/eclipse-rtems-git-properties-menu.png |
---|
195 | :width: 100% |
---|
196 | :align: center |
---|
197 | :alt: |
---|
198 | |
---|
199 | Click on the **Autotools** item then **Configure Settings** and **Platform |
---|
200 | specifiers** and set the **Target platform** field with ``i386-rtems4.12``: |
---|
201 | |
---|
202 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-target.png |
---|
203 | :width: 100% |
---|
204 | :align: center |
---|
205 | :alt: Enter the Autotool target |
---|
206 | |
---|
207 | Select **Platform directories** and enter the **Arch-independent install |
---|
208 | directory (--prefix)** to the RTEMS Kernel prefix of |
---|
209 | :file:`/opt/work/chris/rtems/kernel/4.12`: |
---|
210 | |
---|
211 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-prefix.png |
---|
212 | :width: 100% |
---|
213 | :align: center |
---|
214 | :alt: Enter the Autotool target |
---|
215 | |
---|
216 | We disable networking to use the external LibBSD package and set the BSP to |
---|
217 | ``pc686``. Select the **Advanced** and in the **Additional command-line |
---|
218 | options** enter ``--disable-networking`` and ``--enable-rtemsbsps=pc686``. You |
---|
219 | can add extra options you may need: |
---|
220 | |
---|
221 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-add-opts.png |
---|
222 | :width: 100% |
---|
223 | :align: center |
---|
224 | :alt: Enter the Autotool additional options |
---|
225 | |
---|
226 | Select **C/C++ Build** and **Environment**. Uncheck or clear the **Use default |
---|
227 | build command** and add ``-j N`` where ``N`` is the number of cores you have in |
---|
228 | your machine. The figure has told `make` to run 8 jobs, one per core for an 8 |
---|
229 | core machine. Click on the **File system...** button and navigate to the BSP |
---|
230 | build directory. This is the location Eclipse builds the BSP. RTEMS requires |
---|
231 | you build outside the source tree and in this example we are forcing the build |
---|
232 | directory to something specific. Finish by pressing **Apply** : |
---|
233 | |
---|
234 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-build.png |
---|
235 | :width: 100% |
---|
236 | :align: center |
---|
237 | :alt: C/C++ Build Properties |
---|
238 | |
---|
239 | Select **Environment** under **C/C++ Build** as we need to set the path to the |
---|
240 | RTEMS Tools. In this example we set the path in the Eclipse project so each |
---|
241 | project can have a specific set of tools. Press the **Add...** button: |
---|
242 | |
---|
243 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env.png |
---|
244 | :width: 100% |
---|
245 | :align: center |
---|
246 | :alt: C/C++ Build Environment |
---|
247 | |
---|
248 | Enter the path to the tools, in our case it is |
---|
249 | :file:`/opt/work/rtems/4.12/bin`, then press **Variables** : |
---|
250 | |
---|
251 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var.png |
---|
252 | :width: 85% |
---|
253 | :align: center |
---|
254 | :alt: C/C++ Build Environment |
---|
255 | |
---|
256 | Scroll down and select **PATH** and then press **OK** : |
---|
257 | |
---|
258 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path.png |
---|
259 | :width: 60% |
---|
260 | :align: center |
---|
261 | :alt: C/C++ Build Environment |
---|
262 | |
---|
263 | You will now see the path in the **Value:** field. Make sure you have a path |
---|
264 | separator between the end of the tools path and the path variable we have just |
---|
265 | added. In this case is a Unix host and the separator is `:`. Windows use |
---|
266 | `;`. Press **OK** when you have a valid path: |
---|
267 | |
---|
268 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path-add.png |
---|
269 | :width: 85% |
---|
270 | :align: center |
---|
271 | :alt: C/C++ Build Environment |
---|
272 | |
---|
273 | The **Environment** panel will now show the added `PATH` variable. Click |
---|
274 | **Replace native environment with specified one** as shown and then press |
---|
275 | **Apply** : |
---|
276 | |
---|
277 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-replace.png |
---|
278 | :width: 100% |
---|
279 | :align: center |
---|
280 | :alt: C/C++ Build Environment |
---|
281 | |
---|
282 | Select **Settings** under **C/C++ Build** and check **Elf Parser** and **GNU |
---|
283 | Elf Parser** and then press **OK** : |
---|
284 | |
---|
285 | .. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-settings.png |
---|
286 | :width: 100% |
---|
287 | :align: center |
---|
288 | :alt: C/C++ Build Settings |
---|
289 | |
---|
290 | We are now ready to run configure using Eclipse. Right click on the project |
---|
291 | name ``rtems-git`` and then **Reconfigure Project** : |
---|
292 | |
---|
293 | .. figure:: ../images/eclipse/eclipse-rtems-git-reconfigure.png |
---|
294 | :width: 100% |
---|
295 | :align: center |
---|
296 | :alt: Reconfigure the RTEMS Project |
---|
297 | |
---|
298 | Select the **Console** tab in the output panel to view the configure process |
---|
299 | output. You will notice the end of the configure process shows the names of the |
---|
300 | BSPs we have asked to build. In our case this is the ``pc686`` BSP: |
---|
301 | |
---|
302 | .. figure:: ../images/eclipse/eclipse-rtems-git-reconfigure-console.png |
---|
303 | :width: 100% |
---|
304 | :align: center |
---|
305 | :alt: Reconfigure console output |
---|
306 | |
---|
307 | We can now build RTEMS using Eclipse. Right click on the project name |
---|
308 | ``rtems-git`` and then select **Build Project** : |
---|
309 | |
---|
310 | .. figure:: ../images/eclipse/eclipse-rtems-git-build-project.png |
---|
311 | :width: 100% |
---|
312 | :align: center |
---|
313 | :alt: Reconfigure the RTEMS Project |
---|
314 | |
---|
315 | A **Build Project** message box will appear showing the progress: |
---|
316 | |
---|
317 | .. figure:: ../images/eclipse/eclipse-rtems-git-build-project-building.png |
---|
318 | :width: 75% |
---|
319 | :align: center |
---|
320 | :alt: Reconfigure the RTEMS Project |
---|
321 | |
---|
322 | When finished click on the **Problems** output tab to view any errors or warnings: |
---|
323 | |
---|
324 | .. figure:: ../images/eclipse/eclipse-rtems-git-built.png |
---|
325 | :width: 100% |
---|
326 | :align: center |
---|
327 | :alt: Reconfigure the RTEMS Project |
---|
328 | |
---|
329 | If you get errors during the configure phase or building you will need to |
---|
330 | determine reason why. The main source of errors will be the path to the |
---|
331 | tools. Check the top of the ``config.log`` file ``configure`` generates. This |
---|
332 | file can be found in the top directory of you BSP build tree. The file will |
---|
333 | list the path components near the top and you should see the path to your tools |
---|
334 | listed first. While looking make sure the configure command matches what you |
---|
335 | expect and matches the documentation for configuring RTEMS. |
---|
336 | |
---|
337 | If the contents of ``config.log`` look fine check the build log. The project's |
---|
338 | **Properties** dialog under **C/C++ Build**, **Logging** has a path to a build |
---|
339 | log. Open the build log and search for the error. If you cannot figure out the |
---|
340 | source of the error please ask on the :r:list:`users` for help. |
---|