From dff0d0d6b9134378cdf40d5221fac8d0eeaeba8b Mon Sep 17 00:00:00 2001 From: Thomas Nagy Date: Sat, 23 Jul 2016 01:52:34 +0200 Subject: [PATCH] docs --- docs/book/download.txt | 186 ++++++++++++++++++++++++++--------------- 1 file changed, 119 insertions(+), 67 deletions(-) diff --git a/docs/book/download.txt b/docs/book/download.txt index 90cba360..3ca1a906 100644 --- a/docs/book/download.txt +++ b/docs/book/download.txt @@ -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.