Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 363edba

Browse files
author
Adrian Todt
committed
Added gradle.properties and updated README.md
1 parent 1e8b51d commit 363edba

3 files changed

Lines changed: 102 additions & 88 deletions

File tree

‎.gitignore‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ build/
33
.#*
44
*.iml
55
.idea/
6-
test-config-override.properties
7-
gradle.properties
86

97
# Byte-compiled / optimized / DLL files
108
__pycache__/

‎README.md‎

Lines changed: 64 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,45 @@
22

33
[ ![Download](https://api.bintray.com/packages/rethinkdb/maven/rethinkdb-driver/images/download.svg) ](https://bintray.com/rethinkdb/maven/rethinkdb-driver/_latestVersion)
44

5-
This readme is for anyone who wants to dive in and hack on the Java
6-
driver. If you want to learn to use the Java driver, checkout out the
7-
documentation at [java-api-docs](http://rethinkdb.com/api/java/)
5+
This is the official [RethinkDB](https://rethinkdb.com/) client driver for Java and other JVM languages.
86

9-
## Development
7+
The driver has official docs that you can read at [the RethinkDB documentation](http://rethinkdb.com/api/java/).
8+
9+
## Building from source
10+
11+
To build from source you just need JDK 8 or greater.
12+
13+
Run `./gradlew assemble` to build the jar or `./gradlew install` to install it into your local maven repository.
14+
15+
## Contributing to the driver
1016

1117
### Installation
1218

13-
To be able to start development of the Java driver, first you must install the following:
19+
Besides JDK 8, to be able to contribute to the driver, you must also install:
1420

15-
* python3
21+
* Python *3.6* or *3.7*
22+
* PIP3 libraries:
1623
* mako
1724
* rethinkdb
18-
* gradle
19-
* Java
20-
21-
### Useful make Commands
22-
23-
You can make changes on the driver through make commands. Below
24-
you can find some useful make commands to help you managing the
25-
driver.
2625

27-
| Command | Description |
28-
| ------------------ | -------------------------------------- |
29-
| help | Print available make commands |
30-
| clean | Clean autogenerated artifacts |
31-
| java-clean | Clean Java related artifacts |
32-
| java-convert-tests | Convert Java tests |
33-
| java-driver | Assemble the Java driver |
34-
| java-test | Run tests |
35-
| prepare | Perpare the repository for development |
26+
### Using Gradle
3627

37-
## Contributing
28+
Gradle has some special tasks that help you managing the driver, such as downloading sources from the main repository.
3829

39-
Hurray, You reached this section, which means you are ready to
40-
contribute. You're probably here because you added new ReQL terms and need to update the driver. Once you've got this stuff installed and working, make appropriate changes to term_info.json and then call
41-
`make update-driver`.
30+
You can invoke any task by running `./gradlew taskName` (or `gradlew.bat` in Windows) and get a list of tasks by running `./gradlew tasks`
4231

32+
| Task | Description |
33+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
34+
| `downloadProtoAndTests` | Downloads the proto file and the YAML test files into the repository. |
35+
| `generateJsonFiles` | Using the downloaded proto file, rgenerates the required JSON files for java file generation. |
36+
| `genMainJava`* | Using all the JSON files, regenerates the files on the `com.rethinkdb.gen` package at `src/main/java` |
37+
| `genTestJava` | Using the downloaded YAML test files, regenerates the tests on the `com.rethinkdb.gen` package at `src/test/java` |
4338

44-
---
39+
[*] Currently, `genMainJava` task is disabled because the `generatedJsonFiles` python scripts are generating invalid JSON files.
4540

41+
To setup your environiment to be able to generate driver classes and test files, run the `downloadProtoAndTests` and `generateJsonFiles` tasks.
4642

47-
## Basics
43+
### Basics
4844

4945
The build process runs a python script (`metajava.py`) that
5046
automatically generates the required Java classes for reql terms. The
@@ -56,14 +52,14 @@ metajava.py creates:
5652
ql2.proto -> proto_basic.json ---+
5753
| |
5854
| v
59-
+--> term_info.json -> $BUILD_DIR/java_term_info.json
55+
+--> term_info.json -> build/java_term_info.json
6056
|
6157
v
62-
global_info.json ------------> templates/ -> $PACKAGE_DIR/gen/ast/{Term}.java
58+
global_info.json ------------> templates/ -> src/main/java/com/rethinkdb/gen/ast/{Term}.java
6359
|
64-
+---> $PACKAGE_DIR/gen/proto/{ProtocolType}.java
65-
+---> $PACKAGE_DIR/gen/model/TopLevel.java
66-
+---> $PACKAGE_DIR/gen/exc/Reql{Exception}Error.java
60+
+---> src/main/java/com/rethinkdb/gen/proto/{ProtocolType}.java
61+
+---> src/main/java/com/rethinkdb/gen/model/TopLevel.java
62+
+---> src/main/java/com/rethinkdb/gen/exc/Reql{Exception}Error.java
6763
```
6864

6965
Generally, you won't need to use metajava.py if you only want to build
@@ -76,25 +72,29 @@ If you're building the java driver without changing the template
7672
files, you can simply do:
7773

7874
```bash
79-
$ make java-driver
75+
$ ./gradlew assemble
8076
# or if you want to run tests as well
81-
$ gradle build
77+
$ ./gradlew build
8278
```
8379

84-
This will create the .jar files in `$BUILD_DIR/gradle/libs`.
80+
This will create the .jar files in `build/libs`.
8581

86-
## Testing
82+
### Testing
8783

88-
Tests are created from the polyglot yaml tests located in the rethinkdb github repository's `test/rql_test/src/` directory. To get the polyglot yaml tests run `make prepare` which will checkout the lates rethinkdb repository under `/tmp/rethinkdb/`. The `make java-convert-tests` command is used to run the test conversion, which requires python3 and the above listed python dependencies.
84+
Tests are created from the polyglot yaml tests located in the rethinkdb github repository's `test/rql_test/src/` directory.
85+
To get the polyglot yaml tests, run the Gradle task `downloadProtoAndTests`. Gradle will checkout the tests into `build/rethinkdb_gen`.
8986

90-
`make java-convert-tests` will output junit test files into `src/test/java/gen`. These are also checked into git, so you don't need to run the conversion script if you just want to verify that the existing tests pass.
87+
The `genTestJava` task is used to run the test conversion, which requires python3 and the above listed python dependencies.
88+
It will output JUnit test files into `src/test/java/com/rethinkdb/gen`, using `process_polyglot.py` and `convert_tests.py`.
89+
These are also checked into git, so you don't need to run the conversion script if you just want to verify that the existing tests pass.
9190

92-
`make java-convert-tests` makes use of `process_polyglot.py` and `convert_tests.py`. `process_polyglot.py` is intended to be independent of the java driver, and only handles reading in the polyglot tests and normalizing them into a format that's easier to use to generate new tests from. Short version: `process_polyglot.py` doesn't have the word "java" anywhere in it, while `convert_tests.py` has all of the java specific behavior in it and builds on top of the stream of test definitions that `process_polyglot.py` emits.
91+
`process_polyglot.py` is intended to be independent of the java driver, and only handles reading in the polyglot tests and normalizing them into a format that's easier to use to generate new tests from.
92+
93+
**TL;DR**: `process_polyglot.py` doesn't have the word "java" anywhere in it, while `convert_tests.py` has all of the java specific behavior in it and builds on top of the stream of test definitions that `process_polyglot.py` emits.
9394

9495
## Deploying a release or snapshot
9596

96-
To deploy you'll need to create a file called `gradle.properties` with
97-
the following format:
97+
To deploy you'll need to create a file called `gradle.properties` at `~/.gradle` (`%USERPROFILE%\.gradle` on Windows) with the following:
9898

9999
```
100100
signing.keyId=<KEY_ID>
@@ -105,51 +105,29 @@ ossrhUsername=<SONATYPE_USERNAME>
105105
ossrhPassword=<SONATYPE_PASSWORD>
106106
```
107107

108-
It goes without saying that this file should not be checked back into
109-
git, it's in the `.gitignore` file to prevent accidents. You'll need
110-
to add your gpg signing key id and keyring file. Usually the keyring
111-
file is located at `~/.gnupg/secring.gpg` but it won't expand
112-
home-dirs in the config file so you have to put the absolute path
113-
in. If you don't have a password on your private key for package
114-
signing, you must leave the `signing.password=` line in the properties
115-
file, just empty.
108+
You should note that there's a `gradle.properties` in this repository, but you shouldn't add the above into it,
109+
otherwise your credentials can be checked back into git. Create the file in the `.gradle` folder to prevent accidents.
116110

117-
If you have a gpg version >= 2.1 there is no `secring.gpg` file. If
118-
that's the case, either use a gpg 2.0 or below, or maybe newer
119-
versions of the `signing` plugin for gradle have been released and you
120-
can fix this for gpg 2.1. (PRs welcome)
111+
You'll need to add your gpg signing key id and keyring file. Usually, the keyring file is located at`~/.gnupg/secring.gpg`,
112+
but Gradle won't expand home-dirs in the config file so you have to put the absolute path to your keyring file.
113+
If you don't have a password on your private key for package signing, leave the `signing.password=` line **empty**.
121114

122-
For the sonatype username and password, you'll have to sign up on the
123-
sonatype jira website
124-
(https://issues.sonatype.org/secure/Signup!default.jspa), and you'll
125-
need to be added to the `com.rethinkdb` group (someone internal will
126-
have to do that for you).
115+
You must use gpg 2.0 or below, since gpg 2.1 and greater doesn't use the `secring.gpg` file anymore. This is a limitation
116+
on Gradle's end and there's an [issue regarding that](https://github.com/gradle/gradle/issues/888).
127117

128-
Next, you'll need to run
118+
You also neeed a Sonatype username and password, that you may get from [Sonatype's JIRA](https://issues.sonatype.org/secure/Signup!default.jspa),
119+
with access to the `com.rethinkdb` group. Some RethinkDB maintainer may already have it.
129120

130-
```bash
131-
$ gradle uploadArchives
132-
```
121+
To upload a new release, run the Gradle task `uploadArchives`. This should sign and upload the package to the release
122+
repository. This is for official releases/betas etc. If you just want to upload a snapshot, add the suffix `-SNAPSHOT`
123+
to the `version` value in `build.gradle`. The gradle maven plugin decides which repo to upload to depending on whether
124+
the version looks like `2.2` or `2.2-SNAPSHOT`, so this is important to get right or it won't go to the right place.
125+
126+
If you just want to do a snapshot: if `gradle uploadArchives` succeeds, you're done. The snapshot will be located at
127+
https://oss.sonatype.org/content/repositories/snapshots/com/rethinkdb/rethinkdb-driver/ with the version you gave it.
128+
129+
If you are doing a full release, you need to go to https://oss.sonatype.org/#stagingRepositories and search for
130+
"rethinkdb" in the search box, find the release that is in status `open`. Select it and then click the `Close` button.
131+
This will check it and make it ready for release. If that stage passes you can click the `Release` button.
133132

134-
This should sign and upload the package to the release
135-
repository. This is for official releases/betas etc. If you just want
136-
to upload a snapshot, add the suffix `-SNAPSHOT` to the `version`
137-
value in `build.gradle`. The gradle maven plugin decides which repo to
138-
upload to depending on whether the version looks like `2.2` or
139-
`2.2-SNAPSHOT`, so this is important to get right or it won't go to
140-
the right place.
141-
142-
If you just want to do a snapshot: if `gradle uploadArchives`
143-
succeeds, you're done. The snapshot will be located at
144-
https://oss.sonatype.org/content/repositories/snapshots/com/rethinkdb/rethinkdb-driver/
145-
with the version you gave it.
146-
147-
If you are doing a full release, you need to go to
148-
https://oss.sonatype.org/#stagingRepositories and search for
149-
"rethinkdb" in the search box, find the release that is in status
150-
`open`. Select it and then click the `Close` button. This will check
151-
it and make it ready for release. If that stage passes you can click
152-
the `Release` button.
153-
154-
For full instructions see:
155-
http://central.sonatype.org/pages/releasing-the-deployment.html
133+
For full instructions see: http://central.sonatype.org/pages/releasing-the-deployment.html

‎gradle.properties‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# ## RethinkDB gradle.properties
2+
# This file is used by tasks `downloadProtoAndTests`, `generateJsonFiles`, `genMainJava` and `genTestJava`.
3+
4+
# Checkout repo for git (change here to ssh checkout if you want)
5+
build.rethinkdb_repo=https://github.com/rethinkdb/rethinkdb.git
6+
7+
# The rethinkdb branch to checkout on git
8+
build.rethinkdb_branch=next
9+
10+
# Temporary checkout location
11+
build.rethinkdb_checkout_dir=/tmp/rethinkdb
12+
13+
# ql2.proto-related configurations
14+
build.proto.src_location=src/rdb_protocol
15+
build.proto.target_folder=rdb_protocol
16+
build.proto.file_name=ql2.proto
17+
18+
# polyglot yaml tests-related configurations
19+
build.tests.src_location=test/rql_test/src
20+
build.tests.target_folder=rql_test_src
21+
22+
# json files-related configurations
23+
build.gen.json.target_folder=rdb_json
24+
build.gen.json.proto_basic=proto_basic.json
25+
build.gen.json.term_info=term_info.json
26+
build.gen.json.java_term_info=java_term_info.json
27+
28+
# python scripts-related configurations
29+
build.gen.py.metajava=scripts/metajava.py
30+
build.gen.py.convert_proto=scripts/convert_protofile.py
31+
build.gen.py.convert_tests=scripts/convert_tests.py
32+
build.json.global_info=scripts/global_info.json
33+
34+
# source code generation-related configurations
35+
build.gen.src.main=src/main/java/com/rethinkdb
36+
build.gen.src.main.packages=ast,exc,model,proto
37+
build.gen.src.test=src/test/java/com/rethinkdb
38+
build.gen.src.templates=templates

0 commit comments

Comments
 (0)