diff --git a/build/gradle-plugin/setup.mdx b/build/gradle-plugin/setup.mdx index fcd02ea..6fd25e3 100644 --- a/build/gradle-plugin/setup.mdx +++ b/build/gradle-plugin/setup.mdx @@ -9,6 +9,21 @@ The `gg.grounds.push` Gradle plugin is what actually uploads your JAR to forge. `gg.grounds.push` is **separate** from the convention-plugin bundle (`gg.grounds.paper-conventions`, `gg.grounds.kotlin-conventions`, …). The conventions plugins shape your build; `push` ships its output. You almost certainly want both. +## Convention plugins + +Grounds plugin repositories use convention plugins from `library-gradle-plugin` to shape JVM plugin artifacts: + +- `gg.grounds.paper-conventions` +- `gg.grounds.velocity-conventions` +- `gg.grounds.paper-standalone-conventions` +- `gg.grounds.paper-runtime-consumer-conventions` +- `gg.grounds.paper-runtime-provider-conventions` +- `gg.grounds.velocity-standalone-conventions` +- `gg.grounds.velocity-runtime-consumer-conventions` +- `gg.grounds.velocity-runtime-provider-conventions` + +Runtime-consumer conventions are for internal Paper and Velocity plugins that run with [`plugin-grounds-runtime`](/reference/development/gradle-plugin/runtime-libraries). Standalone conventions are for plugins that must carry their own runtime libraries. + ## Prerequisites - A GitHub personal access token with `read:packages` scope (the plugin lives on GitHub Packages). diff --git a/build/troubleshooting.mdx b/build/troubleshooting.mdx index af86dd5..1da8a12 100644 --- a/build/troubleshooting.mdx +++ b/build/troubleshooting.mdx @@ -61,6 +61,18 @@ resources: Local mode only runs Paper and Velocity. Use `grounds push --target=dev` for `minestom` / `service` workloads. +### Runtime consumer starts without `plugin-grounds-runtime` + +Runtime-consumer artifacts do not have a standalone fallback. Install the matching `plugin-grounds-runtime` Paper or Velocity plugin in local, dev, test, and production environments. + +Use `/grounds-runtime` to confirm the runtime plugin is loaded and to inspect the runtime version, platform, manifest source, and provided libraries. + +### Runtime consumer bundles shared libraries + +Runtime-consumer builds fail when the final shadow JAR includes shared runtime packages such as `io/grpc`, `com/google/protobuf`, `kotlinx/coroutines`, or `kotlin`. + +Remove those libraries from `implementation` and rely on the runtime-consumer compile-only baseline. Keep plugin-private dependencies, such as NATS or Jackson, as `implementation`. If tests need a shared runtime library on the test runtime classpath, add it to `testImplementation`. + ### `unknown baseImage` Your manifest references a base image source key that Forge does not know, or that is not allowed for the selected `type`. diff --git a/docs.json b/docs.json index 04e0b38..76ea2bc 100644 --- a/docs.json +++ b/docs.json @@ -160,7 +160,8 @@ "group": "Convention plugins", "pages": [ "reference/development/gradle-plugin/index", - "reference/development/gradle-plugin/usage" + "reference/development/gradle-plugin/usage", + "reference/development/gradle-plugin/runtime-libraries" ] }, { diff --git a/reference/development/gradle-plugin/runtime-libraries.mdx b/reference/development/gradle-plugin/runtime-libraries.mdx new file mode 100644 index 0000000..f35392a --- /dev/null +++ b/reference/development/gradle-plugin/runtime-libraries.mdx @@ -0,0 +1,82 @@ +--- +title: "Runtime libraries" +description: "Share selected JVM libraries through plugin-grounds-runtime for Paper and Velocity plugins." +--- + +`plugin-grounds-runtime` is an internal Paper and Velocity plugin that provides selected shared JVM libraries to Grounds plugins at runtime. + +Runtime-consumer conventions automatically add baseline shared runtime libraries to the compile-only classpath. Plugin modules should not declare those libraries as implementation dependencies and must not bundle them in their shadow JARs. + +## When to use runtime consumers + +Use runtime-consumer conventions for internal Paper and Velocity plugins that run on Grounds base images and can require `plugin-grounds-runtime` in local, dev, test, and production environments. + +Use standalone conventions when a plugin must run without `plugin-grounds-runtime`. + +## Provided libraries + +- Kotlin standard library family +- Kotlin coroutines +- protobuf-java +- gRPC baseline modules + +## Updating runtime libraries + +Update shared runtime libraries in `plugin-grounds-runtime`. That repository owns the runtime platform: + +- Paper and Velocity runtime plugin artifacts +- `grounds-runtime-bom`, which pins the shared library versions +- `grounds-runtime-catalog`, which is used by base images to generate `/opt/grounds/runtime-manifest.json` + +Runtime-consumer Gradle conventions depend on `grounds-runtime-bom` through `groundsRuntime.runtimeVersion` or the `groundsRuntime.version` Gradle property. They keep shared libraries on the compile-only classpath without declaring versions in each plugin. + +When a bundled runtime library changes, release `plugin-grounds-runtime` first. Then bump `groundsRuntime.version` in consumer builds and `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers` to the same released version. Do not duplicate shared library versions in Dockerfiles or consumer plugin builds. + +## Adding a shared dependency + +Add a dependency to the shared runtime only when it is common runtime surface for multiple internal Paper or Velocity plugins. Keep plugin-private clients, app-specific libraries, and test-only libraries in the consumer plugin build. + +1. Add or update the dependency in `plugin-grounds-runtime` under `runtime-catalog/grounds-runtime-libraries.json`. +2. If the dependency exposes packages that can conflict with server or plugin classpaths, update the runtime relocation policy and consumer shadow exclusions. +3. If this is a version-only update, release `plugin-grounds-runtime` and bump consumer `groundsRuntime.version`. +4. If this adds or removes a module, also update `library-gradle-plugin` so the runtime-consumer conventions add the versionless dependency and validate the correct package prefixes. +5. Release `plugin-grounds-runtime` before `library-gradle-plugin`, consumer plugins, and `containers`. + +The split is intentional: + +- `plugin-grounds-runtime` owns versions through `grounds-runtime-bom`. +- `library-gradle-plugin` owns build policy: which modules are added, what gets relocated, and what must not be bundled by runtime consumers. +- `containers` owns installation of the released runtime plugin and matching catalog. + +## Not provided + +- Paper API +- Velocity API +- Minestom +- Plugin-specific clients such as NATS +- Jackson and other private implementation dependencies + +## Gradle convention IDs + +- `gg.grounds.paper-standalone-conventions` +- `gg.grounds.paper-runtime-consumer-conventions` +- `gg.grounds.paper-runtime-provider-conventions` +- `gg.grounds.velocity-standalone-conventions` +- `gg.grounds.velocity-runtime-consumer-conventions` +- `gg.grounds.velocity-runtime-provider-conventions` + +## Migrating a plugin + +1. Switch Paper or Velocity modules to runtime-consumer conventions. +2. Remove shared runtime libraries from `implementation`. +3. Keep plugin-private dependencies as `implementation`. +4. Keep test-only runtime requirements in `testImplementation`. +5. Add the loader dependency on `plugin-grounds-runtime`. +6. Build and inspect the final shadow JAR. +7. Run the plugin locally with the matching runtime plugin installed. + +## Debugging + +Run `/grounds-runtime` in Paper or Velocity to inspect the installed runtime version, platform, manifest source, and provided libraries. + +Runtime-consumer artifacts do not have a standalone fallback. Local, dev, test, and production environments must install the matching `plugin-grounds-runtime` plugin.