doc: add basic docs about declarative projects
Conversion of Shea's *.md, added as a subsection. Shea is left as author. I made this new bit a separate file, though it might be questionable.
This commit is contained in:
Shea Levy
Vladimír Čunát
parent
b3169ce438
commit
d6ccbeedbd
96
doc/manual/declarative-projects.xml
Normal file
96
doc/manual/declarative-projects.xml
Normal file
|
|
@ -0,0 +1,96 @@
|
||||||
|
<section xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
xml:id="sec-declarative-projects">
|
||||||
|
|
||||||
|
<title>Declarative projects</title>
|
||||||
|
<para>
|
||||||
|
Hydra also supports declarative projects, where jobsets are generated
|
||||||
|
and configured automatically from specification files instead of being
|
||||||
|
managed through the UI. A jobset specification is a JSON object
|
||||||
|
containing the configuration of the jobset, for example:
|
||||||
|
</para>
|
||||||
|
<programlisting language="json">
|
||||||
|
{
|
||||||
|
"enabled": 1,
|
||||||
|
"hidden": false,
|
||||||
|
"description": "js",
|
||||||
|
"nixexprinput": "src",
|
||||||
|
"nixexprpath": "release.nix",
|
||||||
|
"checkinterval": 300,
|
||||||
|
"schedulingshares": 100,
|
||||||
|
"enableemail": false,
|
||||||
|
"emailoverride": "",
|
||||||
|
"keepnr": 3,
|
||||||
|
"inputs": {
|
||||||
|
"src": { "type": "git", "value": "git://github.com/shlevy/declarative-hydra-example.git", "emailresponsible": false },
|
||||||
|
"nixpkgs": { "type": "git", "value": "git://github.com/NixOS/nixpkgs.git release-16.03", "emailresponsible": false }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
To configure a declarative project, take the following steps:
|
||||||
|
</para>
|
||||||
|
<orderedlist numeration="arabic" spacing="compact">
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Create a jobset repository in the normal way (e.g. a git repo with
|
||||||
|
a <literal>release.nix</literal> file, any other needed helper
|
||||||
|
files, and taking any kind of hydra input), but without adding it
|
||||||
|
to the UI. The nix expression of this repository should contain a
|
||||||
|
single job, named <literal>jobsets</literal>. The output of the
|
||||||
|
<literal>jobsets</literal> job should be a JSON file containing an
|
||||||
|
object of jobset specifications. Each member of the object will
|
||||||
|
become a jobset of the project, configured by the corresponding
|
||||||
|
jobset specification.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
In some hydra-fetchable source (potentially, but not necessarily,
|
||||||
|
the same repo you created in step 1), create a JSON file
|
||||||
|
containing a jobset specification that points to the jobset
|
||||||
|
repository you created in the first step, specifying any needed
|
||||||
|
inputs (e.g. nixpkgs) as necessary.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
In the project creation/edit page, set declarative input type,
|
||||||
|
declarative input value, and declarative spec file to point to the
|
||||||
|
source and JSON file you created in step 2.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
<para>
|
||||||
|
Hydra will create a special jobset named <literal>.jobsets</literal>,
|
||||||
|
which whenever evaluated will go through the steps above in reverse
|
||||||
|
order:
|
||||||
|
</para>
|
||||||
|
<orderedlist numeration="arabic" spacing="compact">
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Hydra will fetch the input specified by the declarative input type
|
||||||
|
and value.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Hydra will use the configuration given in the declarative spec
|
||||||
|
file as the jobset configuration for this evaluation. In addition
|
||||||
|
to any inputs specified in the spec file, hydra will also pass the
|
||||||
|
<literal>declInput</literal> argument corresponding to the input
|
||||||
|
fetched in step 1.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
As normal, hydra will build the jobs specified in the jobset
|
||||||
|
repository, which in this case is the single
|
||||||
|
<literal>jobsets</literal> job. When that job completes, hydra
|
||||||
|
will read the created jobset specifications and create
|
||||||
|
corresponding jobsets in the project, disabling any jobsets that
|
||||||
|
used to exist but are not present in the current spec.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</section>
|
||||||
|
|
@ -1,5 +1,6 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
xml:id="chap-projects">
|
xml:id="chap-projects">
|
||||||
|
|
||||||
<title>Creating and Managing Projects</title>
|
<title>Creating and Managing Projects</title>
|
||||||
|
|
@ -468,6 +469,7 @@ build_exotic =
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<xi:include href="declarative-projects.xml" />
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue