This section contains instructions on building and installing Mars.
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
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.
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
If you are actually working on Mars, you may wish to use the slightly more detailed build instructions.
Unpack the Mars sources and build the Mars compiler:
cd <mars>/src
make
Install the mars and marsc executables to somewhere in your PATH. For example:
cp mars marsc /usr/local/bin/
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.
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.
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.
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!
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.
If you actually need to update a version number, here are the places in which you need to do it:
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/*.