doc: Import the "Creating Projects" chapter by Visser & Dolstra.

[?]

Mar 16, 2011, 10:50 PM

PKE6I67S7TDGKEFCKIQZOZ5PSDZXCSPOQGSKDAE5NST3NOOLRUXAC

Dependencies

[2] 5AKAE3R6 start of hydra manual
[3] FV2M6MOT hydra: use autoconf/-make
[4] CPQQFQMZ doc: Reintegrate the intro by Visser & Dolstra from `manual.html'.
[*] 6A6CZ7SC draft manual

Change contents

replacement in doc/manual/Makefile.am at line 1

[3.16946]→[3.16947:17008](∅→∅)

DOCBOOK_FILES = installation.xml introduction.xml manual.xml

[3.16946]

[3.17008]

DOCBOOK_FILES = installation.xml introduction.xml manual.xml projects.xml
edit in doc/manual/Makefile.am at line 21

[3.17479]→[3.17479:17482](∅→∅)
replacement in doc/manual/manual.xml at line 59

[2.1160]→[2.1160:1161](∅→∅)

[2.1160]

[2.1161]

<xi:include href="projects.xml" />
file addition: projects.xml (----------)

[6.18]

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-projects">

<title>Creating and Managing Projects</title>

<para>
Once Hydra is installed and running, the next step is to add
projects to the build farm. We follow the example of the <link
xlink:href="http://nixos.org/patchelf.html">Patchelf
project</link>, a software tool written in C and using the GNU
Build System (GNU Autoconf and GNU Automake).
</para>

<para>
Log in to the web interface of your Hydra installation using the
user name and password you inserted in the database (by default,
Hydra's web server listens on <link
xlink:href="http://localhost:3000/"><literal>localhost:3000</literal></link>).
Then follow the "Create Project" link to create a new project.
</para>

<section>
<title>Project Information</title>

<para>
A project definition consists of some general information and a
set of job sets. The general information identifies a project,
its owner, and current state of activity.

Here's what we fill in for the patchelf project:

<screen>
Identifier: patchelf
</screen>

The <emphasis>identifier</emphasis> is the identity of the
project. It is used in URLs and in the names of build results.
</para>

<para>
The identifier should be a unique name (it is the primary
database key for the project table in the database). If you try
to create a project with an already existing identifier you'd
get an error message such as:

<screen>
I'm very sorry, but an error occurred:
DBIx::Class::ResultSet::create(): DBI Exception: DBD::SQLite::st execute failed: column name is not unique(19) at dbdimp.c line 402
</screen>

So try to create the project after entering just the general
information to figure out if you have chosen a unique name.
Job sets can be added once the project has been created.

<screen>
Display name: Patchelf
</screen>

The <emphasis>display name</emphasis> is used in menus.

<screen>
Description: A tool for modifying ELF binaries
</screen>

The <emphasis>description</emphasis> is used as short
documentation of the nature of the project.

<screen>
Owner: eelco
</screen>

The <emphasis>owner</emphasis> of a project can create and edit
job sets.

<screen>
Enabled: Yes
</screen>

Only if the project is <emphasis>enabled</emphasis> are builds
performed.
</para>

<para>
Once created there should be an entry for the project in the
sidebar. Go to the project page for the <link
xlink:href="http://localhost:3000/project/patchelf">Patchelf</link>
project.
</para>
</section>

<section>
<title>Job Sets</title>

<para>
A project can consist of multiple <emphasis>job sets</emphasis>
(hereafter <emphasis>jobsets</emphasis>), separate tasks that
can be built separately, but may depend on each other (without
cyclic dependencies, of course). Go to the <link
xlink:href="http://localhost:3000/project/patchelf/edit">Edit</link>
page of the Patchelf project and "Add a new jobset" by providing
the following "Information":

<screen>
Identifier: trunk
Description: Trunk
Nix expression: release.nix in input patchelfSrc
</screen>

This states that in order to build the <literal>trunk</literal>
jobset, the Nix expression in the file
<filename>release.nix</filename>, which can be obtained from
input <literal>patchelfSrc</literal>, should be
evaluated. (We'll have a look at
<filename>release.nix</filename> later.)

</para>

<para>
To realize a job we probably need a number of inputs, which can
be declared in the table below. As many inputs as required can
be added. For patchelf we declare the following inputs.

<screen>
patchelfSrc
'Subversion checkout' https://svn.nixos.org/repos/nix/patchelf/trunk

nixpkgs 'Subversion checkout' https://svn.nixos.org/repos/nix/nixpkgs/trunk

officialRelease Boolean false

system String value "i686-linux"
</screen>
</para>
</section>

<section>
<title>Release Set</title>


there must be one primary job

check the radio button of exactly one job

https://svn.nixos.org/repos/nix/nixpkgs/trunk
</section>

<section>
<title>Building Jobs</title>
</section>

<section>
<title><filename>release.nix</filename></title>

- Voorbeelden van Nix expressies voor Hydra:

https://svn.nixos.org/repos/nix/patchelf/trunk/release.nix
https://svn.nixos.org/repos/nix/nix/trunk/release.nix
https://svn.nixos.org/repos/nix/hydra/trunk/release.nix
</section>

<section>
<title>Building on the Command Line</title>

Overigens zijn die helemaal niet Hydra-specifiek, je kunt ze gewoon vanaf de
command line bouwen, bijv. als je een patchelf checkout hebt (met een nixpkgs
checkout in ../nixpkgs):

<screen>
$ nix-build release.nix -A rpm_fedora10i386
</screen>

</section>
</chapter>