Rewrite obbench, adding yarns and Debian packaging

1 files changed, 74 insertions, 0 deletions

diff --git a/yarns/200-config.yarn b/yarns/200-config.yarn
new file mode 100644
index 0000000..5202b2a
--- /dev/null
+++ b/yarns/200-config.yarn
@@ -0,0 +1,74 @@
+# Configuration
+
+Obbench configuration is split into two: a benchmark specification
+file in YAML, and a user- and site-specific configuration. The former
+specifies the benchmarks to run, and the latter where state and
+results should be put on the local machine.
+
+
+## Benchmark specification YAML file
+
+The benchmark specification file uses [YAML][] as the syntax. The top
+level object is an "associative array", corresponding to a Perl
+hashmap, a Python dict, or more generally a set of key/value pairs.
+
+[YAML]: https://en.wikipedia.org/wiki/YAML
+
+An example:
+
+    EXAMPLE benchmark specification file
+    git: /home/liw/obnam/obnam
+    obnam_config:
+      repository-format: green-albatross
+    benchmarks:
+      - name: many_files
+        description: backup many small files
+        steps:
+          - live: genbackupdata . --create=10 --file-size=1
+            obnam: backup
+            reference: 31
+          - obnam: restore
+            reference: 32
+          - obnam: backup
+
+The top level keys are:
+
+key           |type         |description
+--------------|-------------|------
+`git`         |URL          |location of Obnam git repository
+`obnam_config`|dict         |Obnam configuration variables
+`benchmarks`  |list of dicts|actual benchmark specifications
+
+There are no default values, so for example the git URL to the Obnam
+repository needs to specified every time.
+
+The Obnam configuration variables are as specified by Obnam itself.
+Any configuration variables may be used. Note that obbench itself
+provides the following settings for Obnam: `quiet`, `repository`,
+`root`, and `log`. The benchmark specification should probably not
+override those.
+
+The benchmark have the following key/value pairs.
+
+key          |type         |description
+-------------|-------------|-----------
+`name`       |symbol       |name of the benchmark
+`description`|text         |description of the benchmark
+`steps`      |list of dicts|list of steps in the benchmark
+
+The steps can use the following keys:
+
+key    |type      |description
+-------|----------|-----------
+`live` |shell     |modify live data for step
+`obnam`|subcommand|Obnam subcommand to run
+
+Every step optionally modifies the live data to be backed up. This is
+done by running an arbitrary shell command. Additionally, an Obnam
+subcommand can be run on the live data. Currently, the supported
+subcommands are `backup` and `restore`. Arbitrary Obnam subcommands
+are not supported.
+
+## Local configuration
+
+FIXME. This needs to be implemented and documented.