From 6b856eb35ead819c75bb1b22f79f91b17a962020 Mon Sep 17 00:00:00 2001 From: David James Sherman Date: Thu, 18 Jan 2018 15:54:55 +0100 Subject: [PATCH] Update README.md --- README.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0ba5e25..d804f60 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,36 @@ -# Aseba Jenkins -Support for building Aseba components in Jenkins 2. +# Aseba Continuous Integration +Support for continuous integration of Aseba software components in Jenkins 2 and in Docker. ## Global Library -If this repository is declared as a [Jenkins global library](https://github.com/jenkinsci/workflow-cps-global-lib-plugin/blob/master/README.md), it will provide a pipeline step function **CMake** that will configure, make, and install a program. The function accepts the following arguments: -* `sourceDir` (default: workDir) -* `getGenerator` (default: 'Unix Makefiles') -* `buildType` (default: 'Debug') -* `buildDir` (default: workDir + '/build') -* `installDir` (default: workdir + '/dist') -* `makeInvocation` (default: 'make') -* `makeInstallInvocation` (default: 'make install') -* `getCmakeArgs`: additional CMake arguments, list or single string (no default) + +### CMake +If this repository is declared as a [Jenkins global library](https://jenkins.io/doc/book/pipeline/shared-libraries/), it will provide a pipeline step function **CMake** that will configure, make, and install a program. The function accepts the following arguments: * `label` optional subdirectory to append to `buildDir` and `installDir` +* `buildDir` where to compile (default: workDir + '/build/' + label) +* `sourceDir` where to find the source (default: workDir) +* `installDir` where to install (default: workdir + '/dist/' + label) +* `cleanBuild` should buildDir be emptied first (default: true) +* `buildType` CMake build type (default: 'Debug') +* `getGenerator` which build generator (default: 'Unix Makefiles') +* `makeInvocation` how to build (default: 'make') +* `makeInstallInvocation` how to install (default: 'make install') +* `getCmakeArgs`: additional CMake arguments, list or single string (no default) +* `getArgumentss`: additional CMake arguments, list or single string (no default) +* `preloadScript`: commands to run first (no default) This function is a stopgap, waiting for the [official CMake plugin](https://wiki.jenkins-ci.org/display/JENKINS/CMake+Plugin) to catch up with Jenkins Pipeline (see [JENKINS-34998 Make CMake plugin compatible with pipeline](https://issues.jenkins-ci.org/browse/JENKINS-34998)). Its arguments try to match [CMake Build Configuration](https://wiki.jenkins-ci.org/display/JENKINS/CMake+Build+Configuration). Like the official plugin, this function runs both CMake and a build invocation (make, make install). -This global library also provides a utility function **FindAvailableNodes** that will filter a list of candidate node labels, by default `['debian','windows','macos']`, and only return those that are available in the current Jenkins instance. +The CMake step constructs a Bash script that is then executed, using a **shell** step if run on Unix, or a **powershell** step if run on Windows. The script is written to the console log so that it can be run manually if desired. + +### FindAvailableNodes +The utility function **FindAvailableNodes** will filter a list of candidate node labels, by default `['debian','windows','macos']`, and only return those that are available in the current Jenkins instance. This can be used to build multi-OS pipelines where some OSes may not be available at a given time. ## Resources -The directory [`resources/buildfarm`](resources/buildfarm) contains Ansible playbooks to install development environments for Linux, macOS, and Windows, with prerequisites for compiling Aseba. It will be necessary to customize the `hosts` inventory to reflect your particular installation. +### Build node configuration +The directory [`resources/buildfarm`](resources/buildfarm) contains [Ansible](https://www.ansible.com) playbooks to install development environments for Linux, macOS, and Windows, with prerequisites for compiling Aseba. It will be necessary to customize the `hosts` inventory to reflect your particular installation. +### Docker images Jenkins can be run in a Docker container to provide a Debian build environment. The directory [`resources/buildfarm/docker`](resources/buildfarm/docker) contains a Dockerfile that will install Aseba prerequisites for building on the master node, and Jenkins plugins needed to run the Aseba Jenkinsfiles.