Docs: Travis-CI Workflow (#5133)

* Docs: Travis-CI Workflow

Add a workflow how to use spack on Travis-CI.

Future Work:

depending if and how we can simplify 5101:
add a multi-compiler, multi-C++-standard, multi-software
build matrix example

* Fix Typos

1 files changed, 78 insertions, 0 deletions

diff --git a/lib/spack/docs/workflows.rst b/lib/spack/docs/workflows.rst
index 84da3b0f44..10843d302b 100644
--- a/lib/spack/docs/workflows.rst
+++ b/lib/spack/docs/workflows.rst
@@ -1028,6 +1028,84 @@ or filesystem views.  However, it has some drawbacks:
    integrate Spack explicitly in their workflow.  Not all users are
    willing to do this.
 
+------------------------
+Using Spack on Travis-CI
+------------------------
+
+Spack can be deployed as a provider for userland software in
+`Travis-CI <https://http://travis-ci.org>`_.
+
+A starting-point for a ``.travis.yml`` file can look as follows.
+It uses `caching <https://docs.travis-ci.com/user/caching/>`_ for
+already built environments, so make sure to clean the Travis cache if
+you run into problems.
+
+The main points that are implemented below:
+
+#. Travis is detected as having up to 34 cores available, but only 2
+   are actually allocated for the user. We limit the parallelism of
+   the spack builds in the config.
+   (The Travis yaml parser is a bit buggy on the echo command.)
+
+#. Builds over 10 minutes need to be prefixed with ``travis_wait``.
+   Alternatively, generate output once with ``spack install -v``.
+
+#. Travis builds are non-interactive. This prevents using bash
+   aliases and functions for modules. We fix that by sourcing
+   ``/etc/profile`` first (or running everything in a subshell with
+   ``bash -l -c '...'``).
+
+.. code-block:: yaml
+
+   language: cpp
+   sudo: false
+   dist: trusty
+
+   cache:
+     apt: true
+     directories:
+       - $HOME/.cache
+
+   addons:
+     apt:
+       sources:
+         - ubuntu-toolchain-r-test
+       packages:
+         - g++-4.9
+         - environment-modules
+
+   env:
+     global:
+       - SPACK_ROOT: $HOME/.cache/spack
+       - PATH: $PATH:$HOME/.cache/spack/bin
+
+   before_install:
+     - export CXX=g++-4.9
+     - export CC=gcc-4.9
+     - export FC=gfortran-4.9
+     - export CXXFLAGS="-std=c++11"
+
+   install:
+     - if ! which spack >/dev/null; then
+         mkdir -p $SPACK_ROOT &&
+         git clone --depth 50 https://github.com/llnl/spack.git $SPACK_ROOT &&
+         echo -e "config:""\n  build_jobs:"" 2" > $SPACK_ROOT/etc/spack/config.yaml;
+       fi
+     - travis_wait spack install cmake@3.7.2~openssl~ncurses
+     - travis_wait spack install boost@1.62.0~graph~iostream~locale~log~wave
+     - spack clean -a
+     - source /etc/profile &&
+       source $SPACK_ROOT/share/spack/setup-env.sh
+     - spack load cmake
+     - spack load boost
+
+   script:
+     - mkdir -p $HOME/build
+     - cd $HOME/build
+     - cmake $TRAVIS_BUILD_DIR
+     - make -j 2
+     - make test
+
 ------------------
 Upstream Bug Fixes
 ------------------