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:
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:
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:
--spdbopensspdb, the debugger for SPy code: you inspect your SPy program (its functions and variables).--pdbopens 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¶
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:
--releasebuilds 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.--staticproduces a statically linked executable, which does not depend on shared libraries (native target only, not supported on macOS).
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).
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:
The call to print has been resolved to a specialized, statically known
function, println[str]. Use -x to also execute the redshifted program:
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.