diff --git a/README.md b/README.md index 4cb7568..b062b03 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,67 @@ # Continuous Integration Scripts for EPICS Modules -The scripts in this repository are intended to provide a common, +The scripts inside this repository are intended to provide a common, easy-to-use and flexible way to add Continuous Integration to EPICS -software modules, e.g. Device Support modules. +software modules, e.g. Device or Driver Support modules. -By including this repository as a Git Submodule, your module will -always use an explicit commit, i.e. a fixed version of the scripts. -That ensures that further development of these scripts cannot break -your setup. +By including this repository as a Git Submodule, you will be able to +use the same flexible, powerful CI setup that EPICS Bases uses, +including a mechanism to specify sets of dependent modules +(with versions) that you want to compile your module against. -## Travis-CI +By using the submodule mechnism, your module will always use an +explicit commit, i.e. a fixed version of the scripts. +This ensures that any further development of the ci-scripts will +never break existing use. -### Features +## This Repository - - Compile against different branches or releases of EPICS Base - - Use different versions of compilers (gcc, clang) - - Cross-compile for Windows 32bit and 64bit using MinGW and WINE - - Cross-compile for RTEMS 4.9 and 4.10 - - Compile on MacOS +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. + +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 +module). +Also, a test suite might not show the same level of quality as an +example. + +## Supported CI Services + + - Travis-CI -### How to Use these Scripts +### How to Use the CI-Scripts - 1. Get an account on [Travis-CI](https://travis-ci.org/), connect - it to your GitHub account and activate your support module's - repository. For more details, please refer to the - [Travis-CI Tutorial](https://docs.travis-ci.com/user/tutorial/). - Make sure to use `travis-ci.org` and not their `.com` site. + 1. Get an account on a supported CI service provider platform. + (More details in the specific README of the subdirectory.) - 1. In your Support Module, add this respository as a Git Submodule - (name suggestion: `.ci`). + 2. In your Support Module, add this ci-scripts respository + as a Git Submodule (name suggestion: `.ci`). ``` $ git submodule add https://github.com/epics-base/ci-scripts .ci ``` - - 1. Create a Travis configuration by copying one of the examples. - ``` - $ cp .ci/.travis.yml.example-full .travis.yml - ``` - - 1. Edit the `.travis.yml` configuration to include the jobs you want - Travis to run. - - 1. Push your changes and check - [travis-ci.org](https://travis-ci.org/) for your build results. -## Releases and Numbering + 3. 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. + + 4. Push your changes and check the CI service for your build results. + +## Releases and Numbering of this Module Major release numbers refer to the API, which is more or less defined -by the `.travis.yml.example-full` configuration example. -Changing this file for the existing configuration options or to add -new configurations options will usually cause a new major release. +by the full configuration examples in the service specific +subdirectories. +If one of these files has to be changed for the existing configuration +options or new options are being added, a new major release is created. -Minor release numbers refer to bugfixes that should not require a user -module (i.e., its `.travis.yml`) to be changed. +Minor release numbers refer to bugfixes that should not require the +configuration inside a user module to be changed. -Again: using git submodule to include these scripts means that user -modules always work with a fixed, frozen version of these scripts. -I.e., developments in the ci-scripts will never break an existing -application. +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\ +existing application. These release numbering considerations are just a hint to assess the -risk when updating the submodule. +risks when updating the submodule. diff --git a/.travis.yml.example-full b/travis/.travis.yml.example-full similarity index 95% rename from .travis.yml.example-full rename to travis/.travis.yml.example-full index 442c46d..1bb4158 100644 --- a/.travis.yml.example-full +++ b/travis/.travis.yml.example-full @@ -24,14 +24,14 @@ addons: - qemu-system-x86 install: - - ./.ci/travis-prepare.sh + - ./.ci/travis/prepare.sh script: - - ./.ci/travis-build.sh + - ./.ci/travis/build.sh # If you need to do more during install and build, # add a local directory to your module and do e.g. -# - ./.ci-local/travis-install-extras.sh +# - ./.ci-local/travis/install-extras.sh # Define build jobs diff --git a/.travis.yml.example-mini b/travis/.travis.yml.example-mini similarity index 88% rename from .travis.yml.example-mini rename to travis/.travis.yml.example-mini index 209c093..d04a9df 100644 --- a/.travis.yml.example-mini +++ b/travis/.travis.yml.example-mini @@ -15,10 +15,10 @@ addons: - perl install: - - ./.ci/travis-prepare.sh + - ./.ci/travis/prepare.sh script: - - ./.ci/travis-build.sh + - ./.ci/travis/build.sh # Build using default gcc for Base branches 7.0 and 3.15 diff --git a/travis/README.md b/travis/README.md new file mode 100644 index 0000000..632e63e --- /dev/null +++ b/travis/README.md @@ -0,0 +1,35 @@ +# Travis-CI Scripts for EPICS Modules + +## Features + + - Compile against different branches or releases of EPICS Base + - Use different versions of compilers (gcc, clang) + - Cross-compile for Windows 32bit using MinGW and WINE + - Cross-compile for RTEMS 4.9 and 4.10 + - Compile on MacOS + +## How to Use these Scripts + + 1. Get an account on [Travis-CI](https://travis-ci.org/), connect + it to your GitHub account and activate your support module's + repository. For more details, please refer to the + [Travis-CI Tutorial](https://docs.travis-ci.com/user/tutorial/). + Make sure to use `travis-ci.org` and not their `.com` site. + + 2. In your Support Module, add this respository as a Git Submodule + (name suggestion: `.ci`). + ``` + $ git submodule add https://github.com/epics-base/ci-scripts .ci + ``` + + 3. Create a Travis configuration by copying one of the examples into + the root directory of your module. + ``` + $ cp .ci/travis/.travis.yml.example-full .travis.yml + ``` + + 4. Edit the `.travis.yml` configuration to include the jobs you want + Travis to run. + + 5. Push your changes and check + [travis-ci.org](https://travis-ci.org/) for your build results. diff --git a/travis-build.sh b/travis/build.sh similarity index 100% rename from travis-build.sh rename to travis/build.sh diff --git a/travis-prepare.sh b/travis/prepare.sh similarity index 100% rename from travis-prepare.sh rename to travis/prepare.sh