[PATCH] user/app: Add a simple Makefile example.

chrisj at rtems.org chrisj at rtems.org
Mon Apr 1 03:29:18 UTC 2019


From: Chris Johns <chrisj at rtems.org>

Closes #3729
---
 user/start/app.rst | 223 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 220 insertions(+), 3 deletions(-)

diff --git a/user/start/app.rst b/user/start/app.rst
index fdf6bb7..0f2dda1 100644
--- a/user/start/app.rst
+++ b/user/start/app.rst
@@ -1,11 +1,228 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2019 Chris Johns <chrisj at rtems.org>
 
 .. _QuickStartAPP:
 
 Build Your Application
 ======================
 
-TODO
+Building an RTEMS application requires you:
+
+#. Create a C file containing the initialisation of RTEMS. This is detailed in
+   the RTEMS Classic API Guide's section Configuring a System.
+
+#. Use the architecture specific compiler, ``CFLAGS`` for the BSP you are
+   building the application for. Your application needs to be built for each
+   BSP, you cannot share object code or libraries between different BSPs.
+
+#. The ``pkg-config`` command is installed on your host.
+
+The prefix used in the Quick Start guide is ``$HOME/quick-start/rtems/5``. The
+last step of :ref:`QuickStartBSPBuild` installs RTEMS under the prefix
+path. This is important as it copies the header files, libraries and other
+files needed to build an application to standard paths under the prefix path.
+
+The BSP architecture determines the name of the compiler you use. RTEMS
+provides a compiler for each architecture. A BSP further specialises the
+architecture to the specific instruction set and configuration to match the
+hardware the RTEMS executable is run on. The compilers are built for RTEMS
+maping some internal aspects of the compiler to RTEMS.
+
+RTEMS provide a ``pkg-config`` file for each installed BSP. The ``pkg-config``
+files holds the BSP specific settings you can use to build an
+application. The files can be listed with:
+
+.. code-block:: none
+
+  $ echo $HOME
+  $ /home/chris
+  $ find $HOME/quick-start/rtems/5 -name \*.pc
+  /home/chris/quick-start/rtems/5/lib/pkgconfig/sparc-rtems5-erc32.pc
+
+In thie case the ``pkg-config`` files are installed under
+``$HOME/quick-start/rtems/5/pkgconfig``. We are building the ERC32 BSP so the
+``pkg-config`` file we are interested in is ``sparc-rtems5-erc32``.
+
+
+The ``pkg-config`` command can be used to list variables provided:
+
+.. code-block:: none
+
+  pkg-config --with-path= $HOME/quick-start/rtems/5 sparc-rtems5-erc32 --print-variables
+
+You can set the environment variable ``PKG_CONFIG_PATH`` and the
+``--with--path`` options can be removed:
+
+.. code-block:: none
+
+  export PKG_CONFIG_PATH=$HOME/quick-start/rtems/5:$PKG_CONFIG_PATH
+
+Again listing the variables:
+
+.. code-block:: none
+
+  pkg-config sparc-rtems5-erc32 --print-variables
+
+The results are:
+
+.. code-block:: none
+
+  CFLAGS
+  RTEMS_CPU
+  RTEMS_BSP
+  LD
+  CXX
+  CC
+  AS
+  target
+  includedir
+  libdir
+  exec_prefix
+  prefix
+  pcfiledir
+
+The following commands assume the ``PKG_CONFIG_PATH`` is set.
+
+To obtain the target:
+
+.. code-block:: none
+
+  pkg-config sparc-rtems5-erc32 --variable=target
+  sparc-rtems5
+
+The target can used as the executable prefix for some of the tools. For
+example to create a suitable ``objcopy`` command in a shell you can:
+
+  echo `pkg-config sparc-rtems5-erc32 --variable=target`-objdump
+  sparc-rtems5-objdump
+
+There are variables for the C and C++ compilers and the linker:
+
+.. code-block:: none
+
+  $ pkg-config sparc-rtems5-erc32 --variable=CC
+  sparc-rtems5-gcc --pipe
+  $ pkg-config sparc-rtems5-erc32 --variable=CXX
+  sparc-rtems5-g++
+
+The ``CFLAGS`` are listed with the ``--cflagfs`` option:
+
+.. code-block:: none
+
+  pkg-config sparc-rtems5-erc32 --cflags
+
+The flags with a ``$HOME`` of ``/home/chris`` are:
+
+.. code-block:: none
+
+  -qrtems -B/home/chris/quick-start/rtems/5/sparc-rtems5/lib/ \
+  -B/home/chris/quick-start/rtems/5/sparc-rtems5/erc32/lib/ --specs bsp_specs \
+  -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes \
+  -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs
+
+Note, the flags exported from RTEMS contain the warning setting for
+RTEMS. These may need to be stripped from the flags you use to as the code you
+are compiling may have some warnings.
+
+Example
+*******
+
+The following C file is a basic initialisation for a simple example
+program. It prints a message and then exits. Copy this to a file called ``init.c``:
+
+.. code-block:: c
+
+ /* Basic RTEMS initialisation */
+
+ #include <stdio.h>
+
+ #include <rtems.h>
+
+ static rtems_task Init(rtems_task_argument ignored)
+ {
+   printf("---------------------------\n\n");
+   printf("User manual example program\n\n");
+   printf("---------------------------\n");
+   rtems_shutdown_executive(0);
+ }
+
+ /* NOTICE: the clock driver is explicitly disabled */
+
+ #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+ #define CONFIGURE_APPLICATION_NEEDS_SIMPLE_CONSOLE_DRIVER
+ #define CONFIGURE_MAXIMUM_TASKS                           1
+ #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+ #define CONFIGURE_INIT_TASK_ATTRIBUTES                    RTEMS_FLOATING_POINT
+
+ #define CONFIGURE_INIT
+
+ #include <rtems/confdefs.h>
+
+Copy the following ``Makefile`` to a file called ``Makefile`` in the same
+directory as the ``init.c``:
+
+.. code-block:: make
+
+  #
+  # Example Makefile. This is a simple as it can be.
+  #
+
+  EXE = example
+
+  prefix = $(HOME)/quick-start/rtems/5
+
+  BSP = sparc-rtems5-erc32
+
+  RTEMS_LIBS = -lrtemsbsp -lrtemscpu
+
+  CC     = $(shell pkg-config --with-path=$(prefix) $(BSP) --variable=CC)
+  CFLAGS = $(shell pkg-config --with-path=$(prefix) $(BSP) --cflags)
+
+  all: ${EXE}.exe
+
+  $(EXE).exe: init.o
+          $(CC) $(CFLAGS) -o $@ $^
+
+  %.o: %.c
+          $(CC) $(CFLAGS) -c -o $@ $<
+
+  clean:
+          rm -f *.exe *.o
+
+The ``Makefile`` calls ``pkg-config`` to get the compiler name and ``CFLAGS``
+and then uses them to compile then link ``init.c`` to create ``example.exe``.
+
+Set the path to the compler:
+
+.. code-block:: none
+
+  export PATH=$HOME/quick-start/rtems/5/bin:$PATH
+
+Run make:
+
+.. code-block:: none
+
+  $ gmake
+  sparc-rtems5-gcc --pipe -qrtems -B/home/chris/quick-start/rtems/5/sparc-rtems5/lib/ -B/home/chris/quick-start/rtems/5/sparc-rtems5/erc32/lib/ --specs bsp_specs -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs  -c -o init.o init.c
+  sparc-rtems5-gcc --pipe -qrtems -B/home/chris/quick-start/rtems/5/sparc-rtems5/lib/ -B/home/chris/quick-start/rtems/5/sparc-rtems5/erc32/lib/ --specs bsp_specs -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs  -o example.exe init.o
+
+The RTEMS can be run using the ``rtems-run`` command:
+
+.. code-block:: none
+
+  $ rtems-run --rtems-bsp=erc32 example.exe
+  RTEMS Testing - Run, 5.0.not_released
+   Command Line: /opt/work/rtems/5/bin/rtems-run --rtems-bsp=erc32 example.exe
+   Python: 3.6.6 (default, Oct  2 2018, 01:22:29) [GCC 4.2.1 Compatible FreeBSD Clang 6.0.0 (tags/RELEASE_600/final 326565)]
+  Host: FreeBSD-12.0-RELEASE-p3-amd64-64bit-ELF (FreeBSD ruru 12.0-RELEASE-p3 FreeBSD 12.0-RELEASE-p3 GENERIC amd64 amd64)
+  ---------------------------
+  User manual example program
+  ---------------------------
+  *** FATAL ***
+  fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT)
+  fatal code: 0 (0x00000000)
+  RTEMS version: 5.0.0.294c6f46a627b06409ee469f4d3a472086a2d76f-modified
+  RTEMS tools: 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
+  executing thread ID: 0x08a010001
+  Run time     : 0:00:01.070216
-- 
2.19.1



More information about the devel mailing list