From c3597fd901b8be94f255eb0ddb6a478c85052c7c Mon Sep 17 00:00:00 2001
From: Ralph Lange <ralph.lange@gmx.de>
Date: Thu, 24 Oct 2019 15:05:40 +0200
Subject: [PATCH] Update documentation

---
 README.md        | 101 ++++++++++++++++++++++++++++++++++++++++++++---
 travis/README.md |  34 ++++++++--------
 2 files changed, 114 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index b062b03..99e4f1b 100644
--- a/README.md
+++ b/README.md
@@ -27,9 +27,31 @@ module).
 Also, a test suite might not show the same level of quality as an
 example.
 
+## Features
+
+ - Compile against different branches or releases of EPICS Base and
+   additional dependencies (modules like asyn, std, etc.).
+
+ - Define settings files that declare sets of dependencies
+   with their versions and locations.
+
+ - Define hook scripts for any dependency.
+   Hooks are run on the dependency module before it is compiled, so
+   the module can be patched or further configured.
+
+ - Define static or shared builds (executables, libraries).
+
+ - Run tests (using the EPICS unit test suite).
+
 ## Supported CI Services
 
- - Travis-CI
+### Travis-CI
+ - Use different compilers (gcc, clang)
+ - Use different gcc versions
+ - Cross-compile for Windows 32bit and 64bit using MinGW and WINE
+ - Cross-compile for RTEMS 4.9 and 4.10
+ - Compile on MacOS
+ - Released versions of dependencies are cached (for faster builds)
  
 ### How to Use the CI-Scripts
 
@@ -41,20 +63,89 @@ example.
     ```
     $ git submodule add https://github.com/epics-base/ci-scripts .ci
     ```
+ 3. Create settings files for different sets of dependencies you
+    want to compile against. E.g., a settings file `foo.set`
+    specifying
+    ```
+    MODULES="sncseq asyn"
 
- 3. Create a configuration for the CI service by copying one of
+    BASE=R3.15.6
+    ASYN=master
+    SNCSEQ=R2-2-7
+    ```
+    will compile against the EPICS Base release 3.15.6, the Sequencer
+    release 2.2.7 and the latest commit on the `master` branch of asyn.
+
+ 4. Create a configuration for the CI service by copying one of
     the examples provided in the service specific subdirectory
     and editing it to include the jobs you want the service to run.
+    Use your dependency settings by defining e.g. `SET=foo` in your jobs.
 	
- 4. Push your changes and check the CI service for your build results.
+ 5. Push your changes and check the CI service for your build results.
 
-## Releases and Numbering of this Module
+## Settings File Syntax
+
+Settings files are sourced by the bash scripts. They are found by searching
+the locations in `SETUP_PATH` (space or colon separated list of directories,
+relative to your module's root directory).
+
+`MODULES="<list of names>"` should list the dependencies (software modules)
+by using their well-known slugs, separated by spaces.
+EPICS Base (`BASE`) will always be a dependency and will be added and
+compiled first. The other dependencies are added and compiled in the order
+they are defined in `MODULES`.
+
+`REPOOWNER=<name>` sets the default GitHub owner (or organization) for all
+dependency modules. Useful if you want to compile against a complete set
+of dependencies forked into your private GitHub area.
+
+For any module mentioned as `foo` in the `MODULES` setting (and for `BASE`),
+the following settings can be configured:
+
+`FOO=<version>` Set version of the module that should be used. Must either
+be a *tag* name (in that case the module is checked out into Travis' cache
+system) or a *branch* name (in that case the module is always checked out
+and recompiled as part of the job). [default: `master`]
+
+`FOO_REPONAME=<name>` Set the name of the remote repository as `<name>.git`.
+[default is the slug in lower case: `foo`]
+
+`FOO_REPOOWNER=<name>` Set the name of the GitHub owner (or organization)
+that the module repository can be found under.
+
+`FOO_REPOURL="<url>"` Set the complete URL of the remote repository.
+
+The default URL for the repository is pointing to GitHub, under
+`$FOO_REPOOWNER` else `$REPOOWNER` else `epics-modules`,
+using `$FOO_REPONAME` else `foo` and the extension`.git`.
+
+`FOO_DEPTH=<number>` Set the depth of the git clone operation. Use 0 for a
+full clone. [default: 5]
+
+`FOO_DIRNAME=<name>` Set the local directory name for the checkout. This will
+be always be extended by the release or branch name as `<name>-<version>`.
+[default is the slug in lower case: `foo`]
+
+`FOO_HOOK=<script>` Set the name of a script that will be run after cloning
+the module, before compiling it. Working directory when running the script
+is the root of the targeted module (e.g. `.../.cache/foo-1.2`).
+[default: no hooks are run]
+
+`FOO_VARNAME=<name>` Set the name that is used for the module when creating
+the `RELEASE.local` files. [default is the slug in upper case: `FOO`]
+
+The ci-scripts module contains default settings for widely used modules, so
+that usually it is sufficient to set `FOO=<version>`.
+Feel free to suggest more default settings using a Pull Request.
+
+## Release Numbering of this Module
 
 Major release numbers refer to the API, which is more or less defined
 by the full configuration examples in the service specific
 subdirectories.
 If one of these files has to be changed for the existing configuration
-options or new options are being added, a new major release is created.
+options or important new options are being added, a new major release
+is created.
 
 Minor release numbers refer to bugfixes that should not require the
 configuration inside a user module to be changed.
diff --git a/travis/README.md b/travis/README.md
index 632e63e..3cbb74e 100644
--- a/travis/README.md
+++ b/travis/README.md
@@ -2,12 +2,13 @@
 
 ## Features
 
- -  Compile against different branches or releases of EPICS Base
- -  Use different versions of compilers (gcc, clang)
- -  Cross-compile for Windows 32bit using MinGW and WINE
- -  Cross-compile for RTEMS 4.9 and 4.10
- -  Compile on MacOS
- 
+ - Use different compilers (gcc, clang)
+ - Use different gcc versions
+ - Cross-compile for Windows 32bit and 64bit using MinGW and WINE
+ - Cross-compile for RTEMS 4.9 and 4.10
+ - Compile on MacOS
+ - Released versions of dependencies are cached (for faster builds)
+
 ## How to Use these Scripts
 
  1. Get an account on [Travis-CI](https://travis-ci.org/), connect
@@ -16,20 +17,21 @@
     [Travis-CI Tutorial](https://docs.travis-ci.com/user/tutorial/).
     Make sure to use `travis-ci.org` and not their `.com` site.
 
- 2. In your Support Module, add this respository as a Git Submodule
-    (name suggestion: `.ci`).
-    ```
-    $ git submodule add https://github.com/epics-base/ci-scripts .ci
-    ```
-	
- 3. Create a Travis configuration by copying one of the examples into
+ 2. Add the ci-scripts respository as a Git Submodule
+    (see [README](../README.md) one level above).
+
+ 3. Add settings files defining which dependencies in which versions
+    you want to build against
+    (see [README](../README.md) one level above).
+
+ 4. Create a Travis configuration by copying one of the examples into
     the root directory of your module.
     ```
     $ cp .ci/travis/.travis.yml.example-full .travis.yml
     ```
 	
- 4. Edit the `.travis.yml` configuration to include the jobs you want
-    Travis to run.
+ 5. Edit the `.travis.yml` configuration to include the jobs you want
+    Travis to run. (The examples are commented.)
 	
- 5. Push your changes and check
+ 6. Push your changes and check
     [travis-ci.org](https://travis-ci.org/) for your build results.