Development

The WSIM source code and issue tracker are hosted at GitLab. All project code and documentation is stored in a single repository.

Structure

The core functionality of WSIM is provided through R packages. These packages are generally independent, but some functionality of wsim.io is accessed from other packages. Where performance is critical, code is written in C++11 and exposed to R using the Rcpp package.

A series of command-line tools provide thin wrappers around the functionality of the R packages.

The package build process, including compilation of C++ sources, is done using the devtools package. Each package contains a Makefile, and package testing and installation can be performed using the check and install targets, respectively.

Testing

Each R package contains an independent test suite, managed using the testthat package. Currently, a small number of regression tests depend on resources that are not included in the git repository. If these resources are available, their location must be specified with the WSIM_TEST_DATA environment variable. These tests are automatically skipped when these resources are inaccessible.

Note

The isciences/wsim-gitlabci Docker image contains all files necessary to run regression tests.

Tests are run on commit using GitLab CI. The GitLab CI test runner pulls the latest published image of the isciences/wsim-gitlabci build environment. It builds the isciences/wsim image on top of this environment, and then runs the test suite within the built container. If the tests pass (and the commit is to the master branch), GitLab CI tags the image as isciences/wsim:latest and pushes it to Docker Hub.

Note

The isciences/wsim-gitlabci image is manually built and pushed when needed. This is done to reduce the execution time of the GitLab CI build and test pipeline.

Documentation

General WSIM documentation (such as this page) is generated using Sphinx from manually-authored reST files stored in the git repository. Documentation figures are generated by R scripts stored with the .rst files. Files created by R scripts will be stored in the docs/_generated folder. Where automated figure creation is not feasible, a static file can be saved to docs/_static, using a non-binary format such as SVG.

R package documentation is automatically generated from source comments, using the Roxygen2 package. The HTML versions of this documentation are generated using pkgdown.

Documentation can be built by running make html.

Versioning

WSIM is versioned using a MAJOR.MINOR.REVISION_NUMBER scheme, where MAJOR.MINOR is currently 2.0, and REVISION_NUMBER is the number of commits in the master branch of the repository.

The values of MAJOR and MINOR are set in .gitlab-ci.yml. During a GitLab CI build, the complete version number is computed and stored in the following locations:

  • the WSIM_VERSION environment variable

  • the DESCRIPTION file of each R package

  • the __version__ file of the wsim_workflow Python package

Containers built from branches other than master will not have a version number assigned. In all cases, a GIT_COMMIT environment variable is also set in Docker containers.