Skip to content

Latest commit

 

History

History
93 lines (70 loc) · 3.98 KB

CONTRIBUTING.md

File metadata and controls

93 lines (70 loc) · 3.98 KB

Contributing to AbSolute

This guide is for anybody who wants to contribute to AbSolute. First, thank you for working on AbSolute and we encourage you to discuss your project with us to be sure your contributions can eventually be integrated.

Getting ready

Install the apron library, the dune build system, the odoc documentation generator and the picasso library (used for visualisation). You can install all of these by doing:

opam install dune apron apronext odoc picasso

You can then clone and build AbSolute (both the tool and the library) by doing:

git clone https://github.com/mpelleau/AbSolute
cd AbSolute
make

Then, verify everything is working well on an example:

./_build/default/absolute-solver/absolute.exe problems/booth.abs

Or maybe simpler create an executable in the root directory and run it by doing:

make absolute
./absolute problems/booth.abs

Guidelines

If you want to contribute to the project, note that functionnal programming is the prefered style. Also we strongly recommend the use of automating indentation, for example using ocamlformat.

Monitoring the performances

It is wishable to monitor the memory and time usage of the changes you may introduce in the solver. To do so, you can install memtrace and memtrace_viewer for the memory, and landmark for the time usage (available via opam):

opam install memtrace memtrace_viewer landmarks

This will allow you to create an executable memabsolute from the Makefile, by doing make memabsolute. This executable can be used in the same way than the absolute executable (it may be slightly slower) but it differs from it a few way: it initializes a memory trace, adds trace points using landmarks, calls absolute, and then outputs a memory trace in the file memperf.log and a time usage trace in the file timeperf.json. You can then examine the traces from a browser.

Additional cool stuff about dune:

  • From the manual: "The dune build and dune runtest commands support a -w (or --watch) flag. When it is passed, dune will perform the action as usual, and then wait for file changes and rebuild (or rerun the tests). This feature requires inotifywait or fswatch to be installed."
  • dune utop src/ starts a REPL with all the absolute libs loaded (need to install utop first: opam install utop).
  • .merlin files are generated automatically (which means it is in sync with the building script).

Creating a new feature

We usually first create a branch or a fork, add and test the new feature, and then create a pull request to merge it into the mainstream repository. When contributing to AbSolute, please first discuss the change you wish to make via an issue, then feel free to fork and submit a PR.

Dont forget to test the project using

dune runtest

Publishing

The project is published with opam. If you want to release a new version of AbSolute, here are the steps:

  1. Create a new release through the Github interface, for example v0.3.0 following the conventions of semantic versionning.
  2. Update the src field in absolute.opam with the address of the .tar.gz given on the release page.
  3. Perform cp absolute.opam packages/absolute/absolute.0.3.0/opam with the same version number as the one used at step (1).
  4. opam admin index to regenerate urls.txt and index.tar.gz.
  5. git add packages/absolute/absolute.0.3.0/opam followed by git commit and git push.

The new version is now installable with opam update followed by opam install absolute.