source: rtems-libbsd/README.waf @ f092186

55-freebsd-126-freebsd-12
Last change on this file since f092186 was 854427b, checked in by Christian Mauderer <christian.mauderer@…>, on 04/06/18 at 08:35:42

waf: Add configurations with different modules.

Update #3351

  • Property mode set to 100644
File size: 7.7 KB
Line 
1RTEMS LibBSD Waf
2~~~~~~~~~~~~~~~~
3
4Welcome to building LibBSD for RTEMS using Waf. This package is a library
5containing various parts of the FreeBSD kernel ported to RTEMS. The library
6replaces the networking port of FreeBSD in the RTEMS kernel sources. This
7package is designed to be updated from the FreeBSD kernel sources and contains
8more than just the networking code.
9
10To build this package you need a current RTEMS tool set for your architecture,
11and a recent RTEMS kernel for your BSP configured with networking disabled
12built and installed. If you already have this you can skip to step 3 of the
13build procedure.
14
15Waf Setup
16~~~~~~~~~
17
18You can find the Waf project at:
19
20 https://waf.io/
21
22Waf is not intended to be installed by distribution packages so we recommend
23you download a recent waf version and install it in your home directory.
24
25Waf is a Python program so you will also need to have a current Python version
26installed and in your path.
27
28Download the latest signed executable file version to $HOME/bin and symlink it
29to waf. Add the directory $HOME/bin to your path if it is not already in your
30default path.
31
32Building and Installing LibBSD
33~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34
35The following instructions show you how to build and install RTEMS Tools and
36RTEMS kernel for your BSP in separate paths. Using separate paths for the tools
37and BSPs lets you manage what you have installed. If you are happy with a
38single path you can use the same path in each stage.
39
40The waf build support for RTEMS requires you provide your BSP name as an
41architecture and BSP pair. You must provide both or waf will generate an error
42message during the configure phase.
43
44We will build an Xilinx Zynq QEMU BSP using the name
45'arm/xilinx_zynq_a9_qemu'.
46
47Steps
48-----
49
50-------------------------------------------------------------------------------
51sandbox="$PWD/sandbox"
52mkdir sandbox
53cd "$sandbox"
54git clone git://git.rtems.org/rtems-source-builder.git
55git clone git://git.rtems.org/rtems.git
56git clone git://git.rtems.org/rtems-libbsd.git
57cd "$sandbox"
58cd rtems-source-builder/rtems
59../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm
60cd "$sandbox"
61cd rtems
62PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap
63cd "$sandbox"
64mkdir b-xilinx_zynq_a9_qemu
65cd b-xilinx_zynq_a9_qemu
66PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \
67  --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \
68  --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu
69PATH="$sandbox/rtems-4.12/bin:$PATH" make
70PATH="$sandbox/rtems-4.12/bin:$PATH" make install
71cd "$sandbox"
72cd rtems-libbsd
73git submodule init
74git submodule update rtems_waf
75waf configure --prefix="$sandbox/rtems-4.12" \
76  --rtems-bsps=arm/xilinx_zynq_a9_qemu \
77  --buildset=buildset/default.ini
78waf
79waf install
80qemu-system-arm -no-reboot -serial null -serial mon:stdio -net none \
81  -nographic -M xilinx-zynq-a9 -m 256M \
82  -kernel build/arm-rtems4.12-xilinx_zynq_a9_qemu/selectpollkqueue01.exe
83-------------------------------------------------------------------------------
84
851. Create a sandbox directory:
86
87    $ sandbox="$PWD/sandbox"
88    $ mkdir sandbox
89
901. Clone the repositories:
91
92    $ cd "$sandbox"
93    $ git clone git://git.rtems.org/rtems-source-builder.git
94    $ git clone git://git.rtems.org/rtems.git
95    $ git clone git://git.rtems.org/rtems-libbsd.git
96
972. Build and install the tools. In this example the path is
98   $sandbox/rtems-4.12:
99
100    $ cd "$sandbox"
101    $ cd rtems-source-builder/rtems
102    $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm
103
1043. Bootstrap the RTEMS sources:
105
106    $ cd "$sandbox"
107    $ cd rtems
108    $ PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap
109
1105. Build and install the RTEMS Board Support Packages (BSP) you want to use. In
111   this example the path is /opt/rtems/4.12/bsps:
112
113    $ cd "$sandbox"
114    $ mkdir b-xilinx_zynq_a9_qemu
115    $ cd b-xilinx_zynq_a9_qemu
116    $ PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \
117        --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \
118        --disable-networking --enable-rtemsbsp=xilinx_zynq_a9_qemu
119    $ PATH="$sandbox/rtems-4.12/bin:$PATH" make
120    $ PATH="$sandbox/rtems-4.12/bin:$PATH" make install
121
1226. Populate the rtems_waf git submodule.  Note, make sure you specify
123   'rtems_waf' or the FreeBSD kernel source will be cloned:
124
125   $ cd "$sandbox"
126   $ cd rtems-libbsd
127   $ git submodule init
128   $ git submodule update rtems_waf
129
1307. Run Waf's configure with your specific settings. In this case the path to
131   the tools and RTEMS are provided on the command line and so do not need to
132   be in your path or environment [1].  You can use
133   '--rtems-archs=arm,sparc,i386' or
134   '--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586' to build for
135   more than BSP at a time.  Note, you must provide the architecture and BSP as
136   a pair. Providing just the BSP name will fail. This call also explicitly
137   provides a buildset via the '--buildset=buildset/default.ini' option. If no
138   buildset is provided the default one (which is the same as the one provided
139   explicitly here) will be used. You can also provide multiple buildsets as a
140   coma separated list or via multiple '--buildset=x' options.
141
142   $ cd "$sandbox"
143   $ cd rtems-libbsd
144   $ waf configure --prefix="$sandbox/rtems-4.12" \
145       --rtems-bsps=arm/xilinx_zynq_a9_qemu \
146       --buildset=buildset/default.ini
147
1488. Build and install.  The LibBSD package will be installed into the prefix
149   provided to configure:
150
151   $ cd "$sandbox"
152   $ cd rtems-libbsd
153   $ waf
154   $ waf install
155
1569. Run the tests on QEMU, for example:
157
158   $ qemu-system-arm -no-reboot -serial null -serial mon:stdio -net none \
159   $   -nographic -M xilinx-zynq-a9 -m 256M \
160   $   -kernel build/arm-rtems4.12-xilinx_zynq_a9_qemu/selectpollkqueue01.exe
161
162[1] It is good practice to keep your environment as empty as possible. Setting
163    paths to tools or specific values to configure or control a build is
164    dangerous because settings can leak between different builds and change
165    what you expect a build to do. The waf tool used here lets you specify on
166    the command line the tools and RTEMS paths and this is embedded in waf's
167    configuration information. If you have a few source trees working at any
168    one time with different tool sets or configurations you can easly move
169    between them safe in the knowledge that one build will not infect another.
170
171Updating RTEMS Waf Support
172~~~~~~~~~~~~~~~~~~~~~~~~~~
173
174If you have a working libbsd repository and new changes to the `rtems_waf`
175submodule has been made, you will need update. A `git status` will indicate
176there are new commits with:
177
178  $ git status
179      [ snip output ]
180            modified:   rtems_waf (new commits)
181      [ snip output ]
182
183To update:
184
185  $ git submodule update rtems_waf
186
187Please make sure you use the exact command or you might find you are cloning
188the whole of the FreeBSD source tree. If that happens simply git ^C and try
189again.
190
191The following is for developers only who need to move libbsd to a newer
192versions:
193
194 $ git submodule update rtems_waf
195 $ cd rtems_waf
196 $ git checkout master
197 $ git pull
198 $ cd ..
199 $ git commit -m "Update rtems_waf" rtems_waf
200
201FreeBSD Developer Support
202~~~~~~~~~~~~~~~~~~~~~~~~~
203
204The --freebsd-option provides a tool you can set special kernel options. This
205is a developer tool and should only be used if you are familiar with the
206internals of the FreeBSD kernel and what these options do.
207
208The options are listed in:
209
210 https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES
211
212An example to turn on a verbose kernel boot, verbose sysinit and bus debugging
213configure with:
214
215 --freebsd-options=bootverbose,verbose_sysinit,bus_debug
216
217The LibBSD waf support splits the options and converts them to uppercase and
218adds them -D options on the compiler command line.
Note: See TracBrowser for help on using the repository browser.