diff --git a/src/main/asciidoc/_chapters/developer.adoc b/src/main/asciidoc/_chapters/developer.adoc index 0283e302c98..6987ffd6b63 100644 --- a/src/main/asciidoc/_chapters/developer.adoc +++ b/src/main/asciidoc/_chapters/developer.adoc @@ -322,16 +322,15 @@ documenting your setup process here. [[build.basic]] === Basic Compile -HBase is compiled using Maven. -You must use at least Maven 3.0.4. -To check your Maven version, run the command +mvn -version+. +HBase is compiled using Maven. You must use at least Maven 3.0.4. To check your Maven version, run +the command +mvn -version+. -.JDK Version Requirements -[NOTE] -==== -Starting with HBase 1.0 you must use Java 7 or later to build from source code. -See <> for more complete information about supported JDK versions. -==== +[[build.basic.jdk_requirements]] +==== JDK Version Requirements + +HBase has Java version compiler requirements that vary by release branch. At compilation time, +HBase has the same version requirements as it does for runtime. See <> for a complete +support matrix of Java version by HBase version. [[maven.build.commands]] ==== Maven Build Commands @@ -397,28 +396,111 @@ mvn clean install -DskipTests See the <> section in <> [[maven.build.hadoop]] -==== Building against various hadoop versions. +==== Building against various Hadoop versions -HBase supports building against Apache Hadoop versions: 2.y and 3.y (early release artifacts). By default we build against Hadoop 2.x. +HBase supports building against Apache Hadoop versions: 2.y and 3.y (early release artifacts). +Exactly which version of Hadoop is used by default varies by release branch. See the section +<> for the complete breakdown of supported Hadoop version by HBase release. -To build against a specific release from the Hadoop 2.y line, set e.g. `-Dhadoop-two.version=2.6.3`. +The mechanism for selecting a Hadoop version at build time is identical across all releases. Which +version of Hadoop is default varies. We manage Hadoop major version selection by way of Maven +profiles. Due to the peculiarities of Maven profile mutual exclusion, the profile that builds +against a particular Hadoop version is activated by setting a property, *not* the usual profile +activation. Hadoop version profile activation is summarized by the following table. + +.Hadoop Profile Activation by HBase Release +[cols="3*^.^", options="header"] +|=== +| | Hadoop2 Activation | Hadoop3 Activation +| HBase 1.3+ | _active by default_ | `-Dhadoop.profile=3.0` +| HBase 3.0+ | _not supported_ | _active by default_ +|=== + +[WARNING] +==== +Please note that where a profile is active by default, `hadoop.profile` must NOT be provided. +==== + +Once the Hadoop major version profile is activated, the exact Hadoop version can be +specified by overriding the appropriate property value. For Hadoop2 versions, the property name +is `hadoop-two.version`. With Hadoop3 versions, the property name is `hadoop-three.version`. + +.Example 1, Building HBase 1.7 against Hadoop 2.10.0 + +For example, to build HBase 1.7 against Hadoop 2.10.0, the profile is set for Hadoop2 by default, +so only `hadoop-two.version` must be specified: [source,bourne] ---- -mvn -Dhadoop-two.version=2.6.3 ... +git checkout branch-1 +mvn -Dhadoop-two.version=2.10.0 ... ---- -To change the major release line of Hadoop we build against, add a hadoop.profile property when you invoke +mvn+: +.Example 2, Building HBase 2.3 against Hadoop 3.3.0-SNAPSHOT + +This is how a developer might check the compatibility of HBase 2.3 against an unreleased Hadoop +version (currently 3.3). Both the Hadoop3 profile and version must be specified: [source,bourne] ---- -mvn -Dhadoop.profile=3.0 ... +git checkout branch-2.3 +mvn -Dhadoop.profile=3.0 -Dhadoop-three.version=3.3.0-SNAPSHOT ... ---- -The above will build against whatever explicit hadoop 3.y version we have in our _pom.xml_ as our '3.0' version. -Tests may not all pass so you may need to pass `-DskipTests` unless you are inclined to fix the failing tests. +.Example 3, Building HBase 3.0 against Hadoop 3.3.0-SNAPSHOT -To pick a particular Hadoop 3.y release, you'd set hadoop-three.version property e.g. `-Dhadoop-three.version=3.0.0`. +The same developer might want also to check the development version of HBase (currently 3.0) +against the development version of Hadoop (currently 3.3). In this case, the Hadoop3 profile is +active by default, so only `hadoop-three.version` must be specified: + +[source,bourne] +---- +git checkout master +mvn -Dhadoop-three.version=3.3.0-SNAPSHOT ... +---- + +[[maven.build.jdk11_hadoop3]] +==== Building with JDK11 and Hadoop3 + +HBase manages JDK-specific build settings using Maven profiles. The profile appropriate to the JDK +in use is automatically activated. Building and running on JDK8 supports both Hadoop2 and Hadoop3. +For JDK11, only Hadoop3 is supported. Thus, the Hadoop3 profile must be active when building on +JDK11, and the artifacts used when running HBase on JDK11 must be compiled against Hadoop3. +Furthermore, the JDK11 profile requires a minimum Hadoop version of 3.2.0. This value is specified +by the JDK11 profile, but it can be overridden using the `hadoop-three.version` property as normal. +For details on Hadoop profile activation by HBase branch, see +<>. See <> for a complete +support matrix of Java version by HBase version. + +.Example 1, Building HBase 2.3 with JDK11 + +To build HBase 2.3 with JDK11, the Hadoop3 profile must be activated explicitly. + +[source,bourne] +---- +git checkout branch-2.3 +JAVA_HOME=/usr/lib/jvm/java-11 mvn -Dhadoop.profile=3.0 ... +---- + +.Example 2, Building HBase 3.0 with JDK11 + +For HBase 3.0, the Hadoop3 profile is active by default, no additional properties need be +specified. + +[source,bourne] +---- +git checkout master +JAVA_HOME=/usr/lib/jvm/java-11 mvn ... +---- + +[[maven.build.jdk11_hadoop3_ide]] +==== Building and testing in an IDE with JDK11 and Hadoop3 + +Continuing the discussion from the <>, building and +testing with JDK11 and Hadoop3 within an IDE may require additional configuration. Specifically, +make sure the JVM version used by the IDE is a JDK11, the active JDK Maven profile is for JDK11, +and the Maven profile for JDK8 is NOT active. Likewise, ensure the Hadoop3 Maven profile is active +and the Hadoop2 Maven profile is NOT active. [[build.protobuf]] ==== Build Protobuf