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:
doxygen <https://www.doxygen.nl>
python3
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