diff options
34 files changed, 477 insertions, 0 deletions
diff --git a/eclipse/conf.py b/eclipse/conf.py new file mode 100644 index 0000000..0af2bde --- /dev/null +++ b/eclipse/conf.py @@ -0,0 +1,13 @@ +import sys, os +sys.path.append(os.path.abspath('../common/')) + +from conf import * + +version = '4.11.0' +release = '4.11.0' + +project = "RTEMS Eclipse Manual" + +latex_documents = [ + ('index', 'eclipse.tex', u'RTEMS Eclipse Manual', u'RTEMS Documentation Project', 'manual'), +] diff --git a/eclipse/glossary.rst b/eclipse/glossary.rst new file mode 100644 index 0000000..ab8f8dd --- /dev/null +++ b/eclipse/glossary.rst @@ -0,0 +1,65 @@ +..comment SPDX-License-Identifier: CC-BY-SA-4.0 + + +.. _glossary: + +Glossary +======== + +.. glossary:: + + Binutils + GNU Binary Utilities such as the assembler ``as``, linker ``ld`` and a + range of other tools used in the development of software. + + DLL + Dynamically Linker Library used on Windows. + + GCC + GNU Compiler Tool chain. It is the GNU C/C++ compiler, binutils and GDB. + + GDB + GNU Debugger + + MinGW + Minimal GNU system for Windows that lets GCC built programs use the + standard Windows operating system DLLs. It lets you build native Windows + programs with the GNU GCC compiler. + + MinGW64 + Minimal GNU system for 64bit Windows. MinGW64 is not the MinGW project. + + MSYS2 + Minimal System 2 is a fork of the MinGW project's MSYS tool and the MinGW + MSYS tool is a fork of Cygwin project. The Cygwin project provides a POSIX + emulation layer for Windows so POSIX software can run on Windows. MSYS is a + minimal version that is just enough to let ``configure`` scripts run. MSYS + has a simplied path structure to make it easier to building native Windows + programs. + + POSIX + Portable Operating System Interface is a standard that lets software be + portable between compliant operating systems. + + prefix + A path used when building a package so all parts of the package reside + under that path. + + RSB + RTEMS Source Builder is part of the RTEMS Tools Project. It builds packages + such as the tools for the RTEMS operating system. + + RTEMS + The Real-Time Executive for Multiprocessor Systems or RTEMS is a open + source fully featured Real Time Operating System or RTOS that supports a + variety of open standard application programming interfaces (API) and + interface standards such as POSIX and BSD sockets. + + Test Suite + See Testsuite + + Testsuite + RTEMS test suite located in the ``testsuites/`` directory. + + Waf + Waf build system. For more information see http://www.waf.io/ diff --git a/eclipse/index.rst b/eclipse/index.rst new file mode 100644 index 0000000..5e5f01b --- /dev/null +++ b/eclipse/index.rst @@ -0,0 +1,27 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. highlight:: c + +===================== +RTEMS Eclipse Manual. +===================== + +Table of Contents +----------------- + +.. toctree:: + :maxdepth: 3 + :numbered: + + overview + + rtems + + glossary + + +* :ref:`genindex` +* :ref:`search` diff --git a/eclipse/overview.rst b/eclipse/overview.rst new file mode 100644 index 0000000..29458e8 --- /dev/null +++ b/eclipse/overview.rst @@ -0,0 +1,26 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _overview: + +Overview +======== + +Welcome to the :ref:term:`RTEMS` Eclipse Manual. + +This document covers using Eclipse with RTEMS. + +RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive +(kernel) which provides a high performance environment for embedded +applications. + +Eclipse is an Integrated Development Environment (IDE) for a wide range of +languages and platforms. + +RTEMS's eco-system provides all the tools and capabilities to integrate with +Eclipse. You can build and develop RTEMS with Eclipse as well as build +applications with Eclipse. + +Unless otherwise stated this document refers to the Eclipse Mars release. diff --git a/eclipse/rtems.rst b/eclipse/rtems.rst new file mode 100644 index 0000000..dbb3f40 --- /dev/null +++ b/eclipse/rtems.rst @@ -0,0 +1,340 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org> +.. comment: All rights reserved. + +.. _rtems-development: + +RTEMS Development +================= + +RTEMS can be developed using Eclipse. The RTEMS kernel is an `autotools` or +`autoconf` and `automake` based package. You can create a project in Eclipse +that lets you configure and build a BSP for an architecture. We assume you have +already build and installed your tools using the RTEMS Source Builder. + +Kernel Source +------------- + +Download or clone the RTEMS Kernel source code. We will clone the source code: + +.. code-block:: shell + + $ git clone git://git.rtems.org/rtems.git rtems.master + Cloning into 'rtems'... + remote: Counting objects: 483342, done. + remote: Compressing objects: 100% (88974/88974), done. + remote: Total 483342 (delta 390053), reused 475669 (delta 383809) + Receiving objects: 100% (483342/483342), 69.88 MiB | 1.37 MiB/s, done. + Resolving deltas: 100% (390053/390053), done. + Checking connectivity... done. + +We need to `bootstrap` the kernel source code. A `botostrap` invokes the +various `autotools` commands need to generate build system files. First we need +to the path to our tools: + +.. code-block:: shell + + $ export PATH=/opt/rtems/4.12/bin:$PATH + +Now run the `bootstrap` command: + +.. code-block:: shell + + $ cd rtems.master + $ ./bootstrap + +Sit back, this can take a while. The Getting Started Guide talks about using +the RSB's `sb-bootstrap` to run the bootstrap process in parallel on all +available cores. The output of the bootstrap has not been copied into this +documentment. + +The source code is now ready. + +Eclipse SDK Software +-------------------- + +We need the following Eclipse SDK Software packages installed: + + - C/C++ Autotools support + - C/C++ Development Tools + - C/C++ GCC Cross Compiler Support + +Start Eclipse and check to see if you have the them installed via the **Help, +Installation Details** menu item: + +.. figure:: ../images/eclipse/eclipse-help-installation.png + :width: 50% + :align: center + :alt: Help, Installation Details + +The dialog box shows the installed software packages and you can see the +**C/C++ Autotools support** and the **C/C++ Development Tools** are installed: + +.. figure:: ../images/eclipse/eclipse-sdk-details.png + :align: center + :alt: SDK Installation Details + +You can see some other software packages are installed in the figure. You can ignore those. + +If you do not have the listed software packages install select **Help, Install +New Software** and in the **Work with:** list box select +**http://download.eclipse.org/releases/mars**. + +.. figure:: ../images/eclipse/eclipse-install-new-software.png + :width: 80% + :align: center + :alt: Help, Install New Software + +Afer a small period of time a list of available packages will populate and you +can select the ones we are interested in. Enter ``autotools`` in the search +box and select the package: + +.. figure:: ../images/eclipse/eclipse-autotools.png + :width: 80% + :align: center + :alt: C/C++ Autotools support + +Clear the search line and enter ``development tools`` in the search box and +then scroll down to find **C/C++ Development Tools**: + +.. figure:: ../images/eclipse/eclipse-cdt.png + :width: 80% + :align: center + :alt: C/C++ Development Tools + +Again clear the search line and enter ``gcc cross`` in the search box and +select the package: + +.. figure:: ../images/eclipse/eclipse-gcc-cross.png + :width: 80% + :align: center + :alt: C/C++ GCC Cross Compiler Support + +Click **Next** and once the **Install Details** have determined what is needed +select **Finish** to install the packages. + +Kernel Build Project +-------------------- + +We create a project in Eclipse that can configure and build RTEMS for the +``pc686`` BSP. This BSP is based on the ``pc386`` BSP and is under the ``i386`` +architecture. + +We assume you have built and installed the ``i386`` RTEMS Tools, obtained the +RTEMS kernel code and ``bootstrapped`` it if a git clone, and installed the +required Eclipse Software packages. + +The paths used in this project are: + +:file:`/opt/work/rtems/4.11` + The RTEMS Tools prefix the tools are install under. + +:file:`/opt/work/chris/rtems/kernel/rtems.master` + The RTEMS Kernel source code. + +:file:`/opt/work/chris/rtems/kernel/4.12` + The RTEMS Kernel prefix. + +:file:`/opt/work/chris/rtems/kernel/bsp/pc` + The RTEMS Kernel BSP build directory. + +The menus shown here may vary from those you have as Eclipse changes them based +on what you do. + +Select **File, New, Project** : + +.. figure:: ../images/eclipse/eclipse-new-project.png + :width: 100% + :align: center + :alt: File, New, Project... + +Click on **C/C++** and select **Makefile Project with Existing Code** then +select **Next** : + +.. figure:: ../images/eclipse/eclipse-project-makefile-existing-code.png + :width: 75% + :align: center + :alt: Makefile Project with Existing Code + +Enter the project name ``rtems-git`` into the **Project Name** field and select +the **Browse...** button and the path to the RTEMS Kernel source code then +click **Finish** : + +.. figure:: ../images/eclipse/eclipse-project-import-existing-code.png + :width: 75% + :align: center + :alt: Import Existing Code + +Eclipse will show the RTEMS Kernel source code in the **Project Explorer** panel: + +.. figure:: ../images/eclipse/eclipse-rtems-git-files.png + :width: 100% + :align: center + :alt: RTEMS GIT Project showing files + +We now convert the project to an Autotools project. Select **File, New, +Convert to a C/C++ Autotools Project** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-convert-autotools.png + :width: 100% + :align: center + :alt: Convert the project to Autotools + +Select **C Project** then **Finish** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-convert-autotools-dialog.png + :width: 85% + :align: center + :alt: Convert the project to Autotools + +We now configure the project's properties by right clicking on the +``rtems-git`` project title and then **Properties** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-properties-menu.png + :width: 100% + :align: center + :alt: + +Click on the **Autotools** item then **Configure Settings** and **Platform +specifiers** and set the **Target platform** field with ``i386-rtems4.12``: + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-target.png + :width: 100% + :align: center + :alt: Enter the Autotool target + +Select **Platform directories** and enter the **Arch-independent install +directory (--prefix)** to the RTEMS Kernel prefix of +:file:`/opt/work/chris/rtems/kernel/4.12`: + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-prefix.png + :width: 100% + :align: center + :alt: Enter the Autotool target + +We disable networking to use the external LibBSD package and set the BSP to +``pc686``. Select the **Advanced** and in the **Additional command-line +options** enter ``--disable-networking`` and ``--enable-rtemsbsps=pc686``. You +can add extra options you may need: + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-at-add-opts.png + :width: 100% + :align: center + :alt: Enter the Autotool additional options + +Select **C/C++ Build** and **Environment**. Uncheck or clear the **Use default +build command** and add ``-j N`` where ``N`` is the number of cores you have in +your machine. The figure has told `make` to run 8 jobs, one per core for an 8 +core machine. Click on the **File system...** button and navigate to the BSP +build directory. This is the location Eclipse builds the BSP. RTEMS requires +you build outside the source tree and in this example we are forcing the build +directory to something specific. Finish by pressing **Apply** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-build.png + :width: 100% + :align: center + :alt: C/C++ Build Properties + +Select **Environment** under **C/C++ Build** as we need to set the path to the +RTEMS Tools. In this example we set the path in the Eclipse project so each +project can have a specific set of tools. Press the **Add...** button: + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env.png + :width: 100% + :align: center + :alt: C/C++ Build Environment + +Enter the path to the tools, in our case it is +:file:`/opt/work/rtems/4.12/bin`, then press **Variables** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var.png + :width: 85% + :align: center + :alt: C/C++ Build Environment + +Scroll down and select **PATH** and then press **OK** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path.png + :width: 60% + :align: center + :alt: C/C++ Build Environment + +You will now see the path in the **Value:** field. Make sure you have a path +separator between the end of the tools path and the path variable we have just +added. In this case is a Unix host and the separator is `:`. Windows use +`;`. Press **OK** when you have a valid path: + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path-add.png + :width: 85% + :align: center + :alt: C/C++ Build Environment + +The **Environment** panel will now show the added `PATH` variable. Click +**Replace native environment with specified one** as shown and then press +**Apply** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-env-replace.png + :width: 100% + :align: center + :alt: C/C++ Build Environment + +Select **Settings** under **C/C++ Build** and check **Elf Parser** and **GNU +Elf Parser** and then press **OK** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-prop-cdt-settings.png + :width: 100% + :align: center + :alt: C/C++ Build Settings + +We are now ready to run configure using Eclipse. Right click on the project +name ``rtems-git`` and then **Reconfigure Project** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-reconfigure.png + :width: 100% + :align: center + :alt: Reconfigure the RTEMS Project + +Select the **Console** tab in the output panel to view the configure process +output. You will notice the end of the configure process shows the names of the +BSPs we have asked to build. In our case this is the ``pc686`` BSP: + +.. figure:: ../images/eclipse/eclipse-rtems-git-reconfigure-console.png + :width: 100% + :align: center + :alt: Reconfigure console output + +We can now build RTEMS using Eclipse. Right click on the project name +``rtems-git`` and then select **Build Project** : + +.. figure:: ../images/eclipse/eclipse-rtems-git-build-project.png + :width: 100% + :align: center + :alt: Reconfigure the RTEMS Project + +A **Build Project** message box will appear showing the progress: + +.. figure:: ../images/eclipse/eclipse-rtems-git-build-project-building.png + :width: 75% + :align: center + :alt: Reconfigure the RTEMS Project + +When finished click on the **Problems** output tab to view any errors or warnings: + +.. figure:: ../images/eclipse/eclipse-rtems-git-built.png + :width: 100% + :align: center + :alt: Reconfigure the RTEMS Project + +If you get errors during the configure phase or building you will need to +determine reason why. The main source of errors will be the path to the +tools. Check the top of the ``config.log`` file ``configure`` generates. This +file can be found in the top directory of you BSP build tree. The file will +list the path components near the top and you should see the path to your tools +listed first. While looking make sure the configure command matches what you +expect and matches the documentation for configuring RTEMS. + +If the contents of ``config.log`` look fine check the build log. The project's +**Properties** dialog under **C/C++ Build**, **Logging** has a path to a build +log. Open the build log and search for the error. If you cannot figure out the +source of the error please ask on the :r:list:`users` for help. diff --git a/eclipse/wscript b/eclipse/wscript new file mode 100644 index 0000000..4a5f474 --- /dev/null +++ b/eclipse/wscript @@ -0,0 +1,6 @@ +from sys import path +from os.path import abspath +path.append(abspath('../common/')) + +from waf import cmd_configure as configure, cmd_build as build, spell, cmd_spell, cmd_options as options, linkcheck, cmd_linkcheck + diff --git a/images/eclipse/eclipse-autotools.png b/images/eclipse/eclipse-autotools.png Binary files differnew file mode 100644 index 0000000..d04a138 --- /dev/null +++ b/images/eclipse/eclipse-autotools.png diff --git a/images/eclipse/eclipse-cdt.png b/images/eclipse/eclipse-cdt.png Binary files differnew file mode 100644 index 0000000..a0cb57d --- /dev/null +++ b/images/eclipse/eclipse-cdt.png diff --git a/images/eclipse/eclipse-gcc-cross.png b/images/eclipse/eclipse-gcc-cross.png Binary files differnew file mode 100644 index 0000000..8cc72e0 --- /dev/null +++ b/images/eclipse/eclipse-gcc-cross.png diff --git a/images/eclipse/eclipse-help-installation.png b/images/eclipse/eclipse-help-installation.png Binary files differnew file mode 100644 index 0000000..1572ce4 --- /dev/null +++ b/images/eclipse/eclipse-help-installation.png diff --git a/images/eclipse/eclipse-install-new-software.png b/images/eclipse/eclipse-install-new-software.png Binary files differnew file mode 100644 index 0000000..7f5d982 --- /dev/null +++ b/images/eclipse/eclipse-install-new-software.png diff --git a/images/eclipse/eclipse-new-project.png b/images/eclipse/eclipse-new-project.png Binary files differnew file mode 100644 index 0000000..b5ef677 --- /dev/null +++ b/images/eclipse/eclipse-new-project.png diff --git a/images/eclipse/eclipse-project-import-existing-code.png b/images/eclipse/eclipse-project-import-existing-code.png Binary files differnew file mode 100644 index 0000000..23e8d4f --- /dev/null +++ b/images/eclipse/eclipse-project-import-existing-code.png diff --git a/images/eclipse/eclipse-project-makefile-existing-code.png b/images/eclipse/eclipse-project-makefile-existing-code.png Binary files differnew file mode 100644 index 0000000..f3fa4fa --- /dev/null +++ b/images/eclipse/eclipse-project-makefile-existing-code.png diff --git a/images/eclipse/eclipse-rtems-git-build-project-building.png b/images/eclipse/eclipse-rtems-git-build-project-building.png Binary files differnew file mode 100644 index 0000000..33e9d3b --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-build-project-building.png diff --git a/images/eclipse/eclipse-rtems-git-build-project.png b/images/eclipse/eclipse-rtems-git-build-project.png Binary files differnew file mode 100644 index 0000000..79fa8a0 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-build-project.png diff --git a/images/eclipse/eclipse-rtems-git-built.png b/images/eclipse/eclipse-rtems-git-built.png Binary files differnew file mode 100644 index 0000000..45e0f40 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-built.png diff --git a/images/eclipse/eclipse-rtems-git-convert-autotools-dialog.png b/images/eclipse/eclipse-rtems-git-convert-autotools-dialog.png Binary files differnew file mode 100644 index 0000000..2ed3979 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-convert-autotools-dialog.png diff --git a/images/eclipse/eclipse-rtems-git-convert-autotools.png b/images/eclipse/eclipse-rtems-git-convert-autotools.png Binary files differnew file mode 100644 index 0000000..62d5bdb --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-convert-autotools.png diff --git a/images/eclipse/eclipse-rtems-git-files.png b/images/eclipse/eclipse-rtems-git-files.png Binary files differnew file mode 100644 index 0000000..0e5e78f --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-files.png diff --git a/images/eclipse/eclipse-rtems-git-prop-at-add-opts.png b/images/eclipse/eclipse-rtems-git-prop-at-add-opts.png Binary files differnew file mode 100644 index 0000000..6363f44 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-at-add-opts.png diff --git a/images/eclipse/eclipse-rtems-git-prop-at-prefix.png b/images/eclipse/eclipse-rtems-git-prop-at-prefix.png Binary files differnew file mode 100644 index 0000000..c4b21c6 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-at-prefix.png diff --git a/images/eclipse/eclipse-rtems-git-prop-at-target.png b/images/eclipse/eclipse-rtems-git-prop-at-target.png Binary files differnew file mode 100644 index 0000000..454bd6f --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-at-target.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-build.png b/images/eclipse/eclipse-rtems-git-prop-cdt-build.png Binary files differnew file mode 100644 index 0000000..1457d08 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-build.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-env-replace.png b/images/eclipse/eclipse-rtems-git-prop-cdt-env-replace.png Binary files differnew file mode 100644 index 0000000..b9c3ea8 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-env-replace.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path-add.png b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path-add.png Binary files differnew file mode 100644 index 0000000..80e99c1 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path-add.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path.png b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path.png Binary files differnew file mode 100644 index 0000000..52ef22c --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var-path.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-env-var.png b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var.png Binary files differnew file mode 100644 index 0000000..030e826 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-env-var.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-env.png b/images/eclipse/eclipse-rtems-git-prop-cdt-env.png Binary files differnew file mode 100644 index 0000000..089862b --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-env.png diff --git a/images/eclipse/eclipse-rtems-git-prop-cdt-settings.png b/images/eclipse/eclipse-rtems-git-prop-cdt-settings.png Binary files differnew file mode 100644 index 0000000..a566669 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-prop-cdt-settings.png diff --git a/images/eclipse/eclipse-rtems-git-properties-menu.png b/images/eclipse/eclipse-rtems-git-properties-menu.png Binary files differnew file mode 100644 index 0000000..33745ba --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-properties-menu.png diff --git a/images/eclipse/eclipse-rtems-git-reconfigure-console.png b/images/eclipse/eclipse-rtems-git-reconfigure-console.png Binary files differnew file mode 100644 index 0000000..fd219bc --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-reconfigure-console.png diff --git a/images/eclipse/eclipse-rtems-git-reconfigure.png b/images/eclipse/eclipse-rtems-git-reconfigure.png Binary files differnew file mode 100644 index 0000000..504daf6 --- /dev/null +++ b/images/eclipse/eclipse-rtems-git-reconfigure.png diff --git a/images/eclipse/eclipse-sdk-details.png b/images/eclipse/eclipse-sdk-details.png Binary files differnew file mode 100644 index 0000000..c8eafe4 --- /dev/null +++ b/images/eclipse/eclipse-sdk-details.png |
