From 1c66026f99ebc3235b6798ea181b56a7738ea347 Mon Sep 17 00:00:00 2001 From: Thomas Nagy Date: Sat, 16 Jul 2016 16:44:54 +0200 Subject: [PATCH] More documentation --- docs/book/download.txt | 4 ++-- docs/book/execution.txt | 41 +++++++++++++++++++++++++++-------------- 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/book/download.txt b/docs/book/download.txt index fca01c81..a61fbf64 100644 --- a/docs/book/download.txt +++ b/docs/book/download.txt @@ -57,7 +57,7 @@ Additional extensions can be added to the waf file and redistributed as part of [source,shishell] --------------- -$ python waf-light --tools=compat15,swig,doxygen +$ python waf-light --tools=swig,msvs --------------- ==== Custom initializers @@ -75,7 +75,7 @@ The following will create a custom waf file that will import and execute the fun [source,shishell] --------------- -$ python waf-light --make-waf --tools=compat15,$PWD/aba.py +$ python waf-light --make-waf --tools=msvs,$PWD/aba.py --prelude=$'\tfrom waflib.extras import aba\n\taba.foo()' $ ./waf --help This is Waf {version} diff --git a/docs/book/execution.txt b/docs/book/execution.txt index c3e15fec..5b4cb5b8 100644 --- a/docs/book/execution.txt +++ b/docs/book/execution.txt @@ -1,15 +1,28 @@ == Projects and commands -The _waf_ script is meant to build software projects, and is of little use when taken alone. This chapter describes what is necessary to set up a waf project and how to use the _waf_ script. - === Waf commands -Waf projects use description files of the name _wscript_ which are python scripts containing functions and variables that may be used by Waf. Particular functions named _waf commands_ may be used by Waf on the command-line. +==== Waf and wscript files -==== Declaring Waf commands +As the Waf file is meant to be a generic utility for building projects, project-specific details are best kept and versioned in files residing along with the project source code. -Waf commands are really simple functions and may execute arbitrary python code such as calling other functions. -They take a single parameter as input and do not have to return any particular value as in the following example: +The Waf project files are modules written in the Python programming language and are named *wscript*. Though they can contain any Python code, Waf can use specific functions and classes defined in them. + +==== Overview of the command-line + +When running the following in a terminal or shell, Waf is instructed to run the two commands called *distclean* and *configure* in this specific order. The *-j1* and *--help* elements are command-line options; they are optional and their position or order in the list of arguments is not meant to be significant. The CFLAGS value provides a way to provide arbitrary data in an unverified way, it is also called an environment variable. + +[source,shishell] +--------------- +$ CFLAGS=-O3 waf distclean configure -j1 --help +--------------- + +NOTE: waf commands are passed after the 'waf' file and contain no '-' or '=' character + +==== Waf commands map Python functions + +Waf commands assume that a corresponding command function is defined in a the wscript file in the current folder. +They take a single context parameter as input and do not have to return any particular value as in the following example: // execution_hello [source,python] @@ -22,9 +35,9 @@ def <1> hello(ctx <2>): --------------- <1> The _waf command_ *hello* -<2> A waf context, used to share data between scripts +<2> A waf context, used to share data among scripts -And here is how to have +waf+ call the function hello from the command-line: +Calling the command instructs +waf+ to call function: [source,shishell] --------------- @@ -33,9 +46,9 @@ hello world 'hello' finished successfully (0.001s) --------------- -==== Chaining Waf commands +==== Waf command chaining -Several commands may be declared in the same _wscript_ file: +As previously mentioned, commands are executed in the order defined on the command-line. A wscript file may thus provide an arbitrary amound of commands in the same _wscript_ file: // execution_ping [source,python] @@ -47,7 +60,7 @@ def pong(ctx): print(' pong! %d' % id(ctx)) --------------- -And may be chained for execution by Waf: +And such commands may be called more than once by being repeated on the command-line: [source,shishell] --------------- @@ -62,7 +75,7 @@ $ waf ping pong ping ping 'ping' finished successfully (0.001s) --------------- -NOTE: The context parameter is a new object for each command executed. The classes are also different: ConfigureContext for configure, BuildContext for build, OptionContext for option, and Context for any other command. +NOTE: Command functions are passed a new context object when they are called; the class for that object is command-specific: ConfigureContext for configure, BuildContext for build, OptionContext for option, and Context for any other command. ==== Using several scripts and folders @@ -118,8 +131,8 @@ NOTE: The method _recurse_, and the attribute _path_ are available on all waf co ==== Configuring a project (the _configure_ command) -Although Waf may be called from any folder containing a 'wscript' file, it is usually a good idea to have a single entry point in the scripts. -Besides ensuring a consistent behaviour, it also saves the redefinition of the same imports and function redefinitions in all wscript files. +Though Waf may be called from any folder containing a 'wscript' file, an entry point must be defined in a particular project file. +This lifts ambiguities and saves the redefinition of the same imports and function definitions in all sub-wscript files of a project. The following concepts help to structure a Waf project: . Project directory: directory containing the source files that will be packaged and redistributed to other developers or to end users