This is an automated email from the ASF dual-hosted git repository.
aw pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/yetus.git
The following commit(s) were added to refs/heads/main by this push:
new 7c61a82 YETUS-921. Update docs to highlight Docker configuration
functions
7c61a82 is described below
commit 7c61a825f1057feb94046024724d72eec395054e
Author: Clay Baenziger <cbaenzi...@bloomberg.net>
AuthorDate: Mon Oct 21 23:22:44 2019 -0400
YETUS-921. Update docs to highlight Docker configuration functions
Signed-off-by: Allen Wittenauer <a...@apache.org>
---
.../in-progress/precommit-advanced.html.md | 12 ++++++------
.../in-progress/precommit-buildtools.html.md | 18 +++++++++++++-----
precommit/src/main/shell/core.d/docker.sh | 2 +-
3 files changed, 20 insertions(+), 12 deletions(-)
diff --git
a/asf-site-src/source/documentation/in-progress/precommit-advanced.html.md
b/asf-site-src/source/documentation/in-progress/precommit-advanced.html.md
index 919254d..10ccf16 100644
--- a/asf-site-src/source/documentation/in-progress/precommit-advanced.html.md
+++ b/asf-site-src/source/documentation/in-progress/precommit-advanced.html.md
@@ -71,13 +71,13 @@ Similarly, there are other functions that may be defined
during the test-patch r
* pluginname\_usage
* executed when the help message is displayed. This is used to display the
plug-in specific options for the user.
-* pluginname\_parse\_args
+* [pluginname\_parse\_args](../precommit-buildtools#pluginname_parse_args)
* executed prior to any other above functions except for pluginname\_usage.
This is useful for parsing the arguments passed from the user and setting up
the execution environment.
-* pluginname\_initialize
+* [pluginname\_initialize](../precommit-buildtools#pluginname_initialize)
* After argument parsing and prior to any other work, the initialize step
allows a plug-in to do any precursor work, set internal defaults, etc.
-* pluginname\_docker\_support
+*
[pluginname\_docker\_support](../precommit-buildtools#pluginname_docker_support)
* Perform any necessary setup to configure Docker support for the given
plugin. Typically this means adding parameters to the docker run command line
via adding to the DOCKER\_EXTRAARGS array.
* pluginname\_precheck
@@ -130,10 +130,10 @@ add_test_type <pluginname>
* pluginname\_clean
* executed to allow the plugin to remove all files that have been generate
by this plugin.
-* pluginname\_logfilter
+*
[pluginname\_\(test\)\_logfilter](../precommit-buildtools/#pluginname_test_logfilter)
* This functions should filter all lines relevant to this test from the
logfile. It is called in preparation for the `calcdiffs` function.
-* pluginname\_calcdiffs
+*
[pluginname\_\(test\)\_calcdiffs](../precommit-buildtools/#pluginname_test_calcdiffs)
* This allows for custom log file difference calculation used to determine
the before and after views. The default is to use the last column of a colon
delimited line of output and perform a diff. If the plug-in does not provide
enough context, this may result in error skew. For example, if three lines in a
row have "Missing period." as the error, test-patch will not be able to
determine exactly which line caused the error. Plug-ins that have this issue
will want to use this or pote [...]
NOTE: If the plug-in has support for maven, the maven_add_install
`pluginname` should be executed. See more information in Custom Maven Tests in
the build tool documentation.
@@ -265,7 +265,7 @@ There are a handful of extremely important system variables
that make life easie
* CHANGED\_MODULES[@] is an array of all modules that house all of the
CHANGED\_FILES[@]. Be aware that the root of the source tree is reported as
'.'.
-* DOCKER\_EXTRAARGS[@] is an array of command line arguments to apply to the
`docker run` command.
+* [DOCKER\_EXTRAARGS\[@\]](../precommit-buildtools#pluginname_docker_support)
is an array of command line arguments to apply to the `docker run` command.
* GITHUB\_REPO is to help test-patch when talking to Github. If test-patch is
given just a number on the command line, it will default to using this repo to
determine the pull request.
diff --git
a/asf-site-src/source/documentation/in-progress/precommit-buildtools.html.md
b/asf-site-src/source/documentation/in-progress/precommit-buildtools.html.md
index ffc0bd0..dd37646 100644
--- a/asf-site-src/source/documentation/in-progress/precommit-buildtools.html.md
+++ b/asf-site-src/source/documentation/in-progress/precommit-buildtools.html.md
@@ -34,8 +34,8 @@
* [pluginname\_parse\_args](#pluginnameparseargs)
* [pluginname\_initialize](#pluginname_initialize)
* [pluginname\_reorder\_modules](#pluginnamereordermodules)
- * [pluginname\_\(test\)\_logfilter](#pluginnametestlogfilter)
- * [pluginname\_\(test\)_calcdiffs](#pluginnametestcalcdiffs)
+ * [pluginname\_\(test\)\_logfilter](#pluginname_test_logfilter)
+ * [pluginname\_\(test\)\_calcdiffs](#pluginname_test_calcdiffs)
* [pluginname\_docker\_support](#pluginnamedockersupport)
* [Apache Ant Specific](#apache-ant-specific)
* [Ant Command Arguments](#ant-command-arguments)
@@ -54,7 +54,7 @@
<!-- /MarkdownTOC -->
-test-patch has the ability to support multiple build tools. Build tool
plug-ins have some extra hooks to do source and object maintenance at key
points. Every build tool plug-in must have one line in order to be recognized:
+test-patch has the ability to support multiple build tools and
[personalities](../precommit-advanced/#personalities). Build tool and
personality plug-ins have some extra hooks to do source and object maintenance
at key points. Every build tool plug-in must have one line in order to be
recognized:
```bash
add_build_tool <pluginname>
@@ -80,6 +80,8 @@ For example, the gradle build tool does not have a standard
way to execute check
# Required Functions
+Note: In a personality, `pluginname` can be arbitrary.
+
## pluginname\_buildfile
This should be an echo of the file that controls the build system. This is
used for module determination. If the build system wishes to disable module
determination, it should echo with no args.
@@ -124,9 +126,15 @@ Some build tools (e.g., maven) use custom output for
certain types of compilatio
## pluginname\_docker\_support
- If this build tool requires extra settings on the `docker run` command line,
this function should be defined and add those options into an array called
`${DOCKER_EXTRAARGS[@]}`. This is particularly useful for things like mounting
volumes for repository caches.
+To affect the various `docker` command lines, one can use helper functions:
+* Affecting `docker build` command line:
+ * [`add_docker_build_arg`](../precommit-apidocs/core/#add_docker_build_arg)
+* Affecting `docker run` command line:
+ * [`add_docker_env`](../precommit-apidocs/core/#add_docker_env)
+
+If the build tool requires extra settings on the `docker run` command line
(more than environment variables) those options should be added into an array
called `${DOCKER_EXTRAARGS[@]}`. This is particularly useful for things like
mounting volumes for repository caches.
- **WARNING**: Be aware that directories that do not exist MAY be created by
root by Docker itself under certain conditions. It is HIGHLY recommend that
`pluginname_initialize` be used to create the necessary directories prior to be
used in the `docker run` command.
+ **WARNING**: Be aware that directories that do not exist MAY be created by
root by Docker itself under certain conditions. It is HIGHLY recommend that
[`pluginname_initialize`](#pluginname\_initialize) be used to create the
necessary directories prior to use in the `docker run` command.
# Apache Ant Specific
diff --git a/precommit/src/main/shell/core.d/docker.sh
b/precommit/src/main/shell/core.d/docker.sh
index 4d210e9..3d324e8 100755
--- a/precommit/src/main/shell/core.d/docker.sh
+++ b/precommit/src/main/shell/core.d/docker.sh
@@ -576,7 +576,7 @@ function docker_version
## @stability stable
## @replaceable yes
## @param envname
-## @param value
+## @param [value]
function add_docker_build_arg
{
declare key="$1"
