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.

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

[GR-42693] First draft of native-image bundle support. #5569

Merged
merged 46 commits into from
Jan 30, 2023
Merged

Conversation

graalvmbot
Copy link
Collaborator

@graalvmbot graalvmbot commented Dec 6, 2022

This PR adds basic bundle support. Two new options are added:

    --bundle-create[=new-bundle.nib]
                          in addition to image building, create a native image bundle file (*.nib
                          file) that allows rebuilding of that image again at a later point. If a
                          bundle-file gets passed the bundle will be created with the given name.
                          Otherwise, the bundle-file name is derived from the image name. Note
                          both bundle options can be combined with --dry-run to only perform the
                          bundle operations without any actual image building.
    --bundle-apply=some-bundle.nib
                          an image will be built from the given bundle file with the exact same
                          arguments and files that have been passed to native-image originally
                          to create the bundle. Note that if an extra --bundle-create gets passed
                          after --bundle-apply, a new bundle will be written based on the given
                          bundle args plus any additional arguments that haven been passed
                          afterwards. For example:
                          > native-image --bundle-apply=app.nib --bundle-create=app_dbg.nib -g
                          creates a new bundle app_dbg.nib based on the given app.nib bundle.
                          Both bundles are the same except the new one also uses the -g option.

1. Create a new bundle with --bundle-create:

> native-image --bundle-create=simple-bundle.nib -cp cp HelloJava

This creates a new bundle that contains the all files from the cp directory and captures the command line args used to create the bundle (-cp cp HelloJava) and all files that were created during image building. Those files are also directly available in directory simple-bundle.output next to the bundle. It is also possible to just create the bundle without getting the image built as well. When --bundle-create is combined with --dry-run a bundle will be created that does not contain an image and also no <bundlename>.output gets created. This is useful if you just want to create a bundle on a machine but build an image from that bundle somewhere else (maybe on a more powerful machine i.e. a build server).

If no filename is passed to --bundle-create then the name of the bundle will be derived from the image name. E.g. in the above case omitting =simple-bundle.nib would result in a bundle named hellojava.nib (because the image name is derived form the main class name HelloJava).

A common pattern that I expect to emerge is users to inject --bundle-create to non-trivial maven or grade native-image builds to retrieve a bundle. For example, adding graalvmNative { binaries { main { buildArgs.add('--bundle-create') }}} in build.gradle of a spring-boot-native application will produce a bundle that can later be rebuilt without requiring the original project. The bundle alone is self-contained and contains everything needed to build the application again.

2. Build an image again from a bundle with --bundle-apply:

native-image --bundle-apply=simple-bundle.nib

The image will be rebuilt in the simple-bundle.output directory.

Note that passing any additional arguments after --bundle-apply will be taken into account in the image build. For example:

native-image --bundle-apply=simple-bundle.nib --pgo-instrument

will again create directory simple-bundle.output but this time the image is built with arguments -cp cp HelloJava --pgo-instrument.

3. Creating a new bundle from an existing one with --bundle-apply + --bundle-create:

Suppose you have a bundle and you want to derive another bundle from it that builds the original application but with pgo optimization. This can be achieved by combining --bundle-apply with as subsequent --bundle-create. For example if we have pgo profile information in the form of a default.iprof in our current working directory we could use the following command to create a new bundle that can build a pgo optimized image.

native-image --dry-run --bundle-apply=simple-bundle.nib --pgo --bundle-create=simple-bundle-pgo.nib

The newly created bundle will contain the default.iprof and the arguments needed to pass it to the builder. Also note the use of --dry-run here again. This will skip image building and only create the new bundle.

@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Dec 6, 2022
@graalvmbot graalvmbot force-pushed the paw/GR-42693 branch 2 times, most recently from 012ef42 to 565831d Compare December 7, 2022 16:06
@oracle-contributor-agreement oracle-contributor-agreement bot added OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. and removed OCA Verified All contributors have signed the Oracle Contributor Agreement. labels Jan 3, 2023
@oracle-contributor-agreement oracle-contributor-agreement bot added OCA Verified All contributors have signed the Oracle Contributor Agreement. and removed OCA Required At least one contributor does not have an approved Oracle Contributor Agreement. labels Jan 11, 2023
@christianwimmer christianwimmer changed the title [GR-42693] First draft of replay-bundle support. [GR-42693] Build bundle support. Jan 11, 2023
@olpaw olpaw changed the title [GR-42693] Build bundle support. [GR-42693] First draft of native-image bundle support. Jan 12, 2023
@olpaw olpaw self-assigned this Jan 12, 2023
@olpaw olpaw added this to the 23.0.0 Release milestone Jan 12, 2023
@graalvmbot graalvmbot force-pushed the paw/GR-42693 branch 2 times, most recently from 154c7b6 to 2597229 Compare January 16, 2023 14:23
@graalvmbot graalvmbot force-pushed the paw/GR-42693 branch 5 times, most recently from 47755d2 to c14b88d Compare January 26, 2023 18:25
@graalvmbot graalvmbot merged commit a477a6d into master Jan 30, 2023
@graalvmbot graalvmbot deleted the paw/GR-42693 branch January 30, 2023 19:58
@olpaw olpaw linked an issue Feb 1, 2023 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
OCA Verified All contributors have signed the Oracle Contributor Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Native Image Build Bundles
2 participants