.. Mars Documentation
Copyright (C) 2008 Matt Giuca
11/12/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 .
.. _ref-man-marsc:
*********
``marsc``
*********
.. sectionauthor:: Matt Giuca
:program:`marsc` -- compiler for programs written in the Mars language
Synopsis
========
.. program:: marsc
:program:`marsc` [:option:`-o ` *output-file*]
[:option:`--backend `\ =\ *backend*]
[:option:`-m ` *name*] [:option:`-h ` | :option:`--help `] [:option:`--version `]
[*mars-source-file*]
Description
===========
:program:`marsc` is the compiler for the Mars programming language. This
command takes a single Mars program, and compiles it with a particular
backend.
By default, Mars code is compiled into LLVM bitcode (``.bc``) files. With LLVM
installed, these can be interpreted with :program:`lli` or compiled into
native executables using :program:`llc` and :program:`clang`. Other backends
are primarily used for debugging.
Options
=======
.. cmdoption:: -o output-file
Compile to the given output filename. If unspecified, the output filename
will be based on the input filename, but with a different extension
(depending on the backend).
.. cmdoption:: --backend=backend
Use a specific backend. This determines what format the output file will be in.
The default backend is *llvm*.
Backends available: *pretty*, *asm*, *llvm*.
.. cmdoption:: -m name
Specify the name of the main function (program entrypoint). This names the
function which will be executed upon program startup. It must have type
:type:`() -> Num`.
If unspecified, there will be no function called at startup, and the
program will serve as a library only.
.. cmdoption:: -d, --destructive
Perform uniqueness analysis and make certain operations destructive, where
possible. This does not change the semantics; it is merely an optimisation.
This makes use of functions like :func:`array_replace` and
:func:`array_concat` use constant time in some cases, rather than linear
time.
This is switched **on** by default. It can be disabled with :option:`-d-`
or :option:`--no-destructive`.
.. cmdoption:: --dump-analysis = dir
Dump logs of any static analysis in HTML form to this directory. Note that
this is for debugging purposes, and could generate a huge amount of data.
If unspecified, no logs will be dumped.
.. cmdoption:: --dump-funcs = a,b,...
Used in conjunction with :option:`--dump-analysis`. Dumps only the
specified functions (given as a comma-separated list).
.. cmdoption:: -h, --help
Display a short help page, then quit.
.. cmdoption:: --version
Display version and copyright information, then quit.
.. _ref-marsc-exe:
Compiling an executable
=======================
Compiling Mars programs into an executable is currently a bit laborious.
:program:`marsc` itself only outputs LLVM bitcode. You need to manually
optimize the bitcode using :program:`opt`, use :program:`llc` to compile the
output into native code, and use :program:`gcc` or :program:`clang` to link it
into an executable.
Here is an example of compiling a single-module Mars program::
marsc -m main hello.mar
opt -std-compile-opts hello.bc -o hello-opt.bc
llc -filetype=obj hello-opt.bc -o hello.o
clang -o hello hello.o -lgc -lm
Exit status
===========
:program:`marsc` will exit with a status of 1 if any fatal errors occur,
including compiler errors or illegal :func:`main` functions.
Otherwise, :program:`marsc` will set its exit status to 0.
Environment
===========
.. envvar:: MARSPATH
Colon-separated list of paths to search for Mars source files. Searched
when the :keyword:`import` statement is used to import Mars modules.
Bugs
====
A list of known bugs is available at https://bugs.launchpad.net/mars/. Bugs
should be reported using the link on that page.