From: Chris Johns <chr...@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 <chr...@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
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
