wtools
ESO waf tools
Functions | Variables
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_cprogram (*target, with_unit_test=True, **kwargs)
 
def declare_cprotobuf (*target, **kwargs)
 
def declare_crtidds (*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_jrtidds (*target, **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_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>/config/* to $PREFIX/config/[package/]module.

Args:
    source:         List of sources or an ant_glob object.
                    Defaults to config/**/* and 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_crtidds()

def wtools.module.declare_crtidds ( *  target,
**  kwargs 
) 
Declare a C/C++ RTI DDS IDL compilation

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

Make sure that the project is configured (use) with 'rtidds', rtiddsgen
tool is in the $PATH and the RTI DDS libraries can be configured by the
pkg-config utility (therefore a rti_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_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_jrtidds()

def wtools.module.declare_jrtidds ( *  target,
**  kwargs 
) 
Declare a Java RTI DDS IDL compilation

Files .idl in interface are transformed into .java and built into a 
JAR file

Make sure that the project is configured (use) with 'rtidds', rtiddsgen
tool is in the $PATH and the RTI DDS libraries can be configured by the
pkg-config utility (therefore a rti_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_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
  rtidds_flags = custom flags to add to rtiddsgen invocation
  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 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 unit tests will have the `PYTHONPATH` populated such that the pyprogram module Python package
can be imported in the tests.

: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.

Variable Documentation

◆ STANDARD_COMMANDS

dictionary wtools.module.STANDARD_COMMANDS
Initial value:
1 = {'configure': _noop,
2  'build': _noop,
3  'options': _noop,
4  'docs': _noop
5  }