Skip to content

DEVEL-README.md

Latest commit

 

History

History
95 lines (55 loc) · 4.19 KB

DEVEL-README.md

File metadata and controls

95 lines (55 loc) · 4.19 KB

How to Contribute

Please read How to Contribute.

Building the code

C code

See Compilation to compile the C code under c/.

R and Python packages

Under r/ or python/, the commands make build and make install will build and install the R and Python packages.

Testing

The C code and the Python and R packages have their own testsuites. See C testsuite to setup and run the C testsuite.

The Python and R testsuites are run automatically via Github Actions for every push and pull request. You can run then manually by running make test under r/ or python/.

You can run all testsuites at once by executing at the top-level:

make test

How to extend the Python API

moocore consists of C code called by R and Python. In both cases, the C code is compiled into a dynamic shared library.

Python uses CFFI to call the C code: https://github.com/multi-objective/moocore/blob/main/python/src/moocore/_ffi_build.py

CFFI is fast and makes very easy to extend the C API. Just add the declaration of the function you want to export to a libmoocore.h.

How to extend the R API

Extending the R API requires adding a C wrapper function that converts from R types to C types and export that C function to R. See Rmoocore.c and init.h

Documentation

Important

The documentation of the R and Python packages should be as consistent as possible.

A major difference is that Python has top-level pages that describe common functionality, Python example, and documentation for individual functions such as igd_plus(), whereas R has the option to describe multiple related functions in the same page R example.

In Python, one must decide where the documentation should be placed (in the common page or in the page of an individual function). In any case, the goals are to avoid duplicating the same text in different parts of the Python documentation and that the text is as similar as possible between Python and R.

References

Important

moocore provides accurate references to the original sources of mathematical concepts and algorithms.

Bibliographic entries should be taken from the IRIDIA BibTeX Repository. If the BibTeX entry does not exist, contribute it. If the entry already exists, you just need to add its label to the file bibkeys.txt and run update_bib.sh.

How to release

  1. Run testsuite workflow

  2. make clean

  3. ./release.py

  4. git ci -a -m "Prepare to release v${PACKAGEVERSION}"

  5. R release (within r/):

    1. make releasebuild and check which files are included in the package.
    2. make releasecheck
    3. Check reverse dependencies
    4. Update cran-comments.md
    5. Submit to CRAN: make submit
    6. While waiting, run benchmarks make benchmarks

  6. Publish a release in github to automatically submit to PyPi.

  7. ./release.py --dev NEW_VERSION

  8. git ci -a -m "Start development of v{NEW_VERSION}"