Compilation

Compilation process

The Plinth compiler compiles source files (.pth) into bitcode files (.pbc), and optionally links them together into a single bitcode file.

Suppose we have a file called Hello.pth, which contains a single class called Hello, which has a main method. We can run the compiler as follows:

plinth -o Hello.pbc
       -l /path/to/plinth.pbc
       -l /path/to/runtime.bc
       --main-type Hello
       Hello.pth

This will compile Hello.pth into Hello.pbc.

Because we said that Hello was the main type, Hello.pbc contains code to call the main method: Hello.main([]string args).

Note

-l /path/to/plinth.pbc tells the compiler to link in the plinth standard library, which contains definitions for string, stdout, and other important types.

-l /path/to/runtime.bc tells the compiler to link in the plinth runtime library at the specified path, which should have been built for the target platform.

There are plans to simplify these options by using environment variables to specify a default set of files to import and link in.

Now we have a file called Hello.pbc which contains all of the LLVM code required to run the program. To execute it, we can use LLVM’s interpreter lli, or compile it to native code using LLVM’s compiler llc followed by gcc.

To execute a plinth program, the bitcode files can either be run via the LLVM interpreter (lli), or compiled to native code via LLVM’s compiler:

> lli Hello.pbc
Hello, World!

> llc Hello.pbc -o Hello.s
> gcc Hello.s -o Hello
> ./Hello
Hello, World!

Compiler options

The full list of options is as follows:

-o <binary>, --output <binary>
	Specifies the name of the binary produced. This will be a plinth bitcode (.pbc) file.
-m <main-type>, --main-type <main-type>
	Specifies the fully qualified name of the main class, which contains the main method.
-d <output-dir>, --output-dir <output-dir>
	Specifies the output directory for the generated bitcode files. They will be generated in a directory structure equivalent to the package structure. If this is not specified, these files will not be generated.
-i <import-file>, --import <import-file>
	Adds a bitcode file to the list of files to import.
-l <library-file>, --link <library-file>
	Adds a bitcode file to the list of files to link. These are also used as import files.