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

doc/manual/Makefile.am

@@ -1,4 +1,4 @@
-DOCBOOK_FILES = installation.xml introduction.xml manual.xml
+DOCBOOK_FILES = installation.xml introduction.xml manual.xml projects.xml
 
 EXTRA_DIST = $(DOCBOOK_FILES) manual.pdf
 
@@ -18,6 +18,3 @@ manual.pdf : $(DOCBOOK_FILES)
 install-data-local:
 	$(INSTALL) -d $(DESTDIR)$(datadir)/doc/hydra/manual
 	$(INSTALL_DATA) manual.pdf $(DESTDIR)$(datadir)/doc/hydra/manual
-
-
-

doc/manual/manual.xml

@@ -56,7 +56,7 @@
 
   <xi:include href="introduction.xml" />
   <xi:include href="installation.xml" />
-
+  <xi:include href="projects.xml" />
   
     
 </book>

doc/manual/projects.xml

@@ -0,0 +1,176 @@
+<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>
+
+    <!-- TODO -->
+    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>