From: Ricardo Wurmus <rekado@elephly.net>
To: guix-devel@gnu.org
Subject: [PATCH] doc: Document database schema.
Date: Fri, 5 May 2017 12:38:14 +0200 [thread overview]
Message-ID: <20170505103814.15565-1-rekado@elephly.net> (raw)
* doc/cuirass.texi: Add "Database" node.
---
doc/cuirass.texi | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 149 insertions(+)
diff --git a/doc/cuirass.texi b/doc/cuirass.texi
index 39d256f..c045002 100644
--- a/doc/cuirass.texi
+++ b/doc/cuirass.texi
@@ -55,6 +55,7 @@ Tutorial sections:
Reference sections:
* Invocation:: How to run Cuirass.
+* Database:: About the database schema.
* Contributing:: Your help needed!
* GNU Free Documentation License:: The license of this manual.
@@ -192,6 +193,154 @@ Display an help message that summarize all the options provided.
@end table
@c *********************************************************************
+@node Database
+@chapter Database schema
+@cindex cuirass database
+@cindex sqlite database
+@cindex persistent configuration
+
+Cuirass uses a SQLite database to store information about jobs and past
+build results, but also to coordinate the execution of jobs.
+
+The database contains the following tables: @code{Specifications},
+@code{Stamps}, @code{Evaluations}, @code{Derivations}, and
+@code{Builds}. The purpose of each of these tables is explained below.
+
+@section Specifications
+@cindex specifications, database
+
+This table stores specifications describing the repository from whence
+Cuirass fetches code and the environment in which it will be processed.
+Entries in this table must have values for the following text fields:
+
+@table @code
+@item repo_name
+This field holds the name of the repository. This field is also the
+primary key of this table.
+
+@item url
+The URL of the repository.
+
+@item load_path
+This text field holds the name of the subdirectory in the checked out
+repository that is passed to the @code{evaluate} tool as the Guile load
+path. This directory is interpreted relative to the repository in the
+Cuirass cache directory. This will usually be the current directory
+@code{"."}.
+
+@item file
+The full path of the Scheme file containing PROC.
+
+@item proc
+This text field holds the name of the procedure in the Scheme file FILE
+that produces a list of jobs.
+
+@item arguments
+A list of arguments to be passed to PROC. This can be used to produce a
+different set of jobs using the same PROC.
+@end table
+
+The following columns are optional:
+
+@table @code
+@item branch
+This text field determines which branch of the repository Cuirass should
+check out.
+
+@item tag
+This text field is an alternative to using BRANCH or REVISION. It tells
+Cuirass to check out the repository at the specified tag.
+
+@item revision
+This text field is an alternative to using BRANCH or TAG. It tells
+Cuirass to check out the repository at a particular revision. In the
+case of a git repository this would be a commit hash.
+
+@item no_compile_p
+When this integer field holds the value @code{1} Cuirass will skip
+compilation for the specified repository.
+@end table
+
+@section Stamps
+@cindex stamps, database
+
+When a specification is processed, the repository must be downloaded at
+a certain revision as specified. The @code{Stamps} table stores the
+current revision for every specification when it is being processed.
+
+The table only has two text columns: @code{specification}, which
+references a specification from the @code{Specifications} table via the
+field @code{repo_name}, and @code{stamp}, which holds the revision
+(e.g. a commit hash).
+
+@section Evaluations
+@cindex evaluations, database
+
+An evaluation relates a specification with the revision of the
+repository specified therein. Derivations and builds (see below) each
+belong to a specific evaluation.
+
+The @code{Evaluations} table has the following columns:
+
+@table @code
+@item id
+This is an automatically incrementing numeric identifier.
+
+@item specification
+This field holds the @code{repo_name} of a specification from the
+@code{Specifications} table.
+
+@item revision
+This text field holds the revision string (e.g. a git commit) of the
+repository specified in the related specification.
+@end table
+
+@section Derivations
+@cindex derivations, database
+
+This table associates a tuple of derivation path and evaluation
+identifier with a job name.
+
+@table @code
+@item derivation
+This column holds the path to the Guix derivation that is supposed to be
+evaluated for this job.
+
+@item evaluation
+This field holds the @code{id} of an evaluation from the
+@code{Evaluations} table.
+
+@item job_name
+This text field holds the name of the job.
+@end table
+
+@section Builds
+@cindex builds, database
+
+This table holds records of completed or failed package builds. Note
+that builds are not in a one to one relationship with derivations in
+order to keep track of non-deterministic compilations.
+
+@table @code
+@item derivation
+This text field holds the path to the derivation file that resulted in
+this build.
+
+@item evaluation
+This integer field references the evaluation identifier from the
+@code{Evaluations} table, indicating to which evaluation this build
+belongs.
+
+@item log
+This text field holds the path to the build log file.
+
+@item output
+This text field holds the path to the build output or @code{NULL} if the
+build failed.
+@end table
+
+
+@c *********************************************************************
@node Contributing
@chapter Contributing
--
2.12.2
next reply other threads:[~2017-05-05 10:38 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-05-05 10:38 Ricardo Wurmus [this message]
2017-05-05 15:36 ` [PATCH] doc: Document database schema Maxim Cournoyer
2017-05-05 16:10 ` Ricardo Wurmus
2017-05-05 16:10 ` Ludovic Courtès
2017-05-05 19:15 ` Ricardo Wurmus
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170505103814.15565-1-rekado@elephly.net \
--to=rekado@elephly.net \
--cc=guix-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.