feat: bazel settings integration

- feat: detect and honor `compilation_mode` flag - feat: build with debug settings if `compilation_mode=dbg` - feat: ability to build a shared library - feat: build with `tool:coverage` if coverage is enabled and a test-only target is being built - docs: add doc which explains shared library feature - docs: add doc for built settings integration (more to come) Relates-To: #78 Relates-To: #85 Signed-off-by: Sam Gammon <[email protected]>
sgammon · Sep 8, 2023 · 6fc5874 · 6fc5874
1 parent ac1fa36
commit 6fc5874
Show file tree

Hide file tree

Showing 17 changed files with 639 additions and 616 deletions.
diff --git a/MODULE.bazel.lock b/MODULE.bazel.lock
diff --git a/README.md b/README.md
@@ -18,10 +18,13 @@ Use [GraalVM](https://graalvm.org) from [Bazel](https://bazel.build), with suppo
 - [Installing components with `gu`](./docs/components.md)
 - [Using GraalVM as a Bazel Java toolchain](./docs/toolchain.md)
 - [Support for Bazel 6, Bazel 7, and Bzlmod](./docs/modern-bazel.md)
-- [Support for Bazel 5 and Bazel 4, drop-in replacement for `rules_graal`](./legacy-bazel.md)
+- [Support for Bazel 4 and Bazel 5, drop-in replacement for `rules_graal`](./legacy-bazel.md)
 - [Run tools from GraalVM directly](./docs/binary-targets.md)
+- [Build native shared libraries from Java or polyglot code](./docs/shared-libraries.md)
 - [Example projects for each Bazel version](./docs/examples.md)
-- Support for macOS, Linux, Windows (including Native Image!)
+- [Hermetic compilation on all platforms](./docs/hermeticity.md)
+- [Respects conventional Bazel build settings](./docs/build-settings.md)
+- Support for macOS, Linux, Windows (including Native Image!) ([support matrix](./docs/modern-bazel.md))
 - Support for the latest modern GraalVM releases (Community Edition and Oracle GraalVM)
 
 ## Installation
@@ -243,13 +246,13 @@ If you install GraalVM at a repository named `@graalvm`, the toolchain targets a
 **Java toolchain:**
 
 ```
-@graalvm//:toolchain
+@graalvm//:jvm
 ```
 
 **GraalVM toolchain:**
 
 ```
-@graalvm//:gvm
+@graalvm//:sdk
 ```
 
 The default `WORKSPACE` and Bzlmod installation instructions register both types of toolchains.

diff --git a/docs/api/defs.md b/docs/api/defs.md
@@ -7,10 +7,11 @@ Target rule definitions, intended for use by rule users.
 ## native_image
 
 <pre>
-native_image(<a href="#native_image-name">name</a>, <a href="#native_image-deps">deps</a>, <a href="#native_image-main_class">main_class</a>, <a href="#native_image-include_resources">include_resources</a>, <a href="#native_image-reflection_configuration">reflection_configuration</a>, <a href="#native_image-jni_configuration">jni_configuration</a>,
-             <a href="#native_image-initialize_at_build_time">initialize_at_build_time</a>, <a href="#native_image-initialize_at_run_time">initialize_at_run_time</a>, <a href="#native_image-native_features">native_features</a>, <a href="#native_image-data">data</a>, <a href="#native_image-extra_args">extra_args</a>,
-             <a href="#native_image-check_toolchains">check_toolchains</a>, <a href="#native_image-static_zlib">static_zlib</a>, <a href="#native_image-c_compiler_option">c_compiler_option</a>, <a href="#native_image-executable_name">executable_name</a>, <a href="#native_image-native_image_tool">native_image_tool</a>,
-             <a href="#native_image-native_image_settings">native_image_settings</a>, <a href="#native_image-kwargs">kwargs</a>)
+native_image(<a href="#native_image-name">name</a>, <a href="#native_image-deps">deps</a>, <a href="#native_image-main_class">main_class</a>, <a href="#native_image-executable_name">executable_name</a>, <a href="#native_image-include_resources">include_resources</a>, <a href="#native_image-reflection_configuration">reflection_configuration</a>,
+             <a href="#native_image-jni_configuration">jni_configuration</a>, <a href="#native_image-initialize_at_build_time">initialize_at_build_time</a>, <a href="#native_image-initialize_at_run_time">initialize_at_run_time</a>, <a href="#native_image-native_features">native_features</a>,
+             <a href="#native_image-debug">debug</a>, <a href="#native_image-optimization_mode">optimization_mode</a>, <a href="#native_image-shared_library">shared_library</a>, <a href="#native_image-static_zlib">static_zlib</a>, <a href="#native_image-c_compiler_option">c_compiler_option</a>, <a href="#native_image-data">data</a>,
+             <a href="#native_image-extra_args">extra_args</a>, <a href="#native_image-allow_fallback">allow_fallback</a>, <a href="#native_image-check_toolchains">check_toolchains</a>, <a href="#native_image-native_image_tool">native_image_tool</a>, <a href="#native_image-native_image_settings">native_image_settings</a>,
+             <a href="#native_image-kwargs">kwargs</a>)
 </pre>
 
 Generates and compiles a GraalVM native image from a Java library target.
@@ -22,19 +23,23 @@ Generates and compiles a GraalVM native image from a Java library target.
 | :------------- | :------------- | :------------- |
 | <a id="native_image-name"></a>name |  Name of the target; required.   |  none |
 | <a id="native_image-deps"></a>deps |  Dependency `java_library` targets to assemble the classpath from. Mandatory.   |  none |
-| <a id="native_image-main_class"></a>main_class |  Entrypoint main class to build from; mandatory.   |  none |
+| <a id="native_image-main_class"></a>main_class |  Entrypoint main class to build from; mandatory unless building a shared library.   |  `None` |
+| <a id="native_image-executable_name"></a>executable_name |  Set the name of the output binary; defaults to `%target%-bin`, or `%target%-bin.exe` on Windows. The special string `%target%`, if present, is replaced with `name`.   |  `select({"@bazel_tools//src/conditions:windows": "%target%-bin.exe", "//conditions:default": "%target%-bin"})` |
 | <a id="native_image-include_resources"></a>include_resources |  Glob to pass to `IncludeResources`. No default; optional.   |  `None` |
 | <a id="native_image-reflection_configuration"></a>reflection_configuration |  Reflection configuration file. No default; optional.   |  `None` |
 | <a id="native_image-jni_configuration"></a>jni_configuration |  JNI configuration file. No default; optional.   |  `None` |
 | <a id="native_image-initialize_at_build_time"></a>initialize_at_build_time |  Classes or patterns to pass to `--initialize-at-build-time`. No default; optional.   |  `[]` |
 | <a id="native_image-initialize_at_run_time"></a>initialize_at_run_time |  Classes or patterns to pass to `--initialize-at-run-time`. No default; optional.   |  `[]` |
 | <a id="native_image-native_features"></a>native_features |  GraalVM `Feature` classes to include and apply. No default; optional.   |  `[]` |
+| <a id="native_image-debug"></a>debug |  Whether to include debug symbols; by default, this flag's state is managed by Bazel. Passing `--compilation_mode=dbg` is sufficient to flip this to `True`, or it can be overridden via this parameter.   |  `select({"@rules_graalvm//internal/conditions/compiler:debug": True, "//conditions:default": False})` |
+| <a id="native_image-optimization_mode"></a>optimization_mode |  Behaves the same as `debug`; normally, this flag's state is managed by Bazel. Passing `--compilation_mode=fastbuild\|opt\|dbg` is sufficient to set this flag, or it can be overridden via this parameter.   |  `select({"@rules_graalvm//internal/conditions/compiler:fastbuild": "b", "@rules_graalvm//internal/conditions/compiler:optimized": "2", "//conditions:default": ""})` |
+| <a id="native_image-shared_library"></a>shared_library |  Build a shared library binary instead of an executable.   |  `None` |
+| <a id="native_image-static_zlib"></a>static_zlib |  A cc_library or cc_import target that provides zlib as a static library. On Linux, this is used when Graal statically links zlib into the binary, e.g. with `-H:+StaticExecutableWithDynamicLibC`.   |  `None` |
+| <a id="native_image-c_compiler_option"></a>c_compiler_option |  Extra C compiler options to pass through `native-image`. No default; optional.   |  `[]` |
 | <a id="native_image-data"></a>data |  Data files to make available during the compilation. No default; optional.   |  `[]` |
 | <a id="native_image-extra_args"></a>extra_args |  Extra `native-image` args to pass. Last wins. No default; optional.   |  `[]` |
+| <a id="native_image-allow_fallback"></a>allow_fallback |  Whether to allow fall-back to a partial native image; defaults to `False`.   |  `False` |
 | <a id="native_image-check_toolchains"></a>check_toolchains |  Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.   |  `select({"@bazel_tools//src/conditions:windows": True, "//conditions:default": False})` |
-| <a id="native_image-static_zlib"></a>static_zlib |  A cc_library or cc_import target that provides zlib as a static library. On Linux, this is used when Graal statically links zlib into the binary, e.g. with `-H:+StaticExecutableWithDynamicLibC`.   |  `None` |
-| <a id="native_image-c_compiler_option"></a>c_compiler_option |  Extra C compiler options to pass through `native-image`. No default; optional.   |  `[]` |
-| <a id="native_image-executable_name"></a>executable_name |  Set the name of the output binary; defaults to `%target%-bin`, or `%target%-bin.exe` on Windows. The special string `%target%`, if present, is replaced with `name`.   |  `select({"@bazel_tools//src/conditions:windows": "%target%-bin.exe", "//conditions:default": "%target%-bin"})` |
 | <a id="native_image-native_image_tool"></a>native_image_tool |  Specific `native-image` executable target to use.   |  `None` |
 | <a id="native_image-native_image_settings"></a>native_image_settings |  Suite(s) of Native Image build settings to use.   |  `[Label("@rules_graalvm//internal/native_image:defaults")]` |
 | <a id="native_image-kwargs"></a>kwargs |  Extra keyword arguments are passed to the underlying `native_image` rule.   |  none |