[b14fd1f] | 1 | RTEMS LibBSD Waf |
---|
| 2 | ~~~~~~~~~~~~~~~~ |
---|
| 3 | |
---|
[11ec988] | 4 | Welcome to building LibBSD for RTEMS using Waf. This package is a library |
---|
| 5 | containing various parts of the FreeBSD kernel ported to RTEMS. The library |
---|
| 6 | replaces the networking port of FreeBSD in the RTEMS kernel sources. This |
---|
| 7 | package is designed to be updated from the FreeBSD kernel sources and contains |
---|
| 8 | more than just the networking code. |
---|
[b14fd1f] | 9 | |
---|
[11ec988] | 10 | To build this package you need a current RTEMS tool set for your architecture, |
---|
| 11 | and a recent RTEMS kernel for your BSP configured with networking disabled |
---|
| 12 | built and installed. If you already have this you can skip to step 3 of the |
---|
| 13 | build procedure. |
---|
[b14fd1f] | 14 | |
---|
[11ec988] | 15 | Waf Setup |
---|
| 16 | ~~~~~~~~~ |
---|
[b14fd1f] | 17 | |
---|
[11ec988] | 18 | You can find the Waf project at: |
---|
[b14fd1f] | 19 | |
---|
[11ec988] | 20 | https://waf.io/ |
---|
[b14fd1f] | 21 | |
---|
[11ec988] | 22 | Waf is not intended to be installed by distribution packages so we recommend |
---|
| 23 | you download a recent waf version and install it in your home directory. |
---|
| 24 | |
---|
| 25 | Waf is a Python program so you will also need to have a current Python version |
---|
| 26 | installed and in your path. |
---|
| 27 | |
---|
| 28 | Download the latest signed executable file version to $HOME/bin and symlink it |
---|
| 29 | to waf. Add the directory $HOME/bin to your path if it is not already in your |
---|
| 30 | default path. |
---|
| 31 | |
---|
| 32 | Building and Installing LibBSD |
---|
| 33 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 34 | |
---|
| 35 | The following instructions show you how to build and install RTEMS Tools and |
---|
| 36 | RTEMS kernel for your BSP in separate paths. Using separate paths for the tools |
---|
| 37 | and BSPs lets you manage what you have installed. If you are happy with a |
---|
| 38 | single path you can use the same path in each stage. |
---|
| 39 | |
---|
| 40 | The waf build support for RTEMS requires you provide your BSP name as an |
---|
| 41 | architecture and BSP pair. You must provide both or waf will generate an error |
---|
| 42 | message during the configure phase. |
---|
| 43 | |
---|
| 44 | We will build an ARM Realview PBX A9 QEMU BSP using the name |
---|
| 45 | 'arm/realview_pbx_a9_qemu'. |
---|
[b14fd1f] | 46 | |
---|
| 47 | Steps |
---|
| 48 | ----- |
---|
| 49 | |
---|
[cf72971] | 50 | ------------------------------------------------------------------------------- |
---|
| 51 | sandbox="$PWD/sandbox" |
---|
| 52 | mkdir sandbox |
---|
| 53 | cd "$sandbox" |
---|
| 54 | git clone git://git.rtems.org/rtems-source-builder.git |
---|
| 55 | git clone git://git.rtems.org/rtems.git |
---|
| 56 | git clone git://git.rtems.org/rtems-libbsd.git |
---|
| 57 | cd "$sandbox" |
---|
| 58 | cd rtems-source-builder/rtems |
---|
| 59 | ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm |
---|
| 60 | cd "$sandbox" |
---|
| 61 | cd rtems |
---|
| 62 | PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap |
---|
| 63 | cd "$sandbox" |
---|
| 64 | mkdir b-realview_pbx_a9_qemu |
---|
| 65 | cd b-realview_pbx_a9_qemu |
---|
| 66 | PATH="$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 |
---|
| 69 | PATH="$sandbox/rtems-4.12/bin:$PATH" make |
---|
| 70 | PATH="$sandbox/rtems-4.12/bin:$PATH" make install |
---|
| 71 | cd "$sandbox" |
---|
| 72 | cd rtems-libbsd |
---|
| 73 | git submodule init |
---|
| 74 | git submodule update rtems_waf |
---|
| 75 | waf configure --prefix="$sandbox/rtems-4.12" \ |
---|
| 76 | --rtems-bsps=arm/realview_pbx_a9_qemu |
---|
| 77 | waf |
---|
| 78 | waf install |
---|
| 79 | ------------------------------------------------------------------------------- |
---|
| 80 | |
---|
| 81 | 1. Create a sandbox directory: |
---|
| 82 | |
---|
| 83 | $ sandbox="$PWD/sandbox" |
---|
| 84 | $ mkdir sandbox |
---|
| 85 | |
---|
| 86 | 1. Clone the repositories: |
---|
| 87 | |
---|
| 88 | $ cd "$sandbox" |
---|
[b39854a] | 89 | $ git clone git://git.rtems.org/rtems-source-builder.git |
---|
[cf72971] | 90 | $ git clone git://git.rtems.org/rtems.git |
---|
| 91 | $ git clone git://git.rtems.org/rtems-libbsd.git |
---|
[b39854a] | 92 | |
---|
| 93 | 2. Build and install the tools. In this example the path is |
---|
[cf72971] | 94 | $sandbox/rtems-4.12: |
---|
[b14fd1f] | 95 | |
---|
[cf72971] | 96 | $ cd "$sandbox" |
---|
[b14fd1f] | 97 | $ cd rtems-source-builder/rtems |
---|
[cf72971] | 98 | $ ../source-builder/sb-set-builder --prefix="$sandbox/rtems-4.12" 4.12/rtems-arm |
---|
[b39854a] | 99 | |
---|
[cf72971] | 100 | 3. Bootstrap the RTEMS sources: |
---|
[b39854a] | 101 | |
---|
[cf72971] | 102 | $ cd "$sandbox" |
---|
| 103 | $ cd rtems |
---|
| 104 | $ PATH="$sandbox/rtems-4.12/bin:$PATH" ./bootstrap |
---|
[b39854a] | 105 | |
---|
| 106 | 5. Build and install the RTEMS Board Support Packages (BSP) you want to use. In |
---|
[ff6534b] | 107 | this example the path is /opt/rtems/4.12/bsps: |
---|
[b14fd1f] | 108 | |
---|
[cf72971] | 109 | $ cd "$sandbox" |
---|
[b39854a] | 110 | $ mkdir b-realview_pbx_a9_qemu |
---|
| 111 | $ cd b-realview_pbx_a9_qemu |
---|
[cf72971] | 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 |
---|
[b14fd1f] | 117 | |
---|
[cf72971] | 118 | 6. Populate the rtems_waf git submodule. Note, make sure you specify |
---|
| 119 | 'rtems_waf' or the FreeBSD kernel source will be cloned: |
---|
[aca5496] | 120 | |
---|
[cf72971] | 121 | $ cd "$sandbox" |
---|
| 122 | $ cd rtems-libbsd |
---|
| 123 | $ git submodule init |
---|
| 124 | $ git submodule update rtems_waf |
---|
[b14fd1f] | 125 | |
---|
[b39854a] | 126 | 7. Run Waf's configure with your specific settings. In this case the path to |
---|
[11ec988] | 127 | the tools and RTEMS are provided on the command line and so do not need to |
---|
[cf72971] | 128 | be in your path or environment [1]. You can use |
---|
| 129 | '--rtems-archs=arm,sparc,i386' or |
---|
[b14fd1f] | 130 | '--rtems-bsps=arm/realview_pbx_a9_qemu,sparc/sis,i386/pc586' to build for |
---|
[cf72971] | 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: |
---|
[11ec988] | 133 | |
---|
[cf72971] | 134 | $ cd "$sandbox" |
---|
| 135 | $ cd rtems-libbsd |
---|
| 136 | $ waf configure --prefix="$sandbox/rtems-4.12" \ |
---|
| 137 | --rtems-bsps=arm/realview_pbx_a9_qemu |
---|
[b14fd1f] | 138 | |
---|
[cf72971] | 139 | 8. Build and install. The LibBSD package will be installed into the prefix |
---|
| 140 | provided to configure: |
---|
[11ec988] | 141 | |
---|
[cf72971] | 142 | $ cd "$sandbox" |
---|
| 143 | $ cd rtems-libbsd |
---|
[b14fd1f] | 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. |
---|
[97c5024a] | 155 | |
---|
| 156 | Updating RTEMS Waf Support |
---|
| 157 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 158 | |
---|
| 159 | If you have a working libbsd repository and new changes to the `rtems_waf` |
---|
| 160 | submodule has been made, you will need update. A `git status` will indicate |
---|
| 161 | there are new commits with: |
---|
| 162 | |
---|
| 163 | $ git status |
---|
| 164 | [ snip output ] |
---|
| 165 | modified: rtems_waf (new commits) |
---|
| 166 | [ snip output ] |
---|
| 167 | |
---|
| 168 | To update: |
---|
| 169 | |
---|
| 170 | $ git submodule update rtems_waf |
---|
| 171 | |
---|
| 172 | Please make sure you use the exact command or you might find you are cloning |
---|
| 173 | the whole of the FreeBSD source tree. If that happens simply git ^C and try |
---|
| 174 | again. |
---|
| 175 | |
---|
| 176 | The following is for developers only who need to move libbsd to a newer |
---|
| 177 | versions: |
---|
| 178 | |
---|
| 179 | $ git submodule update rtems_waf |
---|
| 180 | $ cd rtems_waf |
---|
| 181 | $ git checkout master |
---|
| 182 | $ git pull |
---|
[68bf405] | 183 | $ cd .. |
---|
[97c5024a] | 184 | $ git commit -m "Update rtems_waf" rtems_waf |
---|
[e1e10cd] | 185 | |
---|
| 186 | FreeBSD Developer Support |
---|
| 187 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
| 188 | |
---|
| 189 | The --freebsd-option provides a tool you can set special kernel options. This |
---|
| 190 | is a developer tool and should only be used if you are familiar with the |
---|
| 191 | internals of the FreeBSD kernel and what these options do. |
---|
| 192 | |
---|
| 193 | The options are listed in: |
---|
| 194 | |
---|
| 195 | https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES |
---|
| 196 | |
---|
| 197 | An example to turn on a verbose kernel boot, verbose sysinit and bus debugging |
---|
| 198 | configure with: |
---|
| 199 | |
---|
| 200 | --freebsd-options=bootverbose,verbose_sysinit,bus_debug |
---|
| 201 | |
---|
| 202 | The LibBSD waf support splits the options and converts them to uppercase and |
---|
| 203 | adds them -D options on the compiler command line. |
---|