epics/ci-scripts
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

travis: update and improve documentation

Browse Source
This commit is contained in:
Ralph Lange
2019-12-06 10:13:56 +01:00
parent de43213873
commit 40fe8f3852
5 changed files with 84 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.travis.yml
View File

@@ -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

62
README.md
View File

@@ -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 <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

25
travis/.travis.yml.example-full
View File

@@ -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)

2
travis/.travis.yml.example-mini
View File

@@ -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

10
travis/README.md
View File

@@ -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.