.. Mars Documentation
Copyright (C) 2008-2009 Matt Giuca
8/1/2009
.. 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 .
.. _faq:
**************************
Frequently Asked Questions
**************************
.. sectionauthor:: Matt Giuca
And other trivialities.
The Language
============
What features is Mars missing such that it isn't a "real language"?
-------------------------------------------------------------------
Mars is deliberately short on a lot of common features, in order to keep the
language simple and manageable. This is about researching language features,
not being useful, so I'm not putting in features that aren't interesting or
necessary. I may put some of these in later on, though.
Deliberately-missing features include:
* Array syntax. You have to type ``array_ref(a, i)`` rather than ``a[i]``.
* Several primitive types.
* Char (currently all characters are just Ints, and strings are just
arrays of Ints). This would be really useful because string literals
could print out properly, instead of like ``[116, 104, 105, 115]``.
* Float. Mars doesn't have floats because they're unnecessary, but a real
language would have them. Note that this might complicate things a lot,
because operators like ``+`` (:func:`add`) might have to be overloaded!
* Void. A void type would be useful (for returning from functions), to
avoid having all these functions returning a dummy 0 value. Would be
very handy in interactive mode, to stop them from all printing "0".
* Tuples. Tuple types (``(a, b)``, ``(a, b, c)``, etc) would be
very useful for returning multiple values from a function. Currently,
the :mod:`prelude` provides a handful of user-defined tuple types with
unfriendly syntax.
* More built-ins, such as support for command-line arguments, fopen,
stdin/stdout, sockets, etc. I didn't want to make any more built-ins than
necessary, because they're really hard to maintain, especially with
multiple backends. Note that since Mars has a foreign language interface,
users *can* implement their own otherwise-primitive operations.
* For loops. Very annoying to do without, but I feel that while loops are
enough to demonstrate the "imperative style" of programming, and for loops
are a rather hefty sugar which I don't need to support.
* Break, continue.
* Variadic functions, optional arguments, keyword arguments, other
non-straightforward argument schemes. Definitely something I'm interested
in, but one step at a time.
* Exceptions. Currently ``error`` just terminates the program, with no
possibility of parole.
* Namespaces. For simplicity, importing a module just lumps in all the
imported symbols into the one namespace, like C. Not good for engineering,
but nice and simple.
* Type classes or inheritance. There's no way to have general and special
types, which is fairly limiting. But not important at this stage.
Can I write web apps in Mars?
-----------------------------
Yes! Mars has everything required to support CGI scripts: stdin, stdout, and
reading environment variables. It is therefore possible to write simple web
apps. The library module :mod:`urllib` has some helper functions for writing
web apps. The :file:`samples` directory has an example of a CGI script. CGI
scripts should run with no hassles in a web server like Apache -- just drop
them into the :file:`cgi-bin` directory and visit them.
What about desktop GUI apps?
----------------------------
There are no built-in GUI primitives, but in theory, this is possible. Since
Mars allows calls to native code written in other languages, one would simply
need to write a binding to one of the many widget APIs.
The Implementation
==================
There is a bug in Mars!
-----------------------
Please report it using the bug tracker at
``_. Thanks!
What does the error "Can't find "runtime.bc" in Mars search path" mean?
-----------------------------------------------------------------------
When using the LLVM backend, Mars requires that the file :file:`runtime.bc` is
installed in the Mars search path (the same place where the library files are
installed, usually :file:`/usr/local/lib/mars` or :file:`/usr/lib/mars`.
The file :file:`runtime.bc` needs to be compiled from the file
:file:`runtime.ll` in the :file:`lib` directory of the source tree. This is
done automatically by the automatic build script, but if you are building Mars
manually, you need to do it yourself.
:command:`cd` into the :file:`lib` directory and type ``make``.
Can I compile Mars programs to native code?
-------------------------------------------
Yes, with a bit of effort. The :program:`marsc` program compiles Mars programs
into ``.bc`` files (LLVM bitcode files). These can be compiled into native
assembly files using the program :program:`llc`, which can then be compiled
into native executables using :program:`clang` or however you prefer to
compile/link assembly files.
See :ref:`ref-marsc-exe` for details on compiling native executables.
What are the .bc files produced by :program:`marsc`?
----------------------------------------------------
These are LLVM bitcode files. They are a low-level machine instruction format
which can be executed by the :program:`lli` program on the command-line. They
can also be compiled into native executables using :program:`llc`. These tools
are part of the LLVM package.
What are the .mas files produced by :program:`marsc` --backend=asm?
-------------------------------------------------------------------
These are "Mars assembly" files. They aren't actually executable and can't be
read by any program -- they are designed for humans to read, so we can debug
the Mars compiler.
.. _ref-show_free:
I am getting "Runtime Error: show:free" or "eq:free" at the interactive prompt
------------------------------------------------------------------------------
This can happen in rare circumstances, and it's a pretty tricky problem to
solve. It should *only* happen at the interactive prompt -- if you see this
error when running normal code, please report it!
.. highlight:: marscon
This only occurs if you assign a polymorphic function which calls (or is)
:func:`show` or :func:`eq` to an interpreter variable, then call that. For
example::
?> x = show
?> x(1)
Runtime Error: show:free
This is because when :func:`show` is assigned to the interpreter variable,
Mars must make a decision about which version of :func:`show` (which type the
argument has) to load. Since you haven't yet chosen a type, Mars chooses a
version of show which produces the above error. The solution is not to assign
polymorphic functions to interpreter variables (you can still *call*
polymorphic functions on the command-line; for example, ``show(1)`` is still
valid).
.. highlight:: mars
If you are interested in the details, see :ref:`ref-typedicts`.