ceph/src/jaegertracing/thrift/lib/java/README.md

   1 Thrift Java Software Library
   2
   3 License
   4 =======
   5
   6 Licensed to the Apache Software Foundation (ASF) under one
   7 or more contributor license agreements. See the NOTICE file
   8 distributed with this work for additional information
   9 regarding copyright ownership. The ASF licenses this file
  10 to you under the Apache License, Version 2.0 (the
  11 "License"); you may not use this file except in compliance
  12 with the License. You may obtain a copy of the License at
  13
  14   http://www.apache.org/licenses/LICENSE-2.0
  15
  16 Unless required by applicable law or agreed to in writing,
  17 software distributed under the License is distributed on an
  18 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  19 KIND, either express or implied. See the License for the
  20 specific language governing permissions and limitations
  21 under the License.
  22
  23 Building and installing from source
  24 ===================================
  25
  26 When using a CMake build from the source distribution on Linux the
  27 easiest way to build and install is this simple command line:
  28
  29     make all && sudo make install/fast
  30
  31 It is important to use the install/fast option to eliminate
  32 the automatic rebuild by dependency that causes issues because
  33 the build tooling is designed to work with cached files in the
  34 user home directory during the build process. Instead this builds
  35 the code in the expected local build tree and then uses CMake
  36 install code to copy to the target destination.
  37
  38 Building Thrift with Gradle without CMake/Autoconf
  39 ==================================================
  40
  41 The Thrift Java source is not build using the GNU tools, but rather uses
  42 the Gradle build system, which tends to be predominant amongst Java
  43 developers.
  44
  45 To compile the Java Thrift libraries, simply do the following:
  46
  47     ./gradlew
  48
  49 Yep, that's easy. Look for libthrift-<version>.jar in the build/libs directory.
  50
  51 The default build will run the unit tests which expect a usable
  52 Thrift compiler to exist on the system. You have two choices for
  53 that.
  54
  55 * Build the Thrift executable from source at the default
  56   location in the source tree. The project is configured
  57   to look for it there.
  58 * Install the published binary distribution to have Thrift
  59   executable in a known location and add the path to the
  60   ~/.gradle/gradle.properties file using the property name
  61   "thrift.compiler". For example this would set the path in
  62   a Windows box if Thrift was installed under C:\Thrift
  63
  64     thrift.compiler=C:/Thrift/thrift.exe
  65
  66 To just build the library without running unit tests you simply do this.
  67
  68     ./gradlew assemble
  69
  70 To install the library in the local Maven repository location
  71 where other Maven or Gradle builds can reference it simply do this.
  72
  73     ./gradlew install
  74
  75 The library will be placed in your home directory under .m2/repository
  76
  77 To include Thrift in your applications simply add libthrift.jar to your
  78 classpath, or install if in your default system classpath of choice.
  79
  80
  81 Build Thrift behind a proxy:
  82
  83     ./gradlew -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
  84
  85 or via
  86
  87     ./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
  88
  89
  90 Unit Test HTML Reports
  91 ======================
  92
  93 The build will automatically generate an HTML Unit Test report. This can be found
  94 under build/reports/tests/test/index.html. It can be viewed with a browser
  95 directly from that location.
  96
  97
  98 Clover Code Coverage for Thrift
  99 ===============================
 100
 101 The build will optionally generate Clover Code coverage if the Gradle property
 102 `cloverEnabled=true` is set in ~/.gradle/gradle.properties or on the command line
 103 via `-PcloverEnabled=true`. The generated report can be found under the location
 104 build/reports/clover/html/index.html. It can be viewed with a browser
 105 directly from that location. Additionally, a PDF report is generated and is found
 106 under the location build/reports/clover/clover.pdf.
 107
 108 The following command will build, unit test, and generate Clover reports:
 109
 110     ./gradlew -PcloverEnabled=true
 111
 112
 113 Publishing Maven Artifacts to Maven Central
 114 ===========================================
 115
 116 The Automake build generates a Makefile that provides the correct parameters
 117 when you run the build provided the configure.ac has been set with the correct
 118 version number. The Gradle build will receive the correct value for the build.
 119 The same applies to the CMake build, the value from the configure.ac file will
 120 be used if you execute these commands:
 121
 122     make maven-publish   -- This is for an Automake Linux build
 123     make MavenPublish    -- This is for a CMake generated build
 124
 125 The uploadArchives task in Gradle is preconfigured with all necessary details
 126 to sign and publish the artifacts from the build to the Apache Maven staging
 127 repository. The task requires the following externally provided properties to
 128 authenticate to the repository and sign the artifacts. The preferred approach
 129 is to create or edit the ~/.gradle/gradle.properties file and add the following
 130 properties to it.
 131
 132     # Signing key information for artifacts PGP signature (values are examples)
 133     signing.keyId=24875D73
 134     signing.password=secret
 135     signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
 136
 137     # Apache Maven staging repository user credentials
 138     mavenUser=meMyselfAndI
 139     mavenPassword=MySuperAwesomeSecretPassword
 140
 141 NOTE: If you do not have a secring.gpg file, see the
 142 [gradle signing docs](https://docs.gradle.org/current/userguide/signing_plugin.html)
 143 for instructions on how to generate it.
 144
 145 It is also possible to manually publish using the Gradle build directly.
 146 With the key information and credentials in place the following will generate
 147 if needed the build artifacts and proceed to publish the results.
 148
 149     ./gradlew -Prelease=true uploadArchives
 150
 151 It is also possible to override the target repository for the Maven Publication
 152 by using a Gradle property, for example you can publish signed JAR files to your
 153 company internal server if you add this to the command line or in the
 154 ~/.gradle/gradle.properties file. The URL below assumes a Nexus Repository.
 155
 156     maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
 157
 158 Or the same on the command line:
 159
 160     ./gradlew -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
 161
 162
 163 Dependencies
 164 ============
 165
 166 Gradle
 167 http://gradle.org/
 168
 169 # Breaking Changes
 170
 171 ## 0.13.0
 172
 173 * The signature of the 'process' method in TAsyncProcessor and TProcessor has
 174 changed to remove the boolean return type and instead rely on Exceptions.
 175
 176 * Per THRIFT-4805, TSaslTransportException has been removed. The same condition
 177 is now covered by TTansportException, where `TTransportException.getType() == END_OF_FILE`.
 178
 179 ## 0.12.0
 180
 181 The access modifier of the AutoExpandingBuffer class has been changed from
 182 public to default (package) and will no longer be accessible by third-party
 183 libraries.
 184
 185 The access modifier of the ShortStack class has been changed from
 186 public to default (package) and will no longer be accessible by third-party
 187 libraries.
 188