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.

[source,shell]

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]

<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 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 installedllc, llvm-objcopy, and opt` executables to your path.