DEVELOPMENT.md

Working with the cocoex code base

Before you start

To work with the coco-experiment source code, you need quite a few tools in very specific versions. We provide a Conda environment file env.yaml and recommend you use it to setup your development environment. It is regularly tested on Linux, Windows and macOS and is what is used in CI.

Following these steps should setup a fresh cocoex environment:

1. Create or update a new conda environment with all the requirements by running

   conda env create -f env.yaml

   or if you've already setup a cocoex environment

   conda env update -f env.yaml --prune

2. Activate environment

   conda activate cocoex

You now have all required dependencies to work on the code base. If you notice that something is missing, please let us know by opening an issue.

Reusing a conda environment

Say you already have a conda environment named foo that you want to reuse because it contains some additional packages you need for development. Then, once you've activated the environment, you can run

conda env update --file env.yaml

and it will install all the required development dependencies into your existing environment.

Working with the Experimental Code

Before any of the bindings can be built and after every change to the core files (in code-experiments/src/), you need to run scripts/fabricate. The job of fabricate is to bundle the C files and place them in all the right places so that the language specific build tools can find them when building the respective bindings. fabricate also updates the binding metadata to include version information and any other changes that need to be made from one build to the next. It is harmless to run fabricate too often, but forgetting to run it means you might be using stale sources.

Running unit tests

Change to the unit tests directory

cd test/unit-test

Rerun fabricate if not already done

python ../../scripts/fabricate

Build tests using cmake

cmake -B build
cmake --build build

Run tests using ctest

ctest --test-dir build     

Regression tests

Note that I'm not sure the regression tests are really useful at the moment. But here goes:

Change to the regression tests directory

cd test/regression-test

The regression tests require the cocoex Python package. Install it first

python -m pip uninstall -y coco-experiment
python -m pip install ../../build/python/  

Now run the regression tests

python test_suites.py   

and

python test_loggers.py

Integration tests

Still need to fix those up.

cocoex Python package

Change to the cocoex Python package directory

cd build/python

Install the package from source

pip uninstall -y coco-experiment
pip install .

Compilation and installation hints

• Under macOS with an ARM processor it may be necessary to run arch -arm64 pip install . instead.

• When installing from source on older machines, it might be necessary to explicitly enable C99 mode for the C compiler. You can do this running CFLAGS="-std=c99" pip install ..

Testing the cocoex Python package

Install and run pytest

pip install pytest
python -m pytest test

Release a new version

Once you've decided a commit is stable and ready to be released, tag it with the appropriate version and push the tag to Github:

git tag -a -m 'Version X.Y.Z' vX.Y.Z
git push --tags

Note: You can use suffixes for pre-releases such as version 2.6.99rc4 (release candidate 4) or 2.6.99b1 (beta 1).

Once you push a new tag to Github, it will trigger a CI build with the new version number. Once that finishes successfully, you can find the properly built artifacts on the Actions tab on Github.

Python

The Python artifacts are contained in the build arifacts dist-python-sdist and dist-pythobn-wheels. Download and unpack them to an empty directory (assumed to be dist/ here). Now we are ready to upload the built source package and wheels to PyPI using twine:

twine upload dist/*

Thats it! Check PyPI, it should list the new release.

Other languages

TBD - probably as downloads on the new website.