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

docs

Browse Source
This commit is contained in:
Thomas Nagy 2016-07-23 01:52:34 +02:00
parent 445c0214ff
commit dff0d0d6b9
No known key found for this signature in database
GPG Key ID: 49B4C67C05277AAA
1 changed files with 119 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
docs/book/download.txt
View File

@ -1,100 +1,75 @@
== Download and installation == 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] [source,shishell]
--------------- ---------------
$ wget https://waf.io/waf-{version} $ wget https://waf.io/waf-{version}
$ mv waf-{version} waf $ ./waf/utils/verify-sig.py waf-{version}
$ python waf --version
waf {version} (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf)
--------------- ---------------
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: - The source distribution provides a signature file for its archive:
[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.
[source,shishell] [source,shishell]
--------------- ---------------
$ wget https://waf.io/waf-{version}.tar.bz2 $ wget https://waf.io/waf-{version}.tar.bz2
$ tar xjvf waf-{version}.tar.bz2 $ wget https://waf.io/waf-{version}.tar.bz2.asc
$ cd waf-{version} $ gpg --verify waf-{version}.tar.bz2.asc
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: - Most project commits are signed with the same public key:
[source,shishell] [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] [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] 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.
---------------
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. The following diagram represents the process used to find the +waflib+ directory:
[source,shishell] image::waflib{PIC}["Waflib discovery"{backend@docbook:,width=450:},align="center"]
---------------
$ 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
==== Permissions and aliases ==== 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] [source,shishell]
--------------- ---------------
$ python waf $ 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] [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. 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.