qbicc

This is the README for qbicc. There’s not much here yet but be sure to read the overview.

Our Zulip chat is a great place to ask questions and get started.

Building

To quickly build the project, execute mvn install -DskipTests in the root. This will build qbicc using the latest pre-built release of the qbicc-class-library. Adding -DskipTests avoids running the integration tests, which take about 15 minutes.

Class Library

Qbicc uses a customized version of the OpenJDK libraries: qbicc-class-library. The class libraries are released as a maven artifact, but if you are developing qbicc you will eventually want to build your own local version.

Note: You must clone the qbicc-class-library repository on a case-sensitive file system. If you are on macOS, please follow the instructions for creating a case-sensitive file system on macOS before executing the commands below.

git clone --recurse-submodules [email protected]:qbicc/qbicc-class-library.git
cd qbicc-class-library
mvn install

Running with Maven

Add the following XML to the plugins element of your Maven build to automatically produce a qbicc-built native image:

<plugin>
    <groupId>org.qbicc</groupId>
    <artifactId>qbicc-maven-plugin</artifactId>
    <version>${qbicc.version}</version>
    <executions>
        <execution>
            <id>qbicc-compile</id>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <!-- replace this with your main class name -->
                <mainClass>hello.world.Main</mainClass>
            </configuration>
        </execution>
    </executions>
</plugin>

Be sure to configure the qbicc.version property in your POM to correspond to the current version of qbicc.

Running with jbang

To run the driver, first build the project and then use jbang to run it:

jbang --quiet org.qbicc:qbicc-main:0.39.0 --app-path-file /path/to/main.jar --output-path /tmp/output hello/world/Main

For a step-by-step example, see examples/helloworld/hello/world/Main.java

Running with a locally built Class Library

After building the class library, you can get qbicc to use it simply by adding the command line argument --rt-version=17.alpha.0.NNN-SNAPSHOT (where NNN matches your local class lib version) to your qbicc invocation. For example,

jbang --quiet org.qbicc:qbicc-main:0.39.0 --app-path-file /path/to/main.jar --output-path /tmp/output --rt-version=17.alpha.0.NNN-SNAPSHOT hello/world/Main

JBang cache

When plugins are added or removed, the jbang cache may become inconsistent and result in build errors. If that happens, add the --fresh option to the above command line. Eg: jbang --fresh …​ Alternatively, clear the entire cache using:

jbang cache clear

Requirements

Please ensure the follow are installed and available on your path:

• LLVM 13

• JDK 17

• Maven 3.6.1+

MacOS

To prevent Java versioning errors it is best to install Maven manually rather than with homebrew (see https://maven.apache.org/install.html). The homebrew Maven install has a dependency on Java 16 which may cause Maven to use the wrong version of Java when building qbicc.

The libgcc_s.1.dylib is also required to be available and must be present (or symlinked) to /usr/local/lib/libgcc_s.1.dylib, or the path to that library must be added to the LIBRARY_PATH environment variable.

One way to get this library, if it’s not already on your system, is to brew install gcc.

For Catalina, it may already be present; check in /usr/lib for libgcc_s.1.dylib. If it is present, no further action is necessary.

For BigSur, the brew install gcc path is likely necessary and following symlink resolves the issue:

ln -s $(brew --prefix gcc)/lib/gcc/11/libgcc_s.1.dylib /usr/local/lib/libgcc_s.1.dylib

Alternatively, you can ensure that $(brew --prefix gcc)/lib/gcc/11 is set on the LIBRARY_PATH environment variable.