mirror of https://gitlab.com/ita1024/waf.git
docs
This commit is contained in:
Thomas Nagy
parent
86121c8ea0
commit
de96c3c537
|
|
@ -207,7 +207,7 @@ just a test
|
|||
|
||||
=== Custom build outputs
|
||||
|
||||
==== Multiple configurations
|
||||
==== Multiple configuration folders
|
||||
|
||||
The _WAFLOCK_ environment variable is used to control the configuration lock and to point at the default build directory. Observe the results on the following project:
|
||||
|
||||
|
|
@ -271,7 +271,7 @@ $ tree -a
|
|||
<3> The configuration _release_ is used with a different lock file and a different build directory.
|
||||
<4> The contents of the project directory contain the two lock files and the two build folders.
|
||||
|
||||
The lock file may also be changed from the code by changing the appropriate variable in the waf scripts:
|
||||
The lock file name may also be changed from the code by changing the appropriate variable in the waf file:
|
||||
|
||||
[source,python]
|
||||
---------------
|
||||
|
|
@ -279,7 +279,7 @@ from waflib import Options
|
|||
Options.lockfile = '.lock-wafname'
|
||||
---------------
|
||||
|
||||
NOTE: The output directory pointed at by the waf lock file only has effect when not given in the waf script
|
||||
NOTE: The output directory pointed at by the waf lock file only has effect when not given in the waf file
|
||||
|
||||
==== Changing the output directory
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
== Projects and commands
|
||||
|
||||
=== Waf commands
|
||||
=== Waf commands and usage
|
||||
|
||||
As the Waf file is meant to be a generic utility for building projects, project-specific details are best kept and versioned in files residing along with the project source code. These files are modules written in the Python programming language and are named *wscript*. Although they can contain any Python code, Waf can use specific functions and classes defined in them. The next sections will explore a particularly useful concept called *function commands*.
|
||||
|
||||
|
|
@ -28,14 +28,11 @@ They take a single context parameter as input and do not have to return any part
|
|||
#! /usr/bin/env python
|
||||
# encoding: utf-8
|
||||
|
||||
def <1> hello(ctx <2>):
|
||||
def hello(ctx):
|
||||
print('hello world')
|
||||
---------------
|
||||
|
||||
<1> The _waf command_ *hello*
|
||||
<2> A waf context, used to share data among scripts
|
||||
|
||||
Calling the command instructs +waf+ to call function:
|
||||
Calling the command instructs +waf+ to call function the function *hello*:
|
||||
|
||||
[source,shishell]
|
||||
---------------
|
||||
|
|
@ -44,7 +41,9 @@ hello world
|
|||
'hello' finished successfully (0.001s)
|
||||
---------------
|
||||
|
||||
==== Waf command chaining
|
||||
The context object object enables data sharing across scripts, its usage will be described in sections further down.
|
||||
|
||||
==== Waf commands may be chained
|
||||
|
||||
As previously mentioned, commands are executed in the order defined on the command-line. A wscript file may thus provide an arbitrary amound of commands in the same _wscript_ file:
|
||||
|
||||
|
|
@ -73,9 +72,11 @@ $ waf ping pong ping ping
|
|||
'ping' finished successfully (0.001s)
|
||||
---------------
|
||||
|
||||
When an error occurs, the execution is interrupted and no further commands are called.
|
||||
|
||||
NOTE: Command functions are passed a new context object when they are called; the class for that object is command-specific: ConfigureContext for configure, BuildContext for build, OptionContext for option, and Context for any other command.
|
||||
|
||||
==== Using several scripts and folders
|
||||
==== Basic project structure
|
||||
|
||||
Although a Waf project must contain a top-level _wscript_ file, the contents may be split into several sub-project files. We will now illustrate this concept on a small project:
|
||||
|
||||
|
|
@ -123,9 +124,11 @@ $ waf ping
|
|||
'ping' finished successfully (0.001s)
|
||||
---------------
|
||||
|
||||
NOTE: The method _recurse_, and the attribute _path_ are available on all waf context classes
|
||||
NOTE: The method _recurse_, and the attribute _path_ are available on all waf context classes so that all waf commands may use them.
|
||||
|
||||
=== Waf project definition
|
||||
=== Fundamental Waf commands
|
||||
|
||||
The following sections provide details on major Waf commands which are often used or re-implemented in project files.
|
||||
|
||||
==== Configuring a project (the _configure_ command)
|
||||
|
||||
|
|
|
|||
|
|
@ -28,24 +28,24 @@ As software is getting increasingly complex and feature-rich, so is the process
|
|||
|
||||
While compilers sometimes attempt to do provide full build automation, they are usually limited to very specific features. For example, the Java compiler (javac) can build a whole source code tree at once, but another compiler is necessary to produce archive files (jar). Text editors and Integrated Development Environments (IDE such as Xcode or Eclipse) can provide build automation features, but their user interfaces are best at editing software, not at running builds. Version control systems such as Git are best-suited for managing end-user files, but are typically unfit for calling compilers and running scripts. And though orchestration solutions (Jenkins, Teamcity) are sometimes understood as build systems, they are usually unable to build the software themselves: they require build scripts and build software that is executed on their build agents (Maven, Make, etc).
|
||||
|
||||
We thus argue that building software is a unique activity in software development that requires a unique set of tools. The term "build system" is typically used to denote such software, and we believe two definitions should be separated:
|
||||
We thus argue that building software is a unique activity in software development that requires a unique set of tools. The term "build system" is typically used to denote such software, and we believe two definitions should be distinguished:
|
||||
|
||||
1. It is a piece of software that helps automating processes in a software project, and that it aimed in particular at processing source code
|
||||
2. It is the overall tool set required to process a work on a particular software project: compilers, build scripts, orchestration software, version control system, etc.
|
||||
A. It is a piece of software that helps automating processes in a software project, and that it aimed in particular at processing source code
|
||||
B. It is the overall tool set required to process a work on a particular software project: compilers, build scripts, orchestration software, version control system, etc.
|
||||
|
||||
Waf fits in the first definition which we use in the rest of this document.
|
||||
Waf matches the first definition which is used in the rest of this document.
|
||||
|
||||
=== The Waf framework
|
||||
|
||||
Build systems are usually bound to the specific frameworks that they belong to. For example, Visual Studio users will often use MSBuild and Angular.js users will probably use Npm. Such solutions are usually focusing on very specific features and are typically limited where it comes to processing other languages or different projects. For example, Ant is better suited than Make for managing Java projects, but is more limited than Make for managing simple c projects. Since programming languages and solutions evolve constantly, creating the ideal build system for everything is not really possible, so there are trade-offs between framework specialization and genericity.
|
||||
Build systems are usually bound to the specific frameworks that they belong to. For example, Visual Studio projects will often require MSBuild and Angular.js projects typically require Npm. Such solutions are usually focused on very specific features and are usually limited where it comes to processing other languages or different projects. For example, Ant is better suited than Make for managing Java projects, but is less convenient than Make for building simple c projects. Since programming languages and solutions evolve constantly, creating the ideal build system for everything is not really possible, so there are trade-offs between framework specialization and genericity.
|
||||
|
||||
There is yet a common subset of problems that build systems aim to address:
|
||||
|
||||
. Run compilers and scripts as distinct processes
|
||||
. Run processes only when necessary by recording "what has changed"
|
||||
. Run processes in parallel for efficiency reasons
|
||||
. Facilitate the execution of software tests such as configuration tests
|
||||
. Provide support for typical compilers and tools configurations
|
||||
- Run compilers and scripts as distinct processes
|
||||
- Run processes only when necessary by recording "what has changed"
|
||||
- Run processes in parallel for efficiency reasons
|
||||
- Facilitate the execution of software tests such as configuration tests
|
||||
- Provide support for typical compilers and tools configurations
|
||||
|
||||
Waf fulfills the features above out-of-the-box, and provides a framework to extend its functionality when necessary.
|
||||
The main differences compared to other frameworks lie it its design:
|
||||
|
|
|
|||
|
|
@ -143,7 +143,8 @@ def build(bld):
|
|||
bld(rule='${ADOC} -a icons=true -b html5 -a stylesheet=${SRC[1].abspath()} -a iconsdir=. -a toc -d book -o ${TGT} ${SRC[0].abspath()}',
|
||||
source='waf_.txt waf.css', target='index.html', scan=ascii_doc_scan)
|
||||
|
||||
bld(rule='${A2X} -L -a toc --icons-dir=. --icons -d book -f pdf --dblatex-opts "-s ${SRC[1].abspath()} -p ${SRC[2].abspath()} -o ${TGT}" ${SRC[0].bldpath()}',
|
||||
if True:
|
||||
bld(rule='${A2X} -L -a toc --icons-dir=. --icons -d book -f pdf --dblatex-opts "-s ${SRC[1].abspath()} -p ${SRC[2].abspath()} -o ${TGT}" ${SRC[0].bldpath()}',
|
||||
shell=True,
|
||||
source='waf_.txt asciidoc-dblatex.sty asciidoc-dblatex.xsl', target='waf.pdf', scan=ascii_doc_scan)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue