documentation/0.16.0-SNAPSHOT/precommit/buildtools/index.html - yetus - Git at Google

 <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html>
     <head>
         <meta charset="utf-8">
         <title>Apache Yetus</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta name="description" content="">
         <meta name="author" content="">

         <link href="../../../../assets/css/bootstrap.css" rel="stylesheet">
         <link href="../../../../assets/css/bootstrap-theme.css" rel="stylesheet">
         <link href="../../../../assets/css/font-awesome.css" rel="stylesheet">

         <!-- JS -->
         <script type="text/javascript" src="../../../../assets/js/jquery-2.1.4.min.js"></script>
         <script type="text/javascript" src="../../../../assets/js/bootstrap.js"></script>
   </head>
     <body>

 <div class="navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container">
         <div class="navbar-header">
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
             </button>
             <a class="img-responsive pull-left" href="/">
                 <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
             </a>
         </div>
         <div class="navbar-collapse collapse">
             <ul class="nav navbar-nav">
                 <li><a href="/downloads/">Downloads</a>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu">
                       <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
                       <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
                       <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
                       <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
                       </li>
                       <li><a href="/documentation/history/">History of the Project</a>
                       </li>
                     </ul>
                 </li>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
                         </li>
                     </ul>
                 </li>
                 <li>
                     <li class="dropdown">
                         <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
                         <ul class="dropdown-menu" role="menu">
                             <li><a href="https://www.apache.org">Apache Homepage</a>
                             </li>
                             <li><a href="https://www.apache.org/licenses/">Apache License</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                             </li>
                             <li><a href="https://www.apache.org/security/">Security</a>
                             </li>
                         </ul>
                     </li>
                 </li>
             </ul>
         </div>
         <!--/.nav-collapse -->
     </div>
 </div>

       <div class="container">
         <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->
 <!-- markdownlint-disable MD051 -->

 <h1 id="build-tool-support">Build Tool Support</h1>

 <!-- MarkdownTOC levels="1,2" autolink="true" indent="  " bullets="*" bracket="round" -->

 <ul>
   <li><a href="#global-variables">Global Variables</a>
     <ul>
       <li><a href="#buildtoolcwd">BUILDTOOLCWD</a></li>
       <li><a href="#unsupported_test">UNSUPPORTED_TEST</a></li>
     </ul>
   </li>
   <li><a href="#required-functions">Required Functions</a>
     <ul>
       <li><a href="#pluginname_buildfile">pluginname_buildfile</a></li>
       <li><a href="#pluginname_executor">pluginname_executor</a></li>
       <li><a href="#pluginname_modules_worker">pluginname_modules_worker</a></li>
       <li><a href="#pluginname_builtin_personality_modules">pluginname_builtin_personality_modules</a></li>
       <li><a href="#pluginname_builtin_personality_file_tests">pluginname_builtin_personality_file_tests</a></li>
     </ul>
   </li>
   <li><a href="#optional-functions">Optional Functions</a>
     <ul>
       <li><a href="#pluginname_parse_args">pluginname_parse_args</a></li>
       <li><a href="#pluginname_initialize">pluginname_initialize</a></li>
       <li><a href="#pluginname_reorder_modules">pluginname_reorder_modules</a></li>
       <li><a href="#pluginname_test_logfilter">pluginname_(test)_logfilter</a></li>
       <li><a href="#pluginname_test_calcdiffs">pluginname_(test)_calcdiffs</a></li>
       <li><a href="#pluginname_docker_support">pluginname_docker_support</a></li>
     </ul>
   </li>
   <li><a href="#apache-ant-specific">Apache Ant Specific</a>
     <ul>
       <li><a href="#ant-command-arguments">Ant Command Arguments</a></li>
       <li><a href="#ant-in-docker-mode">Ant in Docker Mode</a></li>
     </ul>
   </li>
   <li><a href="#autoconf-specific">autoconf Specific</a>
     <ul>
       <li><a href="#autoconf-command-arguments">autoconf Command Arguments</a></li>
     </ul>
   </li>
   <li><a href="#cmake-specific">CMAKE Specific</a></li>
   <li><a href="#gradle-specific">Gradle Specific</a></li>
   <li><a href="#make-specific">Make Specific</a></li>
   <li><a href="#apache-maven-specific">Apache Maven Specific</a>
     <ul>
       <li><a href="#command-arguments">Command Arguments</a></li>
       <li><a href="#per-instance-repositories">Per-instance Repositories</a></li>
       <li><a href="#maven-in-docker-mode">Maven in Docker Mode</a></li>
       <li><a href="#test-profile">Test Profile</a></li>
       <li><a href="#custom-maven-tests">Custom Maven Tests</a></li>
     </ul>
   </li>
 </ul>

 <!-- /MarkdownTOC -->

 <p>test-patch has the ability to support multiple build tools and <a href="../advanced/#personalities">personalities</a>.  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:</p>

 <div class="highlight"><pre class="highlight shell"><code>add_build_tool &lt;pluginname&gt;
 </code></pre></div>
 <h1 id="global-variables">Global Variables</h1>

 <h2 id="buildtoolcwd">BUILDTOOLCWD</h2>

 <p>This variable determines where the build tool's command (as returned by pluginname_executor) should actually execute.  It should be one of three values:</p>

 <ul>
   <li>basedir  - always execute at the root of the source tree</li>
   <li>module   - (default) switch to the directory as given by the module being processed</li>
   <li>/(path)  - change to the directory as given by this absolute path. This allows for custom directories to be created and used as necessary.  If the path does not exist, it will be created. If /(path) is used, two special substitutions may be made:
     <ul>
       <li>@@@BASEDIR@@@ will be replaced with the root of the source tree</li>
       <li>@@@MODULEDIR@@@ will be replaced with the module name</li>
     </ul>
   </li>
 </ul>

 <h2 id="unsupported_test">UNSUPPORTED_TEST</h2>

 <p>If pluginname_modules_worker is given a test type that is not supported by the build system, set UNSUPPORTED_TEST=true.  If it is supported, set UNSUPPORTED_TEST=false.</p>

 <p>For example, the gradle build tool does not have a standard way to execute checkstyle. So when checkstyle is requested, gradle_modules_worker sets UNSUPPORTED_TEST to true and returns out of the routine.</p>

 <h1 id="required-functions">Required Functions</h1>

 <p>Note: In a personality, <code>pluginname</code> can be arbitrary.</p>

 <h2 id="pluginname_buildfile">pluginname_buildfile</h2>

 <p>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.</p>

 <h2 id="pluginname_executor">pluginname_executor</h2>

 <p>This should be an echo of how to run the build tool, any extra arguments, etc.</p>

 <h2 id="pluginname_modules_worker">pluginname_modules_worker</h2>

 <p>Input is the branch and the test being run.  This should call <code>modules_workers</code> with the generic parts to run that test on the build system.  For example, if it is convention to use 'test' to trigger 'unit' tests, then <code>modules_workers</code> should be called with 'test' appended onto its normal parameters.</p>

 <h2 id="pluginname_builtin_personality_modules">pluginname_builtin_personality_modules</h2>

 <p>Default method to determine how to enqueue modules for processing.  Note that personalities may override this function. Requires two arguments: repo status and test desired. For example, in a maven build, values may be 'branch' and 'mvninstall'.</p>

 <h2 id="pluginname_builtin_personality_file_tests">pluginname_builtin_personality_file_tests</h2>

 <p>Default method to determine which tests to trigger.  Note that personalities may override this function. Requires a single argument: the file in which the tests exist.</p>

 <h1 id="optional-functions">Optional Functions</h1>

 <h2 id="pluginname_parse_args">pluginname_parse_args</h2>

 <p>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.</p>

 <h2 id="pluginname_initialize">pluginname_initialize</h2>

 <p>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.</p>

 <h2 id="pluginname_reorder_modules">pluginname_reorder_modules</h2>

 <p>This functions allows the plugin to (re-)order the modules (e.g. based on the output of the maven dependency plugin). When called CHANGED_MODULES[@] already contains all changed modules. It must be altered to have an effect.</p>

 <h2 id="pluginname_test_logfilter">pluginname_(test)_logfilter</h2>

 <p>This functions should filter all lines relevant to this test from the logfile. It is called in preparation for the <code>calcdiffs</code> function. The test plug-in name should be in the (test) part of the function name.</p>

 <h2 id="pluginname_test_calcdiffs">pluginname_(test)_calcdiffs</h2>

 <p>Some build tools (e.g., maven) use custom output for certain types of compilations (e.g., java).  This allows for custom log file difference calculation used to determine the before and after views.</p>

 <h2 id="pluginname_docker_support">pluginname_docker_support</h2>

 <p>To affect the various <code>docker</code> command lines, one can use helper functions:</p>

 <ul>
   <li>Affecting <code>docker build</code> command line:
     <ul>
       <li><a href="../apidocs/core/#add_docker_build_arg"><code>add_docker_build_arg</code></a></li>
     </ul>
   </li>
   <li>Affecting <code>docker run</code> command line:
     <ul>
       <li><a href="../apidocs/core/#add_docker_env"><code>add_docker_env</code></a></li>
     </ul>
   </li>
 </ul>

 <p>If the build tool requires extra settings on the <code>docker run</code> command line (more than environment variables) those options should be added into an array called <code>${DOCKER_EXTRAARGS[@]}</code>. This is particularly useful for things like mounting volumes for repository caches.</p>

 <div class="highlight"><pre class="highlight plaintext"><code>**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.
 </code></pre></div>
 <h1 id="apache-ant-specific">Apache Ant Specific</h1>

 <h2 id="ant-command-arguments">Ant Command Arguments</h2>

 <p>test-patch always passes -noinput to Ant.  This forces ant to be non-interactive.</p>

 <h2 id="ant-in-docker-mode">Ant in Docker Mode</h2>

 <p>In Docker mode, the <code>${HOME}/.ivy2</code> directory is shared amongst all invocations.</p>

 <h1 id="autoconf-specific">autoconf Specific</h1>

 <p>autoconf requires make to be enabled.  autoreconf is always used to rebuild the configure script.</p>

 <h2 id="autoconf-command-arguments">autoconf Command Arguments</h2>

 <p>autoconf will always run configure with prefix set to a directory in the patch processing directory.  To configure other flags, set the AUTCONF_CONF_FLAGS environment variable.</p>

 <h1 id="cmake-specific">CMAKE Specific</h1>

 <p>By default, cmake will create a 'build' directory and perform all work there.  This may be changed either on the command line or via a personality setting.  cmake requires make to be enabled.</p>

 <h1 id="gradle-specific">Gradle Specific</h1>

 <p>The gradle plug-in always rebuilds the gradlew file and uses gradlew as the method to execute commands.</p>

 <p>In Docker mode, the <code>${HOME}/.gradle</code> directory is shared amongst all invocations.</p>

 <h1 id="make-specific">Make Specific</h1>

 <p>No notes.</p>

 <h1 id="apache-maven-specific">Apache Maven Specific</h1>

 <h2 id="command-arguments">Command Arguments</h2>

 <p>test-patch always passes –batch-mode to maven to force it into non-interactive mode.  Additionally, some tests will also force -fae in order to get all of messages/errors during that mode. Some tests are executed with -DskipTests.  Additional arguments should be handled via the personality.</p>

 <h2 id="per-instance-repositories">Per-instance Repositories</h2>

 <p>Under many common configurations, maven (as of 3.3.3 and lower) may not properly handle being executed by multiple processes simultaneously, especially given that some tests require the <code>mvn install</code> command to be used.</p>

 <p>To assist, <code>test-patch</code> supports a <code>--mvn-custom-repos</code> option to set the <code>-Dmaven.repo.local</code> value to a per-instance repository directory keyed to the project and branch being used for the test.  If the <code>--jenkins</code> flag is also passed, the instance will be tied to the Jenkins <code>${EXECUTOR_NUMBER}</code> value.  Otherwise, the instance value will be randomly generated via <code>${RANDOM}</code>.  If the repository has not been used in 30 days, it will be automatically deleted when any test run for that project (regardless of branch!).</p>

 <p>By default, <code>test-patch</code> uses <code>${HOME}/yetus-m2</code> as the base directory to store these custom maven repositories.  That location may be changed via the <code>--mvn-custom-repos-dir</code> option.</p>

 <p>The location of the <code>settings.xml</code> may be changed via the <code>--mvn-settings</code> option.</p>

 <h2 id="maven-in-docker-mode">Maven in Docker Mode</h2>

 <p>In Docker mode, <code>${HOME}/.m2</code> is shared amongst all invocations.  If <code>--mvn-custom-repos</code> is used, all of <code>--mvn-custom-repos-dir</code> is shared with all invocations.  The per-instance directory will be calculated and configured after Docker has launched.</p>

 <h2 id="test-profile">Test Profile</h2>

 <p>By default, test-patch will pass -Ptest-patch to Maven. This will allow you to configure special actions that should only happen when running underneath test-patch.</p>

 <h2 id="custom-maven-tests">Custom Maven Tests</h2>

 <p>Maven will test eclipse and site if maven is being used as the build tool and appropriate files trigger them.</p>

 <p>Maven will trigger add a maven install test when the <code>maven_add_install</code> function has been used and the related tests are required. Plug-ins that need to run maven before MUST call it as part of their respective initialize functions, otherwise maven may fail unexpectedly.  All Apache Yetus provided plug-ins that require maven will trigger the maven install functionality.</p>

     </div>

 <div class="container">
     <hr>
     <footer class="footer">
         <div class="row-fluid">
             <div class="span12 text-left">
               <div class="span12">
                 Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
               </div>
             </div>

         </div>

     </footer>
 </div>

   </body>
 </html>
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Yetus</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="description" content="">
	<meta name="author" content="">

	<link href="../../../../assets/css/bootstrap.css" rel="stylesheet">
	<link href="../../../../assets/css/bootstrap-theme.css" rel="stylesheet">
	<link href="../../../../assets/css/font-awesome.css" rel="stylesheet">

	<!-- JS -->
	<script type="text/javascript" src="../../../../assets/js/jquery-2.1.4.min.js"></script>
	<script type="text/javascript" src="../../../../assets/js/bootstrap.js"></script>
	</head>
	<body>

	<div class="navbar navbar-inverse navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="img-responsive pull-left" href="/">
	<img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
	</a>
	</div>
	<div class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li><a href="/downloads/">Downloads</a>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
	<li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
	<li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
	<li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
	</li>
	<li><a href="/documentation/history/">History of the Project</a>
	</li>
	</ul>
	</li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
	</li>
	</ul>
	</li>
	<li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="https://www.apache.org">Apache Homepage</a>
	</li>
	<li><a href="https://www.apache.org/licenses/">Apache License</a>
	</li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	</li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	</li>
	<li><a href="https://www.apache.org/security/">Security</a>
	</li>
	</ul>
	</li>
	</li>
	</ul>
	</div>
	<!--/.nav-collapse -->
	</div>
	</div>

	<div class="container">
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<!-- markdownlint-disable MD051 -->

	<h1 id="build-tool-support">Build Tool Support</h1>

	<!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" -->

	<ul>
	<li><a href="#global-variables">Global Variables</a>
	<ul>
	<li><a href="#buildtoolcwd">BUILDTOOLCWD</a></li>
	<li><a href="#unsupported_test">UNSUPPORTED_TEST</a></li>
	</ul>
	</li>
	<li><a href="#required-functions">Required Functions</a>
	<ul>
	<li><a href="#pluginname_buildfile">pluginname_buildfile</a></li>
	<li><a href="#pluginname_executor">pluginname_executor</a></li>
	<li><a href="#pluginname_modules_worker">pluginname_modules_worker</a></li>
	<li><a href="#pluginname_builtin_personality_modules">pluginname_builtin_personality_modules</a></li>
	<li><a href="#pluginname_builtin_personality_file_tests">pluginname_builtin_personality_file_tests</a></li>
	</ul>
	</li>
	<li><a href="#optional-functions">Optional Functions</a>
	<ul>
	<li><a href="#pluginname_parse_args">pluginname_parse_args</a></li>
	<li><a href="#pluginname_initialize">pluginname_initialize</a></li>
	<li><a href="#pluginname_reorder_modules">pluginname_reorder_modules</a></li>
	<li><a href="#pluginname_test_logfilter">pluginname_(test)_logfilter</a></li>
	<li><a href="#pluginname_test_calcdiffs">pluginname_(test)_calcdiffs</a></li>
	<li><a href="#pluginname_docker_support">pluginname_docker_support</a></li>
	</ul>
	</li>
	<li><a href="#apache-ant-specific">Apache Ant Specific</a>
	<ul>
	<li><a href="#ant-command-arguments">Ant Command Arguments</a></li>
	<li><a href="#ant-in-docker-mode">Ant in Docker Mode</a></li>
	</ul>
	</li>
	<li><a href="#autoconf-specific">autoconf Specific</a>
	<ul>
	<li><a href="#autoconf-command-arguments">autoconf Command Arguments</a></li>
	</ul>
	</li>
	<li><a href="#cmake-specific">CMAKE Specific</a></li>
	<li><a href="#gradle-specific">Gradle Specific</a></li>
	<li><a href="#make-specific">Make Specific</a></li>
	<li><a href="#apache-maven-specific">Apache Maven Specific</a>
	<ul>
	<li><a href="#command-arguments">Command Arguments</a></li>
	<li><a href="#per-instance-repositories">Per-instance Repositories</a></li>
	<li><a href="#maven-in-docker-mode">Maven in Docker Mode</a></li>
	<li><a href="#test-profile">Test Profile</a></li>
	<li><a href="#custom-maven-tests">Custom Maven Tests</a></li>
	</ul>
	</li>
	</ul>

	<!-- /MarkdownTOC -->

	<p>test-patch has the ability to support multiple build tools and <a href="../advanced/#personalities">personalities</a>. 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:</p>

	<div class="highlight"><pre class="highlight shell"><code>add_build_tool <pluginname>
	</code></pre></div>
	<h1 id="global-variables">Global Variables</h1>

	<h2 id="buildtoolcwd">BUILDTOOLCWD</h2>

	<p>This variable determines where the build tool's command (as returned by pluginname_executor) should actually execute. It should be one of three values:</p>

	<ul>
	<li>basedir - always execute at the root of the source tree</li>
	<li>module - (default) switch to the directory as given by the module being processed</li>
	<li>/(path) - change to the directory as given by this absolute path. This allows for custom directories to be created and used as necessary. If the path does not exist, it will be created. If /(path) is used, two special substitutions may be made:
	<ul>
	<li>@@@BASEDIR@@@ will be replaced with the root of the source tree</li>
	<li>@@@MODULEDIR@@@ will be replaced with the module name</li>
	</ul>
	</li>
	</ul>

	<h2 id="unsupported_test">UNSUPPORTED_TEST</h2>

	<p>If pluginname_modules_worker is given a test type that is not supported by the build system, set UNSUPPORTED_TEST=true. If it is supported, set UNSUPPORTED_TEST=false.</p>

	<p>For example, the gradle build tool does not have a standard way to execute checkstyle. So when checkstyle is requested, gradle_modules_worker sets UNSUPPORTED_TEST to true and returns out of the routine.</p>

	<h1 id="required-functions">Required Functions</h1>

	<p>Note: In a personality, <code>pluginname</code> can be arbitrary.</p>

	<h2 id="pluginname_buildfile">pluginname_buildfile</h2>

	<p>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.</p>

	<h2 id="pluginname_executor">pluginname_executor</h2>

	<p>This should be an echo of how to run the build tool, any extra arguments, etc.</p>

	<h2 id="pluginname_modules_worker">pluginname_modules_worker</h2>

	<p>Input is the branch and the test being run. This should call <code>modules_workers</code> with the generic parts to run that test on the build system. For example, if it is convention to use 'test' to trigger 'unit' tests, then <code>modules_workers</code> should be called with 'test' appended onto its normal parameters.</p>

	<h2 id="pluginname_builtin_personality_modules">pluginname_builtin_personality_modules</h2>

	<p>Default method to determine how to enqueue modules for processing. Note that personalities may override this function. Requires two arguments: repo status and test desired. For example, in a maven build, values may be 'branch' and 'mvninstall'.</p>

	<h2 id="pluginname_builtin_personality_file_tests">pluginname_builtin_personality_file_tests</h2>

	<p>Default method to determine which tests to trigger. Note that personalities may override this function. Requires a single argument: the file in which the tests exist.</p>

	<h1 id="optional-functions">Optional Functions</h1>

	<h2 id="pluginname_parse_args">pluginname_parse_args</h2>

	<p>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.</p>

	<h2 id="pluginname_initialize">pluginname_initialize</h2>

	<p>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.</p>

	<h2 id="pluginname_reorder_modules">pluginname_reorder_modules</h2>

	<p>This functions allows the plugin to (re-)order the modules (e.g. based on the output of the maven dependency plugin). When called CHANGED_MODULES[@] already contains all changed modules. It must be altered to have an effect.</p>

	<h2 id="pluginname_test_logfilter">pluginname_(test)_logfilter</h2>

	<p>This functions should filter all lines relevant to this test from the logfile. It is called in preparation for the <code>calcdiffs</code> function. The test plug-in name should be in the (test) part of the function name.</p>

	<h2 id="pluginname_test_calcdiffs">pluginname_(test)_calcdiffs</h2>

	<p>Some build tools (e.g., maven) use custom output for certain types of compilations (e.g., java). This allows for custom log file difference calculation used to determine the before and after views.</p>

	<h2 id="pluginname_docker_support">pluginname_docker_support</h2>

	<p>To affect the various <code>docker</code> command lines, one can use helper functions:</p>

	<ul>
	<li>Affecting <code>docker build</code> command line:
	<ul>
	<li><a href="../apidocs/core/#add_docker_build_arg"><code>add_docker_build_arg</code></a></li>
	</ul>
	</li>
	<li>Affecting <code>docker run</code> command line:
	<ul>
	<li><a href="../apidocs/core/#add_docker_env"><code>add_docker_env</code></a></li>
	</ul>
	</li>
	</ul>

	<p>If the build tool requires extra settings on the <code>docker run</code> command line (more than environment variables) those options should be added into an array called <code>${DOCKER_EXTRAARGS[@]}</code>. This is particularly useful for things like mounting volumes for repository caches.</p>

	<div class="highlight"><pre class="highlight plaintext"><code>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.
	</code></pre></div>
	<h1 id="apache-ant-specific">Apache Ant Specific</h1>

	<h2 id="ant-command-arguments">Ant Command Arguments</h2>

	<p>test-patch always passes -noinput to Ant. This forces ant to be non-interactive.</p>

	<h2 id="ant-in-docker-mode">Ant in Docker Mode</h2>

	<p>In Docker mode, the <code>${HOME}/.ivy2</code> directory is shared amongst all invocations.</p>

	<h1 id="autoconf-specific">autoconf Specific</h1>

	<p>autoconf requires make to be enabled. autoreconf is always used to rebuild the configure script.</p>

	<h2 id="autoconf-command-arguments">autoconf Command Arguments</h2>

	<p>autoconf will always run configure with prefix set to a directory in the patch processing directory. To configure other flags, set the AUTCONF_CONF_FLAGS environment variable.</p>

	<h1 id="cmake-specific">CMAKE Specific</h1>

	<p>By default, cmake will create a 'build' directory and perform all work there. This may be changed either on the command line or via a personality setting. cmake requires make to be enabled.</p>

	<h1 id="gradle-specific">Gradle Specific</h1>

	<p>The gradle plug-in always rebuilds the gradlew file and uses gradlew as the method to execute commands.</p>

	<p>In Docker mode, the <code>${HOME}/.gradle</code> directory is shared amongst all invocations.</p>

	<h1 id="make-specific">Make Specific</h1>

	<p>No notes.</p>

	<h1 id="apache-maven-specific">Apache Maven Specific</h1>

	<h2 id="command-arguments">Command Arguments</h2>

	<p>test-patch always passes –batch-mode to maven to force it into non-interactive mode. Additionally, some tests will also force -fae in order to get all of messages/errors during that mode. Some tests are executed with -DskipTests. Additional arguments should be handled via the personality.</p>

	<h2 id="per-instance-repositories">Per-instance Repositories</h2>

	<p>Under many common configurations, maven (as of 3.3.3 and lower) may not properly handle being executed by multiple processes simultaneously, especially given that some tests require the <code>mvn install</code> command to be used.</p>

	<p>To assist, <code>test-patch</code> supports a <code>--mvn-custom-repos</code> option to set the <code>-Dmaven.repo.local</code> value to a per-instance repository directory keyed to the project and branch being used for the test. If the <code>--jenkins</code> flag is also passed, the instance will be tied to the Jenkins <code>${EXECUTOR_NUMBER}</code> value. Otherwise, the instance value will be randomly generated via <code>${RANDOM}</code>. If the repository has not been used in 30 days, it will be automatically deleted when any test run for that project (regardless of branch!).</p>

	<p>By default, <code>test-patch</code> uses <code>${HOME}/yetus-m2</code> as the base directory to store these custom maven repositories. That location may be changed via the <code>--mvn-custom-repos-dir</code> option.</p>

	<p>The location of the <code>settings.xml</code> may be changed via the <code>--mvn-settings</code> option.</p>

	<h2 id="maven-in-docker-mode">Maven in Docker Mode</h2>

	<p>In Docker mode, <code>${HOME}/.m2</code> is shared amongst all invocations. If <code>--mvn-custom-repos</code> is used, all of <code>--mvn-custom-repos-dir</code> is shared with all invocations. The per-instance directory will be calculated and configured after Docker has launched.</p>

	<h2 id="test-profile">Test Profile</h2>

	<p>By default, test-patch will pass -Ptest-patch to Maven. This will allow you to configure special actions that should only happen when running underneath test-patch.</p>

	<h2 id="custom-maven-tests">Custom Maven Tests</h2>

	<p>Maven will test eclipse and site if maven is being used as the build tool and appropriate files trigger them.</p>

	<p>Maven will trigger add a maven install test when the <code>maven_add_install</code> function has been used and the related tests are required. Plug-ins that need to run maven before MUST call it as part of their respective initialize functions, otherwise maven may fail unexpectedly. All Apache Yetus provided plug-ins that require maven will trigger the maven install functionality.</p>

	</div>

	<div class="container">
	<hr>
	<footer class="footer">
	<div class="row-fluid">
	<div class="span12 text-left">
	<div class="span12">
	Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
	</div>
	</div>

	</div>

	</footer>
	</div>

	</body>
	</html>