Building and Installing

This section contains instructions on building and installing Mars.

Requirements

  • Unix- or Windows-based operating system. (Tested on Ubuntu 11.10). Instructions assume a Unix environment and Bash shell (and familiarity with the Unix command-line interface).

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:

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 --with-llds-base-grade=none --with-default-grade=hlc.gc to avoid some bugs in Mercury (see the Mercury FAQ). Also add the --disable-most-grades option to ./configure, to significantly reduce the build time (on a fast machine, it will still take around 2 hours to complete the make and make install process).

Note

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
make

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 and /usr/local/man/man1.

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
    make
    
  2. Install the mars and marsc executables to somewhere in your PATH. For example:

    cp mars marsc /usr/local/bin/
    
  3. 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.

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

    cd <mars>/test
    ./runtest
    

    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.

  5. 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.

  6. 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.

Warning

MAKE SURE the executable does not depend on Mercury, if making a Debian package. This can be done by running ldd <mars>/src/mars. It should not depend on any files called libmer* or libgc*. Note that the automatic process ensures this by linking statically; the manual process does not.

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
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/conf.py.
  • 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 should also update the date at the top of the man pages in man/*.