Skip to content

Commit fccf255

Browse files
countableSetcountableSet
authored
update readme with better usage and development info (#12)
1 parent 440bfdd commit fccf255

File tree

1 file changed

+123
-78
lines changed

1 file changed

+123
-78
lines changed

‎README.md‎

Lines changed: 123 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -8,50 +8,108 @@ It supports the generation of Java based servers with the following flavours sup
88
+ [Spring Boot/Spring MVC](https://spring.io/projects/spring-boot "Spring Boot")
99
+ [Undertow](http://undertow.io/ "Undertow")
1010
+ JAX-RS ([Jersey](https://eclipse-ee4j.github.io/jersey/), [Apache CFX](http://cxf.apache.org/))
11-
+ [Jakarta EE](https://jakarta.ee/ "Jakarta")
12-
13-
## Building & Running
14-
15-
### Requirements
16-
17-
The build has been tested with [Zulu's OpenJDK](https://www.azul.com/downloads/#zulu "JDK Downloads") version 11.
18-
19-
The build uses gradle to generate the artifacts. No installation is required as the project uses the
20-
[gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html "gradle wrapper") setup.
11+
+ [Jakarta EE](https://jakarta.ee/ "Jakarta")
12+
13+
# Contents
14+
15+
<!-- Generated with https://github.com/thlorenz/doctoc -->
16+
<!-- doctoc README.md >
17+
18+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
19+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
20+
21+
- [Using](#using)
22+
- [Runtime libraries](#runtime-libraries)
23+
- [Protoc plugin](#protoc-plugin)
24+
- [via gradle](#via-gradle)
25+
- [via protoc](#via-protoc)
26+
- [Development](#development)
27+
- [Requirements](#requirements)
28+
- [Modules](#modules)
29+
- [Gradle commands](#gradle-commands)
30+
- [Remote Debug](#remote-debug)
31+
- [Guides](#guides)
32+
33+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
34+
35+
## Using
36+
37+
### Runtime libraries
38+
39+
Follow the [Working with the Gradle registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry) docs to set up authentication with GitHub packages.
40+
41+
[Published](https://github.com/orgs/github/packages?repo_name=flit) runtime libraries example Gradle setup:
42+
```groovy
43+
repositories {
44+
maven {
45+
name = 'GithubPackages'
46+
url 'https://maven.pkg.github.com/github/flit'
47+
credentials {
48+
username = project.findProperty('gpr.user') ?: System.getenv('GITHUB_ACTOR')
49+
password = project.findProperty('gpr.key') ?: System.getenv('GITHUB_TOKEN')
50+
}
51+
content {
52+
includeGroup('com.flit')
53+
}
54+
}
55+
}
2156
22-
To test you will need an installation of the [protocol buffers compiler](https://github.com/protocolbuffers/protobuf/releases "protobuf releases").
57+
dependencies {
58+
implementation("com.flit:flit-core-runtime:<version>")
59+
implementation("com.flit:flit-spring-runtime:<version>")
60+
implementation("com.flit:flit-jaxrs-runtime:<version>")
61+
implementation("com.flit:flit-jakarta-runtime:<version>")
62+
implementation("com.flit:flit-undertow-runtime:<version>")
63+
}
64+
```
2365

24-
### Modules
66+
### Protoc plugin
2567

26-
The project is split into the following modules:
27-
28-
| Module | Description |
29-
|:-------------------|:----------------------------------------------|
30-
| `plugin` | The `protoc` plugin |
31-
| `runtime:core` | Core functionality required by generated code |
32-
| `runtime:jakarta` | Runtime library for Jakarta servers |
33-
| `runtime:jaxrs` | Runtime library for JAX-RS servers |
34-
| `runtime:spring` | Runtime library for Spring MVC/Boot servers |
35-
| `runtime:undertow` | Runtime library for Undertow servers |
68+
Plugin `com.flit.flit-plugin` shadow jar can be downloaded from [here](https://github.com/github/flit/packages/1832284).
3669

70+
The flit plugin accepts the following plugin parameters:
3771

38-
### Build
72+
| Name | Required | Type | Description |
73+
|:----------|:---------:|:-------------------------------------------|:-------------------------------------------------------|
74+
| `target` | Y | `enum[server]` | The type of target to generate e.g. server, client etc |
75+
| `type` | Y | `enum[spring,undertow,boot,jakarta,jaxrs]` | Type of target to generate |
76+
| `context` | N | `string` | Base context for routing, default is `/twirp` |
77+
| `request` | N | `string` | If the request parameter should pass to the service |
3978

40-
To build the various components, run the following:
79+
#### via gradle
4180

42-
git clone git@github.com:github/flit.git
43-
cd flit
44-
./gradlew clean build
81+
The plugin can be called from the Gradle protobuf plugin via additional configuration. For example:
4582

46-
### Installation
83+
```groovy
84+
protobuf {
85+
plugins {
86+
flit {
87+
path = "${projectDir}/script/protoc-gen-flit"
88+
}
89+
}
4790
48-
Currently, the run script only supports *nix but the run script should be fairly easy to migrate to windows.
91+
generateProtoTasks {
92+
ofSourceSet('main')*.plugins {
93+
flit {
94+
option 'target=server'
95+
option 'type=spring'
96+
option 'request=Service'
97+
}
98+
}
99+
}
100+
}
101+
```
102+
```shell
103+
#!/usr/bin/env bash
49104

50-
After building:
105+
DIR=$(dirname "$0")
51106

52-
cp plugin/build/libs/plugin-all.jar /code/java-project/scripts/
107+
JAR=$(ls -c ${DIR}/plugin-*-all.jar | head -1)
108+
java ${FLIT_JAVA_OPTS} -jar $JAR $@
109+
```
110+
Where the plugin jar is located in the same directly as the script.
53111

54-
## Running
112+
#### via protoc
55113

56114
The plugin is executed as part of a protoc compilation step:
57115

@@ -61,59 +119,46 @@ The plugin is executed as part of a protoc compilation step:
61119
--flit_out=target=server,type=undertow:../java \
62120
./haberdasher.proto
63121

64-
### Options
122+
## Development
65123

66-
The flit plugin accepts the following plugin parameters:
124+
### Requirements
67125

68-
| Name | Required | Type | Description |
69-
|:----------|:---------:|:-------------------------------------------|:-------------------------------------------------------|
70-
| `target` | Y | `enum[server]` | The type of target to generate e.g. server, client etc |
71-
| `type` | Y | `enum[spring,undertow,boot,jakarta,jaxrs]` | Type of target to generate |
72-
| `context` | N | `string` | Base context for routing, default is `/twirp` |
73-
| `request` | N | `string` | If the request parameter should pass to the service |
126+
The build has been tested with [Zulu's OpenJDK](https://www.azul.com/downloads/#zulu "JDK Downloads") version 11.
74127

75-
# Development
128+
The build uses gradle to generate the artifacts. No installation is required as the project uses the
129+
[gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html "gradle wrapper") setup.
76130

77-
All development is done in Java using JDK 8 (as mentioned above).
131+
Optional: to test you will need an installation of the [protocol buffers compiler](https://github.com/protocolbuffers/protobuf/releases "protobuf releases").
78132

79-
Remote debugging can be performed as follows:
133+
### Modules
80134

81-
export FLIT_JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005,quiet=y"
82-
protoc \
83-
--proto_path=. \
84-
--java_out=../java \
85-
--flit_out=target=server,type=undertow:../java \
86-
./haberdasher.proto
87-
88-
When running with the above options, the generator will enable a remote java debug session on port 5005. This is useful
89-
for debugging a full generation step.
90-
91-
## Test Fixture Generation
92-
93-
The test resources contains a fake plugin that simply dumps the binary request to a file called `file.bin`. This utility
94-
can be used to generate test fixtures which can be fed to tests to drive plugin generation, for example:
95-
96-
$ protoc \
97-
--plugin=${PWD}/protoc-gen-dump \
98-
--dump_out=target=server,type=undertow:../java \
99-
./helloworld.proto
100-
$ mv file.bin helloworld.bin
101-
102-
This can be run from the resources directory to generate a `CodeGeneratorRequest` protobuf file, which can then be read
103-
by tests:
104-
105-
PluginProtos.CodeGeneratorRequest request = null;
106-
try (InputStream is = this.getClass().getClassLoader().getResource("helloworld.bin").openStream()) {
107-
request = PluginProtos.CodeGeneratorRequest
108-
.newBuilder()
109-
.mergeFrom(is)
110-
.build();
111-
}
135+
The project is split into the following modules:
136+
137+
| Module | Description |
138+
|:-------------------|:----------------------------------------------|
139+
| `plugin` | The `protoc` plugin |
140+
| `runtime:core` | Core functionality required by generated code |
141+
| `runtime:jakarta` | Runtime library for Jakarta servers |
142+
| `runtime:jaxrs` | Runtime library for JAX-RS servers |
143+
| `runtime:spring` | Runtime library for Spring MVC/Boot servers |
144+
| `runtime:undertow` | Runtime library for Undertow servers |
145+
146+
### Gradle commands
147+
148+
* clean `./gradlew clean`
149+
* build `./gradlew build`
150+
* test `./gradlew test`
151+
* publish `./gradlew publish`
152+
153+
### Remote Debug
154+
155+
Use remote JVM debugging by setting:
156+
157+
```shell
158+
export FLIT_JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005,quiet=y"
159+
```
112160

113-
Plugin plugin = new Plugin(request);
114-
plugin.process();
115-
116-
# Guides
161+
## Guides
117162

118163
| Platform | Document |
119164
|:----------|:--------------------------------------|

0 commit comments

Comments
 (0)