FWGS/waf
2
0
Fork 0
mirror of https://gitlab.com/ita1024/waf.git synced 2024-11-21 17:35:55 +01:00
Code Issues Projects Releases Wiki Activity

More documentation

Browse Source
This commit is contained in:
Thomas Nagy 2016-07-16 16:44:54 +02:00
parent fb6d9aaee3
commit 1c66026f99
2 changed files with 29 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/book/download.txt
View File

@ -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}

41
docs/book/execution.txt
View File

@ -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