diff --git a/samples/grpc-server/HELP-gradle.md b/samples/grpc-server/HELP-gradle.md new file mode 100644 index 0000000..224f1eb --- /dev/null +++ b/samples/grpc-server/HELP-gradle.md @@ -0,0 +1,71 @@ +# Getting Started + +### Reference Documentation +For further reference, please consider the following sections: + +* [Official Gradle documentation](https://docs.gradle.org) +* [Spring Boot Gradle Plugin Reference Guide](https://docs.spring.io/spring-boot/3.4.3/gradle-plugin) +* [Create an OCI image](https://docs.spring.io/spring-boot/3.4.3/gradle-plugin/packaging-oci-image.html) +* [GraalVM Native Image Support](https://docs.spring.io/spring-boot/3.4.3/reference/packaging/native-image/introducing-graalvm-native-images.html) +* [Spring gRPC [Experimental]](https://docs.spring.io/spring-grpc/reference/index.html) + +### Additional Links +These additional references should also help you: + +* [Gradle Build Scans – insights for your project's build](https://scans.gradle.com#gradle) +* [Configure AOT settings in Build Plugin](https://docs.spring.io/spring-boot/3.4.3/how-to/aot.html) +* [Various sample apps using Spring gRPC](https://github.com/spring-projects-experimental/spring-grpc/tree/main/samples) + +## GraalVM Native Support + +This project has been configured to let you generate either a lightweight container or a native executable. +It is also possible to run your tests in a native image. + +### Lightweight Container with Cloud Native Buildpacks +If you're already familiar with Spring Boot container images support, this is the easiest way to get started. +Docker should be installed and configured on your machine prior to creating the image. + +To create the image, run the following goal: + +``` +$ ./gradlew bootBuildImage +``` + +Then, you can run the app like any other container: + +``` +$ docker run --rm grpc-server:0.5.0-SNAPSHOT +``` + +### Executable with Native Build Tools +Use this option if you want to explore more options such as running your tests in a native image. +The GraalVM `native-image` compiler should be installed and configured on your machine. + +NOTE: GraalVM 22.3+ is required. + +To create the executable, run the following goal: + +``` +$ ./gradlew nativeCompile +``` + +Then, you can run the app as follows: +``` +$ build/native/nativeCompile/grpc-server +``` + +You can also run your existing tests suite in a native image. +This is an efficient way to validate the compatibility of your application. + +To run your existing tests in a native image, run the following goal: + +``` +$ ./gradlew nativeTest +``` + +### Gradle Toolchain support + +There are some limitations regarding Native Build Tools and Gradle toolchains. +Native Build Tools disable toolchain support by default. +Effectively, native image compilation is done with the JDK used to execute Gradle. +You can read more about [toolchain support in the Native Build Tools here](https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html#configuration-toolchains). diff --git a/samples/grpc-server/HELP-maven.md b/samples/grpc-server/HELP-maven.md new file mode 100644 index 0000000..6bee451 --- /dev/null +++ b/samples/grpc-server/HELP-maven.md @@ -0,0 +1,71 @@ +# Getting Started + +### Reference Documentation +For further reference, please consider the following sections: + +* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html) +* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/3.4.3/maven-plugin) +* [Create an OCI image](https://docs.spring.io/spring-boot/3.4.3/maven-plugin/build-image.html) +* [GraalVM Native Image Support](https://docs.spring.io/spring-boot/3.4.3/reference/packaging/native-image/introducing-graalvm-native-images.html) +* [Spring gRPC [Experimental]](https://docs.spring.io/spring-grpc/reference/index.html) + +### Additional Links +These additional references should also help you: + +* [Configure AOT settings in Build Plugin](https://docs.spring.io/spring-boot/3.4.3/how-to/aot.html) +* [Various sample apps using Spring gRPC](https://github.com/spring-projects-experimental/spring-grpc/tree/main/samples) + +## GraalVM Native Support + +This project has been configured to let you generate either a lightweight container or a native executable. +It is also possible to run your tests in a native image. + +### Lightweight Container with Cloud Native Buildpacks +If you're already familiar with Spring Boot container images support, this is the easiest way to get started. +Docker should be installed and configured on your machine prior to creating the image. + +To create the image, run the following goal: + +``` +$ ./mvnw spring-boot:build-image -Pnative +``` + +Then, you can run the app like any other container: + +``` +$ docker run --rm grpc-server-sample:0.5.0-SNAPSHOT +``` + +### Executable with Native Build Tools +Use this option if you want to explore more options such as running your tests in a native image. +The GraalVM `native-image` compiler should be installed and configured on your machine. + +NOTE: GraalVM 22.3+ is required. + +To create the executable, run the following goal: + +``` +$ ./mvnw native:compile -Pnative +``` + +Then, you can run the app as follows: +``` +$ target/grpc-server-sample +``` + +You can also run your existing tests suite in a native image. +This is an efficient way to validate the compatibility of your application. + +To run your existing tests in a native image, run the following goal: + +``` +$ ./mvnw test -PnativeTest +``` + + +### Maven Parent overrides + +Due to Maven's design, elements are inherited from the parent POM to the project POM. +While most of the inheritance is fine, it also inherits unwanted elements like `` and `` from the parent. +To prevent this, the project POM contains empty overrides for these elements. +If you manually switch to a different parent and actually want the inheritance, you need to remove those overrides. diff --git a/samples/grpc-server/README.md b/samples/grpc-server/README.md index 975f063..78548e7 100644 --- a/samples/grpc-server/README.md +++ b/samples/grpc-server/README.md @@ -12,7 +12,6 @@ $ ./mvnw spring-boot:run ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v3.0.0) - 2022-12-08T05:32:24.934-08:00 INFO 551632 --- [ main] com.example.demo.DemoApplication : Starting DemoApplication using Java 17.0.5 with PID 551632 (/home/dsyer/dev/scratch/demo/target/classes started by dsyer in /home/dsyer/dev/scratch/demo) 2022-12-08T05:32:24.938-08:00 INFO 551632 --- [ main] com.example.demo.DemoApplication : No active profile set, falling back to 1 default profile: "default" 2022-12-08T05:32:25.377-08:00 WARN 551632 --- [ main] ocalVariableTableParameterNameDiscoverer : Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection: net.devh.boot.grpc.server.autoconfigure.GrpcHealthServiceAutoConfiguration @@ -36,26 +35,6 @@ $ grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello ``` ## Native Image +[Native Image with Gradle](./HELP-gradle.md) -The app compiles to a native image if the JVM is GraalVM: - -``` -$ ./mvnw -Pnative native:compile -$ ./target/demo - . ____ _ __ _ _ - /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ -( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ - \\/ ___)| |_)| | | | | || (_| | ) ) ) ) - ' |____| .__|_| |_|_| |_\__, | / / / / - =========|_|==============|___/=/_/_/_/ - :: Spring Boot :: (v3.0.0) - -2022-12-08T05:36:54.365-08:00 INFO 554359 --- [ main] com.example.demo.DemoApplication : Starting AOT-processed DemoApplication using Java 17.0.5 with PID 554359 (/home/dsyer/dev/scratch/demo/target/demo started by dsyer in /home/dsyer/dev/scratch/demo) -2022-12-08T05:36:54.366-08:00 INFO 554359 --- [ main] com.example.demo.DemoApplication : No active profile set, falling back to 1 default profile: "default" -2022-12-08T05:36:54.377-08:00 INFO 554359 --- [ main] g.s.a.GrpcServerFactoryAutoConfiguration : Detected grpc-netty: Creating NettyGrpcServerFactory -2022-12-08T05:36:54.392-08:00 INFO 554359 --- [ main] n.d.b.g.s.s.AbstractGrpcServerFactory : Registered gRPC service: Simple, bean: grpcServerService, class: com.example.demo.GrpcServerService -2022-12-08T05:36:54.392-08:00 INFO 554359 --- [ main] n.d.b.g.s.s.AbstractGrpcServerFactory : Registered gRPC service: grpc.health.v1.Health, bean: grpcHealthService, class: io.grpc.protobuf.services.HealthServiceImpl -2022-12-08T05:36:54.392-08:00 INFO 554359 --- [ main] n.d.b.g.s.s.AbstractGrpcServerFactory : Registered gRPC service: grpc.reflection.v1alpha.ServerReflection, bean: protoReflectionService, class: io.grpc.protobuf.services.ProtoReflectionService -2022-12-08T05:36:54.396-08:00 INFO 554359 --- [ main] n.d.b.g.s.s.GrpcServerLifecycle : gRPC Server started, listening on address: *, port: 9090 -2022-12-08T05:36:54.396-08:00 INFO 554359 --- [ main] com.example.demo.DemoApplication : Started DemoApplication in 0.046 seconds (process running for 0.052) -``` +[Native Image with Maven](./HELP-maven.md) \ No newline at end of file