Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation of "Separating Java and native image compilation" section #19610

Merged
merged 1 commit into from
Aug 24, 2021
Merged

Improve documentation of "Separating Java and native image compilation" section #19610

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions docs/src/main/asciidoc/building-native-image.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,25 +632,25 @@ For this use case, you can set the `quarkus.package.type=native-sources`.
This will execute the java compilation as if you would have started native compilation (`-Pnative`), but stops before triggering the actual call to GraalVM's `native-image`.

[source,bash]
---
----
$ ./mvnw clean package -Dquarkus.package.type=native-sources
---
----

After compilation has finished, you find the build artifact in `target/native-sources`:

[source,bash]
---
----
$ cd target/native-sources
$ ls
native-image.args getting-started-1.0.0-SNAPSHOT-runner.jar
---
native-image.args getting-started-1.0.0-SNAPSHOT-runner.jar lib
----

You see that, beside the expected JAR, a file `native-image.args` was created.
From the output above one can see that, in addition to the produced jar file and the associated lib directory, a text file named `native-image.args` was created.
This file holds all parameters (including the name of the JAR to compile) to pass along to GraalVM's `native-image` command.
If you have GraalVM installed, you can start the native compilation by executing:

[source,bash]
---
----
$ cd target/native-source
$ native-image $(cat native-image.args)
...
Expand All @@ -659,14 +659,14 @@ native-image.args
getting-started-1.0.0-SNAPSHOT-runner
getting-started-1.0.0-SNAPSHOT-runner.build_artifacts.txt
getting-started-1.0.0-SNAPSHOT-runner.jar
---
----

The process for Gradle is analogous.

Running the build process in a container is also possible:

[source,bash,subs=attributes+]
---
----
cd target/native-image
docker run \
-it \
Expand All @@ -676,28 +676,28 @@ docker run \
--entrypoint bin/sh \
quay.io/quarkus/ubi-quarkus-native-image:{graalvm-flavor} \ <3>
-c "native-image $(cat native-image.args) -J-Xmx4g" <4>
---
----

<1> Mount the host's directory `target/native-image` to the container's `/work`. Thus, the generated binary will also be written to this directory.
<2> Switch the working directory to `/work`, which we have mounted in <1>.
<3> Use the `quay.io/quarkus/ubi-quarkus-native-image:{graalvm-flavor}` docker image introduced in <<#multistage-docker,Using a multi-stage Docker build>> to build the native image.
<4> Call `native-image` with the content of file `native-image.args` as arguments. We also supply an additional argument to limit the process's maximum memory limitation to 4 Gigabyte.
<4> Call `native-image` with the content of file `native-image.args` as arguments. We also supply an additional argument to limit the process's maximum memory to 4 Gigabytes (this may vary depending on the project being built and the machine building it).

In a CI/CD setup, we would:
[WARNING]
====
If you are running on a Windows machine, please keep in mind that the binary was created within a Linux docker container.
Hence, the binary will not be executable on the host Windows machine.
====

1. register the output of the step executing `./mvnw ...` command (i.e. directory `target/native-image`) as build artifact,
2. require this artifact in the step executing the `native-image ...` command, and
3. register the output of the step executing the `native-image ...` command (i.e. files matching `target/*runner`) as build artifact.
A high level overview of what the various steps of a CI/CD pipeline would look is the following:

The environment executing `1` only needs access to a Java- and a Maven- (or Gradle)-installation, while the environment executing `3` only needs access to a GraalVM installation (including the `native-image` feature).
1. Register the output of the step executing `./mvnw ...` command (i.e. directory `target/native-image`) as a build artifact,
2. Require this artifact in the step executing the `native-image ...` command, and
3. Register the output of the step executing the `native-image ...` command (i.e. files matching `target/*runner`) as build artifact.

The generated binary can then be used to create a container image, as explained above.
The environment executing step `1` only needs Java and Maven (or Gradle) installed, while the environment executing step `3` only needs a GraalVM installation (including the `native-image` feature).

[WARNING]
===
If you are running on a Windows machine, please keep in mind that the binary was created within a Linux docker container.
Hence, the binary will not be executable on the host Windows machine.
===
Depending on what the final desired output of the CI/CD pipeline is, the generated binary might then be used to create a container image.

== Debugging native executable

Expand Down