Plinth

This project aims to implement a new programming language called "Plinth".

There is not yet much documentation on the syntax and semantics of the language, but more will be made available when more of the core language features have been implemented.

Instructions

You will need: Java (JDK) >= 1.7, LLVM 3.3, Clang, Apache Ant, GCC (to compile to native code), and optionally Python 3 (to run the test suite).

To compile the compiler, use the ant build script defined in build.xml:

Plinth$ ant

This will compile all of the source files in src to bin, all of the runtime code in runtime to runtime/runtime.bc, and all of the plinth standard library in plinth-src to plinth-bin.

To run the test suite:

Plinth$ ant run-tests

To compile Test.pth to binary.pbc:

Plinth$ ./plinth -o binary.pbc --main-type foo.bar.Test -l runtime/runtime.bc -l plinth-bin/plinth.pbc Test.pth

The file runtime/runtime.bc is the compiled and linked version of all of the C and LLVM code in runtime. The ant build compiles this for whichever platform you are on.

The file plinth-bin/plinth.pbc is the compiled and linked version of all of the plinth code in plinth-src. It contains the standard library, which includes strings, standard input and output, and lots of the core functionality of the language. This file is completely platform independent.

To generate an executable from the linked bitcode:

llc binary.pbc -o binary.s
gcc binary.s -o binary -lm

To run your program and check its return code:

./binary
echo $?

Alternatively, you can run the LLVM bitcode generated by the compiler directly via the LLVM interpreter (although this may not work correctly with Plinth's exceptions):

lli binary.pbc
echo $?

Using your own LLVM build

If you wish to use a custom build of LLVM when using plinth, you may find the following notes helpful:

• Plinth links to the LLVM shared library at runtime, so when you are building LLVM make sure to use the configuration flag --enable-shared to build it.

• To link to LLVM at runtime, the plinth compiler searches for "LLVM-3.3", which translates to libLLVM-3.3.so on Linux. If you wish to use a different shared library, you need to change a line in src/nativelib/llvm/LLVM.java: Native.register("LLVM-3.3"); should use your shared library name.

• If the ant build process gives you errors about being unable to find llvm-link, try adding the path to your LLVM install's bin folder to your PATH environment variable.

• If running the compiler fails with a message like:

    java.lang.UnsatisfiedLinkError: Unable to load library 'LLVM-3.3': libLLVM-3.3.so: cannot open shared object file: No such file or directory
  

  Try adding the path to your LLVM install's lib folder (which should contain libLLVM-3.3.so) to your LD_LIBRARY_PATH environment variable.