From e867277f6e4a8cb982739167997c8648a3d1bcba Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Mon, 8 Jun 2020 10:26:17 +0200 Subject: [PATCH] Update README files for v3.0 --- README.md | 65 ++++++++++++++++++++++++++++++---------------- appveyor/README.md | 23 +++++++++------- travis/README.md | 10 ++++--- 3 files changed, 61 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 507d6e9..8627062 100644 --- a/README.md +++ b/README.md @@ -20,58 +20,70 @@ never break existing use. ## This Repository -In addition to the scripts themselves (in the subdirectories), -this repository contains the test suite that is used to verify -functionality and features of the ci-scripts. +In addition to the script that runs the builds and tests, this repository +contains service specific documentation and example configuration files +(in the subdirectories), and a small test suite that is used to verify +functionality and features of the ci-scripts module itself You are welcome to use the test suite as a reference, but keep in -mind that in your module the path to the scripts has one level more -(e.g., `./travis/abc` here would be `./.ci/travis/abc` in your +mind that in your main module the path to the scripts has one level more +(e.g., `./abc` here would be `./.ci/abc` in your module). -Also, a test suite might not show the same level of quality as an -example. +Also, a test suite might not show the same quality and documentation levels +as an example. ## Features - Compile against different branches or releases of EPICS Base and - additional dependencies (modules like asyn, std, etc.). + additional dependencies (modules like asyn, std, sequencer, etc.). - Define settings files that declare sets of dependencies with their versions and locations. - - Define hook scripts for any dependency. + - Define hooks for any dependency. Hooks are run on the dependency module before it is compiled, so the module can be patched or further configured. - - Define static or shared builds (executables, libraries). + - Define shared (default) or static builds (for executables and libraries). + + - Define optimized (default) or debug builds. - - Run tests (using the EPICS unit test suite). + - Run tests (using the EPICS build system, i.e., `make runtests` + and friends). ## Supported CI Services ### [Travis-CI](https://travis-ci.org/) + - Five parallel runners on Linux/Windows (one runner on MacOS) - 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 (Base >= 3.16.2) - - Compile on MacOS - - Built dependencies are cached (for faster builds) + - Cross-compile for RTEMS 4.9 and 4.10 (Base >= 3.15) + - Compile natively on MacOS (clang) + - Compile natively on Windows (gcc/MinGW, Visual Studio 2017) + - Built dependencies are cached (for faster builds). -See specific **[ci-scripts on Travis-CI README](travis/README.md)** for more details. +See specific +**[ci-scripts on Travis-CI README](travis/README.md)** +for more details. ### [AppVeyor](https://www.appveyor.com/) - - Use different compilers (Visual Studio, MinGW) + - One parallel runner (all builds are sequential) + - Use different compilers (Visual Studio, gcc/MinGW) - Use different Visual Studio versions: \ - 2008, 2010, 2012, 2013, 2015, 2017, 2019 + 2008, 2010, 2012, 2013, 2015, 2017, 2019 - Compile for Windows 32bit and 64bit + - No useful caching available. -See specific **[ci-scripts on AppVeyor README](appveyor/README.md)** for more details. +See specific +**[ci-scripts on AppVeyor README](appveyor/README.md)** +for more details. ## 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](https://www.appveyor.com/), Azure Pipelines...) + [AppVeyor](https://www.appveyor.com/), ...) (More details in the specific README of the subdirectory.) @@ -94,8 +106,8 @@ See specific **[ci-scripts on AppVeyor README](appveyor/README.md)** for more de ``` will compile against the EPICS Base 3.15 branch, the Sequencer release 2.2.8 and release 4.34 of asyn. - (Any settings can be overridden from the specific job configuration - in e.g. `.travis.yml`.) + (Any settings can be overridden from the specific job line + in the service configuration, e.g., `.travis.yml`.) 4. Create a configuration for the CI service by copying one of the examples provided in the service specific subdirectory @@ -111,8 +123,8 @@ 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. +Base (39) x StreamDevice (50) x ASYN (40) x Sequencer (52) would produce +more than 4 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 @@ -201,6 +213,13 @@ builds to higher verbosity. For debugging on your local machine, you may set `CACHEDIR` to change the location for the dependency builds. [default is `$HOME/.cache`] +Service specific debugging options are described in the README files +in the service specific subdirectories: + +- [Travis-CI README](travis/README.md) +- [AppVeyor README](appveyor/README.md) + + ## References: EPICS Modules Using ci-scripts [EPICS Base](https://github.com/epics-base/epics-base) and its submodules diff --git a/appveyor/README.md b/appveyor/README.md index 2ee6084..e4005f3 100644 --- a/appveyor/README.md +++ b/appveyor/README.md @@ -2,11 +2,12 @@ ## Features - - Use different compilers (Visual Studio, MinGW) - - Use different VS versions (2008, 2010, 2012, 2013, 2015, 2017, 2019) + - One parallel runner (all builds are sequential) + - Use different compilers (Visual Studio, gcc/MinGW) + - Use different Visual Studio versions: \ + 2008, 2010, 2012, 2013, 2015, 2017, 2019 - Compile for Windows 32bit and 64bit - - Create static libraries or DLLs (plus the matching executables) - - Create optimized or debug builds + - No useful caching available. ## How to Use these Scripts @@ -33,24 +34,26 @@ AppVeyor automatically creates a build matrix with the following axes: 1. `configuration:` \ - Select static or dynamic (DLL) as well as regular or debug builds. + Select shared (DLL) or static as well as optimized or debug builds. \ + Default: `shared-optimized` 2. `platform:` \ Select 32bit or 64bit processor architecture. 3. `environment: / matrix:` \ List of environment variable settings. Each list element (starting with a dash) is one step on the axis of the build matrix. \ - Set `CMP` to select the compiler: `mingw` for the native + Set `CMP` to select the compiler: `gcc` for the native [MinGW](http://mingw-w64.org/) GNU compiler, `vs2008` ...`vs2019` (options listed above) for the Microsoft Visual Studio compilers. Your builds will take long. \ - AppVeyor only grants a single worker VM - all jobs of the matrix are - executed sequentially. Each job will take between 6 and 15 minutes, - plus testing time. + AppVeyor only grants a single parallel runner VM - all jobs of the matrix + are executed sequentially. AppVeyor also does not provide a usable cache + mechanism to retain dependency artifacts across builds. + Each job will take between 6 and 15 minutes, plus testing time, every time. The `matrix: / exclude:` setting can be used to reduce the number of jobs. Check the [AppVeyor docs][appveyor.doc.matrix] - for more ways to reduce the build matrix size. + for more ways to reduce the build matrix size. \ E.g., you can opt for not creating matrix axes for `configuration:` and`platform:` by moving these configurations into the job lines under `environment: / matrix:`. diff --git a/travis/README.md b/travis/README.md index 1f4bcb0..2d9dac5 100644 --- a/travis/README.md +++ b/travis/README.md @@ -2,12 +2,14 @@ ## Features + - Five parallel runners on Linux/Windows (one runner on MacOS) - 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 - - Compile on MacOS - - Released versions of dependencies are cached (for faster builds) + - Cross-compile for RTEMS 4.9 and 4.10 (Base >= 3.15) + - Compile natively on MacOS (clang) + - Compile natively on Windows (gcc/MinGW, Visual Studio 2017) + - Built dependencies are cached (for faster builds). ## How to Use these Scripts @@ -34,7 +36,7 @@ Travis to run. Build jobs are declared in the list following the `jobs: include:` - declaration. Each element (starting with `-` in column 3) defines the + declaration. Each element (starting with a dash) defines the settings for one build job. `env:` controls the setting of environment variables,`dist:` specifies the Linux distribution, `os:` the operating system.