b399ba825002f63dc50e57d6432aa6d168019109
[sqoop.git] / COMPILING.txt
1
2 = Compiling
3
4 This document explains how to compile and test Sqoop.
5
6 ////
7 Licensed to the Apache Software Foundation (ASF) under one
8 or more contributor license agreements.  See the NOTICE file
9 distributed with this work for additional information
10 regarding copyright ownership.  The ASF licenses this file
11 to you under the Apache License, Version 2.0 (the
12 "License"); you may not use this file except in compliance
13 with the License.  You may obtain a copy of the License at
14
15   http://www.apache.org/licenses/LICENSE-2.0
16
17 Unless required by applicable law or agreed to in writing,
18 software distributed under the License is distributed on an
19 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 KIND, either express or implied.  See the License for the
21 specific language governing permissions and limitations
22 under the License.
23 ////
24
25
26 == Build Dependencies
27
28 Compiling Sqoop requires the following tools:
29
30 * Apache ant (1.9.7) or Gradle (4.9)
31 * Java JDK 1.8
32
33 Additionally, building the documentation requires these tools:
34
35 * asciidoc
36 * make
37 * python 2.5+
38 * xmlto
39 * tar
40 * gzip
41
42 Furthermore, Sqoop's build can be instrumented with the following:
43
44 * findbugs (1.3.9) for code quality checks
45 * cobertura (1.9.4.1) for code coverage
46 * checkstyle (5.x) for code style checks
47
48 == The Basics
49
50 Sqoop can be compiled and tested with both Ant and Gradle. Type +ant -p+ or +./gradlew tasks --all+ to see the list of available targets/tasks.
51
52 Type +ant+ or +./gradlew jar+ to compile all java sources. You can then run Sqoop with +bin/sqoop+.
53
54 If you want to build everything (including the documentation), type
55 +ant package+ or +./gradlew package+. This will appear in the
56 +build/sqoop-(version)/+ directory.
57
58 == Testing Sqoop
59
60 Sqoop supports both Ant and Gradle but the test tasks are a bit different in each build tools.
61
62 === Testing with Ant
63 The Ant build defines two main test categories: unit and third party tests.
64
65 Classes with the +Test+ prefix are unit tests and classes with the +Test+ postfix are third party tests.
66
67 Sqoop unit tests can be run with +ant test+. This command
68 will run all the "basic" checks against an in-memory database, HSQLDB.
69
70 Sqoop's third party tests are compatibility tests that check its ability to work with
71 several third-party databases. To enable these tests, you will need to install
72 and configure the databases or run them in Docker containers, and download the JDBC drivers for each one.
73
74 For more information about how to run this suite see the 'Third party tests' section.
75
76 Note that the unit test suite contains several Amazon S3 test classes too which test the "RDBMS to Amazon S3" use case with an in-memory database, HSQLDB.
77 To enable these tests, you will need to have either permanent or temporary Amazon S3 security credentials.
78
79 For more information about how to run this suite see the 'Amazon S3 tests' section.
80
81 === Testing with Gradle
82
83 The Gradle build supports JUnit's +@Category+ annotation so we have access to much more fine grained test categories here.
84 The test categories are defined as marker interfaces under +org.apache.sqoop.testcategories+ package.
85
86 The following table shows the currently supported test categories and their hierarchy:
87
88 .Available test categories
89 [width="40%",frame="topbot",options="header"]
90 |======================
91 |Category              |Subcategory
92 .3+|+SqoopTest+        |+UnitTest+
93                        |+IntegrationTest+
94                        |+ManualTest+
95 .9+|+ThirdPartyTest+   |+CubridTest+
96                        |+Db2Test+
97                        |+MainFrameTest+
98                        |+MysqlTest+
99                        |+NetezzaTest+
100                        |+OracleTest+
101                        |+PostgresqlTest+
102                        |+SqlServerTest+
103                        |+S3Test+
104 |+KerberizedTest+      |
105 |======================
106
107 ==== SqoopTest
108 A general category including UnitTest, IntegrationTest and ManualTest.
109
110 ==== UnitTest
111 A unit test shall test one class at a time having it's dependencies mocked.
112 A unit test shall not start a mini cluster nor an embedded database and it shall not use a JDBC driver.
113
114 ==== IntegrationTest
115 An integration test shall test if independently developed classes work together correctly.
116 An integration test checks a whole scenario and thus may start mini clusters or embedded databases and may connect to
117 external resources like RDBMS instances.
118
119 ==== ManualTest
120 Deprecated category, shall not be used nor extended.
121
122 ==== ThirdPartyTest
123 A third party test shall test a scenario where a third party side is required such as a JDBC driver or an external RDBMS instance.
124 The subcategories define what kind of third party dependency is needed by the test.
125
126 ==== KerberizedTest
127 A kerberized test shall run in kerberized environment thus it starts mini KDC server.
128
129 ==== Categorizing tests
130 Note that if you add a new test you have to make sure that it is categorized otherwise Gradle will not execute it.
131
132 The categorizing steps are the following:
133
134 * Decide if the test is a unit or an integration test, mark the test class with the +@Category+ annotation and add the
135 corresponding marker interface to it.
136 * If the test needs a JDBC driver or an external service then add +ThirdPartyTest+ or one of its subinterfaces to the
137 +@Category+ annotation. Try to use the most specific interface.
138 * If the test starts a Mini KDC then add the +KerberizedTest+ interface to the +@Category+ annotation.
139
140 ==== Available test targets
141
142 * +unitTest+: Runs unit tests which do not need proprietary JDBC driver.
143 * +integrationTest+: Runs integration tests which do not need a docker container or an external database/service.
144 * +kerberizedTest+: Runs kerberized tests.
145 * +thirdPartyTest+: Runs third-party tests. For more information see the 'Third party tests' section.
146 * +test+: Runs tests that do not need external JDBC driver and/or a docker container.
147 This the same as running unitTest, integrationTest and kerberizedTest.
148 * +s3Test+: Runs S3 tests. For more information see the 'Amazon S3 tests' section.
149 * +allTest+: Runs all Sqoop tests.
150
151
152 The https://docs.gradle.org/current/dsl/org.gradle.api.tasks.testing.Test.html#org.gradle.api.tasks.testing.Test:forkEvery[forkEvery]
153 parameter of most of the Gradle test tasks is set to +0+ which means that all of the tests run in a single JVM.
154 The only exception is the +kerberizedTest+ task which requires a new JVM for every test class.
155 The benefit of this setup is that the test tasks finish much faster since the JVM creation is a slow operation however
156 the Sqoop test framework seems to consume/leak too much memory which can lead to an +OutOfMemoryError+ during the build.
157 To prevent the JVM running out of memory you can use the +-DforkEvery.default+ property to set the forkEvery
158 parameter for all the test tasks except +kerberizedTest+:
159
160 ----
161 ./gradlew -DforkEvery.default=30 test
162 ----
163
164 === Third party tests
165
166 ==== Installing the necessary databases
167
168 ===== MySQL
169
170 Install MySQL server and client 5.0. Download MySQL Connector/J 5.0.8 for
171 JDBC. Instructions for configuring the MySQL database are in MySQLAuthTest
172 and DirectMySQLTest.
173
174 Use the following system properties to configure connection to the MySQL host used for testing:
175 sqoop.test.mysql.connectstring.host_url, sqoop.test.mysql.databasename, sqoop.test.mysql.username and
176 sqoop.test.mysql.password.
177 Specify these properties on the command line or via the build.properties file. For example:
178
179 sqoop.test.mysql.connectstring.host_url=jdbc:mysql://host.example.com/
180 sqoop.test.mysql.databasename=MYDB
181 sqoop.test.mysql.username=MYUSR
182 sqoop.test.mysql.password=MYPWD
183
184 If not specified, the default value used for this property is:
185 jdbc:mysql://localhost/
186
187 ===== Oracle
188
189 Install Oracle Enterprise Edition 10.2.0+. Instructions for configuring the
190 database are in OracleManagerTest. Download the ojdbc6_g jar.
191
192 If running the tests against Oracle XE (Express Edition) - a lot of them will
193 fail as it does not include the partitioning feature.
194
195 Use the following system properties to configure connection to the Oracle host used for testing:
196 sqoop.test.oracle.connectstring, sqoop.test.oracle.username and  sqoop.test.oracle.password.
197 Specify these properties on the command line or via the build.properties file. For example:
198
199 sqoop.test.oracle.connectstring=jdbc:oracle:thin:@//host.example.com/xe
200 sqoop.test.oracle.username=MYUSR
201 sqoop.test.oracle.password=MYPWD
202
203 If not specified, the default value used for this property is:
204 jdbc:oracle:thin:@//localhost/xe
205
206 Users sqooptest and sqooptest2 should be created prior to running the tests.
207 SQL script is available in src/test/oraoop/create_users.sql
208
209 ===== PostgreSQL
210
211 Install PostgreSQL 8.3.9. Download the postgresql 8.4 jdbc driver. Instructions
212 for configuring the database are in PostgresqlTest.
213
214 Use the following system properties to configure connection to the PostgreSQL host used for testing:
215 sqoop.test.postgresql.connectstring.host_url, sqoop.test.postgresql.database, sqoop.test.postgresql.username and
216 sqoop.test.postgresql.password.
217 Specify this property on the
218 command line or via the build.properties file. For example:
219
220 sqoop.test.postgresql.connectstring.host_url=jdbc:postgresql://sqoop-dbs.sf.cloudera.com/
221 sqoop.test.postgresql.database=MYDB
222 sqoop.test.postgresql.username=MYUSR
223 sqoop.test.postgresql.password=MYPWD
224
225 If not specified, the default value used for this property is:
226 jdbc:postgresql://localhost/
227
228 ===== SQL Server
229
230 Install SQL Server Express 2012 and create a database instance and
231 download the appropriate JDBC driver. Instructions for configuring the
232 database can be found in SQLServerManagerImportManualTest.
233
234 Use the following system properties to configure connection to the SQL Server host used for testing:
235 sqoop.test.sqlserver.connectstring.host_url, sqoop.test.sqlserver.database, sqoop.test.sqlserver.username and
236 sqoop.test.sqlserver.password.
237 the URL for the SQL Server host used for testing. Specify this property on the
238 command line or via the build.properties file. For example:
239
240 sqoop.test.sqlserver.connectstring.host_url=jdbc:sqlserver://sqlserverhost:1433
241 sqoop.test.sqlserver.database=MYDB
242 ms.sqlserver.username=MYUSR
243 ms.sqlserver.password=MYPWD
244
245 If not specified, the default value used for this property is:
246 jdbc:sqlserver://sqlserverhost:1433
247
248 This can be useful if you have the hostname sqlserverhost mapped to the IP
249 address of the SQL Server instance.
250
251 ===== Cubrid
252
253 Install Cubrid 9.2.2.0003 and create a database instance and download the
254 appropriate JDBC driver. Instructions for configuring the database are in
255 CubridAuthTest, CubridCompatTest, CubridManagerImportTest
256 and CubridManagerExportTest.
257
258 Use the following system properties to configure connection to the Cubrid host used for testing:
259 sqoop.test.cubrid.connectstring.host_url, sqoop.test.cubrid.connectstring.database,
260 sqoop.test.cubrid.connectstring.username and sqoop.test.cubrid.connectstring.password.
261 Specify this property on the command
262 line or via the build.properties file. For example:
263
264 sqoop.test.cubrid.connectstring.host_url=jdbc:cubrid:localhost
265 sqoop.test.cubrid.connectstring.database=MYDB
266 sqoop.test.cubrid.connectstring.username=MYUSR
267 sqoop.test.cubrid.connectstring.password=MYPWD
268
269 If not specified, the default value used for this property is:
270 jdbc:cubrid:localhost
271
272 ===== DB2
273
274 Install DB2 9.74 Express C and download the appropriate JDBC driver.
275 Instructions for configuring the server can be found in
276 DB2ManagerImportManualTest.
277
278 Use the following system properties to configure connection to the DB2 host used for testing:
279 sqoop.test.db2.connectstring.host_url, sqoop.test.db2.connectstring.database, sqoop.test.db2.connectstring.username and
280 sqoop.test.db2.connectstring.password.
281 Specify this property on
282 the command line or via build.properties file. For example:
283
284 sqoop.test.db2.connectstring.host_url=jdbc:db2://db2host:50000
285 sqoop.test.db2.connectstring.database=MYDB
286 sqoop.test.db2.connectstring.username=MYUSR
287 sqoop.test.db2.connectstring.password=MYPWD
288
289 If not specified, the default value used for this property is:
290 jdbc:db2://db2host:50000
291
292 This can be useful if you have the hostname db2host mapped to the IP
293 address of the DB2 Server instance.
294
295 ==== Running the Third-party Tests on native database servers
296
297 After the third-party databases are installed and configured, run:
298
299 ++++
300 ant test -Dthirdparty=true -Dsqoop.thirdparty.lib.dir=/path/to/jdbc/drivers/
301 ./gradlew -Dsqoop.thirdparty.lib.dir=/relative/path/to/jdbc/drivers/ thirdPartyTest
302 ++++
303
304 This command will run all thirdparty tests except some DB2 tests.
305 To run these DB2 test, specify the property "manual" instead of "thirdparty"
306 as follows:
307
308 ++++
309 ant test -Dmanual=true -Dsqoop.thirdparty.lib.dir=/path/to/jdbc/drivers/
310 ./gradlew -Dsqoop.thirdparty.lib.dir=/relative/path/to/jdbc/drivers/ manualTest
311 ++++
312
313 Note that +sqoop.thirdparty.lib.dir+ can also be specified in
314 +build.properties+.
315
316 ==== Setting up and executing third-party tests with databases running in Docker containers
317
318 The easiest way to run the Sqoop third party test pack is to start all the necessary database servers in Docker containers. This eliminates the need of installing and setting up 6 different RDBMSs on the development machines and provides a clean database environment every time the tests are executed.
319
320 ===== Installing docker
321
322 The first step is to install a recent version (1.13.0+) of Docker and Docker Compose on your development machine. Please refer to the Docker documentation for the installation instructions for your OS environment:
323
324 https://docs.docker.com/engine/installation/
325 https://docs.docker.com/compose/install/
326
327 ===== Downloading docker images
328
329 MySQL, PostgreSQL, MSSQL, DB2 and Cubrid images are freely available on Docker Hub so they will be pulled automatically by the startup command specified below however the Oracle EE image has to be built manually. Please refer to the README.md file on the below Github project for building instructions:
330
331 https://github.com/oracle/docker-images/tree/master/OracleDatabase
332
333 Please note that Sqoop third party tests require Oracle Enterprise Edition and the startup command assumes version 12.2.0.1.
334
335 ===== Starting the Docker containers
336
337 A startup script has been added to the Sqoop project to make the Docker container initialization easier:
338
339 ----
340 <sqoop_workspace>/src/scripts/thirdpartytest/start-thirdpartytest-db-containers.sh
341 ----
342
343 If it is executed without parameters it starts the following services:
344
345 .Third party test DB docker services
346 [width="40%",frame="topbot",options="header"]
347 |======================
348 |Service name    |Database version
349 |+mysql+         |MySql 5.7.19
350 |+postgresql+    |PostgreSQL 9.6.4
351 |+mssql+         |MSSQL 14.0.1000.169 Developer Edition
352 |+cubrid+        |Cubrid 10.0
353 |+oracle+        |Oracle EE 12.2.0.1
354 |+db2+           |DB2 Express Edition 10.5.0.5-3.10.0
355 |======================
356
357 The script starts up all the services by default but you can override this behavior by specifying the service names in the parameter list. For example if you want to start up mysql and postgresql services only you can execute the script like this:
358
359 ----
360 <sqoop_workspace>/src/scripts/thirdpartytest/start-thirdpartytest-db-containers.sh mysql postgresql
361 ----
362
363 After the startup script is executed the containers need some time to initialize the databases. You can follow the status of the containers using the docker ps command. If a service is properly initialized you will see a healthy status in the output of the docker ps command. For example the below output means that Cubrid is started up successfully and it is ready to be used but DB2 is still starting up:
364
365 ----
366 61c4ef871cbb        cubrid/cubrid:10.0                    "/entrypoint.sh"         43 seconds ago      Up 38 seconds (healthy)            0.0.0.0:33000->33000/tcp           sqoop_cubrid_container
367 158e5421d134        ibmcom/db2express-c:10.5.0.5-3.10.0   "/home/db2inst1/db..."   43 seconds ago      Up 40 seconds (health: starting)   22/tcp, 0.0.0.0:50000->50000/tcp   sqoop_db2_container
368 ----
369
370 Most of the containers need less than 1 minute to start up but DB2 needs ~5 minutes and Oracle needs ~15 minutes. The Docker images need ~17GB free disk space and Docker requires ~5GB of memory to start all of them at the same time.
371
372 ===== Stopping the Docker containers
373
374 You can stop and remove the Docker containers using the following command:
375
376 ----
377 <sqoop_workspace>/src/scripts/thirdpartytest/stop-thirdpartytest-db-containers.sh
378 ----
379
380 ===== Running the third party tests using docker containers
381
382 You can execute the third party tests against the DBs running in Docker containers using the following command (replace <path_to_thirdparty_lib_directory> with the path you have the necessary JDBC drivers,
383 <your-bucket-url> and <your-credential-generator-command> with the values described in the 'Amazon S3 tests' section):
384
385 ----
386 ant clean test -Dthirdparty=true -Dsqoop.thirdparty.lib.dir=<path_to_thirdparty_lib_directory> \
387     -Dsqoop.test.mysql.connectstring.host_url=jdbc:mysql://127.0.0.1:3306/ \
388     -Dsqoop.test.mysql.databasename=sqoop \
389     -Dsqoop.test.mysql.password=Sqoop12345 \
390     -Dsqoop.test.mysql.username=sqoop \
391     -Dsqoop.test.oracle.connectstring=jdbc:oracle:thin:@//localhost:1521/sqoop \
392     -Dsqoop.test.oracle.username=SYSTEM \
393     -Dsqoop.test.oracle.password=Sqoop12345 \
394     -Dsqoop.test.postgresql.connectstring.host_url=jdbc:postgresql://localhost/ \
395     -Dsqoop.test.postgresql.database=sqoop \
396     -Dsqoop.test.postgresql.username=sqoop \
397     -Dsqoop.test.postgresql.password=Sqoop12345 \
398     -Dsqoop.test.cubrid.connectstring.host_url=jdbc:cubrid:localhost:33000 \
399     -Dsqoop.test.cubrid.connectstring.username=sqoop \
400     -Dsqoop.test.cubrid.connectstring.database=sqoop \
401     -Dsqoop.test.cubrid.connectstring.password=Sqoop12345 \
402     -Dmapred.child.java.opts="\-Djava.security.egd=file:/dev/../dev/urandom" \
403     -Dtest.timeout=10000000 \
404     -Dsqoop.test.sqlserver.connectstring.host_url=jdbc:sqlserver://localhost:1433 \
405     -Dsqoop.test.sqlserver.database=master \
406     -Dms.sqlserver.username=sa \
407     -Dms.sqlserver.password=Sqoop12345 \
408     -Dsqoop.test.db2.connectstring.host_url=jdbc:db2://localhost:50000 \
409     -Dsqoop.test.db2.connectstring.database=SQOOP \
410     -Dsqoop.test.db2.connectstring.username=DB2INST1 \
411     -Dsqoop.test.db2.connectstring.password=Sqoop12345 \
412     -Ds3.bucket.url=<your-bucket-url> \
413     -Ds3.generator.command=<your-credential-generator-command>
414 ----
415
416 or
417
418 ----
419 ./gradlew -Dsqoop.thirdparty.lib.dir=<path_to_thirdparty_lib_directory> \
420     -Dsqoop.test.mysql.connectstring.host_url=jdbc:mysql://127.0.0.1:3306/ \
421     -Dsqoop.test.mysql.databasename=sqoop \
422     -Dsqoop.test.mysql.password=Sqoop12345 \
423     -Dsqoop.test.mysql.username=sqoop \
424     -Dsqoop.test.oracle.connectstring=jdbc:oracle:thin:@//localhost:1521/sqoop \
425     -Dsqoop.test.oracle.username=SYSTEM \
426     -Dsqoop.test.oracle.password=Sqoop12345 \
427     -Dsqoop.test.postgresql.connectstring.host_url=jdbc:postgresql://localhost/ \
428     -Dsqoop.test.postgresql.database=sqoop \
429     -Dsqoop.test.postgresql.username=sqoop \
430     -Dsqoop.test.postgresql.password=Sqoop12345 \
431     -Dsqoop.test.cubrid.connectstring.host_url=jdbc:cubrid:localhost:33000 \
432     -Dsqoop.test.cubrid.connectstring.username=sqoop \
433     -Dsqoop.test.cubrid.connectstring.database=sqoop \
434     -Dsqoop.test.cubrid.connectstring.password=Sqoop12345 \
435     -Dmapred.child.java.opts="\-Djava.security.egd=file:/dev/../dev/urandom" \
436     -Dtest.timeout=10000000 \
437     -Dsqoop.test.sqlserver.connectstring.host_url=jdbc:sqlserver://localhost:1433 \
438     -Dsqoop.test.sqlserver.database=master \
439     -Dms.sqlserver.username=sa \
440     -Dms.sqlserver.password=Sqoop12345 \
441     -Dsqoop.test.db2.connectstring.host_url=jdbc:db2://localhost:50000 \
442     -Dsqoop.test.db2.connectstring.database=SQOOP \
443     -Dsqoop.test.db2.connectstring.username=DB2INST1 \
444     -Dsqoop.test.db2.connectstring.password=Sqoop12345 \
445     -Ds3.bucket.url=<your-bucket-url> \
446     -Ds3.generator.command=<your-credential-generator-command> \
447     thirdPartyTest
448 ----
449
450 Please note that even if you do not need to install RDBMSs to run Sqoop third party tests against the Docker containers you still need to install the following tools:
451
452 * mysqldump
453 * mysqlimport
454 * psql
455
456 === Amazon S3 tests
457
458 To enable Amazon S3 tests you need to have Amazon S3 security credentials. To pass these credentials to Sqoop during
459 test execution you need to have a generator command that writes Amazon S3 credentials to the first
460 line of standard output in the following order: access key, secret key and session token (the latter one only in case
461 of temporary credentials) having them separated by spaces.
462
463 You can then pass the bucket URL and the generator command to the tests via system properties as follows:
464
465 ----
466 ant clean test -Ds3.bucket.url=<your-bucket-url> -Ds3.generator.command=<your-credential-generator-command>
467 ----
468
469 or
470
471 ----
472 ./gradlew s3Test -Ds3.bucket.url=<your-bucket-url> -Ds3.generator.command=<your-credential-generator-command>
473 ----
474
475
476 == Code Quality Analysis
477
478 We have three tools which can be used to analyze Sqoop's code quality.
479
480 === Findbugs
481
482 Findbugs detects common errors in programming. New patches should not
483 trigger additional warnings in Findbugs.
484
485 Install findbugs (1.3.9) according to its instructions. To use it,
486 run:
487
488 ----
489 ant findbugs -Dfindbugs.home=/path/to/findbugs/
490 ----
491
492 or
493
494 ----
495 ./gradlew findbugsMain
496 ----
497
498 A report will be generated in +build/findbugs/+
499
500 === Code Coverage reports
501
502 For ant Cobertura runs code coverage checks. It instruments the build and
503 checks that each line and conditional expression is evaluated along
504 all possible paths.
505
506 Install Cobertura according to its instructions. Then run a test with:
507
508 ----
509 ant clean
510 ant cobertura -Dcobertura.home=/path/to/cobertura
511 ant cobertura -Dcobertura.home=/path/to/cobertura \
512     -Dthirdparty=true -Dsqoop.thirdparty.lib.dir=/path/to/thirdparty
513 ----
514
515 For Gradle we run Jacoco for code coverage checks. You can create single reports or composite reports,
516 where you can check the combined coverage of unit and thirdparty tests.
517
518 ----
519 ./gradlew clean
520 ./gradlew test
521 ./gradlew jacocoTestReport
522
523 ./gradlew -Dsqoop.thirdparty.lib.dir=<path_to_thirdparty_lib_directory> thirdPartyTest
524 ./gradlew jacocoThirdPartyReport
525 ----
526
527 or generate the composite report after running test and thirdPartyTest
528
529 ----
530 ./gradlew jacocoCompositeReport
531 ----
532
533 (You'll need to run the cobertura target twice; once against the regular
534 test targets, and once against the thirdparty targets.)
535
536 When complete, the report will be placed in +build/cobertura/+
537
538 New patches should come with sufficient tests for their functionality
539 as well as their error recovery code paths. Cobertura can help assess
540 whether your tests are thorough enough, or where gaps lie.
541
542 === Checkstyle
543
544 Checkstyle enforces our style guide. There are currently a very small
545 number of violations of this style in the source code, but hopefully this
546 will remain the case. New code should not trigger additional checkstyle
547 warnings.
548
549 Checkstyle does not need to be installed manually; it will be retrieved via
550 Ivy when necessary.
551
552 To run checkstyle, execute:
553
554 ----
555 ant checkstyle
556 ----
557
558 or
559
560 ----
561 ./gradlew checkStyleMain
562 ----
563
564 A report will be generated as +build/checkstyle-errors.html+
565
566
567 == Deploying to Maven
568
569 To use Sqoop as a dependency in other projects, you can pull Sqoop into your
570 dependency management system through Maven.
571
572 To install Sqoop in your local +.m2+ cache, run:
573
574 ----
575 ant mvn-install
576 ----
577
578 or
579
580 ----
581 ./gradlew publishToMavenLocal
582 ----
583
584 This will install a pom and the Sqoop jar.
585
586 To deploy Sqoop to a public repository, use:
587
588 ----
589 ant mvn-deploy
590 ----
591
592 or
593
594 ----
595 ./gradlew publishSqoopPublicationToCloudera.snapshot.repoRepository
596 ./gradlew -DmvnRepo=x publishSqoopPublicationToCloudera.x.repoRepository
597 ----
598
599 By default, this deploys to +repository.cloudera.com+. You can choose
600 the complete URL to deploy to with the +mvn.deploy.url+ property.
601 By default, this deploys to the "snapshots" repository. To deploy to
602 "staging" or "releases" on repository.cloudera.com, set the
603 +mvn.repo+ property accordingly.
604
605 == Releasing Sqoop
606
607 To build a full release of Sqoop, run +ant release -Dversion=(somever)+.
608 This will build a binary release tarball and the web-based documentation
609 as well as run a release audit which flags any source files which may
610 be missing license headers.
611
612 (The release audit can be run standalone with the +ant releaseaudit+ (+./gradlew rat+)
613 target.)
614
615 You must set the +version+ property explicitly; you cannot release a
616 snapshot. To simultaneously deploy this to a maven repository, include
617 the +mvn-install+ or +mvn-deploy+ targets as well.
618
619
620 == Using Eclipse
621
622 Running +ant eclipse+ will generate +.project+ and +.classpath+ files that
623 will allow you to edit Sqoop sources in Eclipse with all the library
624 dependencies correctly resolved. To compile the jars, you should still
625 use Ant or Gradle.
626
627 == Building the documentation
628
629 Building the documentation requires that you have toxml installed.
630 Also, one needs to set the XML_CATALOG_FILES environment variable.
631
632 ----
633 export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
634 ant docs
635 ----
636
637 or
638
639 ----
640 export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
641 ./gradlew docs
642 ----
643
644 == Other important Gradle commands
645
646 * +./gradlew wrapper+ to generate gradle wrapper (to ensure you are using the correct, compatible version of gradle)
647 * +./gradlew tasks+ to list all top-level gradle tasks or run +./gradlew tasks --all+ to show all tasks and subtasks
648 * +./gradlew compileJava+ to compile the main Java source
649 * +./gradlew test --debug-jvm+ to run remote debug on port 5005
650 * +./gradlew test --tests TestSqoopOptions+, +./gradlew thirdPartyTest --tests TestS3*+ to run one or more tests matching a pattern (use with test or thirdPartyTest)
651 * +./gradlew build --refresh-dependencies+ to refresh dependencies for a build
652 * +./gradle build -x test+ for skipping a single test or a set of tests
653 * +./gradlew dependencyInsight --configuration optionalConfiguration --dependency searchedForDependency+ to get a dependency tree
654 * +./gradlew dependencies+ to get the list of the dependencies of the selected project, broken down by configuration