[rtems-libbsd commit] Add a README for using waf.

[Chris Johns]

Module:    rtems-libbsd
Branch:    master
Commit:    b14fd1fcba610cdabde9e2ee5e502774a444502d
Changeset: http://git.rtems.org/rtems-libbsd/commit/?id=b14fd1fcba610cdabde9e2ee5e502774a444502d

Author:    Chris Johns <chrisj at rtems.org>
Date:      Wed May 20 18:21:38 2015 +1000

Add a README for using waf.

---

 README.waf | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/README.waf b/README.waf
new file mode 100644
index 0000000..31dd05c
--- /dev/null
+++ b/README.waf
@@ -0,0 +1,70 @@
+RTEMS LibBSD Waf
+~~~~~~~~~~~~~~~~
+
+You can find the Waf project here:
+
+ http://code.google.com/p/waf/
+
+Simple instructions on How to set up Waf is here:
+
+ https://ftp.rtems.org/pub/rtems/people/chrisj/rtl/rtems-linker/waf.html
+
+These instructions show you how to build and install RTEMS Tools, RTEMS kernel
+for your BSP in separate paths. Using separate paths for the tools and BSPs
+lets you manage what you have installed. If you are happy with a single path
+you can just the same path in each stage.
+
+We will build an ARM Realview PBX A9 QEMU BSP (arm/realview_pbx_a9_qemu).
+
+Steps
+-----
+
+1. Build and install the tools. In this example the path is
+   /opt/rtems/4.11/tools:
+
+    $ cd rtems-source-builder/rtems
+    $ ../souce-builder/sb-set-builder \
+            --prefix=/opt/rtems/4.11/tools 4.11/rtems-arm
+
+2. Build and install the RTEMS Board Support Packages (BSP) you want to use. In
+   this example the path is /opt/rtems/4.11/bsps:
+
+    $ mkdir realview_pbx_a9_qemu
+    $ cd realview_pbx_a9_qemu
+    $ ../rtems-4.11/configure \
+            --target=arm-rtems4.11 --prefix=/opt/rtems/4.11/bsps \
+            --disable-networking --enable-rtemsbsp=realview_pbx_a9_qemu
+    $ make
+    $ make install
+
+3. Populate the git submodule:
+
+    $ rtems-libbsd
+    $ git submodule init
+    $ git submodule update
+
+5. Configure with your specific settings. In this case the path to the tools
+   and RTEMS are provided on the command line and so do not need to be in your
+   path or environment [1]:
+
+    $ waf configure --rtems=/opt/rtems/4.11/bsps \
+                    --rtems-tools=/opt/rtems/4.11/tools \
+                    --rtems-bsps=arm/realview_pbx_a9_qemu
+
+   You can use '--rtems-archs=arm,sparc,i386' or
+   '--rtems-bsps=arm/realview_pbx_a9_qemu,sparc/sis,i386/pc586' to build for
+   more than BSP at a time.
+
+6. Build and install:
+
+   $ waf
+   $ waf install
+
+[1] It is good practice to keep your environment as empty as possible. Setting
+    paths to tools or specific values to configure or control a build is
+    dangerous because settings can leak between different builds and change
+    what you expect a build to do. The waf tool used here lets you specify on
+    the command line the tools and RTEMS paths and this is embedded in waf's
+    configuration information. If you have a few source trees working at any
+    one time with different tool sets or configurations you can easly move
+    between them safe in the knowledge that one build will not infect another.