]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
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 |