From c616d030eacf6850fe9bab9ef298ccb74534e5c0 Mon Sep 17 00:00:00 2001
From: Egor Tensin <Egor.Tensin@gmail.com>
Date: Wed, 28 Apr 2021 15:38:31 +0300
Subject: add docs/ci.md

---
 README.md  | 47 +++----------------------------------------
 docs/ci.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 44 deletions(-)
 create mode 100644 docs/ci.md

diff --git a/README.md b/README.md
index 7e62c44..a99e950 100644
--- a/README.md
+++ b/README.md
@@ -117,50 +117,9 @@ parameters from environment variables.
 | Build path        | `$TRAVIS_BUILD_DIR/../build/cmake`   | `%APPVEYOR_BUILD_FOLDER%\..\build\cmake`   | `$GITHUB_WORKSPACE/../build/cmake`
 | Install path      | `$TRAVIS_BUILD_DIR/../build/install` | `%APPVEYOR_BUILD_FOLDER%\..\build\install` | `$GITHUB_WORKSPACE/../build/install`
 
-For example, the following Travis workflow:
-
-```
-language: cpp
-os: linux
-dist: focal
-
-env:
-  global:
-    BOOST_VERSION: 1.65.0
-  jobs:
-    - CONFIGURATION=Debug   PLATFORM=x64
-    - CONFIGURATION=Release PLATFORM=x64
-
-before_script: ci-boost -- --with-filesystem
-script: ci-cmake --install
-```
-
-is roughly equivalent to running
-
-```
-boost-download --cache "$TRAVIS_BUILD_DIR/../build" -- 1.65.0
-mv -- \
-    "$TRAVIS_BUILD_DIR/../build/boost_1_65_0" \
-    "$TRAVIS_BUILD_DIR/../build/boost"
-
-boost-build                            \
-    --platform x64                     \
-    --configuration Debug Release      \
-    --                                 \
-    "$TRAVIS_BUILD_DIR/../build/boost" \
-    --with-filesystem
-
-for configuration in Debug Release; do
-    cmake-build                                        \
-        --platform x64                                 \
-        --configuration "$configuration"               \
-        --boost "$TRAVIS_BUILD_DIR/../build/boost"     \
-        --build "$TRAVIS_BUILD_DIR/../build/cmake"     \
-        --install "$TRAVIS_BUILD_DIR/../build/install" \
-        --                                             \
-        "$TRAVIS_BUILD_DIR"
-done
-```
+
+For an example of how to integrate `ci-boost` and `ci-cmake` into a CI
+workflow, see [docs/ci.md](docs/ci.md).
 
 Tools
 -----
diff --git a/docs/ci.md b/docs/ci.md
new file mode 100644
index 0000000..d0695b7
--- /dev/null
+++ b/docs/ci.md
@@ -0,0 +1,68 @@
+`ci-boost` and `ci-cmake` are thin wrappers around `boost-download`/`boost-build`
+and `cmake-build` accordingly.  They work by reading environment variables and
+passing their values as command line parameters to the more generic scripts.
+This facilitates matrix-building the project without too much fuss.
+
+For example, the following Travis workflow:
+
+```
+language: cpp
+os: linux
+dist: focal
+
+env:
+  global:
+    BOOST_VERSION: 1.65.0
+  jobs:
+    - CONFIGURATION=Debug   PLATFORM=x64
+    - CONFIGURATION=Release PLATFORM=x64
+
+before_script: ci-boost -- --with-filesystem
+script: ci-cmake --install
+```
+
+is roughly equivalent to running
+
+```
+boost-download --cache "$TRAVIS_BUILD_DIR/../build" -- 1.65.0
+mv -- \
+    "$TRAVIS_BUILD_DIR/../build/boost_1_65_0" \
+    "$TRAVIS_BUILD_DIR/../build/boost"
+
+boost-build                            \
+    --platform x64                     \
+    --configuration Debug Release      \
+    --                                 \
+    "$TRAVIS_BUILD_DIR/../build/boost" \
+    --with-filesystem
+
+for configuration in Debug Release; do
+    cmake-build                                        \
+        --platform x64                                 \
+        --configuration "$configuration"               \
+        --boost "$TRAVIS_BUILD_DIR/../build/boost"     \
+        --build "$TRAVIS_BUILD_DIR/../build/cmake"     \
+        --install "$TRAVIS_BUILD_DIR/../build/install" \
+        --                                             \
+        "$TRAVIS_BUILD_DIR"
+done
+```
+
+Caching
+-------
+
+`ci-boost` downloads the Boost distribution archive to the "../build/"
+directory (resolved relatively to the root checkout directory).  You can cache
+the archive like this (using GitHub Actions as an example):
+
+```
+- name: Cache Boost
+  uses: actions/cache@v2
+  with:
+    path: '${{ runner.workspace }}/build/boost_*.tar.gz'
+    key: 'boost_${{ env.BOOST_VERSION }}'
+
+- name: Build Boost
+  # This won't re-download the archive unnecessarily.
+  run: ci-boost -- --with-filesystem
+```
-- 
cgit v1.2.3