New project

Table of Contents

• Basic prerequisites
• Starting a new project
• Project requires

Basic prerequisites

The waf-extension wtools is designed to make it easy to work with the standard languages and libraries used at ESO. For this reason there are built-in knowledge and dependencies to a a few libraries and tools. If the standard ELT development environment is used, all dependencies should be satisfied already.

The dependencies are:

• boost
• google test
• qt5
• clang-tidy (optional)
• pylint (optional)

The waf installation also needs to have some extras built in:

• boost
• qt5
• color_gcc
• doxygen
• pytest
• javatest
• protoc

Starting a new project

Create a directory to act as the root of the new project, this directory is from this point referred to the project root.

In the past, a directory with wtools would then need to be created in the project root to be able to use the package, but since many ELT DevEnv versions wtools is shipped and already present in the default Python path so this is not strictly needed anymore. Only in the case that a specific version is required or wtools is used in a different development environment, the wtools package must be now placed in the project root directory by some means, for example defining it as a git module or by pointing to it with a symbolic link to a location where it was previously downloaded.

1. Edit wscript and declare project:

   # cat wscript
   from wtools import project
    
   def configure(cnf):
       # External dependencies are configured here
       pass
    
   project.declare_project(name='Example',
                           version='1.0-dev',
                           requires='cxx qt5 python', # required features the project needs
                           recurse='pkg1 pkg2') # recurse into package or module directories 

2. The requires parameter specifies which features the project needs (c.f. project requires)
3. Add modules and packages in the structure you prefer c.f. basic project as defined in the recurse definition of the project.

Project requires

Possible project requires can be queried to wtools by inserting an invalid entry in the requires parameter. This is an example output generated:

cuda (requires cxx):
   | Provides Nvidia CUDA support with `nvcc` compiler
   |
   | Enables the following tools/features:
   |   - cuda
 
cxx:
   | Provides C/C++ support including
   |     - Clang Tidy (linting)
   | 
   |     Options:
   |         cxx=dict(
   |             cxx_std=std               # C++ standard in use (default c++17)
   |             clang_tidy_config=path    # Path to clang-tidy configuration file
   |             gcovr_no_generated=False  # Include generated code in gcovr reports
   |             gcovr_html_medium=XX      # Set threshold for medium coverage for gcovr reports
   |             gcovr_html_high=XX        # Set threshold for high coverage for gcovr reports
   |         )
   |         c=dict(
   |             c_std=std                 # C standard in use (default c17)
   |         )
   |
   | Enables the following tools/features:
   |   - cxx
   |   - compiler_c
   |   - compiler_cxx
   |   - buildcopy
   |   - clangdb
 
python:
   | Provides Python support:
   |     - Python3.5+
   |     - Pylint (linting)
   | 
   |     Options:
   |         python=dict(
   |             pylint_config=path  # Path to pylint configuration file.
   |             pytest_config=path  # Path to pytest configuration file.
   |         )
   |
   | Enables the following tools/features:
   |   - python
   |   - buildcopy
 
qt5 (requires cxx):
   | Provides Qt5 for C++ support
   |
   | Enables the following tools/features:
   |   - qt5
 
pyqt5 (requires python):
   | Provides Qt5 for Python support
   |
   | Enables the following tools/features:
   |   - pyqt5
 
java:
   | Provides Java support
   |     - checkstyle (linting)
   | 
   |     Options:
   |         java=dict(
   |             checkstyle_config=path  # Path to checkstyle configuration file.
   |         )
   |
   | Enables the following tools/features:
   |   - java
   |   - buildcopy
 
protoc (requires cxx):
   | Provides Google Protobuffer C++ support
   |
   | Enables the following tools/features:
   |   - protoc
 
cii:
   | Provides CII support
   |
   | Enables the following tools/features:
   |   - malicd
 
sphinx:
   | Provides support for Sphinx documentation.
   |
   | Enables the following tools/features:
   |   - sphinx
 
gtest (requires cxx):
   | Provides support for google test testing framework.
   |
   | Enables the following tools/features:
   |   - waf_unit_test
 
qttest (requires qt5, cxx):
   | Provides support for QTTest testing framework.
   |
   | Enables the following tools/features:
   |   - waf_unit_test
 
catch2 (requires cxx):
   | Provides support for catch2 testing framework.
   |
   | Enables the following tools/features:
   |   - waf_unit_test
 
gbench (requires cxx):
   | Provides support for google test + google bench testing framework.
   |
   | Enables the following tools/features:
   |   - waf_unit_test
 
nosetests (requires python):
   | Provides support for Python nosetest testing framework.
   |
   | Enables the following tools/features:
   |   - pytest
   |   - waf_unit_test
   |   - buildcopy
 
pytest (requires python):
   | Provides support for Python pytest testing framework.
   | 
   |        With regards to ESO ELT module structure for Python Program there is a limitation with PyTest
   |        as there cannot be two same named namespaces (ie. the program and the same named program package).
   |        In such cases the auto_pyunit will remove the program script from the tests issuing a warning to
   |        the user.
   |        See also: https://docs.pytest.org/en/latest/pythonpath.html
   |        and: https://github.com/pytest-dev/pytest/issues/3151
   |
   | Enables the following tools/features:
   |   - pytest
   |   - waf_unit_test
   |   - buildcopy
 
testng (requires java):
   | Provides support for QTTest testing framework.
   |
   | Enables the following tools/features:
   |   - javatest
   |   - waf_unit_test
 
boost (requires cxx):
   | Provides C++ boost libraries support (available as use='BOOST')
   |     It is further configured with dict boost, which contains various attributes, e.g.:
   |     `boost=dict(libs="program_options datetime", force_static=False)`
   |
   | Enables the following tools/features:
   |   - boost
 
pybind11 (requires cxx, python):
   | Provides pybind11 support
   |
   | Enables the following tools/features: