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.

The project root needs to two things:

• wtools
• A wscript declaring the project.

Assuming you are using subversion and have created an empty project root directory the following steps describes the basic setup:

1. Checkout the empty project: $ svn co <path-to-project-root>
2. Navigate into the project root: $ cd <project-root>
3. Set up the wtools as an external: $ svn propset svn:externals "wtools http://svnhq9.hq.eso.org/p9/trunk/EELT/DevEnv/wtools/wtools" .
4. Update svn to fetch the external: $ svn update
5. 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 

6. The requires parameter specifies which features the project needs (c.f. project requires)
7. 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:

gtest (requires cxx):
   | Provides support for google test testing framework.
   | 
   | Enables the following tools/features: 
   |   - waf_unit_test
 
boost (requires cxx):
   | Provides C++ boost libraries support (available as use='BOOST')
   |     It is further configured with attribute boost_libs attribute, e.g.:
   |     `boost_libs='program_options datetime'`
   | 
   | Enables the following tools/features: 
   |   - boost
 
cxx:
   | Provides C/C++ support including 
   |     - Clang Tidy (linting)
   | 
   |     Options:
   |         cxx_std=std (=c++11)  Changes the default C++ standard in use.
   |         cxx_cstd=std (=c11)  Changes the default C standard in use.
   |         cxx=dict(
   |             clang_tidy_config=path  # Path to clang-tidy configuration file.
   |         )
   | 
   | Enables the following tools/features: 
   |   - cxx
   |   - compiler_c
   |   - compiler_cxx
   |   - buildcopy
   |   - clangdb
 
rtidds (requires cxx):
   | Provides RTIDDS C++ support
   | 
   | Enables the following tools/features: 
   |   - rti_idl
 
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
 
cii:
   | Provides CII support
   | 
   | Enables the following tools/features: 
   |   - malicd
 
java:
   | Provides Java support
   |     - checkstyle (linting)
   | 
   |     Options:
   |         java=dict(
   |             checkstyle_config=path  # Path to checkstyle configuration file.
   |         )
   | 
   | Enables the following tools/features: 
   |   - java
   |   - buildcopy
 
catch2 (requires cxx):
   | Provides support for catch2 testing framework.
   | 
   | Enables the following tools/features: 
   |   - waf_unit_test
 
protoc (requires cxx):
   | Provides Google Protobuffer C++ support
   | 
   | Enables the following tools/features: 
   |   - protoc
 
sphinx:
   | Provides support for Sphinx documentation.
   | 
   | Enables the following tools/features: 
   |   - sphinx
 
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
 
python:
   | Provides Python support:
   |     - Python3.5+
   |     - Pylint (linting)
   | 
   |     Options:
   |         python=dict(
   |             pylint_config=path  # Path to pylint configuration file.
   |         )
   | 
   | Enables the following tools/features: 
   |   - python
   |   - buildcopy
 
qt5 (requires cxx):
   | Provides Qt5 for C++ support
   | 
   | Enables the following tools/features: 
   |   - qt5
 
testng (requires java):
   | Provides support for QTTest testing framework.
   | 
   | Enables the following tools/features: 
   |   - javatest
   |   - waf_unit_test
 
pyqt5 (requires python):
   | Provides Qt5 for Python support
   | 
   | Enables the following tools/features: 
   |   - pyqt5
 
qttest (requires qt5, cxx):
   | Provides support for QTTest testing framework.
   | 
   | Enables the following tools/features: 
   |   - waf_unit_test