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 <sam@elide.ventures>

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.

docs/build-settings.md

@@ -0,0 +1,18 @@
+## How Bazel settings integrate with Native Image
+
+Several familiar Bazel settings are integrated into the Native Image build pipeline, so that conventional use of Bazel
+features translates relatively well to Native Image option control. See the table below for more information.
+
+### Compilation mode
+
+> Flag: [`--compilation_mode`][1] or [`-c`][1]
+
+| **Flag setting** | **Effective `native-image` options** | **Notes** |
+| ---------------- | ------------------------------------ | ------------------------------------------ |
+| `dbg` | `-g` | No optimization flag set |
+| `fastbuild` | `-Ob` | Activates GraalVM [fast build][2] mode |
+| `opt` | `-O2` | Builds with optimizations turned on |
+| (None set) | (Nothing passed) | Default GraalVM behavior builds with `-O2` |
+
+[1]: https://bazel.build/docs/user-manual#compilation-mode
+[2]: https://www.graalvm.org/latest/reference-manual/native-image/overview/BuildOutput/#build-stages

docs/index.md

@@ -18,10 +18,13 @@ Use [GraalVM](https://graalvm.org) from [Bazel](https://bazel.build), with suppo
 - [Installing components with `gu`](./components.md)
 - [Using GraalVM as a Bazel Java toolchain](./toolchain.md)
 - [Support for Bazel 6, Bazel 7, and Bzlmod](./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 GraalVM binaries directly](./binary-targets.md)
+- [Build native shared libraries from Java or polyglot code](./shared-libraries.md)
 - [Example projects for each Bazel version](./examples.md)
-- Support for macOS, Linux, Windows (including Native Image!)
+- [Hermetic compilation on all platforms](./hermeticity.md)
+- [Respects conventional Bazel build settings](./build-settings.md)
+- Support for macOS, Linux, Windows (including Native Image!) ([support matrix](./modern-bazel.md))
 - Support for the latest modern GraalVM releases (Community Edition and Oracle GraalVM)
 
 ## Installation
@@ -215,7 +218,7 @@ make sure to add the `native_image_tool` attribute to point to `@yourrepo//:nati
 
 ## Examples
 
-See the list of [examples](./docs/examples.md), which are used as continuous integration tests. Examples are available
+See the list of [examples](./examples.md), which are used as continuous integration tests. Examples are available
 for Bazel 4-7.
 
 ## Hermeticity / strictness
@@ -241,13 +244,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.

docs/shared-libraries.md

@@ -0,0 +1,34 @@
+## Shared libraries with GraalVM and Bazel
+
+GraalVM can build [native shared libraries][1] from Java or polyglot code. This functionality is integrated with these
+rules, via the `shared_library` target attribute on `native_image`:
+
+```python
+load("@rules_graalvm//:defs.bzl", "native_image")
+```
+
+```python
+java_library(
+ name = "example",
+ srcs = ["..."],
+)
+
+native_image(
+ name = "some_name",
+ shared_library = True,
+ deps = [
+ ":example",
+ ],
+)
+```
+
+### How `main_class` works with shared libraries
+
+Even when building a shared library, GraalVM typically needs a `main_class`. Instead of becoming a runnable entrypoint,
+the `main_class` is used by the Native Image compiler as the starting point for points-to analysis and code gen.
+
+Alternatively, the [`@CEntryPoint` API][2] can be used to define library entrypoints. See [here][3] for more information.
+
+[1]: https://www.graalvm.org/latest/reference-manual/native-image/guides/build-native-shared-library/
+[2]: https://www.graalvm.org/sdk/javadoc/org/graalvm/nativeimage/c/function/CEntryPoint.html
+[3]: https://www.graalvm.org/latest/reference-manual/native-image/guides/build-native-shared-library/

graal/graal.bzl

@@ -6,6 +6,8 @@ load(
 )
 load(
  "//internal/native_image:classic.bzl",
+ _DEBUG_CONDITION = "DEBUG_CONDITION",
+ _OPTIMIZATION_MODE_CONDITION = "DEBUG_CONDITION",
  _BAZEL_CPP_TOOLCHAIN_TYPE = "BAZEL_CPP_TOOLCHAIN_TYPE",
  _BAZEL_CURRENT_CPP_TOOLCHAIN = "BAZEL_CURRENT_CPP_TOOLCHAIN",
  _DEFAULT_GVM_REPO = "DEFAULT_GVM_REPO",
@@ -15,6 +17,10 @@ load(
 
 _DEFAULT_NATIVE_IMAGE_TOOL = Label("%s//:native-image" % _DEFAULT_GVM_REPO)
 
+_DEBUG = select(_DEBUG_CONDITION)
+
+_OPTIMIZATION_MODE = select(_OPTIMIZATION_MODE_CONDITION)
+
 _native_image = rule(
  implementation = _graal_binary_implementation,
  attrs = dicts.add(_NATIVE_IMAGE_ATTRS, **{
@@ -42,48 +48,59 @@ _native_image = rule(
 def native_image(
  name,
  deps,
- main_class,
+ main_class = None,
+ executable_name = select({
+ "@bazel_tools//src/conditions:windows": "%target%-bin.exe",
+ "//conditions:default": "%target%-bin",
+ }),
  include_resources = None,
  reflection_configuration = None,
  jni_configuration = None,
  initialize_at_build_time = [],
  initialize_at_run_time = [],
  native_features = [],
+ debug = _DEBUG,
+ optimization_mode = _OPTIMIZATION_MODE,
+ shared_library = False,
+ static_zlib = None,
+ c_compiler_option = [],
  data = [],
  extra_args = [],
+ allow_fallback = False,
  check_toolchains = select({
  "@bazel_tools//src/conditions:windows": True,
  "//conditions:default": False,
  }),
- c_compiler_option = [],
- static_zlib = None,
- executable_name = select({
- "@bazel_tools//src/conditions:windows": "%target%-bin.exe",
- "//conditions:default": "%target%-bin",
- }),
  native_image_tool = _DEFAULT_NATIVE_IMAGE_TOOL,
  **kwargs):
  """Generates and compiles a GraalVM native image from a Java library target.
 
  Args:
  name: Name of the target; required.
  deps: Dependency `java_library` targets to assemble the classpath from. Mandatory.
- main_class: Entrypoint main class to build from; mandatory.
+ main_class: Entrypoint main class to build from; mandatory unless building a shared library.
+ 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`.
  include_resources: Glob to pass to `IncludeResources`. No default; optional.
  reflection_configuration: Reflection configuration file. No default; optional.
  jni_configuration: JNI configuration file. No default; optional.
  initialize_at_build_time: Classes or patterns to pass to `--initialize-at-build-time`. No default; optional.
  initialize_at_run_time: Classes or patterns to pass to `--initialize-at-run-time`. No default; optional.
  native_features: GraalVM `Feature` classes to include and apply. No default; optional.
- data: Data files to make available during the compilation. No default; optional.
- extra_args: Extra `native-image` args to pass. Last wins. No default; optional.
- check_toolchains: Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.
- c_compiler_option: Extra C compiler options to pass through `native-image`. No default; optional.
+ 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.
+ 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.
+ shared_library: Build a shared library binary instead of an executable.
  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`.
- 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`.
+ c_compiler_option: Extra C compiler options to pass through `native-image`. No default; optional.
+ data: Data files to make available during the compilation. No default; optional.
+ extra_args: Extra `native-image` args to pass. Last wins. No default; optional.
+ allow_fallback: Whether to allow fall-back to a partial native image; defaults to `False`.
+ check_toolchains: Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.
  native_image_tool: Specific `native-image` executable target to use.
  **kwargs: Extra keyword arguments are passed to the underlying `native_image` rule.
  """
@@ -98,11 +115,15 @@ def native_image(
  initialize_at_build_time = initialize_at_build_time,
  initialize_at_run_time = initialize_at_run_time,
  native_features = native_features,
+ debug = debug,
+ optimization_mode = optimization_mode,
+ shared_library = shared_library,
  data = data,
  extra_args = extra_args,
  check_toolchains = check_toolchains,
  static_zlib = static_zlib,
  c_compiler_option = c_compiler_option,
+ allow_fallback = allow_fallback,
  executable_name = executable_name,
  native_image_tool = native_image_tool,
  **kwargs
@@ -111,48 +132,59 @@ def native_image(
 def graal_binary(
  name,
  deps,
- main_class,
+ main_class = None,
+ executable_name = select({
+ "@bazel_tools//src/conditions:windows": "%target%-bin.exe",
+ "//conditions:default": "%target%-bin",
+ }),
  include_resources = None,
  reflection_configuration = None,
  jni_configuration = None,
  initialize_at_build_time = [],
  initialize_at_run_time = [],
  native_features = [],
+ debug = _DEBUG,
+ optimization_mode = _OPTIMIZATION_MODE,
+ shared_library = False,
+ static_zlib = None,
+ c_compiler_option = [],
  data = [],
  extra_args = [],
+ allow_fallback = False,
  check_toolchains = select({
  "@bazel_tools//src/conditions:windows": True,
  "//conditions:default": False,
  }),
- c_compiler_option = [],
- static_zlib = None,
- executable_name = select({
- "@bazel_tools//src/conditions:windows": "%target%-bin.exe",
- "//conditions:default": "%target%-bin",
- }),
  native_image_tool = _DEFAULT_NATIVE_IMAGE_TOOL,
  **kwargs):
  """Alias for the renamed `native_image` rule. Identical.
 
  Args:
  name: Name of the target; required.
  deps: Dependency `java_library` targets to assemble the classpath from. Mandatory.
- main_class: Entrypoint main class to build from; mandatory.
+ main_class: Entrypoint main class to build from; mandatory unless building a shared library.
+ 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`.
  include_resources: Glob to pass to `IncludeResources`. No default; optional.
  reflection_configuration: Reflection configuration file. No default; optional.
  jni_configuration: JNI configuration file. No default; optional.
  initialize_at_build_time: Classes or patterns to pass to `--initialize-at-build-time`. No default; optional.
  initialize_at_run_time: Classes or patterns to pass to `--initialize-at-run-time`. No default; optional.
  native_features: GraalVM `Feature` classes to include and apply. No default; optional.
- data: Data files to make available during the compilation. No default; optional.
- extra_args: Extra `native-image` args to pass. Last wins. No default; optional.
- check_toolchains: Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.
+ 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.
+ 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.
+ shared_library: Build a shared library binary instead of an executable.
  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`.
  c_compiler_option: Extra C compiler options to pass through `native-image`. No default; optional.
- 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`.
+ data: Data files to make available during the compilation. No default; optional.
+ extra_args: Extra `native-image` args to pass. Last wins. No default; optional.
+ allow_fallback: Whether to allow fall-back to a partial native image; defaults to `False`.
+ check_toolchains: Whether to perform toolchain checks in `native-image`; defaults to `True` on Windows, `False` otherwise.
  native_image_tool: Specific `native-image` executable target to use.
  **kwargs: Extra keyword arguments are passed to the underlying `native_image` rule.
  """
@@ -167,6 +199,9 @@ def graal_binary(
  initialize_at_build_time = initialize_at_build_time,
  initialize_at_run_time = initialize_at_run_time,
  native_features = native_features,
+ debug = debug,
+ optimization_mode = optimization_mode,
+ shared_library = shared_library,
  data = data,
  extra_args = extra_args,
  static_zlib = static_zlib,