156 lines
4.7 KiB
Org Mode
156 lines
4.7 KiB
Org Mode
-*- mode: org -*-
|
||
|
||
Cuirass is a continuous integration tool using GNU Guix.
|
||
|
||
* Requirements
|
||
|
||
Cuirass currently depends on the following packages:
|
||
|
||
- GNU Guile 3.0.x or 2.2.x
|
||
- GNU Guix (and all its development dependencies)
|
||
- GNU Make
|
||
- Guile-JSON 3.x
|
||
- Guile-Avahi
|
||
- Guile-Squee
|
||
- Guile-Git
|
||
- Guile-zlib
|
||
- Guile-Mastodon
|
||
- Guile-Simple-ZMQ
|
||
- Ephemeral PostgreSQL (for the tests)
|
||
- Mailutils
|
||
- Fibers
|
||
|
||
A convenient way to install those dependencies is to install Guix and execute
|
||
the following command:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
guix shell -CPNW --expose=/var/log/guix/drvs \
|
||
--expose=/var/run/dbus --expose=/run/avahi-daemon \
|
||
--expose=/etc/ssl/certs
|
||
#+END_EXAMPLE
|
||
|
||
This will build and enter a containarized environment which provides all the
|
||
necessary dependencies and resources.
|
||
|
||
The =-W= flag gives access to the outer =guix-daemon= and to the store, which
|
||
is necessary when running =cuirass= to perform actual builds. Exposing
|
||
=/var/log/guix/drvs= allows =cuirass web= to display build logs. The
|
||
next two =--expose= flags give access to the outer =avahi-daemon=, which is
|
||
used by =cuirass remote-server= and =cuirass remote-worker=; this is a
|
||
requirement for =tests/remote.scm=. Last, exposing the host’s
|
||
=/etc/ssl/certs= allows access to X.509 root certificates, necessary when
|
||
accessing for instance Git repositories over HTTPS.
|
||
|
||
* Build Instructions
|
||
|
||
When all the dependencies are available on you system, in order to build
|
||
Cuirass, you can proceed with the usual:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./bootstrap && ./configure && make
|
||
#+END_EXAMPLE
|
||
|
||
* Database connection
|
||
|
||
Cuirass uses PostgreSQL to store information about jobs, past build results
|
||
and to coordinate the execution of jobs. The database connection string must
|
||
be passed to Cuirass using the =database= argument, under the keyword/value
|
||
format described [[https://www.postgresql.org/docs/10/libpq-connect.html#LIBPQ-CONNSTRING][here]]. The PostgreSQL database must be created beforehand.
|
||
|
||
By default, this command:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass register
|
||
#+END_EXAMPLE
|
||
|
||
will connect using the Unix socket at =/var/run/postgresql= to the =cuirass=
|
||
database and is equivalent to:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass register --database="dbname=cuirass host=/var/run/postgresql"
|
||
#+END_EXAMPLE
|
||
|
||
To use a TCP connection, one can use:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass register --database="host=127.0.0.1"
|
||
#+END_EXAMPLE
|
||
|
||
For a test run, instead of running a full-blown PostgreSQL, you can use the
|
||
=pg_tmp= program from [[https://eradman.com/ephemeralpg/][ephemeralpg]] like so:
|
||
|
||
#+begin_example
|
||
DB=$(pg_tmp)
|
||
./pre-inst-env cuirass register -S examples/cuirass.scm --database=$DB &
|
||
./pre-inst-env cuirass web --database=$DB
|
||
#+end_example
|
||
|
||
Or, if you want to test the ZeroMQ-based remote build mechanism, you can run:
|
||
|
||
#+begin_example
|
||
DB=$(pg_tmp)
|
||
./pre-inst-env cuirass register -S examples/cuirass.scm --database=$DB \
|
||
--build-remote &
|
||
./pre-inst-env cuirass web --database=$DB &
|
||
./pre-inst-env cuirass remote-server --database=$DB \
|
||
--public-key=tests/signing-key.pub --private-key=tests/signing-key.sec &
|
||
./pre-inst-env cuirass remote-worker \
|
||
--public-key=tests/signing-key.pub --private-key=tests/signing-key.sec &
|
||
#+end_example
|
||
|
||
* Run tests
|
||
|
||
Cuirass tests also require an access to a PostgreSQL database, provided by the
|
||
Ephemeral PostgreSQL package. The =pg_tmp= script needs to be part of the
|
||
path before running the usual:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
make check
|
||
#+END_EXAMPLE
|
||
|
||
* Example
|
||
|
||
A quick way to manually test Cuirass is to execute:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass register --specifications=examples/hello.scm
|
||
#+END_EXAMPLE
|
||
|
||
This will read the file "examples/hello.scm" which contains a list of
|
||
specifications and add them to the =cuirass= database. It will then build the
|
||
=hello= package on top of the default Guix channel.
|
||
|
||
Cuirass then loops evaluating/building the specs. The database keeps track
|
||
of the specifications in order to allow users to accumulate specifications.
|
||
To resume the evaluation/build process you can execute the same command
|
||
without the '--specifications' option:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass register
|
||
#+END_EXAMPLE
|
||
|
||
To start the web interface run:
|
||
|
||
#+BEGIN_EXAMPLE
|
||
./pre-inst-env cuirass web
|
||
#+END_EXAMPLE
|
||
|
||
* Contributing
|
||
|
||
See the manual for useful hacking informations, by running
|
||
|
||
#+BEGIN_EXAMPLE
|
||
info -f doc/cuirass.info "Contributing"
|
||
#+END_EXAMPLE
|
||
|
||
You can authenticate the code in this repository by running:
|
||
|
||
#+begin_example
|
||
guix git authenticate \
|
||
c75620777c33273fcd14261660288ec1b2dc8123 \
|
||
3CE464558A84FDC69DB40CFB090B11993D9AEBB5
|
||
#+end_example
|
||
|
||
The command silently exits with zero on success, and errors out
|
||
otherwise. We recommend invoking it from =.git/hooks/pre-push=.
|