Usage

After you have successfully installed Spiral, you can find the executable in target/debug/spiral (or target/release/spiral). You should have also received your copy of the standard library in the directory stdlib/. Spiral programs also need to be linked with the runtime library, so make sure there is the static library rt/build/runtime_debug.a or rt/build/runtime_fast.a.

To compile a Spiral program, you will need to tell the compiler the path to the source file, paths where to find another Spiral modules (most notably the standard library) and a path to a runtime library. (These paths could have ,,reasonable defaults'', but I believe that such implicit dependencies are the root of all evil.)

When Spiral looks for modules, it walks through a list of directories. To add a directory to this list, use -I <dir> (or --include <dir>). To let the program access the standard library, add -I stdlib. If you build your own set of modules, you can add more directories to this list simply by repeating the flag multiple times. The path to the runtime library is specified with -t <file> (or --runtime <file>).

The compiler needs to call your system linker and assembler to produce a working executable. By default, it uses clang as linker (this ensures that the C libraries are linked correctly) and as as assembler, so it should work out of the box. However, you can set your own commands by --link-cmd <cmd> and --gas-cmd <cmd>, should you ever need it.

The compilation of a Spiral program is separated into multiple stages. By default, the compiler runs all the steps to obtain the executable, but you can pass the -e (or --emit) flag to inspect one of the intermediate forms (see --help for details). The output file is by default located alongside the input file with the extension determined by the requested type of output (no extension for executables). You can override the output file with -o <file> (or --output <file>).

To sum it up, you want to compile Spiral programs as:

./target/debug/spiral -I stdlib -r rt/build/runtime_debug.a your_program.spiral

(possibly with -o your_executable_with_funny_name).

You can find the concise usage and reveal some secret flags by passing --help to the compiler.

A note on the use of Valgrind: When Spiral programs pass arguments to callers, they first write the arguments on the stack below the current stack frame and then adjust the stack pointer. This is perfectly safe, but it makes Valgrind very unhappy, producing billions of errors about invalid writes (when the arguments are written below the stack pointer) and uninitialized values (when these arguments are subsequently used). To fool valgrind, call it with --undef-value-errors=no --workaround-gcc296-bugs=yes.