travis: update and improve documentation

.travis.yml

@@ -1,4 +1,4 @@
-# .travis.xml for testing EPICS Base ci-scripts
+# .travis.yml for testing EPICS Base ci-scripts
 # (see: https://github.com/epics-base/ci-scripts)
 
 # Note:
@@ -41,12 +41,20 @@ script:
 # Define build jobs
 
 # Well-known variables to use
-# BASE     branch or release tag name of the EPICS Base to use
+# SET      source setup file
 # EXTRA    content will be added to make command line
 # STATIC   set to YES for static build (default: NO)
 # TEST     set to NO to skip running the tests (default: YES)
+# VV       set to make build scripts verbose (default: unset)
 
-matrix:
+# Usually from setup files, but may be specified or overridden
+#  on a job line
+# MODULES  list of dependency modules
+# BASE     branch or release tag name of the EPICS Base to use
+# <MODULE> branch or release tag for a specific module
+# ...      see README for setup file syntax description
+
+jobs:
   include:
 
 # Run unit tests on Linux and Mac

README.md

@@ -49,13 +49,16 @@ example.
  - 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
+ - Cross-compile for RTEMS 4.9 and 4.10 (Base >= 3.16.2)
  - Compile on MacOS
- - Released versions of dependencies are cached (for faster builds)
+ - Built dependencies are cached (for faster builds)
  
 ### How to Use the CI-Scripts
 
  1. Get an account on a supported CI service provider platform.
+    (e.g. [Travis-CI](https://travis-ci.org/),
+    Appveyor, Azure Pipelines...)
+
     (More details in the specific README of the subdirectory.)
 
  2. In your Support Module, add this ci-scripts respository
@@ -63,35 +66,57 @@ example.
     ```
     $ git submodule add https://github.com/epics-base/ci-scripts .ci
     ```
- 3. Create settings files for different sets of dependencies you
+ 3. Create setup files for different sets of dependencies you
-    want to compile against. E.g., a settings file `foo.set`
+    want to compile against. (See below.)
-    specifying
+
+    E.g., a setup file `stable.set` specifying
     ```
     MODULES="sncseq asyn"
 
-    BASE=R3.15.6
+    BASE=${BASE:-R3.15.6}
-    ASYN=master
+    ASYN=${ASYN:-R4-34}
-    SNCSEQ=R2-2-7
+    SNCSEQ=${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.
+    release 2.2.7 and release 4.34 of asyn.
+    (The `${VAR:-default}` form allows overriding from `.travis.yml`.)
 
  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.
+    Use your setup by defining e.g. `SET=stable` in the environment of
-	
+    a job.
+
  5. Push your changes and check the CI service for your build results.
 
-## Settings File Syntax
+## Setup Files
 
-Settings files are sourced by the bash scripts. They are found by searching
+Your module might depend on EPICS Base and a few other support modules.
+(E.g., a specific driver might need StreamDevice, ASYN and the Sequencer.)
+In that case, building against every possible combination of released
+versions of those dependencies is not possible:
+Base (37) x StreamDevice (50) x ASYN (40) x Sequencer (51) would produce
+more than 3.7 million different combinations, i.e. build jobs.
+
+A more reasonable approach is to create a few setups, each being a
+combination of dependency releases, that do a few scans of the available
+"version space". One for the oldest versions you want to support, one or two
+for stable versions that many of your users have in production, one for the
+latest released versions and one for the development branches.
+
+## Setup File Syntax
+
+Setup 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).
 
+Setup files can include other setup files by calling `source_set <setup>`
+(omitting the `.set` extension of the setup file). The configured
+`SETUP_PATH` is searched for the include.
+
 `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
+EPICS Base (slug: `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`.
 
@@ -107,6 +132,8 @@ 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`]
 
+(Use the `${VAR:-default}` form to allow overriding from `.travis.yml`.)
+
 `FOO_REPONAME=<name>` Set the name of the remote repository as `<name>.git`.
 [default is the slug in lower case: `foo`]
 
@@ -139,8 +166,15 @@ 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>`.
+You can find the list of supported (and tested) modules in `defaults.set`.
 Feel free to suggest more default settings using a Pull Request.
 
+## Debugging
+
+Setting `VV=1` in your `.travis.yml` configuration for a specific job
+will run the job with high verbosity, printing every command as it is being
+executed and switching the dependency builds to higher verbosity.
+
 ## Release Numbering of this Module
 
 Major release numbers refer to the API, which is more or less defined

travis/.travis.yml.example-full

@@ -1,6 +1,8 @@
-# .travis.xml for use with EPICS Base ci-scripts
+# .travis.yml for use with EPICS Base ci-scripts
 # (see: https://github.com/epics-base/ci-scripts)
 
+# This is YAML - indentation levels are crucial
+
 language: cpp
 compiler: gcc
 dist: xenial
@@ -24,6 +26,7 @@ addons:
     - clang
     # for mingw builds (32bit and 64bit)
     - g++-mingw-w64-i686
+    - g++-mingw-w64-x86-64
     # for RTEMS cross builds
     - qemu-system-x86
 
@@ -40,13 +43,20 @@ script:
 # Define build jobs
 
 # Well-known variables to use
-# BASE     branch or release tag name of the EPICS Base to use
+# SET      source setup file
 # EXTRA    content will be added to make command line
 # STATIC   set to YES for static build (default: NO)
 # TEST     set to NO to skip running the tests (default: YES)
 # VV       set to make build scripts verbose (default: unset)
 
-matrix:
+# Usually from setup files, but may be specified or overridden
+#  on a job line
+# MODULES  list of dependency modules
+# BASE     branch or release tag name of the EPICS Base to use
+# <MODULE> branch or release tag for a specific module
+# ...      see README for setup file syntax description
+
+jobs:
   include:
 
 # Different configurations of default gcc and clang
@@ -69,7 +79,7 @@ matrix:
   - env: BASE=7.0 EXTRA="CMD_CXXFLAGS=-std=c++11"
     dist: trusty
 
-# Cross-compilation to Windows using MinGW and WINE
+# Cross-compilations to Windows using MinGW and WINE
     
   - env: BASE=7.0 WINE=32 TEST=NO STATIC=YES
     compiler: mingw
@@ -83,7 +93,7 @@ matrix:
 
   - env: BASE=7.0 RTEMS=4.9 TEST=NO
 
-# Other gcc versions (adding as an extra package)
+# Other gcc versions (added as an extra package)
 
   - env: BASE=7.0
     compiler: gcc-6
@@ -99,8 +109,3 @@ matrix:
     os: osx
     compiler: clang
     addons: { homebrew: { packages: ["re2c"], update: true } }
-
-# All above jobs can be defined for other branches or releases of EPICS Base
-# by setting BASE to the branch name or release tag name, e.g.
-# BASE=3.15      (to use the 3.15 branch of Base)
-# BASE=R7.0.3    (to use the 7.0.3 release of Base)

travis/.travis.yml.example-mini

@@ -22,7 +22,7 @@ script:
 
 # Build using default gcc for Base branches 7.0 and 3.15
 
-matrix:
+jobs:
   include:
   - env: BASE=7.0
   - env: BASE=3.15

travis/README.md

@@ -31,7 +31,15 @@
     ```
 	
  5. Edit the `.travis.yml` configuration to include the jobs you want
-    Travis to run. (The examples are commented.)
+    Travis to run.
+
+    Build jobs are declared in the list following the `jobs: include:`
+    declaration. Each element (starting with `-` in column 3) defines the
+    settings for one build job. `env:` controls the setting of environment
+    variables,`dist:` specifies the Linux distribution,
+    `os:` the operating system.
+    Also see the comments in the examples for more hints, and the Travis-CI
+    documentation for more options and more details.
 	
  6. Push your changes and check
     [travis-ci.org](https://travis-ci.org/) for your build results.