qbicc
= qbicc
This is the README
for qbicc. There's not much here yet but be sure to read link:Overview.adoc[the overview].
Our https://qbicc.zulipchat.com[`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: https://github.com/qbicc/qbicc-class-library[`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 https://github.com/qbicc/qbicc-class-library#readme[`instructions for creating a case-sensitive file system on macOS`] before executing the commands below.
git clone --recurse-submodules git@github.com: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:
[source,xml]
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 https://jbang.dev[`jbang`] to run it:
[source,shell]
jbang --quiet org.qbicc:qbicc-main:0.76.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,
[source,shell]
jbang --quiet org.qbicc:qbicc-main:0.76.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:
[source,shell]
jbang cache clear
== Requirements
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.