[rtems_waf commit] Add a README with details on updating a project as well as using rtems_waf
Chris Johns
chrisj at rtems.org
Tue Sep 25 00:26:06 UTC 2018
Module: rtems_waf
Branch: master
Commit: 112ce92e4174a56e428d88cb8f41e9f31f52d4c6
Changeset: http://git.rtems.org/rtems_waf/commit/?id=112ce92e4174a56e428d88cb8f41e9f31f52d4c6
Author: Chris Johns <chrisj at rtems.org>
Date: Tue Sep 25 10:25:37 2018 +1000
Add a README with details on updating a project as well as using rtems_waf
---
README | 389 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 389 insertions(+)
diff --git a/README b/README
new file mode 100644
index 0000000..29db6ef
--- /dev/null
+++ b/README
@@ -0,0 +1,389 @@
+RTEMS Waf
+~~~~~~~~~
+
+RTEMS Waf is a module that supports the Waf build system and RTEMS. The module
+is integrated into a project or library proividing Waf build support to create
+RTEMS libraries or executables.
+
+RTEMS Waf provides:
+
+* Checking for a valid RTEMS installation of tools and kernel.
+
+* Support for multiple versions of RTEMS.
+
+* Support to build a number of BSPs at once.
+
+* Support for the RTEMS tools and kernel being installed under a shared or
+ separate prefixes [2].
+
+* Flexible integration that allows easy project specific specialization.
+
+* Support to check which features RTEMS is built with.
+
+* Support for BSP compiler and linker flags. The flags are separated into their
+ various types to allow flexible options management in a project.
+
+* Support to list the available architectures and BSPs.
+
+* Additional support for creating root file systems for RTEMS targets.
+
+Bugs
+----
+
+Please report issues to the RTEMS Users list mailto:users at rtems.org or raise a
+ticket in RTEMS's Trac under https://devel.rtems.org/.
+
+Feedback is always welcome.
+
+Waf
+---
+
+You can find the Waf project here:
+
+ https://waf.io/
+
+Waf does not come as a package in distrubitions so you need to download and
+install it.
+
+1. Waf is a Python program so you will also need to have a current Python
+ installed and accessible via your environment's path.
+
+2. Download the latest signed Waf executable file from the Waf website.
+
+3. Place the waf executable in a personal directory that is in your path, for
+ example $HOME/bin. Modify the file's permissions so it can be executed:
+
+ $ chmod +x $HOME/bin/waf
+
+Git Submodule
+-------------
+
+RTEMS Waf can be used as a git submodule. This lets a number of projects share
+the common waf support.
+
+1. Add RTEMS Waf a git submodule to your project:
+
+ $ cd my_project
+ $ git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
+
+2. Initialize the submodule(s) for your project:
+
+ $ git submodule init
+
+3. Update the RTEMS Waf submodule:
+
+ $ git submodule update rtems_waf
+
+ Note, the `rtems_waf` submodule name is provided as some projects may have
+ other submodules you may not wish to update.
+
+4. When submodules are added they are headless which means they are not on a
+ current branch. Switch to a branch:
+
+ $ cd rtems_waf
+ $ git checkout master
+ $ cd ..
+
+ Note, you can replace `master` in the `checkout` above with any valid branch
+ in the RTEMS Waf repo.
+
+5. Update the RTEMS Waf submodule to the latest version on the selected branch:
+
+ $ cd rtems_waf
+ $ git pull
+ $ cd ..
+
+6. Check the new submodule is part of your project and ready to be committed:
+
+ $ git status
+
+ The `rtems_waf` module will be listed as `modified`.
+
+7. Commit the change by adding it to your staged files:
+
+ $ git add rtems_waf
+
+ When ready commit:
+
+ $ git commit
+
+ Review the changes and if they are correct push them:
+
+ $ git log -p
+ $ git push
+
+The RTEMS Waf module is updated from time to time as new features are added or
+changes happen in waf. To update a project's existing RTEMS Waf submodule
+perform steps 5. to 7.
+
+Project Instructions
+--------------------
+
+Create a README.waf file in your project and add the Waf installation section,
+your project specific options and the following steps. These steps are for
+RTEMS 5, change for the specific version of RTEMS your project supports.
+
+1. Build or install the tools. In this example the path is the personal prefix
+ of $HOME/development/rtems/5 [1].
+
+2. Build and install the RTEMS Board Support Packages you want to use. In this
+ example separate tools and kernel prefixes are used [2]. The kernel path is
+ $HOME/development/rtems/bsps/5.
+
+3. Unpack this package somewhere, anywhere on your disk and change into the top
+ level directory.
+
+4. Populate the git submodule:
+
+ $ git submodule init
+ $ git submodule update rtems_waf
+
+5. Configure with your specific settings. In this case the path to the tools
+ and the kernel are separate and provided on the command line. Your
+ envronment's path variable does not need to changed [3]. We limit the build
+ to 'sparc/erc32' BSP:
+
+ $ waf configure --rtems=$HOME/development/rtems/bsps/5 \
+ --rtems-tools=$HOME/development/rtems/5 \
+ --rtems-bsps=sparc/erc32
+
+ You can use '--rtems-archs=sparc,i386' or
+ '--rtems-bsps=sparc/erc32,i386/pc586' to build more than BSP at a time.
+
+6. Build:
+
+ $ waf
+
+An RTEMS Waf Project
+--------------------
+
+RTEMS Waf provides a base to build RTEMS application.
+
+Waf provides a build system framework. You can use waf in your project by
+simply prooviding a list of files you wish to build and link to create an
+executable or you can use waf as framework which is integrated into your
+project to become is build system.
+
+Importing RTEMS Waf
+~~~~~~~~~~~~~~~~~~~
+
+Using RTEMS Waf as a submodule means it may not be present if the submodules
+have not been initialized and updated. This results in a Python error. The
+following import is recommended so a user friendly error is reported:
+
+ from __future__ import print_function
+
+ try:
+ import rtems_waf.rtems as rtems
+ except:
+ print('error: no rtems_waf git submodule; see README.waf', file = stderr)
+ import sys
+ sys.exit(1)
+
+Initialization
+~~~~~~~~~~~~~~
+
+The `wscript` `init()` function is called early in waf's processing. The RTEMS
+Waf's `init()` call lets you provide:
+
+1. Filters
+
+2. RTEMS Version
+
+3. Long command line control
+
+4. Waf BSP initialization hook
+
+A example call to RTEMS Waf's `init()` is:
+
+ rtems_version = "5"
+
+ def init(ctx):
+ rtems.init(ctx, version = rtems_version, long_commands = True)
+
+Filters provide a way to control the tools, architectures and BSPs your project
+supports. RTEMS Waf scans and finds all installed RTEMS tool sets and BSPs and
+your project may only support a limited number of these. Filtering provides a
+way for your project to control what RTEMS Waf accepts and rejects when
+automatically scanning the installed tools and RTEMS kernels. A filter is a
+Python dictionary and the following example will accept `arm` and `sparc` tool
+chains and filtering out the `bfin` tool chain. The filter will only build the
+`arm` acrhitecture and will accept all BSPs except ones starting with `lpc` if
+they are installed:
+
+ my_filter = { 'tools': { 'in': ['arm', 'sparc'], 'out': ['bfin'] },
+ 'arch': { 'in': ['arm'], 'out': [] },
+ 'bsps': { 'in': [], 'out': ['lpc.*'] } }
+
+There are three (3) filters the `tools`, `archs` and `bsps` and each of these
+filter types has an `in` and `out` list. The `in` and `out` items are Python
+regular expressions.
+
+The RTEMS Version lets your project provide the default RTEMS version. This can
+be overridden by the configure option `--rtems-version`.
+
+Long commands is specific to Windows and provides support for tool command
+lines that are longer than the standard Windows command shell's limit. The
+support is based on the example available in Waf extra's.
+
+The Waf BSP initialization hook is a function called as part of the RTEMS Waf's
+`init()` call with the Waf environment and list of BSP contexts. This hook can
+be used to provide specialized BSP support.
+
+Options
+~~~~~~~
+
+The `wscript` `option()` function is called to collect command line options for
+Waf argument processing.
+
+A example call to RTEMS Waf's `options()` is:
+
+ def options(opt):
+ rtems.options(opt)
+
+Configure
+~~~~~~~~~
+
+The `wscript` `configure()` function is called when Waf is configuring a
+build. The RTEMS Waf's `configure()` lets you provide:
+
+1. Waf BSP configure hook
+
+A example call to RTEMS Waf's `configure()` is:
+
+ def configure(conf):
+ rtems.configure(conf)
+
+The BSP configure hook is called at end of a BSP's configuration. The BSP's
+`conf` variable and the `arch/bsp` are passed as arguments. The `arch/bsp` is
+the RTEMS standard for specifing a BSP, for example `sparc/erc32`. The BSP
+configure support can be used to check a BSP for header, check an RTEMS feature
+is present for a specific BSP or add per BSP build variant support:
+
+ def bsp_configure(conf, arch_bsp):
+ conf.check(header_name = "dlfcn.h", features = "c")
+ conf.check(header_name = "rtems/pci.h", features = "c", mandatory = False)
+ if not rtems.check_posix(conf):
+ conf.fatal("POSIX is disabled; configure RTEMS with --enable-posix")
+ env = conf.env.derive()
+ for builder in builders:
+ ab = conf.env.RTEMS_ARCH_BSP
+ variant = ab + "-" + builder
+ conf.msg('Configure variant: ', variant)
+ conf.setenv(variant, env)
+ build_variant_bsp_configure(conf, arch_bsp)
+ conf.setenv(ab)
+
+Build
+~~~~~
+
+The `wscript` `build()` function is called when Waf is asking what to
+build.
+
+A example call to RTEMS Waf's `build()` is:
+
+ def build(bld):
+ rtems.build(bld)
+ bld(features = 'c cprogram',
+ target = 'hello.exe',
+ source = ['hello.c'])
+
+In this example the C source file `hello.c` is compiled and linked to create
+the RTEMS executable `hello.exe`. The build is within the context of the BSP.
+
+Example
+~~~~~~~
+
+Save the following as `wscript`:
+
+ #
+ # Example Waf build script for RTEMS
+ #
+ # To configure, build and run:
+ #
+ # $ waf configure --rtems=$HOME/development/rtems/build/5 \
+ # --rtems-tools=$HOME/development/rtems/5 \
+ # --rtems-bsps=sparc/erc32
+ # $ waf
+ # $ $HOME/development/rtems/5/bin/sparc-rtems5-run \
+ # ./build/sparc-rtems5-erc32/hello.exe
+ #
+ # You can use '--rtems-archs=sparc,i386' or
+ # '--rtems-bsps=sparc/erc32,i386/pc586' to build for more than one BSP at a
+ # time.
+ #
+
+ from __future__ import print_function
+
+ rtems_version = "5"
+
+ try:
+ import rtems_waf.rtems as rtems
+ except:
+ print('error: no rtems_waf git submodule; see README.waf', file = stderr)
+ import sys
+ sys.exit(1)
+
+ def init(ctx):
+ rtems.init(ctx, version = rtems_version, long_commands = True)
+
+ def options(opt):
+ rtems.options(opt)
+
+ def configure(conf):
+ rtems.configure(conf)
+
+ def build(bld):
+ rtems.build(bld)
+ bld.env.CFLAGS += ['-O2','-g']
+ bld(features = 'c cprogram',
+ target = 'hello.exe',
+ source = ['hello.c'])
+
+Save the example C hello world as `hello.c`:
+
+ #include <rtems.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+
+ rtems_task Init(rtems_task_argument ignored) {
+ printf("Hello World\n");
+ exit(0);
+ }
+
+ /* configuration information */
+ #include <bsp.h>
+ #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+ #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+ #define CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
+ #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+ #define CONFIGURE_MAXIMUM_TASKS 1
+ #define CONFIGURE_INIT
+ #include <rtems/confdefs.h>
+
+--
+
+[1] A personal prefix is private to you and located where you have enough disk
+ space to complete an RTEMS installation. We often show this as your home
+ directory ($HOME) because it works on machines you may not have root access
+ to and cannot configure. We recommend you never work as root on a machine
+ you control.
+
+[2] RTEMS supports shared or separate tool and kernel prefixes. The prefix is
+ the path given to the tools and kernel when building and is the path the
+ tools or kernel are installed into when you run the install phase of a
+ build. A shared tools and kernel prefix is often used with releases because
+ the tools and kernel in a release are matched and do not change. Separate
+ tools and kernel paths can be used if you have a common tool set with
+ changing kernel versions. This tends to happen when you are testing kernel
+ patches or changes.
+
+[3] It is good practice to keep your environment as empty as possible. Using
+ the environment to set paths to tools or specific values to configure and
+ control builds is dangerous because settings can leak between different
+ builds and change what you expect or not been and seen and lost. 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 affect another.
More information about the vc
mailing list