Readme: add references, FAQ, Travis badge

(closes #13)

.travis.yml

@@ -27,6 +27,11 @@ addons:
     - g++-mingw-w64-i686
     - g++-mingw-w64-x86-64
     - qemu-system-x86
+  homebrew:
+    packages:
+    - re2c
+    - bash
+    update: true
 
 install:
   - ./travis/prepare.sh
@@ -126,7 +131,6 @@ jobs:
   - env: SET=test01 SNCSEQ=master
     os: osx
     compiler: clang
-    addons: { homebrew: { packages: ["re2c"], update: true } }
 
 # Base 3.15 builds
 # ================
@@ -155,7 +159,6 @@ jobs:
   - env: BASE=R3.15.7 SET=test01 SNCSEQ=master
     os: osx
     compiler: clang
-    addons: { homebrew: { packages: ["re2c"], update: true } }
 
 # Base 3.14 builds
 # ================
@@ -175,4 +178,3 @@ jobs:
   - env: BASE=R3.14.12.8 SET=test01 SNCSEQ=master
     os: osx
     compiler: clang
-    addons: { homebrew: { packages: ["re2c"], update: true } }

LICENSE

@@ -0,0 +1,65 @@
+Copyright (c) 2019 EPICS. All rights reserved.
+
+EPICS CI-Scripts are distributed subject to the following
+license conditions:
+
+ SOFTWARE LICENSE AGREEMENT
+ Software: EPICS CI-Scripts
+
+ 1. The "Software", below, refers to EPICS CI-Scripts (in
+    either source code, or binary form and accompanying documentation).
+    Each licensee is addressed as "you" or "Licensee."
+
+ 2. The copyright holders shown above and their third-party licensors
+    hereby grant Licensee a royalty-free nonexclusive license, subject to
+    the limitations stated herein and U.S. Government license rights.
+
+ 3. You may modify and make a copy or copies of the Software for use
+    within your organization, if you meet the following conditions:
+      a. Copies in source code must include the copyright notice and this
+         Software License Agreement.
+      b. Copies in binary form must include the copyright notice and this
+         Software License Agreement in the documentation and/or other
+         materials provided with the copy.
+
+ 4. You may modify a copy or copies of the Software or any portion of it,
+    thus forming a work based on the Software, and distribute copies of
+    such work outside your organization, if you meet all of the following
+    conditions:
+      a. Copies in source code must include the copyright notice and this
+         Software License Agreement;
+      b. Copies in binary form must include the copyright notice and this
+         Software License Agreement in the documentation and/or other
+         materials provided with the copy;
+      c. Modified copies and works based on the Software must carry
+         prominent notices stating that you changed specified portions of
+         the Software.
+
+ 5. Portions of the Software resulted from work developed under a U.S.
+    Government contract and are subject to the following license: the
+    Government is granted for itself and others acting on its behalf a
+    paid-up, nonexclusive, irrevocable worldwide license in this computer
+    software to reproduce, prepare derivative works, and perform publicly
+    and display publicly.
+
+ 6. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY
+    OF ANY KIND. THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE
+    UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR
+    EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+    BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
+    FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME
+    ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS,
+    OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE
+    SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT
+    THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE
+    OR THAT ANY ERRORS WILL BE CORRECTED.
+
+ 7. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDERS, THEIR
+    THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT
+    OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+    CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE,
+    INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY
+    REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF
+    CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR
+    OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
+    POSSIBILITY OF SUCH LOSS OR DAMAGES.

README.md

@@ -1,3 +1,6 @@
+<a target="_blank" href="http://semver.org">![Version][badge.version]</a>
+<a target="_blank" href="https://travis-ci.org/epics-base/ci-scripts">![Travis status][badge.travis]</a>
+
 # Continuous Integration Scripts for EPICS Modules
 
 The scripts inside this repository are intended to provide a common,
@@ -52,8 +55,8 @@ example.
  - Cross-compile for RTEMS 4.9 and 4.10 (Base >= 3.16.2)
  - Compile on MacOS
  - Built dependencies are cached (for faster builds)
- 
+
-### How to Use the CI-Scripts
+## 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/),
@@ -119,7 +122,7 @@ empty. That way any settings can be overridden by settings in `.travis.yml`.
 
 Empty lines or lines starting with `#` are ignored.
 
-`MODULES="<list of names>"` should list the dependencies (software modules)
+`MODULES=<list of names>` should list the dependencies (software modules)
 by using their well-known slugs, separated by spaces.
 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
@@ -133,9 +136,7 @@ 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
+be a *tag* name or a *branch* name. [default: `master`]
-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`]
@@ -143,7 +144,8 @@ and recompiled as part of the job). [default: `master`]
 `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.
+`FOO_REPOURL="<url>"` Set the complete URL of the remote repository. Useful
+for dependencies that are not hosted on GitHub.
 
 The default URL for the repository is pointing to GitHub, under
 `$FOO_REPOOWNER` else `$REPOOWNER` else `epics-modules`,
@@ -178,8 +180,29 @@ 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.
 
+## References: User Modules
+
+EPICS: [PCAS module](https://github.com/epics-modules/pcas)
+
+EPICS Base: [pvData](https://github.com/epics-base/pvDataCPP),
+[pvAccess](https://github.com/epics-base/pvAccessCPP),
+[pva2pva](https://github.com/epics-base/pva2pva)
+
+ESS: [Motor driver (model 3) for EtherCAT Motion Controller](https://github.com/EuropeanSpallationSource/m-epics-ethercatmc)
+
+ITER: [OPC UA Device Support](https://github.com/ralphlange/opcua)
+
+## Frequently Asked Questions
+
+**How can I see what the dependency jobs are actually doing?**
+
+Set `VV=1` in the configuration line of the job you are interested in.
+This will make all builds (not just for your module) verbose.
+
 ## Release Numbering of this Module
 
+The module tries to apply [Semantic Versioning](https://semver.org/).
+
 Major release numbers refer to the API, which is more or less defined
 by the full configuration examples in the service specific
 subdirectories.
@@ -187,12 +210,21 @@ If one of these files has to be changed for the existing configuration
 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
+Minor release numbers refer to additions and enhancements that do not
-configuration inside a user module to be changed.
+require the configuration inside an existing user module to be changed.
 
 Again: using the git submodule mechanism to include these scripts means
 that user modules always work with a fixed, frozen version.
-I.e., developments in the ci-scripts repository will never break an\
+I.e., developments in the ci-scripts repository will never break an
 existing application.
 These release numbering considerations are just a hint to assess the
 risks when updating the submodule.
+
+## License
+
+This module is distributed subject to a Software License Agreement found
+in file LICENSE that is included with this distribution.
+
+<!-- Links -->
+[badge.version]: https://badge.fury.io/gh/epics-base%2Fci-scripts.svg
+[badge.travis]: https://travis-ci.org/epics-base/ci-scripts.svg?branch=master

defaults.set

@@ -33,3 +33,4 @@ STREAM_REPOOWNER=paulscherrerinstitute
 # busy
 # sscan
 # iocStats
+# motor

travis-test.sh

@@ -27,7 +27,7 @@ fn_exists() {
 
 repo_exists() {
   DEP=$1
-  dep_lc=$(echo $DEP | tr 'A-Z' 'a-z')
+  dep_lc=${DEP,,}
   eval dirname=\${${DEP}_DIRNAME:=${dep_lc}}
   eval reponame=\${${DEP}_REPONAME:=${dep_lc}}
   eval repourl=\${${DEP}_REPOURL:="https://github.com/\${${DEP}_REPOOWNER:=${REPOOWNER:-epics-modules}}/${reponame}.git"}
@@ -35,7 +35,7 @@ repo_exists() {
   git ls-remote --quiet --heads --exit-code $repourl > /dev/null 2>&1
 }
 
-SETUP_DIRS=$(echo $SETUP_PATH | tr ":" "\n")
+SETUP_DIRS=${SETUP_PATH//:/ }
 
 SCRIPTDIR=$(dirname $(readlinkf $0))/travis
 CURDIR="$PWD"
@@ -98,6 +98,7 @@ repo_exists AUTOSAVE || die "Defaults for AUTOSAVE do not point to a valid git r
 repo_exists BUSY || die "Defaults for BUSY do not point to a valid git repository at $repourl"
 repo_exists SSCAN || die "Defaults for SSCAN do not point to a valid git repository at $repourl"
 repo_exists IOCSTATS || die "Defaults for IOCSTATS do not point to a valid git repository at $repourl"
+repo_exists MOTOR || die "Defaults for MOTOR do not point to a valid git repository at $repourl"
 
 # test update_release_local()
 ######################################################################
@@ -158,6 +159,7 @@ add_dependency BASE R3.15.6
 [ -e $location/LICENSE ] || die "Missing dependency was not checked out"
 BUILT=$(cat "$location/built")
 [ "$BUILT" != "$hash_3_15_6" ] && die "Wrong commit of dependency checked out (expected=\"$hash_3_15_6\" found=\"$BUILT\")"
+grep -q "include \$(TOP)/../RELEASE.local" $location/configure/RELEASE && die "RELEASE in Base includes RELEASE.local"
 
 # up-to-date dependency does exist in the cache
 ( cd $CACHEDIR; git clone --quiet --depth 5 --recursive --branch R3.15.6 https://github.com/epics-base/epics-base.git base-R3.15.6 )
@@ -173,3 +175,9 @@ BUILT=$(cat "$location/built")
 [ "$BUILT" != "$hash_3_15_6" ] && die "Wrong commit of dependency checked out (expected=\"$hash_3_15_6\" found=\"$BUILT\")"
 
 rm -fr $location
+
+# missing inclusion of RELEASE.local in configure/RELEASE
+location=$CACHEDIR/std-R3-4
+add_dependency STD R3-4
+grep -q "include \$(TOP)/../RELEASE.local" $location/configure/RELEASE || die "Inclusion of RELEASE.local not added to configure/RELEASE"
+rm -fr $location

travis/.travis.yml.example-full

@@ -29,6 +29,13 @@ addons:
     - g++-mingw-w64-x86-64
     # for RTEMS cross builds
     - qemu-system-x86
+  homebrew:
+    packages:
+    # for all EPICS builds
+    - bash
+    # for the sequencer
+    - re2c
+    update: true
 
 install:
   - ./.ci/travis/prepare.sh
@@ -108,4 +115,3 @@ jobs:
   - env: BASE=7.0
     os: osx
     compiler: clang
-    addons: { homebrew: { packages: ["re2c"], update: true } }

travis/prepare.sh

@@ -1,14 +1,24 @@
 #!/bin/bash
 set -e
 
+# The following if clause can be removed for ci-scripts major version 3
+if [ "$TRAVIS_OS_NAME" == osx -a "$BASH_VERSINFO" -lt 4 ]
+then
+    brew install bash
+    if [ $(/usr/local/bin/bash -c 'echo $BASH_VERSINFO') -lt 4 ]
+    then
+        echo "Failed to install a recent bash" >&2
+        exit 1
+    fi
+    exec /usr/local/bin/bash $0 "$@"
+fi
+
 # Set VV in .travis.yml to make scripts verbose
 [ "$VV" ] && set -x
 
 # Perl version of "readlink -f" (which MacOS does not provide)
 readlinkf() { perl -MCwd -e 'print Cwd::abs_path shift' "$1"; }
 
-SETUP_DIRS=$(echo $SETUP_PATH | tr ":" "\n")
-
 SCRIPTDIR=$(dirname $(readlinkf $0))
 CURDIR="$PWD"
 CACHEDIR="$HOME/.cache"
@@ -16,6 +26,8 @@ CACHEDIR="$HOME/.cache"
 # source functions
 . $SCRIPTDIR/utils.sh
 
+echo -e "${ANSI_YELLOW}Using bash version $BASH_VERSION${ANSI_RESET}"
+
 # Load settings
 # -------------
 
@@ -36,7 +48,7 @@ fold_start check.out.dependencies "Checking/cloning dependencies"
 
 for mod in BASE $MODULES
 do
-  mod_uc=$(echo $mod | tr 'a-z' 'A-Z')
+  mod_uc=${mod^^}
   eval add_dependency $mod_uc \${${mod_uc}:=master}
 done
 [ -e ./configure ] && cp ${CACHEDIR}/RELEASE.local ./configure/RELEASE.local
@@ -151,7 +163,7 @@ EOF
   fi
 
 else
-  echo "${ANSI_GREEN}EPICS build system already set up (Base was loaded from cache)${ANSI_RESET}"
+  echo -e "${ANSI_GREEN}EPICS build system already set up (Base was loaded from cache)${ANSI_RESET}"
 fi
 
 # Download RTEMS cross compiler
@@ -174,7 +186,7 @@ fold_start build.dependencies "Build missing/outdated dependencies"
 
 [ "$VV" ] && silent="-s" || silent=
 
-[ -z "$modules_to_compile" ] && echo "${ANSI_GREEN}All dependency modules are up-to-date (nothing to do)${ANSI_RESET}"
+[ -z "$modules_to_compile" ] && echo -e "${ANSI_GREEN}All dependency modules are up-to-date (nothing to do)${ANSI_RESET}"
 
 for module in ${modules_to_compile}
 do
@@ -186,13 +198,13 @@ done
 
 fold_end build.dependencies
 
-echo "${ANSI_BLUE}Dependency module information${ANSI_RESET}"
+echo -e "${ANSI_BLUE}Dependency module information${ANSI_RESET}"
 
 echo "Module     Tag          Binaries    Commit"
 echo "-----------------------------------------------------------------------------------"
 for mod in base $MODULES
 do
-  mod_uc=$(echo $mod | tr 'a-z' 'A-Z')
+  mod_uc=${mod^^}
   eval tag=\${${mod_uc}}
   eval dir=${CACHEDIR}/\${${mod_uc}_DIRNAME}-$tag
   echo "$modules_to_compile" | grep -q "$dir" && stat="rebuilt" || stat="from cache"
@@ -200,5 +212,5 @@ do
   printf "%-10s %-12s %-11s %s\n" "$mod" "$tag" "$stat" "$commit"
 done
 
-echo "${ANSI_BLUE}Contents of RELEASE.local${ANSI_RESET}"
+echo -e "${ANSI_BLUE}Contents of RELEASE.local${ANSI_RESET}"
 cat ${CACHEDIR}/RELEASE.local

travis/utils.sh

@@ -22,28 +22,29 @@ export ANSI_CLEAR="\033[0K"
 # from https://github.com/travis-ci/travis-rubies/blob/build/build.sh
 
 fold_start() {
-  echo -en "travis_fold:start:$1\\r${ANSI_YELLOW}$2${ANSI_RESET}"
+  echo -e "travis_fold:start:$1\\r${ANSI_YELLOW}$2${ANSI_RESET}"
 }
 
 fold_end() {
   echo -en "travis_fold:end:$1\\r"
 }
 
+die() {
+  echo -e "${ANSI_RED}$1${ANSI_RESET}"
+  [ "$UTILS_UNITTEST" ] || exit 1
+}
+
 # source_set(settings)
 #
-# Source a settings file (extension .set) found in the SETUP_DIRS path
+# Source a settings file (extension .set) found in SETUP_PATH
 # May be called recursively (from within a settings file)
 declare -a SEEN_SETUPS
 source_set() {
   local set_file=${1//[$'\r']}
   local set_dir
   local found=0
-  if [ -z "${SETUP_DIRS}" ]
+  [ "${SETUP_PATH}" ] || die "Search path for setup files (SETUP_PATH) is empty"
-  then
+  for set_dir in ${SETUP_PATH//:/ }
-    echo "${ANSI_RED}Search path for setup files (SETUP_PATH) is empty${ANSI_RESET}"
-    [ "$UTILS_UNITTEST" ] || exit 1
-  fi
-  for set_dir in ${SETUP_DIRS}
   do
     if [ -e $set_dir/$set_file.set ]
     then
@@ -75,11 +76,7 @@ source_set() {
       break
     fi
   done
-  if [ $found -eq 0 ]
+  [ $found -ne 0 ] || die "Setup file $set_file.set does not exist in SETUP_PATH search path ($SETUP_PATH)"
-  then
-    echo "${ANSI_RED}Setup file $set_file.set does not exist in SETUP_DIRS search path ($SETUP_DIRS)${ANSI_RESET}"
-    [ "$UTILS_UNITTEST" ] || exit 1
-  fi
 }
 
 # update_release_local(varname, place)
@@ -135,21 +132,18 @@ add_dependency() {
   curdir="$PWD"
   DEP=$1
   TAG=$2
-  dep_lc=$(echo $DEP | tr 'A-Z' 'a-z')
+  dep_lc=${DEP,,}
   eval dirname=\${${DEP}_DIRNAME:=${dep_lc}}
   eval reponame=\${${DEP}_REPONAME:=${dep_lc}}
   eval repourl=\${${DEP}_REPOURL:="https://github.com/\${${DEP}_REPOOWNER:=${REPOOWNER:-epics-modules}}/${reponame}.git"}
   eval varname=\${${DEP}_VARNAME:=${DEP}}
   eval recursive=\${${DEP}_RECURSIVE:=1}
-  recursive=$(echo $recursive | tr 'A-Z' 'a-z')
+  recursive=${recursive,,}
   [ "$recursive" != "0" -a "$recursive" != "no" ] && recurse="--recursive"
 
   # determine if $DEP points to a valid release or branch
-  if ! git ls-remote --quiet --exit-code --refs $repourl "$TAG" > /dev/null 2>&1
+  git ls-remote --quiet --exit-code --refs $repourl "$TAG" > /dev/null 2>&1 ||
-  then
+    die "$TAG is neither a tag nor a branch name for $DEP ($repourl)"
-    echo "${ANSI_RED}$TAG is neither a tag nor a branch name for $DEP ($repourl)${ANSI_RESET}"
-    [ "$UTILS_UNITTEST" ] || exit 1
-  fi
 
   if [ -e $CACHEDIR/$dirname-$TAG ]
   then
@@ -182,6 +176,15 @@ add_dependency() {
     git clone --quiet $deptharg $recurse --branch "$TAG" $repourl $dirname-$TAG
     ( cd $dirname-$TAG && git log -n1 )
     modules_to_compile="${modules_to_compile} $CACHEDIR/$dirname-$TAG"
+    # fix non-base modules that do not include the .local files in configure/RELEASE
+    if [ $DEP != "BASE" ]
+    then
+      release=$CACHEDIR/$dirname-$TAG/configure/RELEASE
+      if [ -e $release ]
+      then
+        grep -q "include \$(TOP)/../RELEASE.local" $release || echo "-include \$(TOP)/../RELEASE.local" >> $release
+      fi
+    fi
     # run hook
     eval hook="\${${DEP}_HOOK}"
     if [ "$hook" ]
@@ -191,8 +194,7 @@ add_dependency() {
         echo "Running hook $hook in $CACHEDIR/$dirname-$TAG"
         ( cd $CACHEDIR/$dirname-$TAG; "$curdir/$hook" )
       else
-        echo "${ANSI_RED}Hook script $hook is not executable or does not exist.${ANSI_RESET}"
+        die "Hook script $hook is not executable or does not exist."
-        exit 1
       fi
     fi
     HEAD=$(cd "$CACHEDIR/$dirname-$TAG" && git log -n1 --pretty=format:%H)