source: rtems-docs/user/start/app.rst

Last change on this file was 6baa2d6, checked in by Utkarsh Verma <utkarsh@…>, on 03/23/23 at 03:40:47

bsp-howto: Fix grammar and improve coherence.
  • Property mode set to 100644
File size: 8.9 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020 Chris Johns
4
5.. _QuickStartAPP:
6
7Build Your Application
8======================
9
10You tested a BSP in the previous section.  We built the ``erc32`` BSP
11and it is installed under :file:`$HOME/quick-start/rtems/@rtems-ver-major@`.
12
13We will now create a simple Hello World application with a Git
14repository and using the `Waf <https://waf.io>`_ build system.
15
16The application is be created in :file:`$HOME/quick-start/app/hello`.
17
18In the output in this section the base directory :file:`$HOME/quick-start` was
19replaced by ``$BASE``.
20
21The steps in this section assume you are in the directory
22:file:`$HOME/quick-start/app/hello` after the first step changes to
23it.
24
25Setup the application work space. Create a new Git repository, download
26the Waf build system, and the `RTEMS Waf
27<https://git.rtems.org/rtems_waf.git/tree/README>`_.
28
29Create the application directory and change into it:
30
31.. code-block:: none
32
33    mkdir -p $HOME/quick-start/app/hello
34    cd $HOME/quick-start/app/hello
35
36Download the Waf build system and set it to executable:
37
38.. code-block:: none
39
40    curl https://waf.io/waf-2.0.19 > waf
41    chmod +x waf
42
43Initialise a new Git repository:
44
45.. code-block:: none
46
47    git init
48
49Add RTEMS Waf support as a Git sub-module and initialise it:
50
51.. code-block:: none
52
53    git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
54
55Create the application source files. Three files are created with an
56editor of your choice.
57
58First create a C file that configures RTEMS. Using an editor create a
59file called :file:`init.c` and copy the following configuration
60settings:
61
62.. code-block:: c
63
64    /*
65     * Simple RTEMS configuration
66     */
67
68    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
69    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
70
71    #define CONFIGURE_UNLIMITED_OBJECTS
72    #define CONFIGURE_UNIFIED_WORK_AREAS
73
74    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
75
76    #define CONFIGURE_INIT
77
78    #include <rtems/confdefs.h>
79
80Create the Hello World application source file. Using an editor
81create :file:`hello.c` and copy the follow code:
82
83.. code-block:: c
84
85    /*
86     * Hello world example
87     */
88    #include <rtems.h>
89    #include <stdlib.h>
90    #include <stdio.h>
91
92    rtems_task Init(
93      rtems_task_argument ignored
94    )
95    {
96      printf( "\nHello World\n" );
97      exit( 0 );
98    }
99
100Finally create the Waf script. Using an editor create :file:`wscript`
101and copy the Waf script:
102
103.. code-block:: python
104
105    #
106    # Hello world Waf script
107    #
108    from __future__ import print_function
109
110    rtems_version = "6"
111
112    try:
113        import rtems_waf.rtems as rtems
114    except:
115        print('error: no rtems_waf git submodule')
116        import sys
117        sys.exit(1)
118
119    def init(ctx):
120        rtems.init(ctx, version = rtems_version, long_commands = True)
121
122    def bsp_configure(conf, arch_bsp):
123        # Add BSP specific configuration checks
124        pass
125
126    def options(opt):
127        rtems.options(opt)
128
129    def configure(conf):
130        rtems.configure(conf, bsp_configure = bsp_configure)
131
132    def build(bld):
133        rtems.build(bld)
134
135        bld(features = 'c cprogram',
136            target = 'hello.exe',
137            cflags = '-g -O2',
138            source = ['hello.c',
139                      'init.c'])
140
141Configure the application using Waf's ``configure`` command:
142
143.. code-block:: none
144
145    ./waf configure --rtems=$HOME/quick-start/rtems/6 --rtems-bsp=sparc/erc32
146
147The output will be something close to:
148
149.. code-block:: none
150
151     Setting top to                           : $BASE/app/hello
152     Setting out to                           : $BASE/app/hello/build
153     RTEMS Version                            : @rtems-ver-major@
154     Architectures                            : sparc-rtems@rtems-ver-major@
155     Board Support Package (BSP)              : sparc-rtems@rtems-ver-major@-erc32
156     Show commands                            : no
157     Long commands                            : no
158     Checking for program 'sparc-rtems@rtems-ver-major@-gcc'  : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
159     Checking for program 'sparc-rtems@rtems-ver-major@-g++'  : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
160     Checking for program 'sparc-rtems@rtems-ver-major@-gcc'  : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
161     Checking for program 'sparc-rtems@rtems-ver-major@-ld'   : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld
162     Checking for program 'sparc-rtems@rtems-ver-major@-ar'   : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
163     Checking for program 'sparc-rtems@rtems-ver-major@-nm'   : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-nm
164     Checking for program 'sparc-rtems@rtems-ver-major@-objdump' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objdump
165     Checking for program 'sparc-rtems@rtems-ver-major@-objcopy' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objcopy
166     Checking for program 'sparc-rtems@rtems-ver-major@-readelf' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-readelf
167     Checking for program 'sparc-rtems6-strip'   : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-strip
168     Checking for program 'sparc-rtems6-ranlib'  : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ranlib
169     Checking for program 'rtems-ld'             : $BASE/rtems/@rtems-ver-major@/bin/rtems-ld
170     Checking for program 'rtems-tld'            : $BASE/rtems/@rtems-ver-major@/bin/rtems-tld
171     Checking for program 'rtems-syms'           : $BASE/rtems/@rtems-ver-major@/bin/rtems-syms
172     Checking for program 'rtems-bin2c'          : $BASE/rtems/@rtems-ver-major@/bin/rtems-bin2c
173     Checking for program 'tar'                  : /usr/bin/tar
174     Checking for program 'gcc, cc'              : $BASE/rtems/6/bin/sparc-rtems6-gcc
175     Checking for program 'ar'                   : $BASE/rtems/6/bin/sparc-rtems6-ar
176     Checking for program 'g++, c++'             : $BASE/rtems/6/bin/sparc-rtems6-g++
177     Checking for program 'ar'                   : $BASE/rtems/6/bin/sparc-rtems6-ar
178     Checking for program 'gas, gcc'             : $BASE/rtems/6/bin/sparc-rtems6-gcc
179     Checking for program 'ar'                   : $BASE/rtems/6/bin/sparc-rtems6-ar
180     Checking for c flags '-MMD'                 : yes
181     Checking for cxx flags '-MMD'               : yes
182     Compiler version (sparc-rtems@rtems-ver-major@-gcc)         : 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
183     Checking for a valid RTEMS BSP installation : yes
184     Checking for RTEMS_DEBUG                    : no
185     Checking for RTEMS_MULTIPROCESSING          : no
186     Checking for RTEMS_NEWLIB                   : yes
187     Checking for RTEMS_POSIX_API                : no
188     Checking for RTEMS_SMP                      : no
189     Checking for RTEMS_NETWORKING               : no
190     'configure' finished successfully (1.142s)
191Build the application:
192
193.. code-block:: none
194
195    ./waf
196
197The output will be something close to:
198
199.. code-block:: none
200
201    Waf: Entering directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32'
202    [1/3] Compiling init.c
203    [2/3] Compiling hello.c
204    [3/3] Linking build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
205    Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32'
206    'build-sparc-rtems@rtems-ver-major@-erc32' finished successfully (0.183s)
207
208Run the executable:
209
210.. code-block:: none
211
212    rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
213
214The output will be something close to:
215
216.. code-block:: none
217
218    RTEMS Testing - Run, @rtems-ver-mjminrev@
219    Command Line: $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
220    Host: Linux  5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64
221    Python: 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0]
222    Host: Linux-5.8.0-44-generic-x86_64-with-glibc2.29 (Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 x86_64)
223
224    SIS - SPARC/RISCV instruction simulator 2.26,  copyright Jiri Gaisler 2020
225    Bug-reports to jiri@gaisler.se
226
227    ERC32 emulation enabled
228
229    Loaded build/sparc-rtems@rtems-ver-major@-erc32/hello.exe, entry 0x02000000
230
231    Hello World
232
233    *** FATAL ***
234    fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT)
235    fatal code: 0 (0x00000000)
236    RTEMS version: 6.0.0.586e06ec6222f1cd1f005aa8f4a34a8b33f5d862
237    RTEMS tools: 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
238    executing thread ID: 0x08a010001
239    executing thread name: UI1
240    cpu 0 in error mode (tt = 0x101)
241    158479  0200d500:  91d02000   ta  0x0
242    Run time     : 0:00:00.259136
243
244Commit the application to the repository:
245
246.. code-block:: none
247
248    git add init.c hello.c wscript
249    git commit -m "My first RTEMS application."
Note: See TracBrowser for help on using the repository browser.