Quickstart

Building the library

Building the documentation

The documentation is automatically built on readthedocs with every commit. However, you can still generate the documentation locally along your normal build (see Building the library). For that you will need the following requirements installed:

Next you need the following python packages breathe and sphinx_rtd_theme. So we start by creating a virtual environment, activating it and installing the packages into it.

~ > python3 -m venv venv
~ > . ./venv/bin/activate
(venv) ~ > pip install  sphinx_rtd_theme breathe
....
Successfully installed Jinja2-2.11.3 MarkupSafe-1.1.1 Pygments-2.8.1
alabaster-0.7.12 babel-2.9.0 breathe-4.29.0 certifi-2020.12.5 chardet-4.0.0
docutils-0.16 idna-2.10 imagesize-1.2.0 packaging-20.9 pyparsing-2.4.7
pytz-2021.1 requests-2.25.1 six-1.15.0 snowballstemmer-2.1.0 sphinx-3.5.4
sphinx-rtd-theme-0.5.2 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2
sphinxcontrib-htmlhelp-1.0.3 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3
sphinxcontrib-serializinghtml-1.1.4 urllib3-1.26.4
(venv) ~ >

Since the documenation is not generated by default, you have to reconfigure your cmake project for the COPASI API next. So change into your build folder from before, and reconfigure with the option -DWITH_DOCUMENTATION=ON.

(venv) ~ > cd copasi-api/build
(venv) build > cmake -DWITH_DOCUMENTATION=ON ..

-- COPASI dependencies: /tmp/copasi-api/dependencies/lib/cmake
...

 Options:

    Enable namespace       = OFF
    Generate documentation = ON
    Additional Defines     =

-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/copasi-api/build
(venv) build >

Errors would have shown if doxygen or sphinx could not be found in the process. Now you are ready to build the documentation with:

(venv) build > make Sphinx
[ 50%] Generating documentation with Sphinx
Running Sphinx v3.5.4
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: 0 added, 3 changed, 0 removed
reading sources... [100%] quickstart/get-started
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] quickstart/get-started
generating indices... genindex done
writing additional pages... search done
copying images... [100%] _static/COPASI_Conly_176x176.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in sphinx.
[100%] Built target Sphinx

(venv) build >

And at this point you have the HTML pages generated in ./docs/sphinx/ with the main document being ./docs/sphinx/index.html

Running the tests

We use the testing framework catch2 <https://github.com/catchorg/Catch2> and integrated it with the cmake build, so after building the library you can run the tests using ctest:

(venv) build > ctest -V

If you want to run tests on another build configuratioon, you can specify those using the -C option. So for example for the debug build:

(venv) build > ctest -C Debug -V

You can also run the test binary directly, but in that case test files provided in ./tests/test-data will not be automatically found, as the source dir is not known.

(venv) build > ./tests/test_api
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
test_api.exe is a Catch v1.5.6 host application.
Run with -? for options

-------------------------------------------------------------------------------
load copasi file and access via regular COPASI api
-------------------------------------------------------------------------------
/copasi-api/tests/TestCore.cpp(32)
...............................................................................

/copasi-api/tests/TestCore.cpp(38): FAILED:
REQUIRE( dm->loadModel(fileName, 0) == true )
with expansion:
    false == true

===============================================================================
test cases:  2 |  1 passed | 1 failed
assertions: 22 | 21 passed | 1 failed

In that case you can specify an environment variable srcdir pointing to it:

(venv) build > srcdir=/copasi-api/tests ./tests/test_api
===============================================================================
All tests passed (24 assertions in 2 test cases)

Additional options of the test runner:

(venv) build > ./tests/test_api -?
Catch v1.5.6
usage:
    test_api [<test name, pattern or tags> ...] [options]

where options are:
    -?, -h, --help               display usage information
    -l, --list-tests             list all/matching test cases
    -t, --list-tags              list all/matching tags
    -s, --success                include successful tests in output
    -b, --break                  break into debugger on failure
    -e, --nothrow                skip exception tests
    -i, --invisibles             show invisibles (tabs, newlines)
    -o, --out <filename>         output filename
    -r, --reporter <name>        reporter to use (defaults to console)
    -n, --name <name>            suite name
    -a, --abort                  abort at first failure
    -x, --abortx <no. failures>  abort after x failures
    -w, --warn <warning name>    enable warnings
    -d, --durations <yes|no>     show test durations
    -f, --input-file <filename>  load test names to run from a file
    -#, --filenames-as-tags      adds a tag for the filename
    --list-test-names-only       list all/matching test cases names only
    --list-reporters             list all reporters
    --order <decl|lex|rand>      test case order (defaults to decl)
    --rng-seed <'time'|number>   set a specific seed for random numbers
    --force-colour               force colourised output (deprecated)
    --use-colour <yes|no>        should output be colourised