Users › 01 Getting started

Getting started

Build the toolchain, run your first program, and learn the four commands you will use every day.

1. Build the toolchain

Lopolith is a C11 program. From the repository root:

$ make            # builds ./loth (the compiler + VM + CLI)
$ make libs       # builds lib/Std.so and lib/Thread.so

make libs matters: the standard library is delivered as native plugins (.so), and #import Std will not resolve until they exist. Build both targets once and you are done.

2. Hello, world

Create hello.loth. A program is one file per class; the file path must match the class name.

%simple com.example.Hello implements Main
    #import Std
    int run(int argc, String[] argv) Main@run {
        Std.print("Hello, world!\n")
        return 0
    }

Hello, world!

$ ./loth run -e com.example.Hello hello.loth
Hello, world!

Three things to notice, because they are different from most languages:

• %simple declares a singleton. There is exactly one Hello object, and its name is both the type and the value.
• implements Main makes it the program entry point. The entry method may have any name as long as it is bound to Main@run; it receives the command-line arguments and its return value becomes the process exit code. The class must be selected explicitly with -e.
• Printing is not built into the language. It comes from the standard library Std, which must be imported.

3. The four commands

loth run -e Class <file.loth> [-cp dir] [args...]     # compile (if needed) and run
loth compile <file.loth> -o <dir>                    # write portable .lothc modules
loth <file.lothc> -e Class [args...]                 # run compiled modules
loth native-info <lib.so>                             # inspect a native library

• run finds the entry point automatically; -e selects it by fully-qualified name when a project has several.
• -cp adds a directory to the search path for .lothc and .so dependencies.
• Arguments after the file (or after -e/-cp) are passed to run(argc, argv).
• The exit code is the value returned by run; usage errors exit with 2, and an uncaught exception exits with 1.

4. Paths are part of the program

The fully-qualified name in the first directive must match the file path:

com/example/Hello.loth   ⇄   %simple com.example.Hello

This mapping is checked by the compiler and by the loader, so a class cannot quietly live under the wrong name. Every file has exactly one primary directive (%class, %interface, %simple, %native, %nativesimple), optionally followed by private helper classes (%sub), which chapter 2 covers.

5. What can go wrong

• module not found: 'Std' (#import) — you did not run make libs.
• path does not match the class directive — the file path and the name in the directive disagree.
• uncaught exception: ... — the program threw and nobody caught it; see chapter 8.