THRIFT-5570: update java lib document about gradle usage (#2583)
* update java doc about gradle usage
* update .gitignore
diff --git a/.gitignore b/.gitignore
index d47c225..7b068e4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -229,6 +229,13 @@
/lib/js/dist
/lib/js/doc
/lib/js/test/build
+/lib/kotlin/cross-test-client/build/
+/lib/kotlin/cross-test-server/build/
+/lib/kotlin/build/
+/lib/kotlin/.gradle/
+/lib/kotlin/gradle/
+/lib/kotlin/gradlew
+/lib/kotlin/gradlew.bat
/lib/netstd/**/bin
/lib/netstd/**/obj
/lib/nodejs/coverage
diff --git a/build/cmake/FindGradle.cmake b/build/cmake/FindGradle.cmake
index 8845d69..3806bd8 100644
--- a/build/cmake/FindGradle.cmake
+++ b/build/cmake/FindGradle.cmake
@@ -21,7 +21,7 @@
# GRADLE_FOUND - system has Gradle
# GRADLE_EXECUTABLE - the Gradle executable
#
-# It will search the environment variable ANT_HOME if it is set
+# It will search the environment variable GRADLE_HOME if it is set
include(FindPackageHandleStandardArgs)
diff --git a/doc/install/debian.md b/doc/install/debian.md
index f1edce5..9be7265 100644
--- a/doc/install/debian.md
+++ b/doc/install/debian.md
@@ -18,7 +18,7 @@
If you would like to build Apache Thrift libraries for other programming languages you may need to install additional packages. The following languages require the specified additional packages:
* Java
- * packages: gradle
+ * packages: gradle (version 6.9.2)
* You will also need Java JDK v1.8 or higher. Type **javac** to see a list of available packages, pick the one you prefer and **apt-get install** it (e.g. default-jdk).
* Ruby
* ruby-full ruby-dev ruby-rspec rake rubygems bundler
@@ -51,7 +51,7 @@
* dart & pub
* https://www.dartlang.org/install/linux
* https://www.dartlang.org/tools/pub/installing
-
+
## Additional reading
diff --git a/lib/java/Makefile.am b/lib/java/Makefile.am
index 42514f4..1e1ee9b 100644
--- a/lib/java/Makefile.am
+++ b/lib/java/Makefile.am
@@ -20,13 +20,13 @@
export CLASSPATH
all-local:
- gradle $(GRADLE_OPTS) assemble \
+ $(GRADLE) $(GRADLE_OPTS) assemble \
-Prelease=true \
-Pthrift.version=$(PACKAGE_VERSION) \
--console=plain
install-exec-hook:
- gradle $(GRADLE_OPTS) install \
+ $(GRADLE) $(GRADLE_OPTS) install \
-Prelease=true \
-Pinstall.path=$(DESTDIR)$(JAVA_PREFIX) \
-Pinstall.javadoc.path=$(DESTDIR)$(docdir)/java \
@@ -34,24 +34,24 @@
--console=plain
clean-local:
- gradle $(GRADLE_OPTS) clean --console=plain
+ $(GRADLE) $(GRADLE_OPTS) clean --console=plain
precross: $(THRIFT)
- gradle $(GRADLE_OPTS) shadowJar \
+ $(GRADLE) $(GRADLE_OPTS) shadowJar \
-Prelease=true \
-Pthrift.version=$(PACKAGE_VERSION) \
-Pthrift.compiler=$(THRIFT) \
--console=plain
check-local: $(THRIFT)
- gradle $(GRADLE_OPTS) test \
+ $(GRADLE) $(GRADLE_OPTS) test \
-Prelease=true \
-Pthrift.version=$(PACKAGE_VERSION) \
-Pthrift.compiler=$(THRIFT) \
--console=plain
maven-publish:
- gradle $(GRADLE_OPTS) uploadArchives \
+ $(GRADLE) $(GRADLE_OPTS) uploadArchives \
-Prelease=true \
-Pthrift.version=$(PACKAGE_VERSION) \
--console=plain
diff --git a/lib/java/README.md b/lib/java/README.md
index f18f7dd..214ac90 100644
--- a/lib/java/README.md
+++ b/lib/java/README.md
@@ -42,11 +42,41 @@
the Gradle build system, which tends to be predominant amongst Java
developers.
+Currently we use gradle 6.9.2 to build the Thrift Java source. The usual way to setup gradle
+project is to include the gradle-wrapper.jar in the project and then run the gradle wrapper to
+bootstrap setting up gradle binaries. However to avoid putting binary files into the source tree we
+have ignored the gradle wrapper files. You are expected to install it manually, as described in
+the [gradle documentation](https://docs.gradle.org/current/userguide/installation.html), or
+following this step (which is also done in the travis CI docker images):
+
+```bash
+export GRADLE_VERSION="6.9.2"
+# install dependencies
+apt-get install -y --no-install-recommends openjdk-11-jdk-headless wget unzip
+# download gradle distribution
+wget https://services.gradle.org/distributions/gradle-$GRADLE_VERSION-bin.zip -q -O /tmp/gradle-$GRADLE_VERSION-bin.zip
+# check binary integrity
+echo "8b356fd8702d5ffa2e066ed0be45a023a779bba4dd1a68fd11bc2a6bdc981e8f /tmp/gradle-$GRADLE_VERSION-bin.zip" | sha256sum -c -
+# unzip and install
+unzip -d /tmp /tmp/gradle-$GRADLE_VERSION-bin.zip
+mv /tmp/gradle-$GRADLE_VERSION /usr/local/gradle
+ln -s /usr/local/gradle/bin/gradle /usr/local/bin
+```
+
+After the above step, `gradle` binary will be available in `/usr/local/bin/`. You can further choose
+to locally create the gradle wrapper (even if they are ignored) using:
+
+```bash
+gradle wrapper --gradle-version $GRADLE_VERSION
+```
+
To compile the Java Thrift libraries, simply do the following:
- gradle
+```bash
+gradle
+```
-Yep, that's easy. Look for libthrift-<version>.jar in the build/libs directory.
+Yep, that's easy. Look for `libthrift-<version>.jar` in the build/libs directory.
The default build will run the unit tests which expect a usable
Thrift compiler to exist on the system. You have two choices for
@@ -65,12 +95,16 @@
To just build the library without running unit tests you simply do this.
- gradle assemble
+```bash
+gradle assemble
+```
To install the library in the local Maven repository location
where other Maven or Gradle builds can reference it simply do this.
- gradle install
+```bash
+gradle install
+```
The library will be placed in your home directory under .m2/repository
@@ -80,12 +114,16 @@
Build Thrift behind a proxy:
- gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
+
+```bash
+gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
+```
or via
- ./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
-
+```bash
+./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
+```
Unit Test HTML Reports
======================
@@ -107,8 +145,9 @@
The following command will build, unit test, and generate Clover reports:
- gradle -PcloverEnabled=true
-
+```bash
+gradle -PcloverEnabled=true
+```
Publishing Maven Artifacts to Maven Central
===========================================
@@ -119,8 +158,10 @@
The same applies to the CMake build, the value from the configure.ac file will
be used if you execute these commands:
- make maven-publish -- This is for an Automake Linux build
- make MavenPublish -- This is for a CMake generated build
+```bash
+make maven-publish -- This is for an Automake Linux build
+make MavenPublish -- This is for a CMake generated build
+```
The uploadArchives task in Gradle is preconfigured with all necessary details
to sign and publish the artifacts from the build to the Apache Maven staging
@@ -129,14 +170,16 @@
is to create or edit the ~/.gradle/gradle.properties file and add the following
properties to it.
- # Signing key information for artifacts PGP signature (values are examples)
- signing.keyId=24875D73
- signing.password=secret
- signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
+```properties
+# Signing key information for artifacts PGP signature (values are examples)
+signing.keyId=24875D73
+signing.password=secret
+signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
- # Apache Maven staging repository user credentials
- mavenUser=meMyselfAndI
- mavenPassword=MySuperAwesomeSecretPassword
+# Apache Maven staging repository user credentials
+mavenUser=meMyselfAndI
+mavenPassword=MySuperAwesomeSecretPassword
+```
NOTE: If you do not have a secring.gpg file, see the
[gradle signing docs](https://docs.gradle.org/current/userguide/signing_plugin.html)
@@ -146,18 +189,24 @@
With the key information and credentials in place the following will generate
if needed the build artifacts and proceed to publish the results.
- gradle -Prelease=true uploadArchives
+```bash
+gradle -Prelease=true uploadArchives
+```
It is also possible to override the target repository for the Maven Publication
by using a Gradle property, for example you can publish signed JAR files to your
company internal server if you add this to the command line or in the
~/.gradle/gradle.properties file. The URL below assumes a Nexus Repository.
- maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
+```properties
+maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
+```
Or the same on the command line:
- gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
+```bash
+gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
+```
Dependencies
diff --git a/lib/kotlin/.gitignore b/lib/kotlin/.gitignore
deleted file mode 100644
index 7d5c789..0000000
--- a/lib/kotlin/.gitignore
+++ /dev/null
@@ -1,78 +0,0 @@
-#
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-#
-
-# Created by https://www.toptal.com/developers/gitignore/api/gradle,kotlin
-# Edit at https://www.toptal.com/developers/gitignore?templates=gradle,kotlin
-
-### Kotlin ###
-# Compiled class file
-*.class
-
-# Log file
-*.log
-
-# BlueJ files
-*.ctxt
-
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
-
-# Package Files #
-*.jar
-*.war
-*.nar
-*.ear
-*.zip
-*.tar.gz
-*.rar
-
-# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
-hs_err_pid*
-replay_pid*
-
-### Gradle ###
-.gradle
-**/build/
-!src/**/build/
-
-# Ignore Gradle GUI config
-gradle-app.setting
-
-# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
-# !gradle-wrapper.jar
-
-# Avoid ignore Gradle wrappper properties
-# !gradle-wrapper.properties
-
-# Cache of project
-.gradletasknamecache
-
-# Eclipse Gradle plugin generated files
-# Eclipse Core
-.project
-# JDT-specific (Eclipse Java Development Tools)
-.classpath
-
-# End of https://www.toptal.com/developers/gitignore/api/gradle,kotlin
-out/
-
-gradlew
-gradlew.bat
-gradle/wrapper/gradle-wrapper.jar
-gradle/wrapper/gradle-wrapper.properties