summaryrefslogtreecommitdiffstats
path: root/user/start/app.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2020-03-12 15:13:39 +1100
committerChris Johns <chrisj@rtems.org>2020-03-13 08:18:36 +1100
commitf6720264ea8ebfdd3a6b7819650520a2d18e7c31 (patch)
tree77191c2d15ae58fc35b51d07c4c7e0b80ecd2c4d /user/start/app.rst
parent88dd013b42bc731e1892802eefe1768ccbd5898d (diff)
downloadrtems-docs-f6720264ea8ebfdd3a6b7819650520a2d18e7c31.tar.bz2
user: Update Quick Start Guide
- Add support for release source archives - Add building the BSP using the RSB - Add building packages using the RSB - Add an application Closes #2998
Diffstat (limited to '')
-rw-r--r--user/start/app.rst245
1 files changed, 242 insertions, 3 deletions
diff --git a/user/start/app.rst b/user/start/app.rst
index fdf6bb7..98fb284 100644
--- a/user/start/app.rst
+++ b/user/start/app.rst
@@ -1,11 +1,250 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
.. _QuickStartAPP:
Build Your Application
======================
-TODO
+You tested a BSP in the previous section. We built the ``erc32`` BSP
+and it is installed under :file:`$HOME/quick-start/rtems/5`.
+
+We will now create a simple hello world application with a Git
+repository and using the `Waf <https://waf.io>`_ build system.
+
+The application is be created in :file:`$HOME/quick-start/app/hello`.
+
+In the output in this section the base directory :file:`$HOME/quick-start` was
+replaced by ``$BASE``.
+
+The steps in this section assume you are in the directory
+:file:`$HOME/quick-start/app/hello` after the first step changes to
+it.
+
+Setup the application work space. Create a new Git repository, download
+the Waf build system, and the `RTEMS Waf
+<https://git.rtems.org/rtems_waf.git/tree/README>`_.
+
+Create the application directory and change into it:
+
+.. code-block:: none
+
+ mkdir -p $HOME/quick-start/app/hello
+ cd $HOME/quick-start/app/hello
+
+Download the Waf build system and set it to executable:
+
+.. code-block:: none
+
+ curl https://waf.io/waf-2.0.19 > waf
+ chmod +w waf
+
+Initialise a new Git repository:
+
+.. code-block:: none
+
+ git init
+
+Add RTEMS Waf support as a Git sub-module and initialise it:
+
+.. code-block:: none
+
+ git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
+
+Create the application source files. Three files are created with an
+editor of your choice.
+
+First create a C file that configures RTEMS. Using an editor create a
+file called :file:`init.c` and copy the following configuration
+settings:
+
+.. code-block:: c
+
+ /*
+ * Simple RTEMS configuration
+ */
+ #include <rtems.h>
+
+ #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+ #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+ #define CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
+
+ #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+ #define CONFIGURE_MAXIMUM_TASKS 1
+
+ #define CONFIGURE_INIT
+
+ #include <rtems/confdefs.h>
+
+Create the *hello world* application source file. Using an editor
+create :file:`hello.c` and copy the follow code:
+
+.. code-block:: c
+
+ /*
+ * Hello world example
+ */
+ #include <rtems.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+
+ rtems_task Init(
+ rtems_task_argument ignored
+ )
+ {
+ printf( "\nHello World\n" );
+ exit( 0 );
+ }
+
+Finally create the Waf script. Using an editor create :file:`wscript`
+and copy the Waf script:
+
+.. code-block:: python
+
+ #
+ # Hello world Waf script
+ #
+ from __future__ import print_function
+
+ rtems_version = "5"
+
+ try:
+ import rtems_waf.rtems as rtems
+ except:
+ print('error: no rtems_waf git submodule')
+ import sys
+ sys.exit(1)
+
+ def init(ctx):
+ rtems.init(ctx, version = rtems_version, long_commands = True)
+
+ def bsp_configure(conf, arch_bsp):
+ # Add BSP specific configuration checks
+ pass
+
+ def options(opt):
+ rtems.options(opt)
+
+ def configure(conf):
+ rtems.configure(conf, bsp_configure = bsp_configure)
+
+ def build(bld):
+ rtems.build(bld)
+
+ bld(features = 'c cprogram',
+ target = 'hello.exe',
+ cflags = '-g -O2',
+ source = ['hello.c',
+ 'init.c'])
+
+Configure the application using Waf's ``configure`` command:
+
+.. code-block:: none
+
+ ./waf configure --rtems=$HOME/quick-start/rtems/5 --rtems-bsp=sparc/erc32
+
+The output will be something close to:
+
+.. code-block:: none
+
+ Setting top to : $BASE/app/hello
+ Setting out to : $BASE/app/hello/build
+ RTEMS Version : 5
+ Architectures : sparc-rtems5
+ Board Support Package (BSP) : sparc-rtems5-erc32
+ Show commands : no
+ Long commands : no
+ Checking for program 'sparc-rtems5-gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
+ Checking for program 'sparc-rtems5-g++' : $BASE/rtems/5/bin/sparc-rtems5-g++
+ Checking for program 'sparc-rtems5-gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
+ Checking for program 'sparc-rtems5-ld' : $BASE/rtems/5/bin/sparc-rtems5-ld
+ Checking for program 'sparc-rtems5-ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
+ Checking for program 'sparc-rtems5-nm' : $BASE/rtems/5/bin/sparc-rtems5-nm
+ Checking for program 'sparc-rtems5-objdump' : $BASE/rtems/5/bin/sparc-rtems5-objdump
+ Checking for program 'sparc-rtems5-objcopy' : $BASE/rtems/5/bin/sparc-rtems5-objcopy
+ Checking for program 'sparc-rtems5-readelf' : $BASE/rtems/5/bin/sparc-rtems5-readelf
+ Checking for program 'sparc-rtems5-strip' : $BASE/rtems/5/bin/sparc-rtems5-strip
+ Checking for program 'sparc-rtems5-ranlib' : $BASE/rtems/5/bin/sparc-rtems5-ranlib
+ Checking for program 'rtems-ld' : $BASE/rtems/5/bin/rtems-ld
+ Checking for program 'rtems-tld' : $BASE/rtems/5/bin/rtems-tld
+ Checking for program 'rtems-syms' : $BASE/rtems/5/bin/rtems-syms
+ Checking for program 'rtems-bin2c' : $BASE/rtems/5/bin/rtems-bin2c
+ Checking for program 'tar' : /usr/bin/tar
+ Checking for program 'gcc, cc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
+ Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
+ Checking for program 'g++, c++' : $BASE/rtems/5/bin/sparc-rtems5-g++
+ Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
+ Checking for program 'gas, gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
+ Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
+ Checking for c flags '-MMD' : yes
+ Checking for cxx flags '-MMD' : yes
+ Compiler version (sparc-rtems5-gcc) : 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
+ Checking for a valid RTEMS BSP installation : yes
+ Checking for RTEMS_DEBUG : no
+ Checking for RTEMS_MULTIPROCESSING : no
+ Checking for RTEMS_NEWLIB : yes
+ Checking for RTEMS_POSIX_API : yes
+ Checking for RTEMS_SMP : no
+ Checking for RTEMS_NETWORKING : no
+ 'configure' finished successfully (0.686s)
+
+Build the application:
+
+.. code-block:: none
+
+ ./waf
+
+The output will be something close to:
+
+.. code-block:: none
+
+ Waf: Entering directory `$BASE/app/hello/build/sparc-rtems5-erc32'
+ [1/3] Compiling init.c
+ [2/3] Compiling hello.c
+ [3/3] Linking build/sparc-rtems5-erc32/hello.exe
+ Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems5-erc32'
+ 'build-sparc-rtems5-erc32' finished successfully (0.183s)
+
+Run the executable:
+
+.. code-block:: none
+
+ $HOME/quick-start/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
+
+The output will be something close to:
+
+.. code-block:: none
+
+ RTEMS Testing - Run, 5.1.0
+ Command Line: $BASE/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
+ Host: FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64
+ Python: 3.7.6 (default, Jan 30 2020, 01:18:54) [Clang 6.0.1 (tags/RELEASE_601/final 335540)]
+ Host: FreeBSD-12.1-RELEASE-p2-amd64-64bit-ELF (FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64 amd64)
+
+ SIS - SPARC/RISCV instruction simulator 2.21, copyright Jiri Gaisler 2019
+ Bug-reports to jiri@gaisler.se
+
+ ERC32 emulation enabled
+
+ Loaded build/sparc-rtems5-erc32/hello.exe, entry 0x02000000
+
+ Hello World
+
+ *** FATAL ***
+ fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT)
+ fatal code: 0 (0x00000000)
+ RTEMS version: 5.1.0
+ RTEMS tools: 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
+ executing thread ID: 0x08a010001
+ executing thread name: UI1
+ cpu 0 in error mode (tt = 0x101)
+ 107883 0200b6c0: 91d02000 ta 0x0
+ Run time : 0:00:01.011474
+
+Commit the application to the repository:
+
+.. code-block:: none
+
+ git add init.c hello.c wscript
+ git commit -m "My first RTEMS application."