From d5c5f90742c4326d330ce1e969318c8d87f69829 Mon Sep 17 00:00:00 2001 From: Eelco Visser Date: Mon, 1 Dec 2008 20:03:18 +0000 Subject: [PATCH] draft manual --- doc/manual/manual.html | 361 +++++++++++++++++++++++++++++++++++++++++ doc/manual/style.css | 288 ++++++++++++++++++++++++++++++++ 2 files changed, 649 insertions(+) create mode 100644 doc/manual/manual.html create mode 100644 doc/manual/style.css diff --git a/doc/manual/manual.html b/doc/manual/manual.html new file mode 100644 index 00000000..d11b97c1 --- /dev/null +++ b/doc/manual/manual.html @@ -0,0 +1,361 @@ + + + + + + +
+ +

The Hydra Buildfarm User Manual

+ + +

Draft (Version 0.1)

+ +

+ +

Eelco Dolstra and Eelco Visser

+ +

+Delft University of Technology +

+Department of Software Technology + +

+Copyright 2008 Eelco Dolstra + +

+ +

Chapter 1. Introduction

+ + +

1.1. About Hydra

+ +Hydra is a buildfarm system based on the Nix software deployment +system. + +

+ +... advantages ... + + +

+ +

+ + +

+ +

1.2. Hydra at nixos.org

+ +The nixos.org installation of Hydra runs at + +
+ http://hydra.nixos.org +
+ +That installation is used to build software components from the +Nix, +NixOS, +Stratego/XT, +and related projects. + +If you are one of the developers on those projects, it is likely that +you will be using the NixOS Hydra server in some way. If you need to +administer automatic builds for your project, you should pull the +right strings to get an account on the server. This manual will tell +you how to set up new projects and build jobs within those projects +and write a release.nix file to describe the build process of your +project to Hydra. You can skip Chapter 2. + +

+ +If your project does not yet have automatic builds within the NixOS +Hydra server, it may actually be eligible. We are in the process of +setting up a large buildfarm that should be able to support open +source and academic software projects. Get in touch. + +

1.3. Hydra on your own buildfarm

+ +If you need to run your own Hydra installation, Chapter 2 explains +how to download and install the system on your own server. + + +

Chapter 2. Installation and Configuration

+ +This chapter explains how to install Hydra on your own buildfarm server. +We assume that you have + +

2.1. Platform Requirements

+ +To run Hydra you need a Linux server with at least a considerable +amount of diskspace to store builds. A multi-core machine is not a +waste since Hydra can schedule multiple simultaneous build jobs. + +

+ +Of course we think it is a good idea to use the NixOS Linux distribution for your +buildfarm server. But this is not a requirement. The Nix software +deployment system can be installed on any Linux distribution in +parallel to the regular package management system. Thus, you can use +Hydra on a Suse, Fedora, or Ubuntu system. + +

+ +Hydra on Windows?? + + +

2.2. Getting Nix

+ +If your server runs NixOS you are all set to continue with +installation of Hydra. Otherwise you first need to install Nix. +The latest stable release is Nix 0.12. +Installation instructions can be found in the +Nix User's Guide. + +

+ +Why Nix ... + +

2.3. Installation

+ +To install Hydra, get the most recent 'closure' available from + +
+ http://hydra.nixos.org/releases/hydra/unstable +
+ +And follow the instructions that are revealed by clicking [help]. + +
+$ gunzip < hydra-build.closure.gz | nix-store --import
+
+ +This unpacks the closure and imports its components into the Nix store. + +
+$ nix-env -i /nix/store/...-hydra-build
+
+ +This makes the tools in the Hydra package available in your Nix user +environment. + +

+ +Command completion should then reveal a number of tools related to +hydra installed: + +

+$ hydra_<tab>
+hydra_build.pl         hydra_fastcgi.pl       hydra_scheduler.pl
+hydra_cgi.pl           hydra_init.pl          hydra_server.pl
+hydra_create.pl        hydra_queue_runner.pl  hydra_test.pl
+
+ + +

2.4. Configuration

+ +The Hydra software is installed in the Nix store, but to run it needs +a directory for storing the database, logs, and session data. In your +.bashrc or similar configuration file define: + +
+ export HYDRA_DATA=/usr/local/hydra
+
+ +and make sure that you actually create that directory. (Of course, you +can use another directory, but then remember to also substitute that +name in the commands below.) + +

+ +Run hydra_init.pl to initialize the database + +

+$ hydra_init.pl
+
+ +Run hydra_server.pl to start the webserver at http://localhost:3000 + +
+$ hydra_server.pl
+
+ +Also start the scheduler, which monitors the source repositories and +adds builds to the queue, and the runner, which executes jobs in the +queue. + +
+$ hydra_scheduler.pl
+$ hydra_queue_runner.pl
+
+ +Now your Hydra server should be up and running and the web interface +operational. + +

2.5. User Administration

+ +To be able to add jobs and create projects you need to register users +in the Hydra database. In the current version, the web interface does +not yet support user administration. Use the following command to add +a new user to the database. + +
+$ sqlite3 /usr/local/hydra/hydra.sqlite "insert into Users(userName, emailAddress, password) values('eelco', 'blablah@example.org', '$(echo -n foobar | sha1sum | cut -c1-40)');"
+
+ +where eelco is the username, and foobar the +password. (Make sure to use other values!) + +

+ +To give this user administrator privileges, follow this up by: + +

+$ sqlite3 /usr/local/hydra/hydra.sqlite "insert into UserRoles(userName, role) values('eelco', 'admin');"
+
+ +Now you should be able to create a project using the Hydra web interface. + +

Chapter 3. Creating Projects

+ +The next step is to add projects to the buildfarm. We follow the +example of the patchelf project at hydra.nixos.org. Note that the +error messages provided as feedback by the webinterface can be +somewhat unfriendly in the current version. + +

+ +Login +to the webinterface of your Hydra installation using +the username and password you inserted in the database. +Then follow the +'Create Project' +link to create a new project. + +

3.1. General information

+ +A project definition consists of some general information + +The general information of a project are mainly its name and +owner. Here's what we fill in for the patchelf project: + +
+  Identifier:    patchelf
+  Display name:  Patchelf
+  Description:   A tool for modifying ELF binaries
+  Owner:         eelco
+  Enabled:       Yes
+
+ +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: + +
+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
+
+ +So try to create the project after entering just the general +information to figure out if you have chosen a unique name. +Jobsets can be added once the project has been created. + +

+ +Once create there should be an entry for the project in the sidebar. Go to +the project page for the +Patchelf +project. + +

Jobsets

+ +A project can consist of multiple `jobsets', separate tasks that can +be built separately, but may depend on each other (without cyclic +dependencies, of course). Go to the +Edit +page of the Patchelf project and 'Add a new jobset' +by providing the following 'Information': + +
+  Identifier:     trunk
+  Description:    Trunk
+  Nix expression: release.nix in input patchelfSrc
+
+ +This states that in order to build the 'Trunk' jobset, the Nix +expression in the file 'release.nix', which can be obtained from input +'patchelfSrc', should be evaluated. (We'll have a look at release.nix +later.) + +

+ +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. + +

+  nixpkgs 'CVS checkout' https://svn.nixos.org/repos/nix/nixpkgs/trunk
+
+ +
+  officialRelease   Boolean false
+
+ + +
+  patchelfSrc Subversion checkout https://svn.nixos.org/repos/nix/patchelf/trunk
+
+ + +
+  system String value "i686-linux" 
+
+ +nixpkgs + +officialRelease + +patchelfSrc + +system + +

Release Set

+ +there must be one primary job + +check the radio button of exactly one job + +https://svn.nixos.org/repos/nix/nixpkgs/trunk + +

Building Jobs

+ + +

release.nix

+ + + +- 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 + +

Building on the command line

+ +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): + +$ nix-build release.nix -A rpm_fedora10i386 + + +

Release Set

+ + + + + \ No newline at end of file diff --git a/doc/manual/style.css b/doc/manual/style.css new file mode 100644 index 00000000..57d95c75 --- /dev/null +++ b/doc/manual/style.css @@ -0,0 +1,288 @@ +/* Copied from http://bakefile.sourceforge.net/, which appears + licensed under the GNU GPL. */ + + +/*************************************************************************** + Basic headers and text: + ***************************************************************************/ + +body +{ + font-family: sans-serif; + background: white; + margin: 2em 1em 2em 1em; +} + +h1,h2,h3 +{ + color: #005aa0; + text-align: left; +} + +h1 /* title */ +{ + font-size: 200%; +} + +h2 /* chapters, appendices, subtitle */ +{ + font-size: 180%; +} + +/* Extra space between chapters, appendices. */ +div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 +{ + margin-top: 1.5em; +} + +div.section > div.titlepage h2 /* sections */ +{ + font-size: 150%; + margin-top: 1.5em; +} + +h3 /* subsections */ +{ + font-size: 125%; +} + +div.simplesect h2 +{ + font-size: 110%; +} + +div.appendix h3 +{ + font-size: 150%; + margin-top: 1.5em; +} + +div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ +{ + margin-top: 1.4em; + font-size: 125%; +} + +div.refsection h3 +{ + font-size: 110%; +} + + +/*************************************************************************** + Examples: + ***************************************************************************/ + +div.example +{ + border: 1px solid #6185a0; + padding: 6px 6px; + margin-left: 1.5em; + margin-right: 1.5em; + background: #f4f4f8; +} + +div.example p.title +{ + margin-top: 0em; +} + + +/*************************************************************************** + Screen dumps: + ***************************************************************************/ + +pre.screen, pre.programlisting +{ + border: 1px solid #6185a0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + color: #600000; + background: #f4f4f8; + font-family: monospace; + /* font-size: 90%; */ +} + +div.example pre.programlisting +{ + border: 0px; + padding: 0 0; + margin: 0 0 0 0; +} + + +/*************************************************************************** + Notes, warnings etc: + ***************************************************************************/ + +.note, .warning +{ + border: 1px solid #6185a0; + padding: 3px 3px; + margin-left: 1.5em; + margin-right: 1.5em; + margin-bottom: 1em; + padding: 0.3em 0.3em 0.3em 0.3em; + background: #fffff5; +} + +div.note, div.warning +{ + font-style: italic; +} + +div.note h3, div.warning h3 +{ + color: red; + font-size: 100%; +// margin: 0 0 0 0; + padding-right: 0.5em; + display: inline; +} + +div.note p, div.warning p +{ + margin-bottom: 0em; +} + +div.note h3 + p, div.warning h3 + p +{ + display: inline; +} + +div.note h3 +{ + color: blue; + font-size: 100%; +} + +div.navfooter * +{ + font-size: 90%; +} + + +/*************************************************************************** + Links colors and highlighting: + ***************************************************************************/ + +a:link { color: #0048b3; } +a:visited { color: #002a6a; } +a:hover { background: #ffffcd; } + + +/*************************************************************************** + Table of contents: + ***************************************************************************/ + +.toc +{ + font-size: 90%; +} + + + +/*************************************************************************** + Special elements: + ***************************************************************************/ + +tt, code +{ + color: #400000; +} + +.term +{ + font-weight: bold; + +} + +div.variablelist dd p, div.glosslist dd p +{ + margin-top: 0em; +} + +div.variablelist dd, div.glosslist dd +{ + margin-left: 1.5em; +} + +div.glosslist dt +{ + font-style: italic; +} + +.default +{ + font-style: italic; +} + +.availability +{ + font-style: italic; +} + +.varname +{ + color: #400000; +} + + +div.informaltable table +{ + border: 1px solid #6185a0; + width: 100%; +} + +div.informaltable td +{ + border: 0; + padding: 5px; +} + +div.informaltable td.default +{ + text-align: right; +} + +div.informaltable th +{ + text-align: left; + color: #005aa0; + border: 0; + padding: 5px; + background: #fffff5; + font-weight: normal; + font-style: italic; +} + +td.varname, td.tagname, td.paramname +{ + font-weight: bold; + vertical-align: top; +} + +div.epigraph +{ + font-style: italic; + text-align: right; +} + +table.productionset table.productionset +{ + font-family: monospace; +} + +strong.command +{ +// font-family: monospace; +// font-style: italic; +// font-weight: normal; + color: #400000; +} + +div.calloutlist td +{ + padding-bottom: 1em; +}