Skip to content

Commit

Permalink
Merge pull request #2137 from orrc/JENKINS-33364_freestyle-config
Browse files Browse the repository at this point in the history 
[JENKINS-33364] Core documentation: Freestyle project config
  • Loading branch information
@daniel-beck
daniel-beck committed Apr 6, 2016
2 parents 4cb3f4e + a07f408 commit 25340e0
Show file tree
Hide file tree
Showing 36 changed files with 336 additions and 173 deletions.
26 changes: 12 additions & 14 deletions core/src/main/resources/hudson/model/AbstractItem/help-slaveAffinity.html
View file
@@ -1,17 +1,15 @@
<div>
Sometimes a project can only be successfully built on a particular agent
(or master). If so, this option forces Jenkins to always build this project
on a specific computer.

If there is a group of machines that the job can be built on, you can specify
that label as the node to tie on, which will cause Jenkins to build the
project on any of the machines with that label.

By default, builds of this project may be executed on any build agents that
are available and configured to accept new builds.
<p>
Otherwise, uncheck the box so that Jenkins can schedule builds on available
nodes, which results in faster turn-around time.

When this option is checked, you have the possibility to ensure that builds of
this project only occur on a certain agent, or set of agents.
<p>
This option is also useful when you'd like to make sure that a project can
be built on a particular node.
</div>
For example, if your project should only be built on a certain operating
system, or on machines that have a certain set of tools installed, or even one
specific machine, you can restrict this project to only execute on agents that
that meet those criteria.
<p>
The help text for the <i>Label Expression</i> field, shown when this option is
checked, provides more detailed information on how to specify agent criteria.
</div>
59 changes: 37 additions & 22 deletions core/src/main/resources/hudson/model/AbstractProject/help-concurrentBuild.html
View file
@@ -1,24 +1,39 @@
<div>
If this option is checked, Jenkins will schedule and execute multiple builds concurrently (provided
that you have sufficient executors and incoming build requests.) This is useful on builds and test jobs that
take a long time, as each build will only contain a smaller number of changes, and the total turn-around
time decreases due to the shorter time a build request spends waiting for the previous build to complete.
It is also very useful with parameterized builds, whose individual executions are independent from each other.

<p>
For other kinds of jobs, allowing concurrent executions of multiple builds may be problematic,
for example if it assumes a monopoly on a certain resource, like database, or for jobs where you use Jenkins
as a cron replacement.

<p>
If you use a custom workspace and enable this option, all your builds will run on the same workspace,
thus unless a care is taken by your side, it'll likely to collide with each other.
Otherwise, even when they are run on the same node, Jenkins will use different workspaces to keep
them isolated.

<p>
When Jenkins creates different workspaces for isolation, Jenkins appends "@<I>num</I>" to the
workspace directory name, e.g. "@2". The separator "@" can be configured by setting the system property
"hudson.slaves.WorkspaceList" to the desired separator string on the Jenkins command line.
E.g. "-Dhudson.slaves.WorkspaceList=-" will use a dash as separator.
<div>
When this option is checked, multiple builds of this project may be executed
in parallel.
<p>
By default, only a single build of a project is executed at a time &mdash; any
other requests to start building that project will remain in the build queue
until the first build is complete.<br>
This is a safe default, as projects can often require exclusive access to
certain resources, such as a database, or a piece of hardware.
<p>
But with this option enabled, if there are enough build executors available
that can handle this project, then multiple builds of this project will take
place in parallel. If there are not enough available executors at any point,
any further build requests will be held in the build queue as normal.
<p>
Enabling concurrent builds is useful for projects that execute lengthy test
suites, as it allows each build to contain a smaller number of changes, while
the total turnaround time decreases as subsequent builds do not need to wait
for previous test runs to complete.<br>
This feature is also useful for parameterised projects, whose individual build
executions &mdash; depending on the parameters used &mdash; can be
completely independent from one another.
<p>
Each concurrently executed build occurs in its own build workspace, isolated
from any other builds. By default, Jenkins appends "<tt>@&lt;num&gt;</tt>" to
the workspace directory name, e.g. "<tt>@2</tt>".<br>
The separator "<tt>@</tt>" can be changed by setting the
<tt>hudson.slaves.WorkspaceList</tt> Java system property when starting
Jenkins. For example, "<tt>hudson.slaves.WorkspaceList=-</tt>" would change
the separator to a hyphen.<br>
For more information on setting system properties, see the <a
href="https://wiki.jenkins-ci.org/display/JENKINS/Features+controlled+by+system+properties"
target="_blank">wiki page</a>.
<p>
However, if you enable the <i>Use custom workspace</i> option, all builds will
be executed in the same workspace. Therefore caution is required, as multiple
builds may end up altering the same directory at the same time.
</div>
176 changes: 126 additions & 50 deletions core/src/main/resources/hudson/model/AbstractProject/help-label.html
View file
@@ -1,52 +1,128 @@
<div>
If you want to always run this project on a specific agent, just specify its name.
This works well when you have a small number of nodes.

<p>
As the size of the cluster grows, it becomes useful not to tie projects to specific agents,
as it hurts resource utilization when agents may come and go. For such situation, assign labels
to agents to classify their capabilities and characteristics, and specify a boolean expression
over those labels to decide where to run.

<h3>Valid Operators</h3>
<p>
The following operators are supported, in the order of precedence.
<dl>
<dt>(expr)</dt>
<dd>parenthesis</dd>

<dt>!expr</dt>
<dd>negation</dd>

<dt>expr&amp;&amp;expr</dt>
<dd>
and
</dd>

<dt>expr||expr</dt>
<dd>
or
</dd>

<dt>a -> b</dt>
<dd>
"implies" operator. Equivalent to <tt>!a|b</tt>.
For example, <tt>windows->x64</tt> could be thought of as "if run on a Windows agent,
that agent must be 64bit." It still allows Jenkins to run this build on linux.
</dd>

<dt>a &lt;-> b</dt>
<dd>
"if and only if" operator. Equivalent to <tt>a&amp;&amp;b || !a&amp;&amp;!b</tt>.
For example, <tt>windows&lt;->sfbay</tt> could be thought of as "if run on a Windows agent,
that agent must be in the SF bay area, but if not on Windows, it must not be in the bay area."
</dd>
</dl>
<p>
All operators are left-associative (i.e., a->b->c &lt;-> (a->b)->c )
An expression can contain whitespace for better readability, and it'll be ignored.

<p>
Label names or agent names can be quoted if they contain unsafe characters. For example,
<tt>"jenkins-solaris (Solaris)" || "Windows 2008"</tt>
Defines a logical expression which determines which agents may execute builds
of this project. This expression, when tested against the name and labels of
each available agent, will be either <i>true</i> or <i>false</i>. If the
expression evaluates to <i>true</i>, then that agent will be allowed to
execute builds of this project.
<p>
If this project should always be built on a specific agent, or on the Jenkins
master, then you can just enter the agent's name, or <code>master</code>,
respectively.
<p>
However, you should generally avoid using the <i>Name</i> of an agent here,
preferring to target the <i>Labels</i> of an agent. As documented on the
configuration page for each agent, and the <i>Configure System</i> page for
the master, labels can be used to represent which operating system the agent
is running on, its CPU architecture, or any number of other characteristics.
<br>
Using labels removes the need to re-configure the label expression entered
here each time that you add, remove, or rename agents.
<p>
A label expression can be as simple as entering a single <b>label</b> or
<b>agent name</b>, for example <code>android-builder</code>, or
<code>linux-machine-42</code>.<br>
You can also make use of various <i>operators</i> to create more complex
expressions.

<h3>Supported operators</h3>
The following operators are supported, in descending order of precedence:
<dl>
<dt><tt>(expression)</tt></dt>
<dd>
parentheses — used to explicitly define the associativity of an expression
</dd>

<dt><tt>!expression</tt></dt>
<dd>
NOT — negation; the result of <tt>expression</tt> must <b>not</b> be true
</dd>

<dt><tt>a &amp;&amp; b</tt></dt>
<dd>
AND — <b>both</b> of the expressions <tt>a</tt> and <tt>b</tt> must be
true
</dd>

<dt><tt>a || b</tt></dt>
<dd>
OR — <b>either</b> of the expressions <tt>a</tt> or <tt>b</tt> may be
true
</dd>

<dt><tt>a -> b</tt></dt>
<dd>
"implies" operator — equivalent to <tt>!a || b</tt>.<br>
For example, <tt>windows -> x64</tt> could be thought of as "if a Windows
agent is used, then that agent <i>must</i> be 64-bit", while still
allowing this project to be executed on any agents that <i>do not</i> have
the <tt>windows</tt> label, regardless of whether they have also have an
<tt>x64</tt> label
</dd>

<dt><tt>a &lt;-> b</tt></dt>
<dd>
"if and only if" operator — equivalent to <tt>a &amp;&amp; b ||
!a &amp;&amp; !b</tt><br>
For example, <tt>windows &lt;-> dc2</tt> could be thought of as "if a
Windows agent is used, then that agent <i>must</i> be in datacenter 2, but
if a non-Windows agent is used, then it <i>must not</i> be in datacenter
2"
</dd>
</dl>

<h3>Notes</h3>
<ul>
<li>
All operators are left-associative, i.e. <tt>a -> b -> c</tt> is
equivalent to <tt>(a -> b) -> c</tt>.
</li>
<li>
Labels or agent names can be surrounded with quotation marks if they
contain characters that would conflict with the operator syntax.<br>
For example, <tt>"osx (10.11)" || "Windows Server"</tt>.
</li>
<li>
Expressions can be written without whitespace, but including it is
recommended for readability; Jenkins will ignore whitespace when
evaluating expressions.
</li>
<li>
Matching labels or agent names with wildcards or regular expressions is
not supported.
</li>
<li>
An empty expression will always evaluate to <i>true</i>, matching all
agents.
</li>
</ul>

<h3>Examples</h3>
<dl>
<dt><tt>master</tt></dt>
<dd>Builds of this project may be executed only on the Jenkins master<dd>

<dt><tt>linux-machine-42</tt></dt>
<dd>
Builds of this project may be executed only on the agent with the name
<tt>linux-machine-42</tt> (or on any machine that happens to have a label
called <tt>linux-machine-42</tt>)
</dd>

<dt><tt>windows &amp;&amp; jdk9</tt></dt>
<dd>
Builds of this project may be executed only on any Windows agent that has
version 9 of the Java Development Kit installed (assuming that agents
with JDK 9 installed have been given a <tt>jdk9</tt> label)
</dd>

<dt><tt>postgres &amp;&amp; !vm &amp;&amp; (linux || freebsd)</tt></dt>
<dd>
Builds of this project may be executed only any on Linux or FreeBSD agent,
so long as they are <i>not</i> a virtual machine, and they have PostgreSQL
installed (assuming that each agent has the appropriate labels — in
particular, each agent running in a virtual machine must have the
<tt>vm</tt> label in order for this example to work as expected)
</dd>

</dl>
</div>
4 changes: 2 additions & 2 deletions core/src/main/resources/hudson/model/Messages.properties
View file
Expand Up @@ -322,9 +322,9 @@ Permalink.LastFailedBuild=Last failed build
Permalink.LastCompletedBuild=Last completed build

ParameterAction.DisplayName=Parameters
ParametersDefinitionProperty.DisplayName=This build is parameterized
ParametersDefinitionProperty.DisplayName=This project is parameterized
StringParameterDefinition.DisplayName=String Parameter
TextParameterDefinition.DisplayName=Text Parameter
TextParameterDefinition.DisplayName=Multi-line String Parameter
FileParameterDefinition.DisplayName=File Parameter
BooleanParameterDefinition.DisplayName=Boolean Parameter
ChoiceParameterDefinition.DisplayName=Choice Parameter
Expand Down
2 changes: 1 addition & 1 deletion core/src/main/resources/hudson/model/Messages_en_GB.properties
View file
@@ -1 +1 @@
ParametersDefinitionProperty.DisplayName=This build is parameterised
ParametersDefinitionProperty.DisplayName=This project is parameterised
2 changes: 1 addition & 1 deletion core/src/main/resources/hudson/model/Messages_it.properties
View file
Expand Up @@ -243,7 +243,7 @@ Permalink.LastFailedBuild=Last failed build

ParameterAction.DisplayName=Parameters
StringParameterDefinition.DisplayName=String Parameter
TextParameterDefinition.DisplayName=Text Parameter
TextParameterDefinition.DisplayName=Multi-line String Parameter
FileParameterDefinition.DisplayName=File Parameter
BooleanParameterDefinition.DisplayName=Boolean Value
ChoiceParameterDefinition.DisplayName=Choice
Expand Down
46 changes: 34 additions & 12 deletions core/src/main/resources/hudson/model/ParametersDefinitionProperty/help.html
View file
@@ -1,14 +1,36 @@
<div>
When you are using Jenkins for various automations, it's sometimes convenient
to be able to "parameterize" a build, by requiring a set of user inputs to
be made available to the build process. For example, you might be setting up
an on-demand test job, where the user can submit a zip file of the binaries to be tested.

<p>
This section configures what parameters your build takes. Parameters are distinguished
by their names, and so you can have multiple parameters provided that they have different names.

<p>
See <a href="http://wiki.jenkins-ci.org/display/JENKINS/Parameterized+Build">the Wiki topic</a>
for more discussions about this feature.
Parameters allow you to prompt users for one or more inputs that will be
passed into a build. For example, you might have a project that runs tests on
demand by allowing users to upload a zip file with binaries to be tested.
This could be done by adding a <i>File Parameter</i> here.
<br>
Or you might have a project that releases some software, and you want users to
enter release notes that will be uploaded along with the software. This could
be done by adding a <i>Multi-line String Parameter</i> here.
<p>
Each parameter has a <i>Name</i> and some sort of <i>Value</i>, depending on
the parameter type. These name-value pairs will be exported as environment
variables when the build starts, allowing subsequent parts of the build
configuration (such as build steps) to access those values, e.g. by using the
<tt>${PARAMETER_NAME}</tt> syntax (or <tt>%PARAMETER_NAME%</tt> on Windows).
<br>
This also implies that each parameter defined here should have a unique
<i>Name</i>.
<p>
When a project is parameterized, the usual <i>Build Now</i> link will be
replaced with a <i>Build with Parameters</i> link, where users will be
prompted to specify values for each of the defined parameters. If they choose
not to enter anything, the build will start with the default value for each
parameter.
<p>
If a build is started automatically, for example if started by an SCM trigger,
the default values for each parameter will be used.
<p>
When a parameterized build is in the queue, attempting to start another build
of the same project will only succeed if the parameter values are different,
or if the <i>Execute concurrent builds if necessary</i> option is enabled.
<p>
See the <a href="https://wiki.jenkins-ci.org/display/JENKINS/Parameterized+Build"
target="_blank">Parameterized Builds wiki page</a> for more information about
this feature.
</div>

0 comments on commit 25340e0

Please sign in to comment.