mirror of https://gitlab.com/ita1024/waf.git
docs
This commit is contained in:
Thomas Nagy
parent
445c0214ff
commit
dff0d0d6b9
|
|
@ -1,100 +1,75 @@
|
|||
== Download and installation
|
||||
|
||||
=== Obtaining the Waf file
|
||||
=== Getting the Waf file
|
||||
|
||||
==== Running the Waf binary script
|
||||
==== How to download Waf
|
||||
|
||||
A Python programming language 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 is required to run Waf. The file may be renamed as *waf* is necessary:
|
||||
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}
|
||||
$ mv waf-{version} waf
|
||||
$ python waf --version
|
||||
waf {version} (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf)
|
||||
$ ./waf/utils/verify-sig.py waf-{version}
|
||||
---------------
|
||||
|
||||
The +waf+ file has its own library compressed as a binary stream in the same file. Upon execution, the library is uncompressed in a hidden folder in the directory of the Waf file. The folder will be re-created if removed. This scheme enables different Waf versions to be executed from the same folders:
|
||||
|
||||
[source,shishell]
|
||||
---------------
|
||||
$ ls -ld .waf*
|
||||
.waf-{version}-2c924e3f453eb715218b9cc852291170
|
||||
---------------
|
||||
|
||||
No installation is necessary, but the folder containing the Waf file must be writable. If this is not possible, use the instructions in the next section to set the *WAFDIR* environment variable.
|
||||
|
||||
If http://docs.python.org/library/bz2.html[bzip2] compression support is missing in the python interpreter, please use the instructions in the next sections to build Waf from source.
|
||||
|
||||
==== Building Waf from source
|
||||
|
||||
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.
|
||||
- The source distribution provides a signature file for its archive:
|
||||
|
||||
[source,shishell]
|
||||
---------------
|
||||
$ wget https://waf.io/waf-{version}.tar.bz2
|
||||
$ tar xjvf waf-{version}.tar.bz2
|
||||
$ cd waf-{version}
|
||||
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)
|
||||
$ wget https://waf.io/waf-{version}.tar.bz2.asc
|
||||
$ gpg --verify waf-{version}.tar.bz2.asc
|
||||
---------------
|
||||
|
||||
For older Python interpreters, the +waf+ file may be created with gzip compression instead of bzip2:
|
||||
- Most project commits are signed with the same public key:
|
||||
|
||||
[source,shishell]
|
||||
---------------
|
||||
$ python waf-light --zip-type=gz
|
||||
$ 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
|
||||
...
|
||||
---------------
|
||||
|
||||
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 to 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). Here is a short example:
|
||||
==== 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-light --tools=swig,msvs
|
||||
$ python waf-{version} --help
|
||||
$ ls -ld .waf*
|
||||
.waf-{version}-2c924e3f453eb715218b9cc852291170
|
||||
---------------
|
||||
|
||||
==== Custom initialization
|
||||
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).
|
||||
|
||||
Extension 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:
|
||||
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].
|
||||
|
||||
[source,python]
|
||||
---------------
|
||||
def foo():
|
||||
from waflib.Context import WAFVERSION
|
||||
print("This is Waf %s" % WAFVERSION)
|
||||
---------------
|
||||
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 will create a custom waf file that will import and execute the function 'foo' before calling the waf library.
|
||||
The following diagram represents the process used to find the +waflib+ directory:
|
||||
|
||||
[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 waf-light to learn more about it, 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.
|
||||
|
||||
=== Using the Waf file
|
||||
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:
|
||||
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:
|
||||
On Unix-like systems, it is usually much more convenient to set the executable permissions and avoid calling +python+ each time:
|
||||
|
||||
[source,shishell]
|
||||
---------------
|
||||
|
|
@ -123,22 +98,99 @@ 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.
|
||||
|
||||
In the next sections of the book, we assume that either an alias or the execution path have been set in a way that +waf+ may be called directly.
|
||||
=== Customization and redistribution
|
||||
|
||||
==== Local waflib folders
|
||||
==== How to build Waf executables
|
||||
|
||||
Although the waf library is unpacked automatically from the waf binary file, it is sometimes necessary to keep its files in a visible folder, which may even be kept in a source control tool (subversion, git, etc). For example, the +waf-light+ script does not contain the waf library, yet it is used to create the +waf+ script by using the directory +waflib+.
|
||||
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.
|
||||
|
||||
Another alternative for Waf developers is to point the environment variable _WAFDIR_ to the folder containing the directory named `waflib`.
|
||||
[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)
|
||||
---------------
|
||||
|
||||
The following diagram represents the process used to find the +waflib+ directory:
|
||||
For older Python interpreters, the +waf+ file may be created with gzip compression instead of bzip2:
|
||||
|
||||
image::waflib{PIC}["Waflib discovery"{backend@docbook:,width=450:},align="center"]
|
||||
[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):
|
||||
|
||||
==== Portability concerns
|
||||
[source,shishell]
|
||||
---------------
|
||||
$ python waf-light --tools=swig,msvs
|
||||
---------------
|
||||
|
||||
By default, the recommended Python interpreter is cPython, for which the supported versions are 2.5 to 3.5. For maximum convenience for end-users, a copy of the http://www.jython.org[Jython] interpreter (version >= 2.5) might even be redistributed along with a copy of the Waf executable.
|
||||
==== How to provide custom initializers
|
||||
|
||||
WARNING: Unless a _WAFDIR_ is set, the 'waf' script must reside in a writable folder to unpack its cache files.
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue