source: rtems-libbsd/README.waf @ 5b4394f

5-freebsd-12freebsd-9.3
Last change on this file since 5b4394f was cf72971, checked in by Sebastian Huber <sebastian.huber@…>, on May 6, 2016 at 11:28:25 AM

README.waf: Make set-up steps self contained

  • Property mode set to 100644
File size: 6.9 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 ARM Realview PBX A9 QEMU BSP using the name
45'arm/realview_pbx_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-realview_pbx_a9_qemu
65cd b-realview_pbx_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=realview_pbx_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/realview_pbx_a9_qemu
77waf
78waf install
79-------------------------------------------------------------------------------
80
811. Create a sandbox directory:
82
83    $ sandbox="$PWD/sandbox"
84    $ mkdir sandbox
85
861. Clone the repositories:
87
88    $ cd "$sandbox"
89    $ git clone git://git.rtems.org/rtems-source-builder.git
90    $ git clone git://git.rtems.org/rtems.git
91    $ git clone git://git.rtems.org/rtems-libbsd.git
92
932. Build and install the tools. In this example the path is
94   $sandbox/rtems-4.12:
95
96    $ cd "$sandbox"
97    $ cd rtems-source-builder/rtems
98    $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm
99
1003. Bootstrap the RTEMS sources:
101
102    $ cd "$sandbox"
103    $ cd rtems
104    $ PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap
105
1065. Build and install the RTEMS Board Support Packages (BSP) you want to use. In
107   this example the path is /opt/rtems/4.12/bsps:
108
109    $ cd "$sandbox"
110    $ mkdir b-realview_pbx_a9_qemu
111    $ cd b-realview_pbx_a9_qemu
112    $ PATH="$sandbox/rtems-4.12/bin:$PATH" "$sandbox/rtems/configure" \
113        --target=arm-rtems4.12 --prefix="$sandbox/rtems-4.12" \
114        --disable-networking --enable-rtemsbsp=realview_pbx_a9_qemu
115    $ PATH="$sandbox/rtems-4.12/bin:$PATH" make
116    $ PATH="$sandbox/rtems-4.12/bin:$PATH" make install
117
1186. Populate the rtems_waf git submodule.  Note, make sure you specify
119   'rtems_waf' or the FreeBSD kernel source will be cloned:
120
121   $ cd "$sandbox"
122   $ cd rtems-libbsd
123   $ git submodule init
124   $ git submodule update rtems_waf
125
1267. Run Waf's configure with your specific settings. In this case the path to
127   the tools and RTEMS are provided on the command line and so do not need to
128   be in your path or environment [1].  You can use
129   '--rtems-archs=arm,sparc,i386' or
130   '--rtems-bsps=arm/realview_pbx_a9_qemu,sparc/sis,i386/pc586' to build for
131   more than BSP at a time.  Note, you must provide the architecture and BSP as
132   a pair. Providing just the BSP name will fail:
133
134   $ cd "$sandbox"
135   $ cd rtems-libbsd
136   $ waf configure --prefix="$sandbox/rtems-4.12" \
137       --rtems-bsps=arm/realview_pbx_a9_qemu
138
1398. Build and install.  The LibBSD package will be installed into the prefix
140   provided to configure:
141
142   $ cd "$sandbox"
143   $ cd rtems-libbsd
144   $ waf
145   $ waf install
146
147[1] It is good practice to keep your environment as empty as possible. Setting
148    paths to tools or specific values to configure or control a build is
149    dangerous because settings can leak between different builds and change
150    what you expect a build to do. The waf tool used here lets you specify on
151    the command line the tools and RTEMS paths and this is embedded in waf's
152    configuration information. If you have a few source trees working at any
153    one time with different tool sets or configurations you can easly move
154    between them safe in the knowledge that one build will not infect another.
155
156Updating RTEMS Waf Support
157~~~~~~~~~~~~~~~~~~~~~~~~~~
158
159If you have a working libbsd repository and new changes to the `rtems_waf`
160submodule has been made, you will need update. A `git status` will indicate
161there are new commits with:
162
163  $ git status
164      [ snip output ]
165            modified:   rtems_waf (new commits)
166      [ snip output ]
167
168To update:
169
170  $ git submodule update rtems_waf
171
172Please make sure you use the exact command or you might find you are cloning
173the whole of the FreeBSD source tree. If that happens simply git ^C and try
174again.
175
176The following is for developers only who need to move libbsd to a newer
177versions:
178
179 $ git submodule update rtems_waf
180 $ cd rtems_waf
181 $ git checkout master
182 $ git pull
183 $ cd ..
184 $ git commit -m "Update rtems_waf" rtems_waf
185
186FreeBSD Developer Support
187~~~~~~~~~~~~~~~~~~~~~~~~~
188
189The --freebsd-option provides a tool you can set special kernel options. This
190is a developer tool and should only be used if you are familiar with the
191internals of the FreeBSD kernel and what these options do.
192
193The options are listed in:
194
195 https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES
196
197An example to turn on a verbose kernel boot, verbose sysinit and bus debugging
198configure with:
199
200 --freebsd-options=bootverbose,verbose_sysinit,bus_debug
201
202The LibBSD waf support splits the options and converts them to uppercase and
203adds them -D options on the compiler command line.
Note: See TracBrowser for help on using the repository browser.