Compiling and Testing Your Code

Each student’s repository contains a global dune-project file and one dune file in every directory that contains source code. These are configuration files to ease compiling your code and unit-testing it. It is based on the Dune tool helping you to build executables, libraries, run tests, and much more with OCaml. We’ll be describing the main command-lines you can use within a unix system where OCaml and Dune have been properly installed. For steps to make a Windows or a linux distribution configuration of needed dependencies through opam please visit the Frequently Asked Questions.

You’ll have enough insight going through the quickstart page of the Dune documentation you can find here. For any in-depth use of Dune you’re advised to have a look at the rest of the offical documentation.

For testing purposes you might want to have a look at the Alcotest documentation : Alcotest.

Danger

If you do not understand what you’re doing DO NOT modify your dune-project or dune files without backing it up. Such a change might compromise your project compilation process. Know that your code will be graded using our own versions of these files, if you count on a modified build configuration to work out with grading process : you are mistaken.

Compiling Your Project

You’re having a dune-project file at the root of your repository. This is the entry point for the configuration files meant to set the scope of your project. Every other dune file contains information about what source files should be compiled, how, and with what dependencies.

Contrary to a lot of (more elaborate) projects, there is no need for a configuration step, you can directly compile your project using the command:

dune build

from within the root of your project repository. This will create a _build/ directory containing a copy of your source files and their respective compilation products.

Danger

We advise you to never modify the source files within that _build/ directory, these files will be overwritten by the “real” ones (those in Source/) every time you do a build or clean command.

If at any time you need to get rid of this _build/ folder and the compilation products (to do a fresh and complete new build for example), you can issue the following command:

dune clean

Testing Your Project

From The Shell

Each repository comes with a number of unit tests included within the tests folders of each one of the project’s phases. These are written using the Alcotest testing library provided for OCaml. You are welcome to add your own tests there if you understand what you are doing, but a lot of them are already given to you.

You can the whole test suite you’re given by simply typing the command:

dune runtest

This shall run three test suites: one for the Builtin part of the project, one for the Scalable part and one for the Zarithing part (for which tests are empty!). You will see three lists of tests: one for each one of those parts. In these lists, each line corresponds to one function and has four columns:

• the first column is the function’s tests result ([OK] if all the tests passed, [ERROR] if at least one did not, and something else in other, more specific, cases)

• the second column is the name of the module in which the function is

• the third column is the number of the function within that module

• the fourth and last column is a short description of the tested function

Below this list, if some tests failed, you will see a description of the first few failed tests and the path of the file that contains the detailed results of this module’s tests.

If you only wish to run the tests of one of the three parts of that project, you can restrict the tests ran by Dune by giving it the folder you wish to test. For example, to only run the tests of the Builtin part of the project, you can issue:

dune runtest Source/builtin

If you want to further restrict what’s ran and you only want to run the tests of a single source file, you can directly run the test executable and give it the name of the module you wish to test (each source file is a module).

There are two ways of doing that: either you execute that file directly after finding it in the _build directory. For example if you only wish to run the basic_arithmetics.ml tests from the Builtin part of the project you can type (don’t forget the starting dot):

./_build/default/Source/tests/builtin/run_tests.exe test basic_arithmetics

or you can ask dune to find and run it itself by giving it the executable’s expected location relative to the source directory:

dune exec Source/tests/builtin/run_tests.exe test basic_arithmetics

In this case you’ll see that the whole test list is still displayed, but every test you didn’t specify is marked as [SKIP].

From within Emacs

You can test your functions from within the OCaml top-level available while being in emacs tuareg-mode .

While being in the builtin directory you can evaluate each one of the expressions of the builtin.ml file in the ocaml top-level interpreter by using the C-c C-e shortcut. In order to evaluate the whole current buffer you can use the C-c C-b shortcut. To evaluate the builtin.ml file without necessarily opening it you can use the top-level directive:

#use "builtin.ml"

All available function within the builtin.ml file are then available within top-level.

The previous strategy is going to raise an error if you try evaluating the file basic_arithmetics.ml. You’ll get an error specifying that the Builtin module is not bounded. This error says the top-level environment cannot see any Builtin module to open ; the basic_arithmetics.ml file starts by openning that module (which corresponds to file builtin.ml). For top-level to evaluate the open Builtin instruction you need to load builtin.ml as a module in top-level using the directive:

#mod_use "builtin.ml"

You can then evaluate basic_arithmetics.ml using the directive:

#use "basic_arithmetics.ml"

In order to evaluate any given file file.ml in top-level you’ll generally need to load the modules it opens through open instructions using #mod_use directive. You’re invited to ask your lab assistants for help if needed.