Skip to content

Commit 0caff74

Browse files
suztomosuztomo
authored
chore: refactoring README and DEVELOPMENT.md (#1351)
Thank you for opening a Pull Request! For general contributing guidelines, please refer to [contributing guide](https://github.com/googleapis/gapic-generator-java/blob/main/CONTRIBUTING.md) - The old file https://github.com/googleapis/gapic-generator-java/blob/main/gapic-generator-java/DEVELOPMENT.md was last touched in mid December. I'm replacing the content with the latest at the root. - Removing the root DEVELOPMENT.md in favor of the file above. - Adding index of the modules at the root README.md - Moving showcase testing guide to showcase/README.md.
1 parent 5ea53e5 commit 0caff74

File tree

8 files changed

+271
-418
lines changed

8 files changed

+271
-418
lines changed

‎DEVELOPMENT.md

+16-236
Original file line numberDiff line numberDiff line change
@@ -1,261 +1,41 @@
1-
# Development Workflow
1+
# Development Setup
2+
3+
You need Java 11 or higher to run the build. The build produces Java 8-compatible
4+
bytecode.
5+
6+
Install [`bazelisk`](https://github.com/bazelbuild/bazelisk) in your `PATH`
7+
for gapic-generator-java's Bazel build.
28

39
## Set Up
410

511
1. Clone this repo.
612

713
2. (OPTIONAL) Copy the Git pre-commit hooks. This will automatically check the build, run
8-
tests, and perform linting before each commit. (Symlinks don't seem to work,
9-
but if you find a way, please add it here!)
14+
tests, and perform linting before each commit. (Symlinks don't seem to work,
15+
but if you find a way, please add it here!)
1016

1117
```sh
1218
cp .githooks/pre-commit .git/hooks/pre-commit
1319
```
14-
15-
3. Install [`bazelisk`](https://github.com/bazelbuild/bazelisk) in your `PATH`.
16-
17-
## Code Formatting
18-
19-
- Run linter checks without actually doing the formatting.
2020

21-
```sh
22-
mvn fmt:check
23-
```
21+
## Run Tests for All Modules
2422

25-
- Format files.
26-
27-
```sh
28-
mvn fmt:format
29-
```
30-
31-
## Test Running
32-
33-
- Run all unit and integration tests.
34-
35-
```sh
36-
mvn install # unit tests, maven test wouldn't work in root folder because gapic-generator-java is dependant on test jars of gax-java
37-
bazel test //... # integration tests
38-
```
39-
40-
- Run all unit tests.
23+
- Run all unit tests in all modules.
4124

4225
```sh
4326
mvn install
4427
```
45-
- For running unit tests in `gapic-generator-java` submodule, first build all modules with `mvn install -DskipTests`, then `cd` into `gapic-generator-java` submodule for the following commands:
46-
- Run a single or multiple unit tests:
47-
48-
```sh
49-
mvn test -Dtest=JavaCodeGeneratorTest
50-
51-
mvn test "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]"
52-
```
53-
54-
- Update all unit test golden files:
55-
56-
```sh
57-
mvn test -DupdateUnitGoldens
58-
```
5928

60-
- Update a single unit test golden file, for example `JavaCodeGeneratorTest.java`:
61-
62-
```sh
63-
mvn test -DupdateUnitGoldens -Dtest=JavaCodeGeneratorTest
64-
```
29+
## Code Formatting
6530

66-
- Run a single integration test for API like `Redis`, it generates Java source
67-
code using the Java microgenerator and compares them with the goldens files
68-
in `test/integration/goldens/redis`.
31+
- Run linter checks without actually doing the formatting.
6932

7033
```sh
71-
bazel test //test/integration:redis
34+
mvn fmt:check
7235
```
7336

74-
- Update integration test golden files, for example `Redis`. This clobbers all the
75-
files in `test/integration/goldens/redis`.
37+
- Format files.
7638

7739
```sh
78-
bazel run //test/integration:update_redis
40+
mvn fmt:format
7941
```
80-
81-
## Showcase Integration Testing
82-
83-
[GAPIC Showcase](https://github.com/googleapis/gapic-showcase) is an API that demonstrates Generated
84-
API Client (GAPIC) features and common API patterns used by Google. It follows the [Cloud APIs
85-
design guide](https://cloud.google.com/apis/design/). `gapic-generator-java` generates a client for
86-
the Showcase API which can communicate with a local Showcase server to perform integration tests.
87-
88-
### Requirements
89-
90-
* Install [Go](https://go.dev) in your `PATH`.
91-
92-
### Installing the Server
93-
94-
Using the latest version of showcase is recommended, but backward compatibility between server
95-
versions is not guaranteed. If changing the version of the server, it may also be necessary to
96-
update to a compatible client version in `./WORKSPACE`.
97-
98-
```shell
99-
$ GAPIC_SHOWCASE_VERSION=0.25.0
100-
$ go install github.com/googleapis/gapic-showcase/cmd/gapic-showcase@v"$GAPIC_SHOWCASE_VERSION"
101-
$ PATH=$PATH:`go env GOPATH`/bin
102-
$ gapic-showcase --help
103-
> Root command of gapic-showcase
104-
>
105-
> Usage:
106-
> gapic-showcase [command]
107-
>
108-
> Available Commands:
109-
> completion Emits bash a completion for gapic-showcase
110-
> compliance This service is used to test that GAPICs...
111-
> echo This service is used showcase the four main types...
112-
> help Help about any command
113-
> identity A simple identity service.
114-
> messaging A simple messaging service that implements chat...
115-
> run Runs the showcase server
116-
> sequence Sub-command for Service: Sequence
117-
> testing A service to facilitate running discrete sets of...
118-
>
119-
> Flags:
120-
> -h, --help help for gapic-showcase
121-
> -j, --json Print JSON output
122-
> -v, --verbose Print verbose output
123-
> --version version for gapic-showcase
124-
```
125-
126-
### Running the Server
127-
128-
Run the showcase server to allow requests to be sent to it. This opens port `:7469` to send and
129-
receive requests.
130-
131-
```shell
132-
$ gapic-showcase run
133-
> 2022/11/21 16:22:15 Showcase listening on port: :7469
134-
> 2022/11/21 16:22:15 Starting endpoint 0: gRPC endpoint
135-
> 2022/11/21 16:22:15 Starting endpoint 1: HTTP/REST endpoint
136-
> 2022/11/21 16:22:15 Starting endpoint multiplexer
137-
> 2022/11/21 16:22:15 Listening for gRPC-fallback connections
138-
> 2022/11/21 16:22:15 Listening for gRPC connections
139-
> 2022/11/21 16:22:15 Listening for REST connections
140-
> 2022/11/21 16:22:15 Fallback server listening on port: :1337
141-
```
142-
143-
### Running the Integration Tests
144-
145-
Open a new terminal window in the root project directory.
146-
147-
```shell
148-
$ cd showcase
149-
$ mvn verify -P enable-integration-tests -P enable-golden-tests
150-
```
151-
152-
Note:
153-
154-
* `-P enable-golden-tests` is optional. These tests do not require a local server.
155-
156-
### Update the Golden Showcase Files
157-
158-
Open a new terminal window in the root project directory.
159-
160-
```shell
161-
$ cd showcase
162-
$ mvn compile -P update
163-
```
164-
165-
## Running the Plugin under googleapis with local gapic-generator-java
166-
167-
For running the Plugin with showcase protos and local gapic-generator-java, see above section "Showcase Integration Testing".
168-
169-
To generate a production GAPIC API:
170-
171-
1. Clone [googleapis](https://github.com/googleapis/googleapis).
172-
173-
2. Modify `googleapis/WORKSPACE` to point to local gapic-generator-java
174-
175-
Normally, googleapis's build pulls in gapic-generator-java from Maven Central.
176-
For a local run, we first need to build a local SNAPSHOT jar of the generator. Then we point googleapis to
177-
both the local SNAPSHOT jar and the local copy of the generator.
178-
179-
Replace the following section in googleapis
180-
```
181-
_gapic_generator_java_version = "2.13.0"
182-
183-
maven_install(
184-
artifacts = [
185-
"com.google.api:gapic-generator-java:" + _gapic_generator_java_version,
186-
],
187-
#Update this False for local development
188-
fail_on_missing_checksum = True,
189-
repositories = [
190-
"m2Local",
191-
"https://repo.maven.apache.org/maven2/",
192-
]
193-
)
194-
195-
http_archive(
196-
name = "gapic_generator_java",
197-
strip_prefix = "gapic-generator-java-%s" % _gapic_generator_java_version,
198-
urls = ["https://github.com/googleapis/gapic-generator-java/archive/v%s.zip" % _gapic_generator_java_version],
199-
)
200-
```
201-
202-
to
203-
204-
```
205-
_gapic_generator_java_version = "2.13.1-SNAPSHOT"
206-
207-
maven_install(
208-
artifacts = [
209-
"com.google.api:gapic-generator-java:" + _gapic_generator_java_version,
210-
],
211-
#Update this False for local development
212-
fail_on_missing_checksum = False,
213-
repositories = [
214-
"m2Local",
215-
"https://repo.maven.apache.org/maven2/",
216-
]
217-
)
218-
219-
local_repository(
220-
name = "gapic_generator_java",
221-
path = "/absolute/path/to/your/local/gapic-generator-java",
222-
)
223-
```
224-
225-
Note: At the time of writing, the gapic-generator version was `2.13.0`. Update the version to the latest version in the pom.xml
226-
227-
3. Build the new target.
228-
229-
You can generate any client library based on the protos within googleapis.
230-
You just need the name of the service within the `java_gapic_assembly_gradle_pkg`
231-
rules within the service's `BUILD.bazel` file.
232-
For instance, to run your local generator on the `speech`'s v2 service, you can
233-
run:
234-
235-
```
236-
bazel build //google/cloud/speech/v2:google-cloud-speech-v2-java
237-
```
238-
239-
Note: If you are running into bazel build issues, you can try to remove gapic-generator-java cached in your local m2
240-
Try running this command:
241-
```
242-
rm -rf ~/.m2/repository/com/google/api/
243-
```
244-
and then rebuild gapic-generator-java (`mvn clean install`).
245-
246-
## FAQ
247-
248-
### Error in workspace: workspace() got unexpected keyword argument 'managed_directories'
249-
250-
Full Error:
251-
252-
```
253-
ERROR: Traceback (most recent call last):
254-
File "/home/alicejli/googleapis/WORKSPACE", line 1, column 10, in <toplevel>
255-
workspace(
256-
Error in workspace: workspace() got unexpected keyword argument 'managed_directories'
257-
ERROR: Error computing the main repository mapping: Encountered error while reading extension file 'tools/build_defs/repo/http.bzl': no such package '@bazel_tools//tools/build_defs/repo': error loading package 'external': Could not load //external package
258-
```
259-
260-
You may be using the latest version of bazel which this project does not support yet. Try installing bazelisk to force
261-
bazel to use the version specified in `.bazeliskrc`

‎README.md

+20-4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=googleapis_gapic-generator-java&metric=coverage)](https://sonarcloud.io/summary/new_code?id=googleapis_gapic-generator-java)
2-
# API Client Generator for Java
32

4-
Generates a Java client library from protocol buffers.
5-
Replaces the Java parts of the
6-
[older monolithic generator](https://github.com/googleapis/gapic-generator).
3+
This repository consists of the following modules:
4+
5+
- **[gapic-generator-java](./gapic-generator-java/README.md)**: the Protobuf compiler plugin to generate Java code.
6+
See [gapic-generator-java/DEVELOPMENT.md] for setup.
7+
- **[gax-java](./gax-java/README.md)**: the runtime library required for Google Cloud client libraries,
8+
including the ones generated by gapic-generator-java.
9+
- **[java-common-protos](./java-common-protos/README.md)** and **[api-common-java](./api-common-java/README.md)**: Protobuf-generated common
10+
classes for Google services. (They are not generated by gapic-generator-java)
11+
- **[java-iam](./java-iam/README.md)**: Protobuf-generated classes for Google's
12+
Identity and Access
13+
Management (IAM). (They are not generated by gapic-generator-java)
14+
- **[showcase](./showcase/README.md)**: demonstration of the generated client
15+
library for the fake "Showcase" API.
16+
- **[gapic-generator-java-bom](./gapic-generator-java-bom)**: The Bill-of-Material for the libraries
17+
produced from this repository. This is used by [google-cloud-java/java-shared-dependencies](
18+
https://github.com/googleapis/google-cloud-java/blob/main/java-shared-dependencies/first-party-dependencies/pom.xml).
19+
20+
## Development Setup
21+
22+
See [DEVELOPMENT.md](DEVELOPMENT.md).

0 commit comments

Comments
 (0)