== Download and installation

=== Getting the Waf file

==== How to download Waf

The release files may be downloaded from the http://waf.io[main site] or http://freehackers.org/~tnagy/release[from a mirror]
while the source may be obtained from https://github.com/waf-project/waf[Github].
The downloads and most project commits are signed with the https://raw.githubusercontent.com/waf-project/waf/master/utils/pubkey.asc[project public key]:

- The Waf executable contains an embedded signature which can be verified by means of a https://raw.githubusercontent.com/waf-project/waf/master/utils/verify-sig.py[script]:

[source,shishell]
---------------
$ wget https://waf.io/waf-{version}
$ ./waf/utils/verify-sig.py waf-{version}
---------------

- The source distribution provides a signature file for its archive:

[source,shishell]
---------------
$ wget https://waf.io/waf-{version}.tar.bz2
$ wget https://waf.io/waf-{version}.tar.bz2.asc
$ gpg --verify waf-{version}.tar.bz2.asc
---------------

- Most project commits are signed with the same public key:

[source,shishell]
---------------
$ git clone https://github.com/waf-project/waf.git
$ cd waf/
$ git show --show-signature
commit b73ccba03cd5f34b40a36e1d60b6a082a04cd563
gpg: Signature made sam. 16 jul. 2016 17:31:19 CEST
gpg:                using RSA key 0x49B4C67C05277AAA
...
---------------

==== How to run Waf

The executable may be run directly through a Python interpreter such as http://www.python.org[cPython] 2.5 to 3.5, http://pypy.org[Pypy] or http://www.jython.org[Jython] >= 2.5.
It provides its own library compressed as a binary stream within the file. Upon execution, this library is uncompressed into a hidden folder in the directory of the file (it is re-created when removed). This scheme enables different Waf versions to be executed from the same folders and under various Python interpreter versions:

[source,shishell]
---------------
$ python waf-{version} --help
$ ls -ld .waf*
.waf-{version}-2c924e3f453eb715218b9cc852291170
---------------

No installation is necessary, but the Python interpreter must feature a http://docs.python.org/library/bz2.html[bzip2 decompressor]; if this module is missing, then it may be necessary to use the build Waf from source (consult the next sections).

Additionally, the folder containing the waf file must be writable; if this is not possible, an alternative is to point the environment variable _WAFDIR_ to the folder containing the directory named https://github.com/waf-project/waf/tree/master/waflib[waflib].

Another possibility consists in providing the waf files in a visible folder, which may then be kept under a version control solution such as Git. For instance, the +waf-light+ script does not contain the waf library, but can be used in the same way as waf if the waflib folder is present.

The following diagram represents the process used to find the +waflib+ directory:

image::waflib{PIC}["Waflib discovery"{backend@docbook:,width=450:},align="center"]

==== Permissions and aliases

Since the waf file is a Python script, it is usually executed by calling +python+ on it:

[source,shishell]
---------------
$ python waf
---------------

On Unix-like systems, it is usually much more convenient to set the executable permissions and avoid calling +python+ each time:

[source,shishell]
---------------
$ chmod 755 waf
$ ./waf --version
waf {version} (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf)
---------------

If the command-line interpreter supports aliases, it is recommended to set one instead of retyping commands:

[source,shishell]
---------------
$ alias waf=$PWD/waf
$ waf --version
waf {version} (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf)
---------------

Else, the execution path may be modified to point at the location of the waf binary:

[source,shishell]
---------------
$ export PATH=$PWD:$PATH
$ waf --version
waf {version} (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf)
---------------

For convenience purposes on Windows systems, a https://github.com/waf-project/waf/tree/master/utils/waf.bat[waf.bat file] is provided to detect the presence of the Python application. It assumes that it is residing in the same folder as the waf file.

=== Customization and redistribution

==== How to build Waf executables

Building Waf requires a Python interpreter having a version number in the range 2.6-3.5. The source code is then processed to support Python 2.5.

[source,shishell]
---------------
$ wget https://waf.io/waf-{version}.tar.bz2
$ tar xjvf waf-{version}.tar.bz2
$ cd waf-{version}
$ ./waf-light
Configuring the project
Setting top to                           : /home/user/waf
Setting out to                           : /home/user/waf/build
Checking for program 'python'            : /usr/bin/python
Waf: Entering directory `/waf-{version}/build'
[1/1] Creating waf
Waf: Leaving directory `/waf-{version}/build'
'build' finished successfully (0.726s)
---------------

For older Python interpreters, the +waf+ file may be created with gzip compression instead of bzip2:

[source,shishell]
---------------
$ python waf-light --zip-type=gz
---------------

Additional extensions can be added to the waf file and redistributed as part of it. For instance, the source distribution contains several extension in testing phase under the folder 'waflib/extras'. Passing a relative path in the _--tools_ switch will include the corresponding file, while passing an absolute path can refer to any file on the filesystem, and non-python files in particular (they will end up in the local the 'waflib/extras/' folder):

[source,shishell]
---------------
$ python waf-light --tools=swig,msvs
---------------

==== How to provide custom initializers

Extensions that provide an initialization may also be used to execute custom functions before the regular execution. Assuming that a file named `aba.py` is present in the current directory:

[source,python]
---------------
def foo():
	from waflib.Context import WAFVERSION
	print("This is Waf %s" % WAFVERSION)
---------------

The following will create a custom waf file that will import and execute the function 'foo' before calling the waf library.

[source,shishell]
---------------
$ 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}
[...]
---------------

A return statement may also be added; please consult the contents of https://github.com/waf-project/waf/blob/master/waf-light#L167[waf-light] to learn more about this, or consider the examples from the https://github.com/waf-project/waf/tree/master/build_system_kit/[build system kit] that illustrate how to create build systems derived from Waf.

==== License and redistribution

The files included in the waf file (https://github.com/waf-project/waf/blob/master/waf-light#L167[waf-light] and all the files under https://github.com/waf-project/waf/tree/master/waflib[waflib]) are published under a BSD license which is reproduced below:

[source,txt]
---------------
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
---------------

Though this license is considered very permissive, a copy of the copyright notice must be included in derivative works.
In order to lift any doubt, such a copy is added to the waf files by default: just open a waf file with a text editor and read its first lines.