Building and Installing

This section contains instructions on building and installing Mars.


  • Unix-based operating system. (Tested on Ubuntu 14.04). Instructions assume a Unix environment and Bash shell (and familiarity with the Unix command-line interface).
  • LibFFI 3.0 or higher (tested against 3.1).
  • LLVM 3.0 or higher (tested against 3.4).
  • Boehm-Demers-Weiser garbage collector 6.0 or higher (tested against 7.2).

Installing binaries

Mars is available for Ubuntu in the form of a pre-compiled Debian package. This is the preferred option for installation.

To install, simply download the file mars_<version>.deb, and type:

sudo dpkg -i mars_<version>.deb

To uninstall at any time, type:

sudo apt-get remove mars

Installation from source

Building from source carries the following additional requirements:

On Ubuntu, the dependencies can be installed with:

sudo apt-get install libffi-dev llvm-dev libgc-dev libreadline-dev
sudo apt-get install python2.7 python-yaml python-sphinx

You will need to build Mercury from source. This can be a painful process. In fact, if you survive this process, you will have no trouble at all setting up Mars itself.

You should use ./configure --disable-most-grades --with-default-grade=hlc.gc to significantly reduce the build time (on a fast machine, it will still take around 40 minutes to complete the make and make install process).


Examples below refer to the directory <mars>. This refers to wherever you have unpacked the Mars source tree.

Automatic build instructions

We provide a convenient makefile, which can be used to automatically build and, if desired, install Mars in the default location.

Just type:

cd <mars>/setup

This will build the Mars executables and the documentation (it simply automates the manual build instructions, outlined below).

If you would like to install Mars, then type:

sudo make install

This will install files in the following directories:

  • /usr/local/bin
  • /usr/local/lib/mars
  • /usr/local/share/man/man1
  • /usr/local/share/doc/mars

You can remove all the installed files again at any later time by typing:

cd <mars>/setup
sudo make remove

Manual build instructions

If you are actually working on Mars, you may wish to use the slightly more detailed build instructions.

  1. Unpack the Mars sources and build the Mars compiler:

    cd <mars>/src
  2. Install the mars and marsc executables to somewhere in your PATH. For example:

    cp mars marsc /usr/local/bin/
  3. Build the Mars runtime:

    cd <mars>/lib
  4. Set up MARSPATH.

    Edit your .bashrc or similar configuration file and add an environment variable MARSPATH. This should contain the location of the lib directory in the Mars source tree. For example:

    export MARSPATH=<mars>/lib

    This variable may contain a colon-separated list of paths, which will be searched for .mar files on Mars’s import statement, similar to PATH in Unix, CLASSPATH in Java, or PYTHONPATH in Python.

    Alternatively, you may wish to copy the contents of <mars>/lib to /usr/local/lib/mars, which is automatically searched. Then you won’t have to set MARSPATH at all.

  5. Run the Mars test suite to test the compiler and library:

    cd <mars>/test

    This should print out that all test cases passed (or were expected to fail). Note that this will require the Python and the PyYAML Python package to run.

  6. Build the documentation:

    cd <mars>/doc
    make html

    This should place the html documentation tree in <mars>/doc/build/html.

    Alternatively, you can build a PDF version (requires LaTeX) by typing:

    cd <mars>/doc
    make latex
    cd build/latex
    make all-pdf

    This will place a PDF file in <mars>/doc/build/latex.

  7. Install vim syntax file.

    If you are a vim user, a syntax highlighting file is provided in <mars>/misc/mars.vim.

    Copy this file to ~/.vim/syntax for local user, or /usr/share/vim/vimcurrent/syntax for all users. Then, edit ~/.vim/after/filetype.vim, and add (or edit) the following lines:

    augroup filetypedetect
        au BufRead,BufNewFile  *.mar               set filetype=mars
    augroup END

    .mar files will now highlight correctly. Note that this is not set up by the automatic install procedures. If you are working with Mars bytecode, you can also copy the file mars-asm.vim and link it to the *.mas type, for proper highlighting of Mars assembly files.

    If you use another editor, feel free to write a syntax highlighting script, and send it to me!

Making a release

If it ever falls upon you to make a source or binary release of Mars, here is how you do it.

First, check out a fresh copy of the Mars source (make sure the <mars>/src/Mercury and <mars>/doc/build directories are gone), and build using the automatic build instructions.

The version numbers are tagged with “~bzr” in the source tree, so any code recklessly exported from there is clearly labeled as unstable (eg in mars --version). When preparing a release, remove the “~bzr” label from all of the places where the version number appears (see updating the version number).

To build a Debian package, simply type:

cd <mars>/setup
make deb

This will create a directory called debian (with all the files which will be installed), and a complete debian package with the current version.

The last thing to do is update the “installed package size” (this is a manual process). Take the total size of the debian directory in kilobytes (use du -k debian), and replace Installed-Size in setup/control. Then re-run make deb.

Updating the version number

If you actually need to update a version number, here are the places in which you need to do it:

  • version_string at the top of src/mars.m and src/marsc.m.
  • version and release in doc/
  • Version in setup/control.
  • DEBFILE at the top of setup/Makefile (this is the Debian package filename).

The latter two include a “-1” suffix. This should be incremented if the Debian package changes but not the program, and reset to “-1” if the program version number increments.

You also need to update the date in the following places:

  • copyright_year at the top of src/mars.m and src/marsc.m.
  • copyright in doc/
  • Top of the man pages in man/*.
  • Copyright at the top of COPYING.