Package waftools¶
-
waftools.__init__.build(bld, trees=[])[source]¶ Perform build command on all given source trees.
Param: bld: build context Param: trees: list of source tree names
-
waftools.__init__.get_scripts(top, name)[source]¶ Returns a list of top level paths containing the specified file name.
Param: top: root where the search should be started. Param: name: name of the file to be found.
-
waftools.__init__.recurse(ctx, trees=[])[source]¶ Recurse on all given source trees.
Param: ctx: waf context Param: trees: list of source tree names
Module bdist¶
Summary¶
Creates archives (.tar.gz) and/or installers (e.g. NSIS) for end users containing all build results (i.e. artifacts).
Description¶
Using this tool, it is possible to create archives and installers containing all files, libraries and binaries that are the results of the build and install process. The structure and prefix will be the same as has been defined in the waf build environment. At present the following distribution formats are supported: - windows installers using NSIS - compressed tar.bz2 archives - list; displays all files (including complete path) to be packaged
When selecting NSIS as distribution method, a .nsi script may be provided, if not a default .nsi script will be generated.
Usage¶
For windows targets platforms installers can be created using the NullSoft Installable Scripting system (NSIS). If no user defined .nsi script is provided a default one will be created in the top level directory of the build system.
The code snippet below presents a wscript that provides support for creating installers using NSIS:
import waftools
def options(opt):
opt.load('compiler_c')
opt.load('bdist', tooldir=waftools.location)
def configure(conf):
conf.load('compiler_c')
conf.load('bdist')
def build(bld):
bld.program(target='hello', source='hello.c')
Using this code snippet, a Windows installer can be created using the following command:
waf bdist --formats=nsis
-
class
waftools.bdist.BDistContext(**kw)[source]¶ Bases:
waflib.Build.InstallContextcreates installers (e.g. NSIS) for end users.
-
bdist_ls(appname, variant, version, files)[source]¶ Lists all files that will be packaged.
Parameters: - appname (str) – Functional application and bdist name
- variant (str or None) – Name of the build variant (if any)
- version (str) – Current version of the application being packaged
- files (list) – List of file nodes
-
bdist_nsis(appname, version)[source]¶ Creates an installer for Windows hosts using NSIS.
If the install script does not exist, a default install script will be created by this module.
Parameters: - appname (str) – Functional application and bdist name
- version (str) – Current version of the application being packaged
-
bdist_tar_bz2(appname, variant, version)[source]¶ Creates a tar.gz archive.
Parameters: - appname (str) – Functional application and bdist name
- variant (str or None) – Name of the build variant (if any)
- version (str) – Current version of the application being packaged
-
cmd= 'bdist'¶
-
execute(*k, **kw)[source]¶ Executes normal ‘install’ into a special, temporary, bdist directory and creates a bdist (e.g. tar.bz2 or rpm) file containing all installed files into the bdist directory.
-
fun= 'build'¶
-
Module ccenv¶
Summary¶
Setup and configure multiple C/C++ build environments and configure common tools for C/C++ projects. When using this module the following tools will be loaded and configured automatically:
- cmake
- codeblocks
- cppcheck
- doxygen
- eclipse
- indent
- makefile
- msdev
- bdist
- tree
Usage¶
The code snippet below provides an example of how a complete build environment can be created allowing you to build, not only for the host system, but also for one or more target platforms using, for instance, a C/C++ cross compiler:
#!/usr/bin/env python
# -*- encoding: utf-8 -*-
import os, waftools
from waftools import ccenv
top = '.'
out = 'build'
ini = os.path.abspath('ccenv.ini').replace('\', '/')
VERSION = '0.0.1'
APPNAME = 'example'
def options(opt):
opt.load('ccenv', tooldir=waftools.location)
def configure(conf):
conf.load('ccenv')
def build(bld):
ccenv.build(bld, trees=['components'])
for var in ccenv.variants(ini):
for ctx in ccenv.contexts():
name = ctx.__name__.replace('Context','').lower()
class _t(ctx):
__doc__ = "%ss '%s'" % (name, var)
cmd = name + '_' + var
variant = var
When loading and configuring the ccenv tool, as shown in the example above, all required C/C++ tools for each build environment variant (i.e. native or cross- compile) will be loaded and configured as well; e.g. compilers, makefile-, cmake-, eclipse-, codeblocks- and msdev exporters, cppcheck source code checking, doxygen documentation creation will be available for each build variant. Additional (ccross) compile build environments can be specified in a seperate .INI file (named ccenv.ini in the example above) using following syntax:
[arm]
prefix = arm-linux-gnueabihf
[msvc]
c = msvc
cxx = msvc
The section name, arm in the example above, specifies the name of the compile build environment variant. The prefix combined with compiler type (c,cxx) will be used in order to create the concrete names of the cross compile toolchain binaries:
AR = arm-linux-gnueabihf-ar
CC = arm-linux-gnueabihf-gcc
CXX = arm-linux-gnueabihf-g++
Concrete build scripts (i.e. wscript files) for components can be placed somewhere within the components sub-directory. Any top level wscript file of a tree (being components in this example) will be detected and incorporated within the build environment. Any wscript files below those top level script files will have to be included using the bld.recurse(‘../somepath’) command from the top level script of that tree.
-
waftools.ccenv.build(bld, trees=[])[source]¶ Performs build context commands for one or more C/C++ build environments using the trees argument as list of source directories.
Parameters: - bld (waflib.Build.BuildContext) – build context
- trees (list) – top level directories containing projects to build
-
waftools.ccenv.configure(conf)[source]¶ Create and configure C/C++ build environment(s).
Parameters: conf (waflib.Configure.ConfigurationContext) – configuration context
-
waftools.ccenv.configure_base(conf)[source]¶ - Generic tool and compiler configuration settings used
- for both host and variant build environments.
Parameters: conf (waflib.Configure.ConfigurationContext) – configuration context
-
waftools.ccenv.configure_gcc(conf)[source]¶ Configures general environment settings for GNU compilers; e.g. set default C/C++ compiler flags and defines based on the value of the command line –debug option.
Parameters: conf (waflib.Configure.ConfigurationContext) – configuration context
-
waftools.ccenv.configure_host(conf, host, c, cxx)[source]¶ Create and configure default C/C++ build environment.
Parameters: - conf (waflib.Configure.ConfigurationContext) – configuration context
- host (str) – name of the host machine (as used in waf)
- c (dict) – contains default C compiler settings
- cxx (dict) – contains default C++ compiler settings
-
waftools.ccenv.configure_msvc(conf)[source]¶ Configures general environment settings for MSVC compilers; e.g. set default C/C++ compiler flags and defines based on the value of the command line –debug option.
Parameters: conf (waflib.Configure.ConfigurationContext) – configuration context
-
waftools.ccenv.configure_variants(conf, host)[source]¶ Create and configure variant C/C++ build environments.
uses the the configuration data as specified in the .ini file using configparser.ExtendedInterpolation syntax.
Parameters: - conf (waflib.Configure.ConfigurationContext) – configuration context
- host (str) – name of the host machine (as used in waf)
-
waftools.ccenv.contexts()[source]¶ Returns a list of build contexts to be used for variant build environments.
-
waftools.ccenv.get_ccenv(fname)[source]¶ Returns dictionary of variant C/C++ build environments. In which the keys are the name of the actual variant C/C++ build environments and its values the settings for that variant build environment.
Parameters: fname (str) – Complete path to the configuration file.
Module ccross¶
Summary¶
Setup and configure multiple C/C++ build environments and configure common C/C++ tools used when cross-compiling. When using this module the following tools will be loaded and configured autmatically as well:
- cmake
- codeblocks
- cppcheck
- doxygen
- eclipse
- gnucc
- indent
- makefile
- msdev
- bdist
- tree
Warning
This module has been marked as deprecated and will be removed in release version 0.5.0; use the ccenv module instead.
Usage¶
The code snippet below provides an example of how a complete build environment can be created allowing you to build, not only for the host system, but also for one or more target platforms using a C/C++ cross compiler:
#!/usr/bin/env python
# -*- encoding: utf-8 -*-
import os, waftools
from waftools import ccross
top = '.'
out = 'build'
prefix = 'output'
VERSION = '0.0.1'
APPNAME = 'cross-test'
def options(opt):
opt.add_option('--prefix', dest='prefix', default=prefix,
help='installation prefix [default: %r]' % prefix)
opt.load('ccross', tooldir=waftools.location)
def configure(conf):
conf.load('ccross')
def build(bld):
ccross.build(bld, trees=['components'])
for var in ccross.variants():
for ctx in ccross.contexts():
name = ctx.__name__.replace('Context','').lower()
class _t(ctx):
__doc__ = "%ss '%s'" % (name, var)
cmd = name + '_' + var
variant = var
When loading and configuring the ccross tool, as shown in the example above, all required C/C++ tools for each build environment variant (i.e. native or cross- compile) will be loaded and configured as well; e.g. compilers, makefile-, cmake-, eclipse-, codeblocks- and msdev exporters, cppcheck source code checking, doxygen documentation creation will be available for each build variant. Cross compile build environments can be specified in a seperate .INI file (named ccross.ini in the example above) using following syntax:
[arm]
c = gcc
cxx = g++
prefix = arm-linux-gnueabihf
The section name, arm in the example above, specifies the name of the cross-compile build environment variant. The prefix combined with compiler type (c,cxx) will be used in order to create the concrete names of the cross compile toolchain binaries:
AR = arm-linux-gnueabihf-ar
CC = arm-linux-gnueabihf-gcc
CXX = arm-linux-gnueabihf-g++
Concrete build scripts (i.e. wscript files) for components can be placed somewhere within the components sub-directory. Any top level wscript file of a tree (being components in this example) will be detected and incorporated within the build environment. Any wscript files below those top level script files will have to be included using the bld.recurse(‘../somepath’) command from the top level script of that tree.
-
waftools.ccross.configure_cross(conf, host)[source]¶ create and configure cross compile environments
uses the the configuration data as specified in the .ini file using configparser.ExtendedInterpolation syntax.
-
waftools.ccross.contexts()[source]¶ Returns a list of cross-compile build contexts.
Parameters: name (list of waflib.Build.BuildContext) – Complete path to the config.ini file
Module cmake¶
Summary¶
Generate cmake files of all C/C++ programs, static- and shared libraries that have been defined within a waf build environment. Once exported to cmake, all exported (C/C++) tasks can be build without any further need for, or dependency, to the waf build system itself.
cmake is an open source cross-platform build system designed to build, test and package software. It is available for all major Desktop Operating Systems (MS Windows, all major Linux distributions and Macintosh OS-X). See http://www.cmake.org for a more detailed description on how to install and use it for your particular Desktop environment.
Description¶
When exporting waf project data, a single top level CMakeLists.txt file will be exported in the top level directory of your waf build environment. This cmake build file will contain references to all exported cmake build files of each individual C/C++ build task. It will also contain generic variables and settings (e.g compiler to use, global preprocessor defines, link options and so on).
Example below presents an overview of an environment in which cmake build files already have been exported:
.
├── components
│ └── clib
│ ├── program
│ │ ├── CMakeLists.txt
│ │ └── wscript
│ ├── shared
│ │ ├── CMakeLists.txt
│ │ └── wscript
│ └── static
│ ├── CMakeLists.txt
│ └── wscript
│
├── CMakeLists.txt
└── wscript
Usage¶
Tasks can be exported to cmake using the command, as shown in the example below:
$ waf cmake
All exported cmake build files can be removed in ‘one go’ using the cmake cleanup option:
$ waf cmake --cmake-clean
Tasks generators to be excluded can be marked with the skipme option as shown below:
def build(bld):
bld.program(name='foo', src='foobar.c', cmake_skip=True)
-
class
waftools.cmake.CMakeContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexport C/C++ tasks to CMake.
-
cmd= 'cmake'¶
-
-
waftools.cmake.cleanup(bld)[source]¶ Removes all generated makefiles from the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
-
waftools.cmake.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
Module codeblocks¶
Summary¶
Exports and converts waf project data, for C/C++ programs, static- and shared libraries, into Code::Blocks project files (.cbp) and workspaces (codeblock.workspace). Code::Blocks is an open source integrated development environment for C and C++. It is available for all major Desktop Operating Systems (MS Windows, all major Linux distributions and Macintosh OS-X). See http://www.codeblocks.org for a more detailed description on how to install and use it for your particular Desktop environment.
Description¶
When exporting waf project data, a single Code::Blocks workspace will be exported in the top level directory of your WAF build environment. This workspace file will contain references to all exported Code::Blocks projects and will include dependencies between those projects.
For each single task generator (waflib.TaskGenerator), for instance a bld.program(...) which has been defined within a wscript file somewhere in the build environment, a single Code::Blocks project file will be generated in the same directory as where the task generator has been defined. The name of this task generator will be used as name for the exported Code::Blocks project file. If for instance the name of the task generator is hello, then a Code::Blocks project file named hello.cbp will be exported.
Example below presents an overview of an environment in which Code::Blocks files already have been exported:
.
├── components
│ └── clib
│ ├── program
│ │ ├── cprogram.cbp
│ │ └── wscript
│ ├── shared
│ │ ├── cshlib.cbp
│ │ └── wscript
│ └── static
│ ├── cstlib.cbp
│ └── wscript
│
├── waf.cbp
├── codeblocks.workspace
└── wscript
Projects will be exported such that they will use the same settings and structure as has been defined for that build task within the waf build environment. Projects will contain exactly one build target per build variant that has been defined in the waf build environment, as explained in the example below;
input: In a waf build environment three variants have been defined, one default (without name) build used for normal compiling and linking for the current host, and two variants used for cross compiling and linking for embedded systems; one is named arm5 the other arm7. Also the complete environment has been configured to be build with debugging information (i.e. the CFLAGS and CXXFLAGS both contain the compiler option`-g`).
output: Each exported project will contain the following build targets: - The first named debug, for the current host platform, - The second named arm5-debug, for the ARM5 target, and - The third named arm7-debug, for the ARM7 target.
Please note that in contrast to a normal IDE setup the exported projects will contain either a debug or a release build target but not both at the same time. By doing so exported projects will always use the same settings (e.g. compiler options, installation paths) as when building the same task in the waf build environment from command line.
Besides these normal projects that will be exported based on the task generators that have been defined within the waf build environment, a special Code::Blocks project named waf.cbp will also be exported. This project will be stored in the top level directory of the build environment and will contain the following build targets per build variant;
- build
- clean
- install
- uninstall
If, for instance, an additional build variant named arm5 has been defined in the waf build environment, then the following build targets will be added as well;
- build_arm5
- clean_arm5
- install_arm5
- uninstall_arm5
Usage¶
Code::Blocks project and workspace files can be exported using the codeblocks command, as shown in the example below:
$ waf codeblocks
When needed, exported Code::Blocks project- and workspaces files can be removed using the clean command, as shown in the example below:
$ waf codeblocks --clean
Once exported simple open the codeblocks.workspace using Code::Blocks. This will automatically open all exported projects as well.
Tasks generators to be excluded can be marked with the skipme option as shown below:
def build(bld):
bld.program(name='foo', src='foobar.c', codeblocks_skip=True)
-
class
waftools.codeblocks.CBProject(bld, gen)[source]¶ Bases:
waftools.codeblocks.CodeBlocksClass used for exporting waf project data to Code::Blocks projects.
Parameters: - bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment.
- gen (waflib.Task.TaskGen) – Task generator that contains all information of the task to be converted and exported to the Code::Blocks project.
-
class
waftools.codeblocks.CBWorkspace(bld)[source]¶ Bases:
waftools.codeblocks.CodeBlocksClass used for exporting waf project data to a Code::Blocks workspace located in the lop level directory of the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment.
-
class
waftools.codeblocks.CodeBlocks(bld)[source]¶ Bases:
objectAbstract base class used for exporting waf project data to Code::Blocks projects and workspaces.
Parameters: bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment. -
OBJECT= '4'¶ Identifier for projects for building objects only
-
PROGRAM= '1'¶ Identifier for projects containing an executable
-
SHLIB= '3'¶ Identifier for projects containing a shared library
-
STLIB= '2'¶ Identifier for projects containing a static library
-
-
class
waftools.codeblocks.CodeblocksContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexport C/C++ tasks to Code::Blocks projects and workspaces.
-
cmd= 'codeblocks'¶
-
-
class
waftools.codeblocks.WafCBProject(bld)[source]¶ Bases:
waftools.codeblocks.CodeBlocksClass used for creating a dummy Code::Blocks project containing only waf commands as pre build steps.
Parameters: bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment.
-
waftools.codeblocks.cleanup(bld)[source]¶ Removes all Code::Blocks projects and workspaces from the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
-
waftools.codeblocks.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
Module cppcheck¶
Summary¶
Provides a waf wrapper (i.e. waftool) around the static C/C++ source code checking tool cppcheck.
See http://cppcheck.sourceforge.net/ for more information on cppcheck itself; how you can obtain and install it for your particular desktop environment. Note that many linux distributions already provide a ready to install version of cppcheck. On Fedora, for instance, it can be installed using yum:
$ sudo yum install cppcheck
Description¶
Each time a C/C++ task generator within your waf build environment is being build or rebuild, its source code can be checked using cppcheck. This module will gather and extract all the required information from the C/C++ task generator (e.g. bld.program defined somewhere in a wscript file) and will use it to perform a source code analysis using cppcheck on command line. The command line results from cppcheck (in XML format) will be used as input in order to create a highlighted and colorful HTML report pinpointing all (possible) problems. For each single C/C++ task defined within your waf build environment such a separate HTML report will be created. Furthermore a single HTML index page will be created containing references to all individual HTML reports of components. All these reports will be stored in the sub directory reports/cppcheck in the top level directory of your build environment. When needed this location can also be changed to, see command line options.
Example below present an example of the reports generated in a build environment in which three C components have been defined:
.
├── components
│ ├── chello
│ │ ├── include
│ │ │ └── hello.h
│ │ ├── src
│ │ │ └── hello.c
│ │ └── wscript
│ ├── ciambad
│ │ ├── cppcheck.suppress
│ │ ├── include
│ │ ├── src
│ │ │ └── iambad.c
│ │ └── wscript
│ └── cleaking
│ ├── include
│ │ └── leaking.h
│ ├── src
│ │ └── leaking.c
│ └── wscript
├── reports
│ └── cppcheck
│ ├── components
│ │ ├── chello
│ │ │ ├── chello.html
│ │ │ ├── index.html
│ │ │ ├── style.css
│ │ │ └── chello.xml
│ │ ├── ciambad
│ │ │ ├── ciambad.html
│ │ │ ├── index.html
│ │ │ ├── style.css
│ │ │ └── ciambad.xml
│ │ └── cleaking
│ │ ├── cleaking.html
│ │ ├── index.html
│ │ ├── style.css
│ │ └── cleaking.xml
│ ├── index.html
│ └── style.css
└── wscript
Note that each report for a task generator from the components directory contains an extra indent in the reports directory; cppchecks reports are stored in a sub directory using the name of the unique task generator as name for that sub directory. This allows for the creation of multiple reports at the same location in case a single wscript file contains multiple task generators in the components directory.
Under normal conditions no additional parameters or definitions are needed in the definition of a C/C++ task generator itself; simply defining it as program, stlib or shlib and adding this module to the top level wscript of your waf build environment will suffice. However in some cases cppcheck might detect problems that are either not true, or you just want to suppress them. In these cases you can either use global suppression options (using command line options) but you can also add special rules to the definition of the C/C++ task generators in question (more on this the next section Usage).
Usage¶
In order to use this waftool simply add it to the ‘options’ and ‘configure’ functions of your main waf script as shown in the example below:
import waftools
def options(opt):
opt.load('cppcheck', tooldir=waftools.location)
def configure(conf):
conf.load('cppcheck')
When configured as shown in the example above, cppcheck will perform a source code analysis on all C/C++ tasks that have been defined in your waf build environment when using the ‘–cppcheck’ build option:
waf build --cppcheck
The example shown below for a C program will be used as input for cppcheck when building the task:
def build(bld):
vbld.program(name='foo', src='foobar.c')
The result of the source code analysis will be stored both as XML and HTML files in the build location for the task. Should any error be detected by cppcheck, then the build process will be aborted and a link to the HTML report will be presented. When desired you also choose to resume with checking other components after a fatal error has been detected using the following command line option:
$ waf build --cppcheck --cppcheck-err-resume
When needed source code checking by cppcheck can be disabled per task or even for each specific error and/or warning within a particular task.
In order to exclude a task from source code checking add the skip option to the task as shown below:
def build(bld):
bld.program(name='foo', src='foobar.c', cppcheck_skip=True)
When needed problems detected by cppcheck may be suppressed using a file containing a list of suppression rules. The relative or absolute path to this file can be added to the build task as shown in the example below:
bld.program(name='bar', src='foobar.c', cppcheck_suppress='bar.suppress')
A cppcheck suppress file should contain one suppress rule per line. Each of these rules will be passed as an ‘–suppress=<rule>’ argument to cppcheck.
-
class
waftools.cppcheck.CppCheck(tgen, root, fatals)[source]¶ Bases:
objectClass used for creating colorfull HTML reports based on the source code check results from cppcheck.
Excutes source code checking on each C/C++ source file defined in the task generator.
Performs following steps per source file: - check source using cppcheck, use xml output - save the result from stderr as xml file - process and convert the results from stderr and save as html report - report defects, if any, to stout and including a link to the report
Parameters: - tgen (waflib.Task.TaskGen) – Contains all input information for the C/C++ component
- root (str) – top level directory for storing the reports
- fatals (list) – list of severities that should be treated as fatal when encountered
-
class
waftools.cppcheck.CppCheckFormatter(**options)[source]¶ Bases:
pygments.formatters.html.HtmlFormatterFormatter used for adding error messages to HTML report containing syntax highlighted source code.
-
errors= []¶ List of error messages. Contains the error message and line number.
-
-
class
waftools.cppcheck.Defect(url, kind, severity, description, verbose, file, line)[source]¶ Bases:
object
-
waftools.cppcheck.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
-
waftools.cppcheck.cppcheck_execute(self)[source]¶ Method that will be invoked by waf for each task generator for the C/C++ language.
Parameters: self (waflib.Task.TaskGen) – A task generator that contains all information of the C/C++ program, shared- or static library to be exported.
-
waftools.cppcheck.options(opt)[source]¶ Adds command line options to the waf build environment
Parameters: opt (waflib.Options.OptionsContext) – Options context from the waf build environment.
-
waftools.cppcheck.postfun(bld)[source]¶ Method that will be invoked by the waf build environment once the build has been completed.
It will use the result of the source code checking stored within the given build context and use it to create a global HTML index. This global index page contains a reference to all reports on C/C++ components that have been checked.
Parameters: bld (waflib.Build.BuildContext) – Build context from the waf build environment.
Module doxygen¶
Summary¶
Generates C/C++ source code documentation using Doxygen.
Description¶
This module contains a wrapper around doxygen; the de facto standard tool for generating documentation from annotated C/C++ sources. Doxygen is part of many linux distributions (e.g. Ubuntu, Fedora, ..) but can also be found at http://www.doxygen.org/
In order to start generating documentation of C/C++ source code simply issue the following command:
$ waf doxygen
When needed the generation of documentation for a specific task can be skipped by adding the feature ‘doxygen_skipme’ to the task, as presented in the example below:
bld.shlib(..., doxygen_skipme=True)
For each C/C++ static- and shared library task doxygen will store the documentation results in:
reports/doxygen/<task-name>
Usage¶
In order to use this waftool simply add it to the ‘options’ and ‘configure’ functions of your main waf script as shown in the example below:
import waftools
def options(opt):
opt.load('doxygen', tooldir=waftools.location)
def configure(conf):
conf.load('doxygen')
When configured as shown in the example above, doxygen will generate source code documentation for all C/C++ tasks that have been defined in your waf build environment when issuing the ‘doxygen’ build command:
waf doxygen --targets=cprogram
-
class
waftools.doxygen.DoxygenContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextgenerates C/C++ source code documentation using doxygen.
-
cmd= 'doxygen'¶
-
execute()[source]¶ Enrty point for the doxygen source code document generator.
iterate through all groups(g) and task generators (t) and generate doxygen report for C and C++ tasks.
-
fun= 'build'¶
-
Module eclipse¶
Summary¶
Exports and converts waf project data, for C/C++ programs, static- and shared libraries, into Eclipse CDT project files (.projects, .cproject). Eclipse is an open source integrated development environment, which can be used, amongst others, for development of C/C++ programs.
See https://www.eclipse.org and https://www.eclipse.org/cdt for a more detailed description on how to install and use it for your particular Desktop environment.
Note
Export of C/C++ projects are supported for GCC/MinGW compilers only, other compilers and/or environments (e.g. MSVC, CygWin) are NOT supported!
Description¶
For each single C/C++ task generator (waflib.TaskGenerator), for instance a bld.program(...) which has been defined within a wscript file somewhere in the build environment, a single Eclipse CDT project file will be generated in the same directory as where the task generator has been defined. Once generated these projects can be imported into Eclipse using ‘Import -> General -> Existing Projects Into Workspace’.
Example below presents an overview of an environment in which Eclipse projects already have been exported:
.
├── components
│ └── clib
│ ├── program
│ │ ├── .project
│ │ ├── .cproject
│ │ └── wscript
│ ├── shared
│ │ ├── .project
│ │ ├── .cproject
│ │ └── wscript
│ └── static
│ ├── .project
│ ├── .cproject
│ └── wscript
│
└── wscript
Warning
Export of multiple C/C++ build tasks (program, stlib and/or shlib) which have been defined within the same directory is not supported.
Projects will be exported such that they will use the same settings and structure as has been defined for that build task within the waf build environment. Projects will contain exactly one build target per build variant that has been defined in the waf build environment, as explained in the example below;
input: In a waf build environment three variants have been defined, one default (without name) build used for normal compiling and linking for the current host, and two variants used for cross compiling and linking for embedded systems; one is named arm5 the other arm7. Also the complete environment has been configured to be build with debugging information (i.e. the CFLAGS and CXXFLAGS both contain the compiler option`-g`).
output: Each exported project will contain the following build targets: - The first named debug, for the current host platform, - The second named arm5-debug, for the ARM5 target, and - The third named arm7-debug, for the ARM7 target.
Please note that in contrast to a normal IDE setup the exported projects will contain either a debug or a release build target but not both at the same time. By doing so exported projects will always use the same settings (e.g. compiler options, installation paths) as when building the same task in the waf build environment from command line.
Usage¶
Eclipse project and workspace files can be exported using the eclipse command, as shown in the example below:
$ waf eclipse
When needed, exported Eclipse project- and workspaces files can be removed using the clean command, as shown in the example below:
$ waf eclipse --clean
Tasks generators to be excluded can be marked with the skipme option as shown below:
def build(bld):
bld.program(name='foo', src='foobar.c', eclipse_skip=True)
-
class
waftools.eclipse.CDTLaunch(bld, tgen, instance, btype, ext)[source]¶ Bases:
waftools.eclipse.ProjectClass for exporting a CDT launcher for C/C++ programs.
Parameters: - bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
- gen (waflib.Task.TaskGen) – The C/C++ task generator for which the launcher should be created.
- instance (str) – Identifier from the Eclipse CDT project of the program to be started by this launcher
- btype (str) – Build type and build directory name (debug|release)
- ext (str) – Program name extension
-
class
waftools.eclipse.CDTProject(bld, tgen)[source]¶ Bases:
waftools.eclipse.EclipseProjectClass for exporting C/C++ task generators to an Eclipse CDT project. When exporting this class exports three files associated with C/C++ projects:
.project .cproject target_name.launch
The first file mostly contains perspective, the second contains the actual C/C++ project while the latter is a launcher which can be import into Eclipse and used to run and/or debug C/C++ programs.
Parameters: - bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
- tgen (waflib.Task.TaskGen) – Task generator that contains all information of the task to be converted and exported to the Eclipse project.
- project – Reference to Eclipse project (which will export the .project file.
- project – Project
-
class
waftools.eclipse.EclipseContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexport C/C++ tasks to Eclipse CDT projects.
-
cmd= 'eclipse'¶
-
-
class
waftools.eclipse.EclipseProject(bld, tgen, fname, template)[source]¶ Bases:
objectAbstract class for exporting Eclipse project files.
Parameters: - bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
- tgen (waflib.Task.TaskGen) – Task generator that contains all information of the task to be converted and exported to the Eclipse project.
-
class
waftools.eclipse.Project(bld, tgen)[source]¶ Bases:
waftools.eclipse.EclipseProjectClass for exporting Eclipse ‘.project’ files.
Parameters: - bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
- tgen (waflib.Task.TaskGen) – Task generator that contains all information of the task to be converted and exported to the Eclipse project.
-
waftools.eclipse.cleanup(bld)[source]¶ Removes all generated Eclipse project- and launcher files
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
-
waftools.eclipse.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
-
waftools.eclipse.detect_project_duplicates(bld, targets)[source]¶ Warns when multiple TaskGen’s have been defined in the same directory.
Since Eclipse works with static project filenames, only one project per directory can be created. If multiple task generators have been defined in the same directory (i.e. same wscript) one will overwrite the other(s). This problem can only e circumvented by changing the structure of the build environment; i.e. place each single task generator in a seperate directory.
-
waftools.eclipse.export(bld)[source]¶ Generates Eclipse CDT projects for each C/C++ task.
Also generates a top level Eclipse PyDev project for the WAF build environment itself. Warns when multiple task have been defined in the same, or top level, directory.
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
Module export¶
Summary¶
Provides conversion and export of C/C++ programs, static- and shared libraries to foreign build system formats (e.g. make) as well as projects and workspaces for C/C++ integrated development environments (e.g. Eclipse).
Description¶
This module can be used to convert and export waf project data of C/C++ programs, static- and shared libraries into one or more of the following formats: - Makefiles (GNU/MinGW/CygWin), - CMake makefiles, - Code::Blocks projects and workspaces, - Eclipse CDT projects - Microsoft Visual Studio
Once exported to Make and/or CMake makefiles, all exported (C/C++) tasks can be build without any further need for, or dependency, to the waf build system itself. Exporting to these formats can be beneficial when you need to tie your build environment to some external system, a CI build system for instance, that is unable to interact with waf, or just does a poor job at it. In this case you can use waf as a kind of templating system, make use of its versatility and export new makefiles whenever needed. Note that in such a case the exported makefiles will merely act as intermediate files that shouldn’t be altered manually; any changes to the build environment needed should made to wscripts within waf build system from they have been generated. Of course one could also use the export as last resort in order to stop using waf as build system altogether and just convert all C/C++ tasks from the waf build environment into Make and/or CMake makefiles.
When exporting C/C++ tasks to integrated developments environments (e.g. Eclipse), data will be converted and exported such, that it will reflect the structure, relations (dependencies) and environment variables as defined within the waf build system as much as possible. This however will be done such that the generated project files and workspaces will have the same structure and content as one would expect when using these files. When exporting to Eclipse, for instance, all project files will contain CDT project data; compilation and linking will be carried out by the CDT engine itself. In most cases the exported project files and workspaces for the integrated development environements will also contain some special build targets that will allow you to execute waf commands from within those IDE’s.
Usage¶
Tasks can be exported to codeblocks using the export command, as shown in the example below:
$ waf export --codeblocks
Exported project files, workspaces and makefiles can be removed in one go using the clean option:
$ waf export --clean --codeblocks
Note that only the formats that have been selected will be cleaned; i.e. exported files from formats not selected will not be removed.
-
class
waftools.export.ExportContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexports and converts C/C++ tasks to external formats (e.g. makefiles, codeblocks, msdev, ...).
-
cmd= 'export'¶
-
execute(*k, **kw)[source]¶ Executes the export command.
The export command installs a special task process method which enables the collection of tasks being executed (i.e. the actual command line being executed). Furthermore it installs a special post_process methods that will be called when the build has been completed (see build_postfun).
Note that before executing the export command, a clean command will forced by the export command. This is needed in order to (re)start the task processing sequence.
-
Module gnucc¶
Configures common release and debug settings for C/C++ compilers.
Warning
This module has been marked as deprecated and will be removed in release version 0.5.0; use the ccenv module instead.
-
waftools.gnucc.configure_gcc(conf)[source]¶ Configures general environment settings for GNU compilers; e.g. set default C/C++ compiler flags and defines based on the value of the command line –debug option.
Parameters: conf (waflib.Configure.ConfigurationContext) – configuration context
Module indent¶
Summary¶
Clean up and format C/C++ source code using GNU indent.
Usage¶
Source code from C/C++ tasks can cleaned and formatted according to the specified rules (default is GNU style) using the following command:
$ waf indent --targets=<task>
When cleaning only those task specified using the ‘–targets=’ option will be cleaned. The default is to clean all task within the entire build environment. Specific C/C++ task can be permanently excluded from cleaning using the ‘indent_skipme’ as attribute for those tasks.
formatting rules can be specified the using a ‘indent.pro’ file using the options as described for GNU indent. These global rules can used by this module when using the ‘–indent-pro=<path-to-indent-pro’ option at configuration time.
-
class
waftools.indent.GnuIndentContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextformat C/C++ source code using GNU indent.
-
cmd= 'indent'¶
-
exec_indent(tgen, sources, headers)[source]¶ execute GNU indent on the source and include files of task generator
Parameters: - tgen (waflib.Task.TaskGenerator) – task of which the source code should be beautified
- sources (list(str, str, ..)) – list of source file names
- headers (list(str, str, ..)) – list of include file names
-
fun= 'build'¶
-
Module makefile¶
Summary¶
Generate GNU Make files of all C/C++ programs, static- and shared libraries that have been defined within a waf build environment. Once exported to makefiles, all exported (C/C++) tasks can be build without any further need for, or dependency, to the waf build system itself.
Description¶
When exporting waf project data, a single top level GNU Make file will be exported in the top level directory of your WAF build environment. This makefile file will contain references to all exported makefiles of each individual C/C++ build task, contains generic variables and settings (e.g compiler to use, global preprocessor defines, link options and so on).
Example below presents the content of the top level makefile that has been exported from the test directory:
#------------------------------------------------------------------------------
# WAFTOOLS generated makefile
# version: 0.1.5
# waf: 1.7.15
#------------------------------------------------------------------------------
SHELL=/bin/sh
# commas, spaces and tabs:
sp:=
sp+=
tab:=$(sp)$(sp)$(sp)$(sp)
comma:=,
# token for separating dictionary keys and values:
dsep:=;
# token for separating list elements:
lsep:=,
# token for joining command and component names (e.g. 'build.hello')
csep:=.
export APPNAME:=waftools-test
export APPVERSION:=0.1.5
export PREFIX:=$(CURDIR)/output
export TOP:=$(CURDIR)
export OUT:=$(TOP)/build
export AR:=/usr/bin/ar
export CC:=/usr/lib64/ccache/gcc
export CXX:=/usr/lib64/ccache/g++
export CFLAGS:=-Wall -g -ggdb
export CXXFLAGS:=-Wall -g -ggdb
export DEFINES:=
export RPATH:=
export BINDIR:=$(PREFIX)/bin
export LIBDIR:=$(PREFIX)/lib
SEARCHPATH=components/
SEARCHFILE=Makefile
#------------------------------------------------------------------------------
# list of unique logical module names;
modules= cleaking cxxshlib ciambad cstlib chello cprogram cxxstlib cxxhello cmath cxxprogram cshlib
# dictionary of modules names (key) and paths to modules;
paths= cleaking;components/cleaking cxxshlib;components/cxxlib/shared ciambad;components/ciambad cstlib;components/clib/static chello;components/chello cprogram;components/clib/program cxxstlib;components/cxxlib/static cxxhello;components/cxxhello cmath;components/cmath cxxprogram;components/cxxlib/program cshlib;components/clib/shared
# dictionary of modules names (key) and module dependencies;
deps= cleaking; cxxshlib; ciambad;cleaking cstlib; chello; cprogram;cstlib,cshlib cxxstlib; cxxhello; cmath; cxxprogram;cxxstlib,cxxshlib cshlib;
#------------------------------------------------------------------------------
# define targets
#------------------------------------------------------------------------------
build_targets=$(addprefix build$(csep),$(modules))
clean_targets=$(addprefix clean$(csep),$(modules))
install_targets=$(addprefix install$(csep),$(modules))
uninstall_targets=$(addprefix uninstall$(csep),$(modules))
cmds=build clean install uninstall
commands=$(sort $(cmds) all help find list modules $(foreach prefix,$(cmds),$($(prefix)_targets)))
.DEFAULT_GOAL:=all
#------------------------------------------------------------------------------
# recursive wild card implementation
#------------------------------------------------------------------------------
define rwildcard
$(wildcard $1$2) $(foreach d,$(wildcard $1*),$(call rwildcard,$d/,$2))
endef
#------------------------------------------------------------------------------
# returns the value from a dictionary
# $1 = key, where key is the functional name of the component.
# $2 = dictionary
#------------------------------------------------------------------------------
define getdval
$(subst $(lastword $(subst $(csep),$(sp),$1))$(dsep),$(sp),$(filter $(lastword $(subst $(csep),$(sp),$1))$(dsep)%,$2))
endef
#------------------------------------------------------------------------------
# returns path to makefile
# $1 = key, where key is the functional name of the component.
#------------------------------------------------------------------------------
define getpath
$(call getdval, $1, $(paths))
endef
#------------------------------------------------------------------------------
# returns component dependencies.
# $1 = key, where key is the functional name of the component.
#------------------------------------------------------------------------------
define getdeps
$(addprefix $(firstword $(subst $(csep),$(sp),$1))$(csep),$(subst $(lsep),$(sp),$(call getdval, $1, $(deps))))
endef
#------------------------------------------------------------------------------
# creates a make recipe:
# 'make -r -C <path> -f <name>.mk <command>'
# where:
# <path> is the relative path to the component
# <name> is the name of the component
# <command> is the make action to be executed, e.g. build, install, clean
#
# $1 = key, where key is the functional recipe name (e.g. build.a).
#------------------------------------------------------------------------------
define domake
$1: $(call getdeps, $1)
$(MAKE) -r -C $(call getpath,$1) -f $(lastword $(subst $(csep),$(sp),$1)).mk $(firstword $(subst $(csep),$(sp),$1))
endef
#------------------------------------------------------------------------------
# return files found in given search path
# $1 = search path
# $2 = file name so search
#------------------------------------------------------------------------------
define dofind
$(foreach path, $(dir $(call rwildcard,$1,$2)),echo " $(path)";)
endef
#------------------------------------------------------------------------------
# definitions of recipes (i.e. make targets)
#------------------------------------------------------------------------------
all: build
build: $(build_targets)
clean: $(clean_targets)
install: build $(install_targets)
uninstall: $(uninstall_targets)
list:
@echo ""
@$(foreach cmd,$(commands),echo " $(cmd)";)
@echo ""
modules:
@echo ""
@$(foreach module,$(modules),echo " $(module)";)
@echo ""
find:
@echo ""
@echo "$@:"
@echo " path=$(SEARCHPATH) file=$(SEARCHFILE)"
@echo ""
@echo "result:"
@$(call dofind,$(SEARCHPATH),$(SEARCHFILE))
@echo ""
help:
@echo ""
@echo "$(APPNAME) version $(APPVERSION)"
@echo ""
@echo "usage:"
@echo " make [-r] [-s] [--jobs=N] [command] [VARIABLE=VALUE]"
@echo ""
@echo "commands:"
@echo " all builds all modules"
@echo " build builds all modules"
@echo " build$(csep)a builds module 'a' and it's dependencies"
@echo " clean removes all build intermediates and outputs"
@echo " clean$(csep)a cleans module 'a' and it's dependencies"
@echo " install installs files in $(PREFIX)"
@echo " install$(csep)a installs module 'a' and it's dependencies"
@echo " uninstall removes all installed files from $(PREFIX)"
@echo " uninstall$(csep)a removes module 'a' and it's dependencies"
@echo " list list available make commands (i.e. recipes)"
@echo " modules list logical names of all modules"
@echo " find [SEARCHPATH=] [SEARCHFILE=] searches for files default(path=$(SEARCHPATH),file=$(SEARCHFILE))"
@echo " help displays this help message."
@echo ""
@echo "remarks:"
@echo " use options '-r' and '--jobs=N' in order to improve speed"
@echo " use options '-s' to decrease verbosity"
@echo ""
$(foreach t,$(build_targets),$(eval $(call domake,$t)))
$(foreach t,$(clean_targets),$(eval $(call domake,$t)))
$(foreach t,$(install_targets),$(eval $(call domake,$t)))
$(foreach t,$(uninstall_targets),$(eval $(call domake,$t)))
.PHONY: $(commands)
Note that only the first two segments within the exported makefile contains project specific data; the first contains global settings, the second contains list of the functional names of the modules, path to those modules and finally dependencies between modules (if any). The remainder of the makefile is generic and will be the same for each project.
For each single task generator (waflib.TaskGenerator), for instance a bld.program(...) which has been defined within a wscript file somewhere in the build environment, a single GNU Make file will be generated in the same directory as where the task generator has been defined. The name of this task generator will be used as name for the exported GNU Make file. If for instance the name of the task generator is hello, then a GNU Make file named hello.mk will be exported.
Example below presents the content of the makefile for the chello component that has been exported from the test directory:
#------------------------------------------------------------------------------
# WAFTOOLS generated makefile
# version: 0.1.5
# waf: 1.7.15
#------------------------------------------------------------------------------
SHELL=/bin/sh
# commas, spaces and tabs:
sp:=
sp+=
tab:=$(sp)$(sp)$(sp)$(sp)
comma:=,
#------------------------------------------------------------------------------
# definition of build and install locations
#------------------------------------------------------------------------------
ifeq ($(TOP),)
TOP=$(CURDIR)
OUT=$(TOP)/build
else
OUT=$(subst $(sp),/,$(call rptotop) build $(call rpofcomp))
endif
PREFIX?=$(HOME)
BINDIR?=$(PREFIX)/bin
LIBDIR?=$(PREFIX)/lib
#------------------------------------------------------------------------------
# component data
#------------------------------------------------------------------------------
BIN=chello
OUTPUT=$(OUT)/$(BIN)
# REMARK: use $(wildcard src/*.c) to include all sources.
SOURCES= src/hello.c
OBJECTS=$(SOURCES:.c=.1.o)
DEFINES+=HELLO_VERSION='"1.2.3"'
DEFINES:=$(addprefix -D,$(DEFINES))
INCLUDES+= ./include
HEADERS:=$(foreach inc,$(INCLUDES),$(wildcard $(inc)/*.h))
INCLUDES:=$(addprefix -I,$(INCLUDES))
CFLAGS+=
LINKFLAGS+=
RPATH+=
RPATH:= $(addprefix -Wl$(comma)-rpath$(comma),$(RPATH))
LIBPATH_ST+=
LIBPATH_ST:= $(addprefix -L,$(LIBPATH_ST))
LIB_ST+=
LIB_ST:= $(addprefix -l,$(LIB_ST))
LIBPATH_SH+=
LIBPATH_SH:= $(addprefix -L,$(LIBPATH_SH))
LINK_ST= -Wl,-Bstatic $(LIBPATH_ST) $(LIB_ST)
LIB_SH+=
LIB_SH:= $(addprefix -l,$(LIB_SH))
LINK_SH= -Wl,-Bdynamic $(LIBPATH_SH) $(LIB_SH)
#------------------------------------------------------------------------------
# returns the relative path of this component from the top directory
#------------------------------------------------------------------------------
define rpofcomp
$(subst $(subst ~,$(HOME),$(TOP))/,,$(CURDIR))
endef
#------------------------------------------------------------------------------
# returns the relative path of this component to the top directory
#------------------------------------------------------------------------------
define rptotop
$(foreach word,$(subst /,$(sp),$(call rpofcomp)),..)
endef
#------------------------------------------------------------------------------
# define targets
#------------------------------------------------------------------------------
commands= build clean install uninstall all
.DEFAULT_GOAL=all
#------------------------------------------------------------------------------
# definitions of recipes (i.e. make targets)
#------------------------------------------------------------------------------
all: build
build: $(OBJECTS)
$(CC) $(LINKFLAGS) $(addprefix $(OUT)/,$(OBJECTS)) -o $(OUTPUT) $(RPATH) $(LINK_ST) $(LINK_SH)
clean:
$(foreach obj,$(OBJECTS),rm -f $(OUT)/$(obj);)
rm -f $(OUTPUT)
install: build
mkdir -p $(BINDIR)
cp $(OUTPUT) $(BINDIR)
uninstall:
rm -f $(BINDIR)/$(BIN)
$(OBJECTS): $(HEADERS)
mkdir -p $(OUT)/$(dir $@)
$(CC) $(CFLAGS) $(INCLUDES) $(DEFINES) $(subst .1.o,.c,$@) -c -o $(OUT)/$@
.PHONY: $(commands)
Note that only one segment of this file, the named component data contains project specific data; the remainder of this makefile is generic.
Example below presents an overview of an environment in which GNU Makefiles already have been exported:
.
├── components
│ └── clib
│ ├── program
│ │ ├── cprogram.mk
│ │ └── wscript
│ ├── shared
│ │ ├── cshlib.mk
│ │ └── wscript
│ └── static
│ ├── cstlib.mk
│ └── wscript
│
├── Makefile
└── wscript
Usage¶
Tasks can be exported to makefiles using the makefile command, as shown in the example below:
$ waf makefile
All exported makefiles can be removed in one go using the makefile clean option:
$ waf makefile --clean
-
class
waftools.makefile.MakeChild(bld, gen, targets)[source]¶ Bases:
waftools.makefile.Make
-
class
waftools.makefile.MakeFileContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexport C/C++ tasks to (GNU) make files.
-
cmd= 'makefile'¶
-
-
class
waftools.makefile.MakeRoot(bld)[source]¶ Bases:
waftools.makefile.Make
-
waftools.makefile.cleanup(bld)[source]¶ Removes all generated makefiles from the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
-
waftools.makefile.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
Module msdev¶
Summary¶
Exports and converts waf project data, for C/C++ programs, static- and shared libraries, into Microsoft Visual Studio, also known as msdev, project files (.vcproj) and solution (.sln) files.
Microsoft Visual Studio is a mature and stable integrated development environment for, amongst others, the C and C++ programming language. A free version of this IDE, known as the express version can be obtained from Microsoft at http://wwww.visualstudio.com.
Description¶
When exporting waf project data, a single Visual Studio solution will be exported in the top level directory of your WAF build environment. This solution file will contain references to all exported Visual Studio projects and will include dependencies between those projects and will have the same name as APPNAME variable from the top level wscript file.
For each single task generator (waflib.TaskGenerator), for instance a bld.program(...) which has been defined within a wscript file somewhere in the build environment, a single Visual Studio project file will be generated in the same directory as where the task generator has been defined. The name of this task generator will be used as name for the exported Visual Studio project file. If for instance the name of the task generator is hello, then a Visual Studio project file named hello.vcproj will be exported.
Example below presents an overview of an environment in which Visual Studio files already have been exported:
.
├── components
│ └── clib
│ ├── program
│ │ ├── cprogram.vcproj
│ │ └── wscript
│ ├── shared
│ │ ├── cshlib.vcproj
│ │ └── wscript
│ └── static
│ ├── cstlib.vcproj
│ └── wscript
│
├── waf.vcproj
├── appname.sln
└── wscript
Projects will be exported such that they will use the same settings and structure as has been defined for that build task within the waf build environment as much as possible. Note that since cross compilation is not really supported in this IDE, only the first environment encountered that is targeted for MS Windows will be exported; i.e. an environment in which:
bld.env.DEST_OS == 'win32'
is true.
Please note that in contrast to a normal IDE setup the exported projects will contain either a debug or a release build target but not both at the same time. By doing so exported projects will always use the same settings (e.g. compiler options, installation paths) as when building the same task in the waf build environment from command line.
Usage¶
Visual Studio project and workspace files can be exported using the msdev command, as shown in the example below:
$ waf msdev
When needed, exported Visual Studio project- and solution files can be removed using the clean command, as shown in the example below:
$ waf msdev --clean
Once exported simply open the appname.sln using Visual Studio this will automatically open all exported projects as well.
Tasks generators to be excluded can be marked with the skipme option as shown below:
def build(bld):
bld.program(name='foo', src='foobar.c', msdev_skip=True)
-
class
waftools.msdev.MsDev(bld)[source]¶ Bases:
objectAbstract base class used for exporting waf project data to Visual Studio projects and solutions.
REMARK: bld.objects() taks generators are treated as static libraries.
Parameters: bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment. -
C= 'c'¶ Identifier for projects using C language
-
CXX= 'cxx'¶ Identifier for projects using C++ language
-
PROGRAM= '1'¶ Identifier for projects containing an executable
-
SHLIB= '2'¶ Identifier for projects containing a shared library
-
STLIB= '4'¶ Identifier for projects containing a static library
-
-
class
waftools.msdev.MsDevContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextexport C/C++ tasks to MS Visual Studio projects and solutions.
-
cmd= 'msdev'¶
-
-
class
waftools.msdev.MsDevProject(bld, gen)[source]¶ Bases:
waftools.msdev.MsDevClass used for exporting waf project data to Visual Studio projects.
Parameters: - bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment.
- gen (waflib.Task.TaskGen) – Task generator that contains all information of the task to be converted and exported to the Visual Studio project.
-
class
waftools.msdev.MsDevSolution(bld)[source]¶ Bases:
waftools.msdev.MsDevClass used for exporting waf project data to a Visual Studio solution located in the lop level directory of the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – Build context as used in wscript files of your waf build environment.
-
waftools.msdev.cleanup(bld)[source]¶ Removes all Visual Studio projects and workspaces from the waf build environment.
Parameters: bld (waflib.Build.BuildContext) – a waf build instance from the top level wscript.
-
waftools.msdev.configure(conf)[source]¶ Method that will be invoked by waf when configuring the build environment.
Parameters: conf (waflib.Configure.ConfigurationContext) – Configuration context from the waf build environment.
Module tree¶
Summary¶
Displays dependencies between task generators (waflib.TaskGenerator) in a waf build environment.
Description¶
This module will, when executed, parse all task generators defined within a concrete waf build environment and present the dependencies between those task generators in a way similar to that of the output of the LINUX tree command.
Example below presents an abbreviated output from the tree command:
$ waf tree --targets=cprogram
+-cprogram
│
│--> program.c.1.o
│
│<-- libcstlib.a
│
│<-- cshlib-1.dll
│
│<-- libcshlib.dll.a
│
│--> cprogram.exe
│
+-cstlib
│ │
│ │--> foo.c.1.o
│ │
│ │--> libcstlib.a
│
+-cshlib
│
│--> bar.c.1.o
│
│--> cshlib-1.dll
│
│--> libcshlib.dll.a
DESCRIPTION:
m (lib) = uses system library 'm' (i.e. libm.so)
'tree' finished successfully (0.112s)
Usage¶
In order to use this waftool simply add it to the options and configure functions of your top level wscript file as shown in the example below:
import waftools
def options(opt):
opt.load('tree', tooldir=waftools.location)
def configure(conf):
conf.load('tree')
When configured as shown in the example above, the tree command can be issued on all targets, a single target or a range of targets:
$ waf tree --targets=blib
-
class
waftools.tree.DependsContext(**kw)[source]¶ Bases:
waflib.Build.BuildContextdisplay dependencies between tasks in a tree like manner.
-
cmd= 'tree'¶
-
execute()[source]¶ Entry point when executing the command (self.cmd).
Displays a list of dependencies for each specified task
-
fun= 'build'¶
-