[JENKINS-29267] CMAKE_BUILD_TOOL: added online doc according to solution

#1
jenkinsci · Aug 15, 2015 · 995633b · 995633b
1 parent fb2e64d
commit 995633b
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 50 deletions.
diff --git a/src/main/resources/hudson/plugins/cmake/BuildToolStep/config.jelly b/src/main/resources/hudson/plugins/cmake/BuildToolStep/config.jelly
@@ -1,5 +1,8 @@
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
+  <f:entry title="${%Use cmake}" field="withCmake" name="NAME">
+    <f:checkbox />
+  </f:entry>
   <f:entry title="${%Arguments}" field="args">
     <f:textbox />
   </f:entry>

diff --git a/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-args.html b/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-args.html
@@ -1,4 +1,4 @@
 <div>
-Specify arguments to pass to the build tool (separated by spaces).<br> 
+Specify arguments to pass to the build tool or <code>cmake</code> (separated by spaces).<br> 
 Arguments may contain spaces if they are enclosed in double quotes. 
 </div>
diff --git a/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-envVars.html b/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-envVars.html
@@ -1,6 +1,6 @@
 <div>
 Specify extra environment variables to pass to the build tool as key-value pairs here.<br>
-Each entry must be on its own line.<br>
+Each entry must be on its own line, for example:<br>
 <code>DESTDIR=path/to/dir<br>
 KEY=VALUE<br><code>
 </div>
diff --git a/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-withCmake.html b/src/main/resources/hudson/plugins/cmake/BuildToolStep/help-withCmake.html
@@ -0,0 +1,9 @@
+<div>
+Whether to run the actual build tool directly (by expanding <code>$CMAKE_BUILD_TOOL</code>)
+or to have <code>cmake</code> run the build tool (by invoking <code>cmake --build</code>).
+<ul>
+<li>Leave unchecked for minimal overhead.</li>
+<li>Check this, if you selected one of the <em>Visual Studio</em> or <em>Xcode</em> generators
+above <strong>AND</strong> if you run CMake v. 3.0 or newer.</li>
+<ul>
+</div>
diff --git a/src/main/resources/hudson/plugins/cmake/CmakeBuilder/config.jelly b/src/main/resources/hudson/plugins/cmake/CmakeBuilder/config.jelly
@@ -3,7 +3,7 @@
   <f:entry title="${%CMake installation}" field="installationName">
     <f:select />
   </f:entry>
-  <f:entry title="Buildscript Generator" field="generator">
+  <f:entry title="Script Generator" field="generator">
     <f:textbox default="Unix Makefiles" />
   </f:entry>
   <f:entry title="Source Directory" field="sourceDir">
@@ -23,19 +23,12 @@
     <f:entry title="Preload Script" field="preloadScript">
       <f:textbox />
     </f:entry>
-
     <f:entry title="Other CMake Arguments" field="cmakeArgs">
       <f:expandableTextbox />
     </f:entry>
   </f:advanced>
   <!--
   -->
-  <!--
-    <f:block>
-    <f:optionalBlock title="${%Show Build tool invocations}" help="help-run-tool.html">
-    <f:entry>
-  help="help-run-tool.html">
-  -->
   <f:entry title="${%Build tool}&lt;br>${%invocations}" field="runTool" >
     <f:repeatable field="steps" header="${%Run build tool}" add="${%Add build tool invocation}">
       <table width="100%">
@@ -50,28 +43,4 @@
   </f:entry>
   <!--
   -->
-  <!--
-    </f:optionalBlock>
-    </f:block>
-  -->
-  <!--
-    <f:entry title="Make Command" field="makeCommand">
-    <f:textbox />
-    </f:entry>
-    <f:entry title="Wipeout Install Dir" field="cleanInstallDir">
-    <f:checkbox />
-    </f:entry>
-    <f:entry title="Install Directory" field="installDir">
-    <f:textbox />
-    </f:entry>
-    <f:entry title="Install Command" field="installCommand">
-    <f:textbox />
-    </f:entry>
-    <f:entry title="Install Directory" field="installDir">
-    <f:textbox />
-    </f:entry>
-    <f:entry title="Install Command" field="installCommand">
-    <f:textbox />
-    </f:entry>
-  -->
 </j:jelly>
diff --git a/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help-generator.html b/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help-generator.html
@@ -16,13 +16,14 @@
 <li><a class="reference internal" href="http://www.cmake.org/cmake/help/v3.0/generator/Xcode.html">Xcode</a></li>
  </ul>
  <p>
- The build tool chosen by CMake &mdash; corresponding to the generator &mdash;
- is exposed in the
- <code><strong>CMAKE_BUILD_TOOL</strong></code> build environment variable.
- Subsequent build steps may use <code>$CMAKE_BUILD_TOOL}</code> 
- to execute the generated scripts.<br>
- Its actual value is retrieved from the generated CMake cache file
- (<code>CMakeCache.txt</code>). Usually that value is something like 
- <code>/usr/bin/gmake</code> on Linux.
+ The build tool chosen by CMake corresponds to the specified script generator
+ and is exposed in the
+ <code><strong>CMAKE_BUILD_TOOL</strong></code> build environment variable for any generator
+ except the <em>Visual Studio</em> and <em>Xcode</em> generators
+ (these generators do not set <code>CMAKE_MAKE_PROGRAM</code> at buildscript generation time).<br>
+ The actual value of <code><strong>CMAKE_BUILD_TOOL</strong></code> is retrieved
+ from the generated CMake cache file (<code>CMakeCache.txt</code>).<br>
+ Subsequent build steps may use <code>${CMAKE_BUILD_TOOL}</code> 
+ to execute the generated scripts.
  </p> 
 </div>
diff --git a/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help-runTool.html b/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help-runTool.html
@@ -1,9 +1,3 @@
 <div>
-Invocations of <code>$CMAKE_BUILD_TOOL</code>, which evaluates to the actual
-build tool that operates on the generated build scripts.<br>
-Would run <code>/usr/bin/gmake</code> if, for example, 
-the "Unix Makefiles" generator was specified and the build node
-is runnung under Linux. 
-<code><strong>$CMAKE_BUILD_TOOL</strong></code> will be started directly
-without any commandline shell.
+Invocations of the actual build tool (e.g. <code>make</code> or <code>ninja</code>).
 </div>
diff --git a/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help.html b/src/main/resources/hudson/plugins/cmake/CmakeBuilder/help.html
@@ -1,5 +1,6 @@
 <div>For projects that use CMake to generate build-scripts.
   This causes Jenkins to invoke cmake with the given options.</br>
   Any non-zero exit code during build-script generation causes Jenkins to mark the build as a failure.</br>
-  Exposes the <code><strong>CMAKE_BUILD_TOOL</strong></code> build environment variable.
+  It also can expose the <code><strong>CMAKE_BUILD_TOOL</strong></code> build environment variable
+  if the chosen generator supports that.
 </div>