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