.. Mars Documentation
Copyright (C) 2008 Matt Giuca
3/9/2008
.. This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.. This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
.. You should have received a copy of the GNU General Public License
along with this program. If not, see .
.. _setup:
.. highlight:: none
Building and Installing
=======================
.. sectionauthor:: Matt Giuca
This section contains instructions on building and installing Mars.
Requirements
------------
* 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_.deb``, and type::
sudo dpkg -i mars_.deb
To uninstall at any time, type::
sudo apt-get remove mars
Installation from source
------------------------
Building from source carries the following additional requirements:
* `Melbourne Mercury Compiler `_
14.01 or higher.
* `GNU Readline `_.
* `Python `_ 2.5 or higher (tested against 2.7), and
`PyYAML `_ Python package, to run test suite.
* `Sphinx `_ to build the documentation.
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).
.. note::
Examples below refer to the directory :file:``. 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 /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``
* ``/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 /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 /src
make
2. Install the :program:`mars` and :program:`marsc` executables to somewhere
in your :envvar:`PATH`.
For example::
cp mars marsc /usr/local/bin/
3. Build the Mars runtime::
cd /lib
make
4. Set up :envvar:`MARSPATH`.
Edit your :file:`.bashrc` or similar configuration file and add an
environment variable :envvar:`MARSPATH`. This should contain the location
of the :file:`lib` directory in the Mars source tree. For example::
export MARSPATH=/lib
This variable may contain a colon-separated list of paths, which will be
searched for :file:`.mar` files on Mars's :keyword:`import` statement,
similar to :envvar:`PATH` in Unix, :envvar:`CLASSPATH` in Java, or
:envvar:`PYTHONPATH` in Python.
Alternatively, you may wish to copy the contents of ``/lib`` to
``/usr/local/lib/mars``, which is automatically searched. Then you won't
have to set :envvar:`MARSPATH` at all.
5. Run the Mars test suite to test the compiler and library::
cd /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.
6. Build the documentation::
cd /doc
make html
This should place the html documentation tree in ``/doc/build/html``.
Alternatively, you can build a PDF version (requires LaTeX) by typing::
cd /doc
make latex
cd build/latex
make all-pdf
This will place a PDF file in ``/doc/build/latex``.
7. Install :program:`vim` syntax file.
If you are a :program:`vim` user, a syntax highlighting file is provided in
``/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
``/src/Mercury`` and ``/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 :ref:`updating the version
number `).
To build a Debian package, simply type::
cd /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 :file:`setup/control`.
Then re-run ``make deb``.
.. _ref-updating-the-version-number:
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 :file:`src/mars.m` and
:file:`src/marsc.m`.
* ``version`` and ``release`` in :file:`doc/conf.py`.
* ``Version`` in :file:`setup/control`.
* ``DEBFILE`` at the top of :file:`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 :file:`src/mars.m` and
:file:`src/marsc.m`.
* ``copyright`` in :file:`doc/conf.py`.
* Top of the man pages in :file:`man/*`.
* Copyright at the top of :file:`COPYING`.