mirror of https://gitlab.com/ita1024/waf.git
197 lines
8.5 KiB
Plaintext
197 lines
8.5 KiB
Plaintext
== 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.
|
|
|