From f6720264ea8ebfdd3a6b7819650520a2d18e7c31 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 12 Mar 2020 15:13:39 +1100 Subject: 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 --- user/start/app.rst | 245 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 242 insertions(+), 3 deletions(-) (limited to 'user/start/app.rst') 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 `_ 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 +`_. + +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 + + #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 + +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 + #include + #include + + 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." -- cgit v1.2.3