Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/qbicc/qbicc

Experimental static compiler for Java programs.
https://github.com/qbicc/qbicc

compiler java llvm native-image openjdk

Last synced: 5 days ago
JSON representation

Experimental static compiler for Java programs.

Awesome Lists containing this project

README 

        
= 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 [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:



[source,xml]

-----



    org.qbicc

    qbicc-maven-plugin

    ${qbicc.version}

    

        

            qbicc-compile

            

                compile

            

            

                

                hello.world.Main

            

        

    



-----



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.