From 8ac4646d0966fe22f8ae8955c7e9b9d56ae8288e Mon Sep 17 00:00:00 2001 From: Thomas Nagy Date: Mon, 6 Apr 2015 14:46:55 +0200 Subject: [PATCH] Updated the apidocs and The Waf Book --- DEVEL | 45 ++++++++---------------- README | 18 +++------- README.md | 4 +-- docs/book/conclusion.txt | 6 ++-- docs/book/configuration.txt | 6 ++-- docs/book/cprog.txt | 6 ++-- docs/book/development.txt | 4 +-- docs/book/download.txt | 30 ++++++++-------- docs/book/nodes.txt | 2 +- docs/book/waf.txt | 2 +- docs/book/wscript | 14 ++++---- docs/sphinx/_templates/indexcontent.html | 4 +-- docs/sphinx/conf.py | 8 ++--- docs/sphinx/tools.rst | 5 ++- docs/sphinx/tutorial.rst | 8 ++--- wscript | 2 +- 16 files changed, 70 insertions(+), 94 deletions(-) diff --git a/DEVEL b/DEVEL index 411faf95..13736285 100644 --- a/DEVEL +++ b/DEVEL @@ -1,45 +1,28 @@ -Main repository for waf 1.8 on http://waf.googlecode.com/git/ -------------------------------------------------------------- +Waf 1.8 is on https://github.com/waf-project/waf +------------------------------------------------ waflib the core library waflib/Tools essential waf tools -waflib/extras contributed tools which are not included in the - waf file by default (except "compat15") -build_system_kit examples of build systems that can be created from waf +waflib/extras contributed tools which are not included in the waf file by default +build_system_kit examples of build systems that can be created from Waf tests various unit tests, most are unused anymore -playground experiments and integration tests for the tools in - the folder waflib/extras -demos integration tests - the folder can be configured - as a standalone project +playground experimental examples and test, most tools lie in the folder waflib/extras +demos integration tests - the folder can be configured as a standalone project demos/* integration tests and examples used as documentation docs documentation -docs/sphinx project extracting the docstrings from the source code to - create the apidocs +docs/sphinx project extracting the docstrings from the source code to create the API documentation -Documentation repository on http://docs.waf.googlecode.com/git/ ---------------------------------------------------------------- +Documentation +------------------------------------------------- -Contains the documentation: -API documentation http://docs.waf.googlecode.com/git/apidocs_17/index.html -The Waf Book http://docs.waf.googlecode.com/git/book_17/single.html -The Waf Book for Waf 1.6 (deprecated) http://docs.waf.googlecode.com/git/book_16/single.html -The Waf Book for Waf 1.5 (deprecated) http://docs.waf.googlecode.com/git/book_15/single.html +API documentation https://waf.io/apidocs/ +The Waf Book https://waf.io/book/ -Programming details -------------------- +Coding guidelines +----------------- +* We use tabs, no spaces * Do not use x.split("\n") but x.splitlines() * Do not catch all exceptions unless you have a good reason to do so (no "except:") * File handles are too easy to get wrong, use Node.readf/Node.writef/Utils.readf/Utils.writef -Wiki documentation on http://wiki.waf.googlecode.com/git/ ---------------------------------------------------------- - -The wiki documentation is always outdated - -Previous branches ------------------ - -old svn repository http://waf.googlecode.com/svn/trunk/ (for waf 1.5, read-only and unused) -old branch for waf 1.5 http://waf.googlecode.com/svn/branches/waf-1.5/ (again, read-only and unused) - diff --git a/README b/README index 54b165d2..8e6f365a 100644 --- a/README +++ b/README @@ -1,11 +1,11 @@ WHAT YOU WILL FIND HERE ----------------------- -Waf 1.8 - for Waf 1.7 use the branch waf-1.7 +Waf 1.8 - Recently moved to https://github.com/waf-project/waf -For the manual: http://docs.waf.googlecode.com/git/book_16/single.html -For the api docs: http://docs.waf.googlecode.com/git/apidocs_16/index.html -For the examples: see the folder demos/ +For the manual: https://waf.io/book/ +For the API documentation: https://waf.io/apidocs/ +For the examples: see the folder demos/ and the folder playground/ HOW TO CREATE THE WAF SCRIPT ---------------------------- @@ -38,16 +38,6 @@ $ cp waf demos/c/ $ cd demos/c/ $ ./waf configure build -USING GIT ---------- - -$ git clone https://code.google.com/p/waf/ -set $HOME/.netrc to read: -machine code.google.com login user@gmail.com password pass -$ git remote add code https://code.google.com/p/waf.docs/ -... make a few changes -$ git push code - --------------------------- Thomas Nagy, 2014-2015 (ita) diff --git a/README.md b/README.md index 48866aff..921a9aff 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ Waf is a Python-based framework for configuring, compiling and installing applic * *Flexibility*: new commands and tasks can be added very easily through subclassing, bottlenecks for specific builds can be eliminated through dynamic method replacement * *Extensibility*: though many programming languages and compilers are already supported by default, many others are available as extensions * *IDE support*: Eclipse, Visual Studio and Xcode project generators (waflib/extras/) - * *Documentation*: the application is based on a robust model documented in [The Waf Book](http://docs.waf.googlecode.com/git/book_18/single.html) and in the [API docs](http://docs.waf.googlecode.com/git/apidocs_17/index.html) + * *Documentation*: the application is based on a robust model documented in [The Waf Book](https://waf.io/book/) and in the [API docs](https://waf.io/apidocs/) * *Python compatibility*: cPython 2.5 to 3.4, Jython 2.5, IronPython, and Pypy -Waf is used in particular by innovative companies such as [Avalanche Studios](http://www.avalanchestudios.se) and by open-source projects such as [the Samba project](http://www.samba.org/). Learn more about Waf by reading [The Waf Book](http://docs.waf.googlecode.com/git/book_18/single.html). +Waf is used in particular by innovative companies such as [Avalanche Studios](http://www.avalanchestudios.se) and by open-source projects such as [the Samba project](https://www.samba.org/). Learn more about Waf by reading [The Waf Book](https://waf.io/book/). For researchers and build system writers, Waf also provides a framework for creating [custom build systems](http://code.google.com/p/waf/source/browse/build_system_kit/) and [package distribution systems](http://code.google.com/p/waf/source/browse/playground/distnet/README.rst). diff --git a/docs/book/conclusion.txt b/docs/book/conclusion.txt index 3ad3dc50..18a60a21 100644 --- a/docs/book/conclusion.txt +++ b/docs/book/conclusion.txt @@ -6,9 +6,9 @@ Due to the amount of features provided by Waf, this book cannot be both complete [options="header"] |================ |Link|Description -|http://docs.waf.googlecode.com/git/apidocs_17/index.html|The apidocs -|http://code.google.com/p/waf|The Waf project page -|http://code.google.com/p/waf/w/list|The Waf wiki, including the frequently asked questions (FAQ) +|https://waf.io/apidocs/index.html|The apidocs +|https://waf.io|The Waf project page and downloads +|https://github.com/waf-project/waf|Source code repository |http://groups.google.com/group/waf-users|The Waf mailing-list |http://waf-devel.blogspot.com/2011/01/python-32-and-build-system-kit.html|Information on the build system kit |================ diff --git a/docs/book/configuration.txt b/docs/book/configuration.txt index d41ded19..390c8cc9 100644 --- a/docs/book/configuration.txt +++ b/docs/book/configuration.txt @@ -178,11 +178,11 @@ out = 'build' def configure(ctx): ctx.find_program('touch', var='TOUCH') - ctx.check_waf_version(mini='1.8.4') + ctx.check_waf_version(mini='1.8.8') ctx.find_file('fstab', ['/opt', '/etc']) --------------- -Although these methods are provided by the context class _waflib.Configure.ConfigurationContext_, they will not appear on it in http://docs.waf.googlecode.com/git/apidocs_17/index.html[API documentation]. For modularity reasons, they are defined as simple functions and then bound dynamically: +Although these methods are provided by the context class _waflib.Configure.ConfigurationContext_, they will not appear on it in https://waf.io/apidocs/index.html[API documentation]. For modularity reasons, they are defined as simple functions and then bound dynamically: [source,python] --------------- @@ -394,7 +394,7 @@ Checking for program some_app : not found $ cat build/config.log <2> # project configured on Tue Jul 13 19:15:04 2010 by -# waf 1.8.4 (abi 98, python 20605f0 on linux2) +# waf 1.8.8 (abi 98, python 20605f0 on linux2) # using /home/waf/bin/waf configure # Checking for program some_app diff --git a/docs/book/cprog.txt b/docs/book/cprog.txt index 0df931c8..f9c7baba 100644 --- a/docs/book/cprog.txt +++ b/docs/book/cprog.txt @@ -204,7 +204,7 @@ from waflib import c_preproc c_preproc.go_absolute = True --------------- -Additional tools such as http://code.google.com/p/waf/source/browse/trunk/waflib/extras/gccdeps.py[gccdeps] or http://code.google.com/p/waf/source/browse/trunk/waflib/extras/dumbpreproc.py[dumbpreproc] provide alternate dependency scanners that can be faster in certain cases (boost). +Additional tools such as https://github.com/waf-project/waf/blob/master/waflib/extras/gccdeps.py[gccdeps] or https://github.com/waf-project/waf/blob/master/waflib/extras//dumbpreproc.py[dumbpreproc] provide alternate dependency scanners that can be faster in certain cases (boost). NOTE: The Waf engine will detect if tasks generate headers necessary for the compilation and compute the build order accordingly. It may sometimes improve the performance of the scanner if the tasks creating headers provide the hint 'ext_out=[".h"]'. @@ -304,7 +304,7 @@ def build(bld): --------------- <1> A simple shared library -<2> The 'cshlib' flags will be propagated to both the library and the program. footnote:[To prevent the propagation, see http://code.google.com/p/waf/source/browse/trunk/docs/book/examples/cprog_propagation/wscript] +<2> The 'cshlib' flags will be propagated to both the library and the program. <3> 'lib3' uses both a shared library and a static library <4> A program using 'lib3' @@ -683,7 +683,7 @@ The outputs are written in the build directory into the file 'config.log': [source,shishell] ------------------ # project configured on Tue Aug 31 17:30:21 2010 by -# waf 1.8.4 (abi 98, python 20605f0 on linux2) +# waf 1.8.8 (abi 98, python 20605f0 on linux2) # using /home/waf/bin/waf configure # --- diff --git a/docs/book/development.txt b/docs/book/development.txt index 755012e9..8cb6031e 100644 --- a/docs/book/development.txt +++ b/docs/book/development.txt @@ -206,11 +206,11 @@ USELIB_VARS['cprogram'] = USELIB_VARS['cxxprogram'] = \ ==== Setting up a Waf directory for development -Waf is hosted on http://code.google.com/p/waf/source[Google code], and uses Subversion for source control. To obtain the development copy, use: +Waf is hosted on https://github.com/waf-project/waf[Github], and uses Git for source control. To obtain the development copy, use: [source,shishell] --------------- -$ git clone http://code.google.com/p/waf/ wafdir +$ git clone https://github.com/waf-project/waf.git wafdir $ cd wafdir $ ./waf-light --make-waf --------------- diff --git a/docs/book/download.txt b/docs/book/download.txt index 386e7bb4..c4f04d03 100644 --- a/docs/book/download.txt +++ b/docs/book/download.txt @@ -2,7 +2,7 @@ === Obtaining the Waf file -The Waf project is located on http://code.google.com/p/waf[Google Code]. +The Waf project is located on https://waf.io[waf.io]. The current Waf version requires an interpreter for the Python programming language such as http://www.python.org[cPython] 2.5 to 3.4, http://pypy.org[Pypy] or http://www.jython.org[Jython] >= 2.5. ==== Downloading and using the Waf binary @@ -11,10 +11,10 @@ The Waf binary is a python script which does not require any installation whatso [source,shishell] --------------- -$ wget http://ftp.waf.io/pub/release/waf-1.8.4 -$ mv waf-1.8.4 waf +$ wget http://ftp.waf.io/pub/release/waf-1.8.8 +$ mv waf-1.8.8 waf $ python waf --version -waf 1.8.4 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) +waf 1.8.8 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) --------------- The +waf+ file has its own library compressed in a binary stream in the same file. Upon execution, the library is uncompressed in a hidden folder in the current directory. The folder will be re-created if removed. This scheme enables different Waf versions to be executed from the same folders: @@ -22,7 +22,7 @@ The +waf+ file has its own library compressed in a binary stream in the same fil [source,shishell] --------------- $ ls -ld .waf* -.waf-1.8.4-2c924e3f453eb715218b9cc852291170 +.waf-1.8.8-2c924e3f453eb715218b9cc852291170 --------------- NOTE: The binary file requires http://docs.python.org/library/bz2.html[bzip2] compression support, which may be unavailable in some self-compiled cPython installations. @@ -33,18 +33,18 @@ Building Waf requires a Python interpreter having a version number in the range [source,shishell] --------------- -$ wget http://ftp.waf.io/pub/release/waf-1.8.4.tar.bz2 -$ tar xjvf waf-1.8.4.tar.bz2 -$ cd waf-1.8.4 +$ wget http://ftp.waf.io/pub/release/waf-1.8.8.tar.bz2 +$ tar xjvf waf-1.8.8.tar.bz2 +$ cd waf-1.8.8 $ python waf-light Configuring the project 'build' finished successfully (0.001s) Checking for program python : /usr/bin/python Checking for python version : (2, 6, 5, 'final', 0) 'configure' finished successfully (0.176s) -Waf: Entering directory `/waf-1.8.4/build' +Waf: Entering directory `/waf-1.8.8/build' [1/1] create_waf: -> waf -Waf: Leaving directory `/waf-1.8.4/build' +Waf: Leaving directory `/waf-1.8.8/build' 'build' finished successfully (2.050s) --------------- @@ -86,13 +86,13 @@ The following will create a custom waf file which will import and execute 'foo' $ python waf-light --make-waf --tools=compat15,$PWD/aba.py --prelude=$'\tfrom waflib.extras import aba\n\taba.foo()' $ ./waf --help -This is Waf 1.8.4 +This is Waf 1.8.8 [...] --------------- Foreign files to add into the folder 'extras' must be given by absolute paths in the _--tools_ switch. Such files do not have to be Python files, yet, a typical scenario is to add an initializer to modify existing -functions and classes from the Waf modules. Various from the http://code.google.com/p/waf/source/browse/trunk/build_system_kit/[build system kit] illustrate how to create custom +functions and classes from the Waf modules. Various from the https://github.com/waf-project/waf/tree/master/build_system_kit/[build system kit] illustrate how to create custom build systems derived from Waf. === Using the Waf file @@ -112,7 +112,7 @@ On unix-like systems, it is usually much more convenient to set the executable p --------------- $ chmod 755 waf $ ./waf --version -waf 1.8.4 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) +waf 1.8.8 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) --------------- If the command-line interpreter supports aliases, it is recommended to set the alias once: @@ -121,7 +121,7 @@ If the command-line interpreter supports aliases, it is recommended to set the a --------------- $ alias waf=$PWD/waf $ waf --version -waf 1.8.4 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) +waf 1.8.8 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) --------------- Or, the execution path may be modified to point at the location of the waf binary: @@ -130,7 +130,7 @@ Or, the execution path may be modified to point at the location of the waf binar --------------- $ export PATH=$PWD:$PATH $ waf --version -waf 1.8.4 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) +waf 1.8.8 (54dc13ba5f51bfe2ae277451ec5ac1d0a91c7aaf) --------------- 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. diff --git a/docs/book/nodes.txt b/docs/book/nodes.txt index 27cc92b6..8e3e302a 100644 --- a/docs/book/nodes.txt +++ b/docs/book/nodes.txt @@ -143,7 +143,7 @@ some text ['.lock-wafbuild', 'foo.txt', 'build', 'wscript', '.git'] --------------- -NOTE: More methods may be found in the http://docs.waf.googlecode.com/git/apidocs_17/index.html[API documentation] +NOTE: More methods may be found in the https://waf.io/apidocs/index.html[API documentation] WARNING: The Node methods are not meant to be safe for concurrent access. The code executed in parallel (method run() of task objects for example) must avoid modifying the Node object data structure. diff --git a/docs/book/waf.txt b/docs/book/waf.txt index 0f61c938..1549b0a7 100644 --- a/docs/book/waf.txt +++ b/docs/book/waf.txt @@ -31,7 +31,7 @@ The Waf framework is somewhat different from traditional build systems in the se The objective of this book is to expose the use of the Waf build system though the use of Waf in practice, the description of the Waf extension system, and an overview of the Waf internals. We hope that this book will serve as a reference for both new and advanced users. Although this book does not deal with build systems in general, a secondary objective is to illustrate quite a few new techniques and patterns through numerous examples. -The chapters are ordered by difficulty, starting from the basic use of Waf and Python, and diving gradually into the most difficult topics. It is therefore recommended to read the chapters in order. It is also possible to start by looking at the http://code.google.com/p/waf/source/browse/#git%2Fdemos[examples] from the Waf distribution before starting the reading. +The chapters are ordered by difficulty, starting from the basic use of Waf and Python, and diving gradually into the most difficult topics. It is therefore recommended to read the chapters in order. It is also possible to start by looking at the https://github.com/waf-project/waf/tree/master/demos[examples] from the Waf distribution before starting the reading. :numbered: diff --git a/docs/book/wscript b/docs/book/wscript index ee49e8bb..efe012b1 100644 --- a/docs/book/wscript +++ b/docs/book/wscript @@ -135,18 +135,18 @@ def build(bld): bld.add_group() # separator, the documents may require any of the pictures from above bld(rule='${ADOC} -a icons=true -a stylesheet=${SRC[1].abspath()} -a iconsdir=. -a toc -d book -o ${TGT} ${SRC[0].abspath()}', - source='waf.txt waf.css', target='single.html', scan=ascii_doc_scan) + source='waf.txt waf.css', target='index.html', scan=ascii_doc_scan) - #bld(rule='${A2X} -L -a toc --icons-dir=. --icons -D ${gen.path.get_bld().abspath()} \ - # -d book -f pdf --dblatex-opts "-s ${SRC[1].abspath()} -p ${SRC[2].abspath()}" ${SRC[0].bldpath()}', - # shell=True, - # source='waf.txt asciidoc-dblatex.sty asciidoc-dblatex.xsl', target='waf.pdf', scan=ascii_doc_scan) + bld(rule='${A2X} -L -a toc --icons-dir=. --icons -D ${gen.path.get_bld().abspath()} \ + -d book -f pdf --dblatex-opts "-s ${SRC[1].abspath()} -p ${SRC[2].abspath()}" ${SRC[0].bldpath()}', + shell=True, + source='waf.txt asciidoc-dblatex.sty asciidoc-dblatex.xsl', target='waf.pdf', scan=ascii_doc_scan) - bld(rule='ln -sf single.html index.html', shell=True) + #bld(rule='ln -sf single.html index.html', shell=True) if bld.options.exe: def exe(ctx): - bld.exec_command('firefox build/single.html') + bld.exec_command('firefox build/index.html') bld.add_post_fun(exe) @TaskGen.feature('sizer') diff --git a/docs/sphinx/_templates/indexcontent.html b/docs/sphinx/_templates/indexcontent.html index ef916e46..b1a10281 100644 --- a/docs/sphinx/_templates/indexcontent.html +++ b/docs/sphinx/_templates/indexcontent.html @@ -45,8 +45,8 @@

Copyright
Copyright notice

-

Reporting bugs
- Where to report bugs

+

Reporting bugs
+ Where to report bugs or request new features

diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 705c6b7e..8c47195d 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -341,16 +341,16 @@ master_doc = 'index' # General information about the project. project = u'Waf' -copyright = u'2010, Thomas Nagy' +copyright = u'2005-2015, Thomas Nagy' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1.7.11' +version = '1.8.8' # The full version, including alpha/beta/rc tags. -release = '1.7.11' +release = '1.8.8' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -402,7 +402,7 @@ html_theme = 'default' #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". +# " v API documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. diff --git a/docs/sphinx/tools.rst b/docs/sphinx/tools.rst index 68bf0328..48305b22 100644 --- a/docs/sphinx/tools.rst +++ b/docs/sphinx/tools.rst @@ -35,6 +35,8 @@ be used directly, for example:: .. toctree:: + tools/clang + tools/clangxx tools/compiler_c tools/compiler_cxx tools/ar @@ -123,6 +125,7 @@ The next tools provide support for code generators used in C and C++ projects. tools/vala tools/glib2 tools/qt4 + tools/qt5 tools/kde4 tools/perl tools/python @@ -131,7 +134,7 @@ The next tools provide support for code generators used in C and C++ projects. Other compilers and tools ------------------------- -.. _extras: http://code.google.com/p/waf/source/browse/trunk/waflib/extras/ +.. _extras: https://github.com/waf-project/waf/tree/master/waflib/extras The following tools provide support for specific compilers or configurations. More tools are present in the extras_ folder, although they are not documented and as stable as the default tools. diff --git a/docs/sphinx/tutorial.rst b/docs/sphinx/tutorial.rst index 81ef3dbc..754ac1ec 100644 --- a/docs/sphinx/tutorial.rst +++ b/docs/sphinx/tutorial.rst @@ -30,14 +30,14 @@ Let's start with a new wscript file in the directory '/tmp/myproject':: def build(bld): print("build!") -We will also use a Waf binary file, for example http://waf.googlecode.com/files/waf-1.6.1, which we will copy in the project directory:: +We will also use a Waf binary file, for example waf-1.8.8, which we will copy in the project directory:: $ cd /tmp/myproject - $ wget http://waf.googlecode.com/files/waf-1.6.1 + $ wget https://waf.io/waf-1.8.8 To execute the project, we will simply call the command as an argument to ``waf``:: - $ ./waf-1.6.1 configure build + $ ./waf-1.8.8 configure build configure! build! @@ -165,7 +165,7 @@ The declaration can be made more user-friendly by binding new methods to the con bld.enterprise_program(source='main.c', target='app') The support code may be turned into a Waf tool by moving it to a separate file. -To ease the deployment, the new Waf tool can even be added to the waf file (see http://code.google.com/p/waf/source/browse/trunk/README). +To ease the deployment, the new Waf tool can even be added to the waf file (see https://github.com/waf-project/waf/blob/master/README#L10). Conclusion ---------- diff --git a/wscript b/wscript index fbd71447..f8923890 100644 --- a/wscript +++ b/wscript @@ -212,7 +212,7 @@ def sfilter(path): #cnt = process_decorators(cnt) #if cnt.find('set(') > -1: # cnt = 'import sys\nif sys.hexversion < 0x020400f0: from sets import Set as set\n' + cnt - cnt = '#! /usr/bin/env python\n# encoding: utf-8\n# WARNING! Do not edit! http://waf.googlecode.com/git/docs/wafbook/single.html#_obtaining_the_waf_file\n\n' + cnt + cnt = '#! /usr/bin/env python\n# encoding: utf-8\n# WARNING! Do not edit! https://waf.io/book/index.html#_obtaining_the_waf_file\n\n' + cnt else: f = open(path, "r")