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