wtools.module Namespace Reference

Functions
def	declare_custom (*provides=None, depends=[])
def	declare_cshlib (*target, with_unit_test=True, **kwargs)
def	declare_cobjects (*target, with_unit_test=True, **kwargs)
def	declare_cstlib (*target, with_unit_test=True, **kwargs)
def	declare_clib (*target, with_unit_test=True, **kwargs)
def	declare_cprogram (*target, with_unit_test=True, **kwargs)
def	declare_cprotobuf (*target, **kwargs)
def	declare_cfastdds (*target, **kwargs)
def	declare_qt5cshlib (*target, with_unit_test=True, **kwargs)
def	declare_qt5cprogram (*target, with_unit_test=True, **kwargs)
def	declare_pypackage (*target, with_unit_test=True, with_doctest=True, **kwargs)
def	declare_pyqt5package (*target, with_unit_test=True, with_doctest=False, **kwargs)
def	declare_pyprogram (*target, with_unit_test=True, with_doctest=False, **kwargs)
def	declare_pyqt5program (*target, with_unit_test=True, with_doctest=False, **kwargs)
def	declare_pyprotobuf (*target, **kwargs)
def	declare_jar (*target, with_unit_test=True, **kwargs)
def	declare_jprotobuf (*target, **kwargs)
def	declare_config (**kwargs)
def	declare_malicd (**kwargs)
def	declare_malicd_topics (**kwargs)
def	declare_sphinx (**kwargs)

Variables
dictionary	STANDARD_COMMANDS

Detailed Description

Macro-like declaration of module.

The declare_* functions will register the standard commands if not supplied,
so if necessary e.g. the build command can be implemented manually
if customizations require it.

Function Documentation

declare_cfastdds()

def wtools.module.declare_cfastdds	(	*	target,
		**	kwargs
	)

Declare a C/C++ Fast DDS IDL compilation

Files .idl in `src/` are transformed into .h/.cxx and built into a
library that can be then used by other modules.

Make sure that the project is configured (use) with 'fast_dds', fastddsgen
tool is in the $PATH and the Fast DDS libraries can be configured by the
pkg-config utility (therefore a fast_dds.pc file is present in the system
or in your private PKG_CONFIG_PATH, see the example configuration file
supplied in the wtools reference project).

declare_clib()

def wtools.module.declare_clib	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare build of both static and shared C/C++ library

Warning: this feature is still considered experimental!

Additional tasks:

- cobjects (to unify compilation)
- unit test (on cobjects)
- install configuration
- install source files

C.f. waf book (waf.io/book) for supported arguments plus in addition "use_static" as "use"
     but only for static libraries

The shared library usename will be the same as the passed target (like in a common shared
only module created with declare_shlib), while the static name will have a '.static' appended.
This should be then explicitly used when the user wants to link to the static one. Of course
as well the generated wdep file, for usage then from another project, will contain the library
named accordingly with the same suffix. When a different project is then loading the libraries
via check_wdep it should therefore use the correct one as needed (or potentially load them
both if both are needed, mapping to two separate use names there as well).
In a similar fashion use names to be used are separated between "use" and "use_static" and
should be explicitly passed.

This module makes some assumptions, as that use-names of shared and dynamic libraries do not
contain assumptions that are very dependant on their shared/static compilation. For the
generation of the common cobjects and unit tests indeed only the use-names of the shared
versions (so plain "use", as it is known from the passed "kwargs") are considered. In a
similar way possible CFLAGS/LDFLAGS are as well single.
For more advanced uses, it is recommended to create a custom module, getting the clib
structure as a reference.

kwargs:
    target: Canonical name of library
    with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
    with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_cobjects()

def wtools.module.declare_cobjects	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare C/C++ objects (collection of source and/or header files).

Additional tasks:

- unit test
- install configuration
- install source files

C.f. waf book (waf.io/book) for supported arguments.

kwargs:
    target: Name for these objects
    with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
    with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_config()

def wtools.module.declare_config

(

**

kwargs

)

Declare a configuration module.
Installs files from <module>/resource/* to $PREFIX/resource/

Args:
    source:         List of sources or an ant_glob object.
                    Defaults to resource/**/*
    install_path:   Destination of sources.
                    Defaults to ${PREFIX}
    rel:            If True copies with whole directory structure, if false flat copy

declare_cprogram()

def wtools.module.declare_cprogram	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare a C/C++ program main artefact
@note By convention the `main()` is assumed to be located in `src/main.cpp`
and will automatically be excluded from the unit test.

Additional tasks:

- unit test
- install configuration
- install source files

C.f. waf book (waf.io/book) for supported arguments.

kwargs:
    target: name of program
    with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
    with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_cprotobuf()

def wtools.module.declare_cprotobuf	(	*	target,
		**	kwargs
	)

Declare C/C++ protobuffer files generation (.proto file to pb.h/.pb.cc)

Files .proto in interface are transformed into .pb.h/.pb.cc and built into
a static library that can be then used by other modules.

protoc is used for the files generation and is searched for in the
configuration stage

declare_cshlib()

def wtools.module.declare_cshlib	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare a C/C++ shared library

Additional tasks:

- unit test
- install configuration
- install source files

C.f. waf book (waf.io/book) for supported arguments.

kwargs:
    target: Canonical name of library
    with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
    with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_cstlib()

def wtools.module.declare_cstlib	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare a C/C++ static library

Additional tasks:

- unit test
- install configuration
- install source files

C.f. waf book (waf.io/book) for supported arguments.

kwargs:
    target: Canonical name of library
    with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
    with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_custom()

def wtools.module.declare_custom	(	*	provides = None,
			depends = []
	)

Declare custom module.

Allows for customized build method definition while retaining option to automatically
track use dependencies in the created config method, although it has to be explicitly
specified by the user when usig this method.

*Note*: The build method must be defined *before* calling this function.

Args:
    provides: List of task generator names that this module provides. The names
              should be in the fully qualified name form ('foo.bar.baz').
    depends: List of task generator use dependencies.

declare_jar()

def wtools.module.declare_jar	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declares Java archive module

Contents under `src/` will be compiled and archived in `<module>.jar` and installed
in `${PREFIX}/lib/`.

Additional tasks:
    - Install config
    - TestNG unit test from test/* files (see javatest extra)
    - TODO: jar runner?

:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.

declare_jprotobuf()

def wtools.module.declare_jprotobuf	(	*	target,
		**	kwargs
	)

Declare Java protobuffer files generation (.proto file to .java)

Files .proto in interface are transformed into .java and built into
a JAR library that can be then used by other modules.

protoc is used for the files generation and is searched for in the
configuration stage

declare_malicd()

def wtools.module.declare_malicd

(

**

kwargs

)

Declare a MAL ICD module.

A single XML definition file should be in source. Libraries for languages
and transports available in the configuration will be generated.

Args:
  use = dependency on other ICDs
  mal_opts = dictionary with options for icd generation, currently used:
      opcua_disabled = if True, disable OPCUA middleware generation
      dds_disabled = if True, disable DDS middleware generation
      zpb_disabled = if True, disable ZEROMQ middleware generation

declare_malicd_topics()

def wtools.module.declare_malicd_topics

(

**

kwargs

)

Declare a MAL ICD topics module.

A single XML definition file should be in source. The filename must be ending
with Topics as by convention (ie. blablablaTopics.xml)  Libraries for languages
available in the configuration will be generated.

Args:

declare_pypackage()

def wtools.module.declare_pypackage	(	*	target,
			with_unit_test = True,
			with_doctest = True,
		**	kwargs
	)

Declare a Python package

:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:param   with_doctest: boolean flag to enable/disable  doctests. Default value is True.
:param   with_ut_lib: (optional) Unit test library to be used to execute the unit test
                      Supported values:
                        - nosetests (default): Nosetests (https://nose.readthedocs.io/en/latest/)
                        - pytest: PyTest (https://docs.pytest.org/en/latest/)

declare_pyprogram()

def wtools.module.declare_pyprogram	(	*	target,
			with_unit_test = True,
			with_doctest = False,
		**	kwargs
	)

Declare a Python program, optional package and unit tests.

wtools assumes by default that there will be:

- A single `src/<module>.py` file representing the program executable. The script will be
  installed to the `$PREFIX/bin` directory without the `.py` extension
- An optional `src/<module>/__init__.py` Python package for bigger programs needing multiple
  files without having to create additional modules.

The default paths for Python program and package may be customized with attributes
`py_program` and `py_package` respectively.

The unit tests will have the `PYTHONPATH` populated such that the pyprogram module Python package
can be imported in the tests.

:param target: Name of install target and task generator (must match target filename)
:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:param   with_doctest: boolean flag to enable/disable  doctests. Default value is False.
:param   with_ut_lib: (optional) Unit test library to be used to execute the unit test
                      Supported values:
                        - nosetests (default): Nosetests (https://nose.readthedocs.io/en/latest/)
                        - pytest: PyTest (https://docs.pytest.org/en/latest/)

declare_pyprotobuf()

def wtools.module.declare_pyprotobuf	(	*	target,
		**	kwargs
	)

Declare a Python protobuffer module package

:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:param   with_doctest: boolean flag to enable/disable  doctests. Default value is False.
:param   with_ut_lib: (optional) Unit test library to be used to execute the unit test
                      Supported values:
                        - nosetests (default): Nosetests (https://nose.readthedocs.io/en/latest/)
                        - pytest: PyTest (https://docs.pytest.org/en/latest/)

declare_pyqt5package()

def wtools.module.declare_pyqt5package	(	*	target,
			with_unit_test = True,
			with_doctest = False,
		**	kwargs
	)

Declare a Python package with Qt5 bindings

:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:param   with_doctest: boolean flag to enable/disable  doctests. Default value is False.
:param   with_ut_lib: (optional) Unit test library to be used to execute the unit test
                      Supported values:
                        - nosetests (default): Nosetests (https://nose.readthedocs.io/en/latest/)
                        - pytest: PyTest (https://docs.pytest.org/en/latest/)

declare_pyqt5program()

def wtools.module.declare_pyqt5program	(	*	target,
			with_unit_test = True,
			with_doctest = False,
		**	kwargs
	)

Declare a Python program using Qt5 bindings, optional package and unit tests.

Please see declare_pyprogram for details, as this is a derivation of a standard python program

:param   with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:param   with_doctest: boolean flag to enable/disable  doctests. Default value is False.
:param   with_ut_lib: (optional) Unit test library to be used to execute the unit test
                      Supported values:
                        - nosetests (default): Nosetests (https://nose.readthedocs.io/en/latest/)
                        - pytest: PyTest (https://docs.pytest.org/en/latest/)

declare_qt5cprogram()

def wtools.module.declare_qt5cprogram	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare a C++ program using Qt5 libraries

Being a C++ application same argument as C++ may apply.

For automatic MOC generation:
    -) Insert the UI (.ui) or header (.h .hpp) file under includes
    -) If an UI is used it will be converted first to a header file
    -) In the interested .cpp file reference a virtual .moc as:
            #if WAF
            #include "include/sameNameAsSource.moc"
            #endif
    Where the .moc filename is the one the reference file will generate

Resource (.qrc) and language (.ts) files are also supported.

More waf level info: https://waf.io/apidocs/tools/qt5.html

Additional tasks:

- unit test (with qt5test)
- install configuration
- install source files

:param str target: Canonical name of qt5 program,
:with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_qt5cshlib()

def wtools.module.declare_qt5cshlib	(	*	target,
			with_unit_test = True,
		**	kwargs
	)

Declare a C++ shared library using Qt5 libraries

Being a C++ shared library same argument as C++ may apply.

For automatic MOC generation:
    -) Insert the UI (.ui) or header (.h .hpp) file under includes
    -) If an UI is used it will be converted first to a header file
    -) In the interested .cpp file reference a virtual .moc as:
            #if WAF
            #include "include/sameNameAsSource.moc"
            #endif
    Where the .moc filename is the one the reference file will generate

Resource (.qrc) and language (.ts) files are also supported.

More waf level info: https://waf.io/apidocs/tools/qt5.html

Additional tasks:

- unit test (with qt5test)
- install configuration
- install source files

:param str target: Canonical name of library,
:param bool qt5_plugin: True if module is a Qt5 plugin false otherwise.
:with_unit_test: boolean flag to enable/disable unit tests. Default value is True.
:with_ut_lib:  (optional) Unit test library to be used to execute the unit test
                  Supported values:
                    - gtest (default): Google test (https://github.com/google/googletest)
                    - qt5test: QT5 unit test (https://doc.qt.io/qt-5/qtest-overview.html)
                    - catch2 : catch2 (https://github.com/catchorg/Catch2)
                    - gbench : google test + benchmark (https://github.com/google/benchmark)

declare_sphinx()

def wtools.module.declare_sphinx

(

**

kwargs

)

Declare sphinx module

Builds Sphinx documentation. Please note that to build and install sphinx documentation module '--with-docs' option
needs to be passed.
For example:

waf build --with-docs

By default documentation will be installed to corresponding folders declared in waf gnu_dirs tool. The default
installation path depends on sphinx_output_format. To change installation path install_path attribute can be passed
to declare_sphinx method.

Args:
    sphinx_output_format  = documentation output format, can be a single format (ie. "html")
                            or a list of formats (ie. ["html", "man", "latex"]). Default is "html".
    install_path_<FORMAT> = installation directory for a specific sphinx format (ie. install_path_man
                            specifies where the 'man' format output is inserted). Can be specified for
                            multiple formats (note: sphinx refers to them also as builders)

Variable Documentation

STANDARD_COMMANDS

dictionary wtools.module.STANDARD_COMMANDS

Initial value:

=  {
    "configure": _noop,
    "build": _noop,
    "options": _noop,
    "docs": _noop,
}