source: rtems-libbsd/README.waf @ e1e10cd

5-freebsd-12freebsd-9.3
Last change on this file since e1e10cd was e1e10cd, checked in by Chris Johns <chrisj@…>, on Apr 23, 2016 at 7:37:27 AM

waf: Add the ability to set FreeBSD options on the configure command line.

Add --freebsd-options to add specific FreeBSD compile time options to
the build. This is a developer tool.

  • Property mode set to 100644
File size: 5.3 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
501. Build and install the tools. In this example the path is
51   /opt/rtems/4.11/tools:
52
53    $ cd rtems-source-builder/rtems
54    $ ../souce-builder/sb-set-builder \
55            --prefix=/opt/rtems/4.11/tools 4.11/rtems-arm
56
572. Build and install the RTEMS Board Support Packages (BSP) you want to use. In
58   this example the path is /opt/rtems/4.11/bsps:
59
60    $ mkdir realview_pbx_a9_qemu
61    $ cd realview_pbx_a9_qemu
62    $ ../rtems-4.11/configure \
63            --target=arm-rtems4.11 --prefix=/opt/rtems/4.11/bsps \
64            --disable-networking --enable-rtemsbsp=realview_pbx_a9_qemu
65    $ make
66    $ make install
67
683. Populate the rtems_waf git submodule:
69
70    $ cd rtems-libbsd
71    $ git submodule init
72    $ git submodule update rtems_waf
73
74   Note, make sure you specify 'rtems_waf' or the FreeBSD kernel source will be
75   cloned.
76
774. Run Waf's configure with your specific settings. In this case the path to
78   the tools and RTEMS are provided on the command line and so do not need to
79   be in your path or environment [1]:
80
81    $ waf configure --prefix=/opt/rtems/4.11/bsps \
82                    --rtems=/opt/rtems/4.11/bsps \
83                    --rtems-tools=/opt/rtems/4.11/tools \
84                    --rtems-bsps=arm/realview_pbx_a9_qemu
85
86   You can use '--rtems-archs=arm,sparc,i386' or
87   '--rtems-bsps=arm/realview_pbx_a9_qemu,sparc/sis,i386/pc586' to build for
88   more than BSP at a time.
89
90   Note, you must provide the architecture and BSP as a pair. Providing just the
91   BSP name will fail.
92
936. Build and install:
94
95   The LibBSD package will be installed into the prefix provided to configure.
96
97   $ waf
98   $ waf install
99
100[1] It is good practice to keep your environment as empty as possible. Setting
101    paths to tools or specific values to configure or control a build is
102    dangerous because settings can leak between different builds and change
103    what you expect a build to do. The waf tool used here lets you specify on
104    the command line the tools and RTEMS paths and this is embedded in waf's
105    configuration information. If you have a few source trees working at any
106    one time with different tool sets or configurations you can easly move
107    between them safe in the knowledge that one build will not infect another.
108
109Updating RTEMS Waf Support
110~~~~~~~~~~~~~~~~~~~~~~~~~~
111
112If you have a working libbsd repository and new changes to the `rtems_waf`
113submodule has been made, you will need update. A `git status` will indicate
114there are new commits with:
115
116  $ git status
117      [ snip output ]
118            modified:   rtems_waf (new commits)
119      [ snip output ]
120
121To update:
122
123  $ git submodule update rtems_waf
124
125Please make sure you use the exact command or you might find you are cloning
126the whole of the FreeBSD source tree. If that happens simply git ^C and try
127again.
128
129The following is for developers only who need to move libbsd to a newer
130versions:
131
132 $ git submodule update rtems_waf
133 $ cd rtems_waf
134 $ git checkout master
135 $ git pull
136 $ cd ..
137 $ git commit -m "Update rtems_waf" rtems_waf
138
139FreeBSD Developer Support
140~~~~~~~~~~~~~~~~~~~~~~~~~
141
142The --freebsd-option provides a tool you can set special kernel options. This
143is a developer tool and should only be used if you are familiar with the
144internals of the FreeBSD kernel and what these options do.
145
146The options are listed in:
147
148 https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES
149
150An example to turn on a verbose kernel boot, verbose sysinit and bus debugging
151configure with:
152
153 --freebsd-options=bootverbose,verbose_sysinit,bus_debug
154
155The LibBSD waf support splits the options and converts them to uppercase and
156adds them -D options on the compiler command line.
Note: See TracBrowser for help on using the repository browser.