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 installRunning 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.65.0 --app-path-file /path/to/main.jar --output-path /tmp/output hello/world/MainFor 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.65.0 --app-path-file /path/to/main.jar --output-path /tmp/output --rt-version=17.alpha.0.NNN-SNAPSHOT hello/world/MainJBang 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 clearRequirements
Please ensure the follow are installed and available on your path:
-
LLVM 13+ (we test against 13, 14, and 15)
-
JDK 17
-
Maven 3.6.1+
MacOS
You can install LLVM, Java and Maven using brew. In addition, you will also need to install XCode (to get Apple’s version of clang). Do not attempt to override XCode’s clang with the one that brew installed` (brew will not put its llvm toolchain into your path by default). Instead use symlinks to add just the brew installed llc, llvm-objcopy, and opt executables to your path.