Skip to content

Getting started

In this tutorial you run your first program in the interpreter, build a native executable, and look at what the compiler does to your program.

Prerequisite

SPy must be installed first: see Install.

Run a program in the interpreter

The repository contains examples/hello.spy:

def main() -> None:
    print("Hello world!")

Every SPy program defines a main function: it is the entry point. Run it with the interpreter, exactly as you would run a Python script:

$ spy examples/hello.spy
Hello world!

Interpreter performance

The interpreter is itself written in Python, so it is currently very slow: every operation of your program is executed by Python. It is meant for quick experiments, for testing and for debugging. It will become at least as fast as Python thanks to two improvements: compiling the interpreter itself (self-hosting) and precompiling the standard library.

The speed of SPy comes from compilation, which is the subject of the next section.

Debugging

The interpreter is also what runs your program under the debugger. If an error occurs, two options of the spy command start a post-mortem session:

  • --spdb opens spdb, the debugger for SPy code: you inspect your SPy program (its functions and variables).
  • --pdb opens the standard Python debugger on the interpreter itself. It is useful to debug SPy, not your own program.

For example: spy --spdb my_program.spy.

Build an executable

$ spy build examples/hello.spy
[debug] examples/build/hello
$ ./examples/build/hello
Hello world!

The default target is native: spy build examples/hello.spy is the same as spy build --target native examples/hello.spy. It only needs a C compiler.

Two options are worth knowing from the start:

  • --release builds an optimized executable (-O3, link-time optimization) without the debug checks. Without it, you get a debug build (-O0 -g), which is faster to compile.
  • --static produces a statically linked executable, which does not depend on shared libraries (native target only, not supported on macOS).
$ spy build --release --static examples/hello.spy
[release] examples/build/hello

Debug and release modes

The two modes differ in more than compiler flags. In debug mode, a pointer also stores the length of the memory it points to (such a pointer is often called a fat pointer). This lets every indexing operation check that the index is in range, and raise an IndexError if it is not. In release mode, pointers are plain addresses and these checks are removed: an out-of-range index silently reads or writes the wrong memory.

The performance difference between the two modes is huge. Use the debug build while developing, and the release build for benchmarks and final executables.

Three levels of compromise

Together with the interpreter, the two build modes give three ways to run a program, with different trade-offs between usability, safety and performance:

Level Usability Safety Performance
interpreter no build step, debugger checks very slow today, later fast compared to Python
compiled, debug build step checks fast
compiled, release build step, slowest build no checks fastest

--target also accepts wasi and emscripten to produce WebAssembly. wasi works out of the box, but emscripten needs the Emscripten SDK (emcc), see the development setup.

For example, to build the hello world example for WASI:

$ spy build -t wasi --release examples/1_high_level/hello.spy
[release] examples/1_high_level/build/hello.wasm

The result is a .wasm file, which needs a WebAssembly runtime to be executed. Wasmtime is one possible choice (see its installation instructions).

$ wasmtime run examples/1_high_level/build/hello.wasm
Hello world!

See what the compiler does

Before generating code, the compiler redshifts the program: it runs all the parts that can be computed ahead of time and keeps only what must happen at run time. Ask for the result with spy redshift:

$ spy redshift examples/hello.spy
def main() -> None:
    `_print::println[str]`('Hello world!')

The call to print has been resolved to a specialized, statically known function, println[str]. Use -x to also execute the redshifted program:

$ spy redshift -x examples/hello.spy
Hello world!

The other compilation phases (see The compilation pipeline) can be inspected the same way, with commands like spy parse, spy scopes or spy build --no-compile.

Where next?

  • Browse the examples: they go from high-level code that looks like Python to low-level memory manipulation.
  • Try SPy without installing anything in the playground.
  • Look at how the compiler works in The compilation pipeline.