From 40fe8f3852ac474dd7e6c81d469f76ecff215756 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Fri, 6 Dec 2019 10:13:56 +0100 Subject: [PATCH] travis: update and improve documentation --- .travis.yml | 14 ++++++-- README.md | 62 +++++++++++++++++++++++++-------- travis/.travis.yml.example-full | 25 +++++++------ travis/.travis.yml.example-mini | 2 +- travis/README.md | 10 +++++- 5 files changed, 84 insertions(+), 29 deletions(-) diff --git a/.travis.yml b/.travis.yml index 05773d7..0ede48a 100644 --- a/.travis.yml +++ b/.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 +# branch or release tag for a specific module +# ... see README for setup file syntax description + +jobs: include: # Run unit tests on Linux and Mac diff --git a/README.md b/README.md index 6bf66ef..d33d79d 100644 --- a/README.md +++ b/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 - want to compile against. E.g., a settings file `foo.set` - specifying + 3. Create setup files for different sets of dependencies you + want to compile against. (See below.) + + E.g., a setup file `stable.set` specifying ``` MODULES="sncseq asyn" - BASE=R3.15.6 - ASYN=master - SNCSEQ=R2-2-7 + BASE=${BASE:-R3.15.6} + ASYN=${ASYN:-R4-34} + 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 ` +(omitting the `.set` extension of the setup file). The configured +`SETUP_PATH` is searched for the include. + `MODULES=""` 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=` Set the name of the remote repository as `.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=`. +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 diff --git a/travis/.travis.yml.example-full b/travis/.travis.yml.example-full index 4d14de3..2567d19 100644 --- a/travis/.travis.yml.example-full +++ b/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 +# 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) diff --git a/travis/.travis.yml.example-mini b/travis/.travis.yml.example-mini index d04a9df..d680894 100644 --- a/travis/.travis.yml.example-mini +++ b/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 diff --git a/travis/README.md b/travis/README.md index 3cbb74e..26a72bc 100644 --- a/travis/README.md +++ b/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.