From dde54921f016da40f8d1a53e401055cfad97c7d1 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Sun, 21 Jan 2018 09:36:23 -0500
Subject: Add manifest reference under builds.sr.ht

---
 builds.sr.ht/index.md    |   2 +-
 builds.sr.ht/manifest.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 104 insertions(+), 1 deletion(-)
 create mode 100644 builds.sr.ht/manifest.md

(limited to 'builds.sr.ht')

diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md
index d199abe..d02958f 100644
--- a/builds.sr.ht/index.md
+++ b/builds.sr.ht/index.md
@@ -64,7 +64,7 @@ features of the build.yml - here's an example that deploys
           rsync --rsh="$sshopts" -rP index.html $deploy:/var/www/web.synapse-bt.org/
           rsync --rsh="$sshopts" -rP dist $deploy:/var/www/web.synapse-bt.org/
 
-A [full reference](manifests.md) for build manifests is available.
+A [full reference](manifest.md) for build manifests is available.
 
 ## Build images
 
diff --git a/builds.sr.ht/manifest.md b/builds.sr.ht/manifest.md
new file mode 100644
index 0000000..95510cd
--- /dev/null
+++ b/builds.sr.ht/manifest.md
@@ -0,0 +1,103 @@
+A build manifest is a YAML file that describes how to perform a build. Here's an
+example:
+
+    image: archlinux
+    packages:
+      - cmake
+      - wlc-git
+      - xorg-server-xwayland
+      - xcb-util-image
+      - json-c
+      - pango
+      - cairo
+      - wayland
+      - gdk-pixbuf2
+      - asciidoc
+    sources:
+      - https://github.com/SirCmpwn/sway
+    tasks:
+      - setup: |
+          cd sway
+          mkdir build
+          cd build
+          cmake ..
+      - build: |
+          cd sway
+          cd build
+          make
+
+The minimum build manifest has an image and at least one task. The various
+properties available are described here:
+
+## image
+
+*string*
+
+Which OS image to build in. A list of available build images can be found
+[here](/builds.sr.ht/#build-images).
+
+## packages
+
+*list* (of *string*)
+
+A list of package names to install on the image. The details of this process
+varies from image to image.
+
+## repositories
+
+*dictionary* (of *string: string*)
+
+A list of extra repositories to enable with the image's package manager.
+The format is name: url, and the syntax of url varies between images.
+
+- **Arch Linux** uses `url#key-id`, where `url` is the URL of the package
+repository and `key-id` is the ID of the published PGP key the packages are
+signed with.
+
+## sources
+
+*list* (of *string*)
+
+A list of git repositories to clone into the home directory of the build
+user in the build environment.
+
+## tasks
+
+*list* (of *string*)
+
+A list of scripts to execute in the build environment. These scripts are run
+with the following preamble:
+
+    #!/usr/bin/env bash
+    . ~/.buildenv
+    set -x
+    set -e
+
+~/.buildenv contains environment variables specified by the `environment`
+directive.
+
+Task names must use only lowercase alphanumeric characters or underscores
+and must be &lt;=128 characters in length. Tasks are executed in the order
+specified.
+
+## triggers
+
+*list* (of *trigger*)
+
+A list of triggers to execute post-build, which can be used to send emails
+or do other post-build tasks. This uses the same structure as triggers in
+[the API](/builds.sr.ht/api.md#post-apijobs), but as YAML rather than JSON.
+
+## environment
+
+*dictionary* (of *string: string* OR *string: list*)
+
+A list of key/value pairs for options to set in the build environment via
+~/.buildenv.
+
+## secrets
+
+*list* (of *string*)
+
+List of secret UUIDs to be added to the guest during the build. See also:
+[secrets](/builds.sr.ht#secrets).
-- 
cgit