Dev Guide

OCaml environment

Lets standardize on Opam 2.0.0~rc. The release candidate is feature-complete and doesn't have any major bugs. 2.0 does have a have a useful feature: you can create local environments with opam switch, and opam will automatically use the correct environment. This will be set in the Makefile; invoking make will set everything for you.

If you've installed with Homebrew, you can upgrade to the newer version of opam with brew upgrade opam --HEAD . This has some side effects that I haven't totally worked out. I had to delete my ~/.opam directory and reinit opam again: opam init . This broke Merlin in Vim, but I think this can be fixed by update paths in ./vimrc; i haven't tested ocp-indent yet.

Commit Conventions

Personally (Nick) I like to write commit messages like this:

Issue #4638: Implement Dependent Type System

This commit explains the functionality that I just implemented,
because it is super awesome.

This way, someone can read the git log as a sort of brief narrative of the development of our language, and it makes it easier to get a sense of where we are.

Here's a great guide on the topic

Workflow

Git workflow

• no one commits to master, always to branches and then request a PR
• no one merges their own pr
• commits are small and atomic, so they can be quickly reviewed
• try to rebase before you PR to reduce merge conflicts

Dev Environment

We've standardized on the following versions:

• ocaml: 4.06
• llvm: 3.8

Given all the trouble that we've had getting our local machines set up, the Docker image used for testing can also be used for local dev. To use the docker image, first install Docker from here. To use run make docker-make to compile inside the image, make docker-test to run tests, and make docker-shell to drop you in a shell inside a running container.

The project directory is mapped to /root/TensorFlock inside the container. Any files written inside that directory, from either the host or guest, are saved to the project directory on the host machine. Any changes to the running container outside of /root/TensorFlock are deleted when the container exists.

Writing Tests

Tests can be thought of as insurance against regressions. The fact that they validate code that you've just written is secondary. While you work on new features, and merge in code for them, you may not have enough to test against, which is totally fine. You can stub in tests that pass, and then fill them in once there's enough functionality to test against.

One technique of testing that we've talked about is test driven development. The idea is simple: write a test for some new functionality, and then write code to make it pass. Here's a good explanation

Tests can be saved following this pattern tests/<syntax_tests, semant_tests, codegen>/<pass, fail>/test_name.tf

Codegen tests that are intended to pass should have a corresponding .pass file used to verify the output of the compiled program. Name the file like so: tests/codegen/pass/some_test.tf => tests/codegen/pass/some_test.pass.