README.md 3.23 KB
Newer Older
ita1024's avatar
docs    
ita1024 committed
1
2
## ABOUT WAF

Thomas Nagy's avatar
Thomas Nagy committed
3
4
5
6
7
8
9
Waf is a Python-based framework for configuring, compiling and installing applications. Here are perhaps the most important features of Waf:

  * *Automatic build order*: the build order is computed from input and output files, among others
  * *Automatic dependencies*: tasks to execute are detected by hashing files and commands
  * *Performance*: tasks are executed in parallel automatically, the startup time is meant to be fast (separation between configuration and build)
  * *Flexibility*: new commands and tasks can be added very easily through subclassing, bottlenecks for specific builds can be eliminated through dynamic method replacement
  * *Extensibility*: though many programming languages and compilers are already supported by default, many others are available as extensions
ita1024's avatar
ita1024 committed
10
  * *IDE support*: Eclipse, Visual Studio and Xcode project generators (`waflib/extras/`)
11
  * *Documentation*: the application is based on a robust model documented in [The Waf Book](https://waf.io/book/) and in the [API docs](https://waf.io/apidocs/)
ita1024's avatar
ita1024 committed
12
  * *Python compatibility*: cPython 2.5 to 3.x, Jython 2.5, IronPython, and Pypy
Thomas Nagy's avatar
Thomas Nagy committed
13

ita1024's avatar
ita1024 committed
14
Waf is used in particular by innovative companies such as [Avalanche Studios](http://www.avalanchestudios.se) and by open-source projects such as [RTEMS](https://www.rtems.org/). Learn more about Waf by reading [The Waf Book](https://waf.io/book/).
Thomas Nagy's avatar
Thomas Nagy committed
15

16
For researchers and build system writers, Waf also provides a framework for creating [custom build systems](https://gitlab.com/ita1024/waf/tree/master/build_system_kit) and [package distribution systems](https://gitlab.com/ita1024/waf/blob/master/playground/distnet/README.rst).
Thomas Nagy's avatar
Thomas Nagy committed
17

18
Download the project from our page on [waf.io](https://waf.io/) or from a mirror on [freehackers.org](http://www.freehackers.org/~tnagy/release/), consult the [manual](https://waf.io/book/), the [API documentation](https://waf.io/apidocs/) and the [showcases](https://gitlab.com/ita1024/waf/tree/master/demos) and [experiments](https://gitlab.com/ita1024/waf/tree/master/playground).
ita1024's avatar
docs    
ita1024 committed
19
20
21

## HOW TO CREATE THE WAF SCRIPT

22
Python >= 2.6 is required to generate the waf script, and the resulting file can then run on Python 2.5.
ita1024's avatar
docs    
ita1024 committed
23
Just run:
ita1024's avatar
docs    
ita1024 committed
24
```sh
ita1024's avatar
ita1024 committed
25
$ python ./waf-light configure build
ita1024's avatar
docs    
ita1024 committed
26
```
ita1024's avatar
docs    
ita1024 committed
27
Or, if several python versions are installed:
ita1024's avatar
docs    
ita1024 committed
28
29
30
31
```sh
$ python3 ./waf-light configure build
```

ita1024's avatar
ita1024 committed
32
33
## CUSTOMIZATION

ita1024's avatar
docs    
ita1024 committed
34
The Waf tools in waflib/extras are not added to the waf script. To add
ita1024's avatar
docs    
ita1024 committed
35
36
some of them, use the --tools switch. An absolute path can be passed
if the module does not exist under the 'extras' folder:
ita1024's avatar
docs    
ita1024 committed
37
```sh
ita1024's avatar
docs    
ita1024 committed
38
$ ./waf-light --tools=swig
ita1024's avatar
docs    
ita1024 committed
39
40
```

ita1024's avatar
docs    
ita1024 committed
41
To customize the initialization, pass the parameter 'prelude'. Here is for example
ita1024's avatar
docs    
ita1024 committed
42
43
44
45
46
how to create a waf file using the compat15 module:
```sh
$ ./waf-light --tools=compat15 --prelude=$'\tfrom waflib.extras import compat15\n'
```

ita1024's avatar
docs    
ita1024 committed
47
48
Although any kind of initialization is possible, using the build system kit
may be easier (folder build\_system\_kit):
ita1024's avatar
docs    
ita1024 committed
49
50
51
52
```sh
$ ./waf-light --make-waf --tools=compat15,/comp/waf/aba.py --prelude=$'\tfrom waflib.extras import compat15\n\tprint("ok")'
```

ita1024's avatar
docs    
ita1024 committed
53
To avoid regenerating the waf file all the time, just set the `WAFDIR` environment variable to the directory containing "waflib".
ita1024's avatar
docs    
ita1024 committed
54

ita1024's avatar
ita1024 committed
55
## HOW TO RUN THE EXAMPLES
ita1024's avatar
docs    
ita1024 committed
56
57
58
59
60
61
62
63

Try this:
```sh
cp waf demos/c/
cd demos/c/
./waf configure build
```