dev-support/HOW_TO_YETUS_LOCAL.md

   1 <!---
   2 Licensed to the Apache Software Foundation (ASF) under one
   3 or more contributor license agreements.  See the NOTICE file
   4 distributed with this work for additional information
   5 regarding copyright ownership.  The ASF licenses this file
   6 to you under the Apache License, Version 2.0 (the
   7 "License"); you may not use this file except in compliance
   8 with the License.  You may obtain a copy of the License at
   9
  10   http://www.apache.org/licenses/LICENSE-2.0
  11
  12 Unless required by applicable law or agreed to in writing,
  13 software distributed under the License is distributed on an
  14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15 KIND, either express or implied.  See the License for the
  16 specific language governing permissions and limitations
  17 under the License.
  18 -->
  19
  20 # How To Use Apache Yetus with Apache HBase
  21
  22 This document describes how to get up and running with [Apache Yetus][yetus],
  23 as pertains to the development of Apache HBase. Specifically this covers the use
  24 of `test-patch`, of which HBase developers make use for tasks related to code
  25 quality. These are normally run via automation in the foundation's
  26 [Build][builds] infrastructure. They can also be run locally, which is the
  27 subject of this document.
  28
  29 The Yetus project provides its own documentation of `test-patch` in
  30 [Basic PreCommit][yetus-basic-precommit]. By comparison, this document is
  31 intended to be highly abbreviated, hands-on, and focused on the HBase use-case.
  32 See that document for more complete explanations and further details.
  33
  34 ## Installation
  35
  36 In order to run Yetus, you'll need to first install Yetus and its dependencies.
  37 This is somewhat simplified when used in Docker mode. Yetus can be retrieved
  38 from a [distribution artifact][yetus-downloads]. Homebrew/Linuxbrew users can
  39 install from the tap, the process for which is also described on the downloads
  40 page.
  41
  42 # Usage Basics
  43
  44 Apache Yetus is comprised of a number of different components. The focus of our
  45 interest is `test-patch`. `test-patch` is a modular system. Many modules depend
  46 on some external tool to provide the underlying functionality. For example, the
  47 `compile` check delegates to a number of provider modules, for example `maven`
  48 or `gradle` for JVM projects. In order to use these modules, those tools must
  49 be installed. Yetus calls these modules "plugins".
  50
  51 To see a list of all plugins available to `test-patch`, use
  52
  53 ```shell script
  54 $ test-patch --list-plugins
  55 ```
  56
  57 To see a list of all the options available in both the core modules as well as
  58 all the plugins, use
  59
  60 ```shell script
  61 $ test-patch --plugins=all --help
  62 ```
  63
  64 An invocation of `test-patch` requires use of one or more plugins. Often times,
  65 when the full suite of checks are run, specify the meta-plugin "all". Otherwise,
  66 a limited selection of plugins can be selected using the `--plugins` argument.
  67
  68 ## The Workspace, The Patch
  69
  70 `test-patch` operates within a "workspace," a checkout from a source control
  71 repository. It has a number of options pertaining to this workspace, such as
  72 the path to the workspace (`--basedir`) and whether it will permit the presence
  73 of uncommitted changes therein (`--dirty-workspace`).
  74
  75 Onto this workspace, it can optionally apply a change, a.k.a., the "patch" in
  76 "test patch." The patch can come from a number of sources, including a patch
  77 file, a JIRA ID, a Pull Request, &c. Or, explicitly inform Yetus that no patch
  78 file is provided, and the repository should be checked as is, by passing
  79 `--empty-patch`.
  80
  81 ## Personalities
  82
  83 `test-patch` is extremely extensible. Even the functionality of its core
  84 modules can be extended or overridden. It allows for this type of
  85 "personalization" by way of "personality" overrides. Yetus ships a number of
  86 these personalities; a pre-packaged personality can be selected via the
  87 `--project` parameter. There is a provided HBase personality in Yetus, however
  88 the HBase project maintains its own within the HBase source repository. Specify
  89 the path to the personality file using `--personality`. The HBase repository
  90 places this file under `dev-support/hbase-personality.sh`.
  91
  92 ## Docker mode
  93
  94 Running Yetus in Docker mode simplifies the concerns of dependencies because
  95 the provided `Dockerfile` handles their installation automatically. However,
  96 for MacOS users, there are a number of known issues with running Docker on OSX,
  97 so it may be preferable to instead run outside of the container.
  98
  99 To run in Docker, of course you must install `docker` or some container runtime
 100 equivalent. [Docker Desktop][docker-desktop] is an option for Mac and Windows
 101 users.
 102
 103 When running `test-patch` with HBase in docker mode, two parameters must be
 104 provided. `--docker` activates the `docker` module, enabling the feature.
 105 Additionally, `--dockerfile` points Yetus at HBase's provided `Dockerfile`,
 106 instead of using the one provided out-of-the-box by Yetus. The HBase repository
 107 places this file under `dev-support/docker/Dockerfile`.
 108
 109 ## JVM and JAVA_HOME
 110
 111 HBase supports compilation and test execution on a number of different JVM
 112 versions. To facilitate this, the `Dockerfile` installs multiple JVMs. An
 113 invocation of `test-patch` requires additional parameters in order to specify
 114 the target JVM. How you do this is slightly different based on whether you run
 115 with or without Docker mode.
 116
 117 ### Setting `JAVA_HOME` Outside of Docker Mode
 118
 119 Simply specify `JAVA_HOME` in the environment in which `test-patch` is launched.
 120
 121 ### Setting `JAVA_HOME` Inside of Docker Mode
 122
 123 The docker image JDKs are available under `/usr/lib/jvm`. Symlinks are provided
 124 for each supported major version, i.e., `java-11`. Use the `test-patch` argument
 125 `--java-home`.
 126
 127 # Example: Run SpotBugs
 128
 129 One of the checks supported by Yetus is the static analysis tool
 130 [SpotBugs][spotbugs]. Let's put together all the above and run SpotBugs with
 131 `test-patch`.
 132
 133 The SpotBugs check depends on a SpotBugs installation. This is provided by the
 134 docker file. For running without docker, you'll need to download and unpack the
 135 SpotBugs binary distribution.
 136
 137 Running the SpotBugs check also depends on [Apache Maven][maven], the build
 138 system used by HBase. In order for the check to function, both the `maven`
 139 and `spotbugs` plugins must be specified. If this dependency is omitted, Yetus
 140 will error with a message similar to
 141
 142 ```
 143 ERROR: you can't specify maven as the buildtool if you don't enable the plugin.
 144 ```
 145
 146 To run just the SpotBugs check, we must explicitly specify `spotbugs` and its
 147 dependency using `--plugins=maven,spotbugs`.
 148
 149 ## Without Docker
 150
 151 Putting it all together, without using docker:
 152
 153 ```shell script
 154 $ cd /path/to/hbase
 155 $ JAVA_HOME=/path/to/jdk-8 test-patch.sh \
 156   --plugins=maven,spotbugs \
 157   --spotbugs-home=/path/to/spotbugs/
 158   --dirty-workspace \
 159   --empty-patch \
 160   --personality=./dev-support/hbase-personality.sh
 161 ```
 162
 163 ## With Docker
 164
 165 Putting it all together, using docker:
 166
 167 ```shell script
 168 $ cd /path/to/hbase
 169 $ test-patch.sh \
 170   --plugins=maven,spotbugs \
 171   --dirty-workspace \
 172   --empty-patch \
 173   --personality=./dev-support/hbase-personality.sh \
 174   --docker \
 175   --dockerfile=./dev-support/docker/Dockerfile \
 176   --java-home=/usr/lib/jvm/java-8
 177 ```
 178
 179 [builds]: https://builds.apache.org
 180 [docker-desktop]: https://www.docker.com/products/docker-desktop
 181 [maven]: https://maven.apache.org
 182 [spotbugs]: https://spotbugs.github.io
 183 [yetus]: https://yetus.apache.org
 184 [yetus-basic-precommit]: https://yetus.apache.org/documentation/in-progress/precommit-basic/
 185 [yetus-downloads]: https://yetus.apache.org/downloads/