Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
242 lines (151 loc) · 8.33 KB

CONTRIBUTING.md

File metadata and controls

242 lines (151 loc) · 8.33 KB

Contributing

Workflow

We follow the common Gitflow Workflow. A quick tutorial on the Gitflow Workflow is available from Atlassian.

In brief, the core of the workflow consists of the following:

  • Basing feature branches off of the develop branch.

    $ git checkout -b some-feature develop

  • Merging into the develop branch via pull requests.

  • Reserving the master branch for releases.

Overall, we follow common git best practices. Please read over this document before making contributions, particularly about Gitflow, commit messages, pull requests (including types of pull requests), and code reviews.

Commits and Commit Messages

We follow standard conventions for making commits and writing effective Git commit messages. First read the brief How to Write a Git Commit Message and then Contributing to a Project from the ProGit book. In short, make logically incremental commits and write substantitive messages that convey why something was changed versus simply saying what was changed.

Coding Style

We follow the standard Scala Style Guide and Effective Scala with respect to coding style. Please read over these guides before contributing.

API Documentation

We use Scaladoc and follow the standard guidelines from Scaladoc for Library Authors.

Development Environment

This project is primarily a Scala project using sbt for building with a few external dependencies.

Dependencies

If you would like to set up a build environment using your own package manager, you will need to find and install the following tools:

  • JDK 8
  • sbt
  • z3
  • Japron (the Apron Java interface)

With the Nix Package Manager

The simplest way to set up the build environment if you are running Linux, macOS, or Windows (with a Linux subsystem) is with the portable Nix Package Manager.

macOS: Installing Nix with Homebrew

$ brew cask install nix

Installing the CUPLV Nix Overlay

With the Nix Package Manager installed, we need to add the cuplv-nixpkgs overlay (globally once).

# From a desired install location, add the cuplv-nixpkgs overlay.
$ git clone https://github.com/cuplv/cuplv-nixpkgs

# This symlinks cuplv-nixpkgs to ~/.config/nixpkgs/overlays/cuplv-nixpkgs
$ cuplv-nixpkgs/install

Entering the Cuanto Build Environment

Then, use nix-shell to open a shell with all dependencies available.

# Enter the cuanto build environment
$ cd cuanto
$ nix-shell
    
# Test the build environment
[nix-shell:~/cuanto]$ sbt test

Setting up a native environment

We offer some instructions on setting up a native build environment. Most dependencies are JVM-based, so this should work for most things.

macOS with Homebrew

Using Homebrew, install dependencies as follows:

$ brew cask install java
$ brew install sbt
$ brew install z3

Building and Testing

See documentation on sbt for details. In brief, it is most convenient to start an sbt shell

$ sbt

and then

  • Build

    > compile

  • Test

    > test

  • Generate API documentation

    > doc

  • Start a Scala console

    > console

  • Prefix any command with ~ to re-execute the command when any file in the project is updated; for example,

    > ~test

IntelliJ Import

If you want to use IntelliJ IDEA as your IDE, use the sbt import wizard. In brief,

  • Make sure the Scala plugin is installed.
  • Import via File > New > Project from Existing Sources > Import project from external model > SBT.
  • We recommend checking Use auto-import to automaticaly stay in sync with build.sbt.
  • Make sure the Project SDK is 1.8.

It is particularly convenient to run ScalaTest via IntelliJ. Get started by right-clicking on a ScalaTest Spec class.

Troubleshooting

Nix Shell

On some Linux and macOS systems, the system-installed version of bash is too old for nix-shell to use. You will see this error if you have this issue:

$ nix-shell

bash: local: -n: invalid option
local: usage: local name[=value] ...
bash: local: -n: invalid option
local: usage: local name[=value] ...
bash: failureHooks: command not found

To fix this issue, you will need a newer version of bash. For example, on macOS, you can get a newer version of bash via Homebrew.

If it is inconvenient to update your system, you can install a suitable version using Nix itself:

$ nix-env -iA nixpkgs.bashInteractive

Apron/Japron Installation

If your development environment does not accommodate nix-installed jars or provide a japron/apron package you will need to build it yourself. Generally there are three phases:

  • Download Apron source code
  • Compile Apron
  • Configure the environment on your machine (assume you are using linux)

Below are detailed steps for setting up an enviroment where Apron relies on:

  1. Clone source code:

    svn co svn://scm.gforge.inria.fr/svnroot/apron/apron/trunk apron

  2. Enter Apron's root directory: cd apron

  3. Configure Apron:

    ./configure -prefix $out -no-cxx -absolute-dylibs

  4. Compile Apron: make

  5. Test if Apron is functioning well: make test

  6. Enter cuanto's root directory: cd cuanto

  7. Create a lib folder in cuanto: mkdir lib

  8. Move the followings files from apron/ to cuanto/lib/:

    apron.jar, gmp.jar, libapron.so, libboxD.so, libjapron.so, libjgmp.so, liboctD.so, libpolkaMPQ.so

    Note that these files are not necessarily in Apron's root directory. They might be under some sub-directories.

  9. Open a shell and type:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUANTO/lib

    (replace $CUANTO with the absolute path of cuanto)

  10. Done.

Apron/Japron installation for MacOS

If you are using MacOS, things will be slightly different when setting up Apron:

  1. Replace step 8 above with:

    Move the followings files from apron/ to cuanto/lib/:

    apron.jar, gmp.jar, libapron.so, libboxD.so, libjapron.dylib (renamed from libjapron.so), libjgmp.dylib (renamed from libjgmp.so), libjgmp.so, liboctD.so, libpolkaMPQ.so

    Note that these files are not necessarily in Apron's root directory. They might be under some sub-directories.

  2. Replace step 9 above with:

    Open a shell and type:

    export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$CUANTO/lib

    (replace $CUANTO with the absolute path of cuanto)

Running on Windows

We recommend using the Bash on Windows for development. This is an almost fully functional implementation of the Linux environment from which you can run bash. After following these instructions, open a bash terminal and follow the instructions for Linux. We currently do not have a good way to make IntelliJ work in this environment, but the command line is fully functional.

If nix-shell emits a disk I/O error then it may be necessary to apply the following [fix][Windows sqlite. Within the /etc/nix/nix.conf add the line

use-sqlite-wal = false