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.
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.
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
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.
To run the driver, first build the project and then use jbang
to run it:
jbang --quiet org.qbicc:qbicc-main:0.72.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
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.72.0 --app-path-file /path/to/main.jar --output-path /tmp/output --rt-version=17.alpha.0.NNN-SNAPSHOT hello/world/Main
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
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+
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.