# Helper class for Jenkins

This repo add functionality for automate building with `platforms.json` configuration.

## Setup

You should add `PLATFORMS_GIT` and `PLATFORMS_FILTER_GIT` environment to your Jenkins with url to git repo, which
contains single `platforms.json` and `filter.json` file.

`PLATFORMS_GIT` -> `platforms.json`

`PLATFORMS_FILTER_GIT` -> `filter.json`


Next you should register this library in Jenkins -> System settings -> Global Pipeline Libraries:
* Library name: `SHS.Platforms`
* Default version: `master`
* Project Repository: `https://git.shstk.ru/SHS/jenkins_lib.git`


Then create pipeline job with fixed name `shstk-platforms` and set script to:
```
@Library('SHS.Platforms') _
node {
	properties([copyArtifactPermission('*')])
    def pl = new org.SHS.Platforms(this)
    pl.createLocal()
}
```
If you want to copy final json to host, add 
```
pl.copyToHost('/your/path/platforms.json')
```

## API

`org.SHS.Platforms` Class:
 * `createLocal()` - download and parse `platforms.json` from `PLATFORMS_GIT` and `filter.json` from `PLATFORMS_FILTER_GIT`, filter/prepare final JSON and save it to artifact
 * `copyToHost(path)` - call after createLocal() to copy final JSON to `path` on your host
 * `get()` - read and parse `platforms_local.json` file from "shstk-platforms" artifact
 * `root()` - returns root JSON object of `platforms.json`
 * `forEach(func, ...)` - iterate over platforms, `func` is only mandatory parameter:
   * `func` - method to execute for each enabled platform, pass JSON element of current platform and optional CMake toolchain argument
   * `stagePrefix` - prefix string for `stage`
   * `stageSuffix` - suffix string for `stage`
   * `whiteList` - array of permitted names, ignored if empty
   * `blackList` - array of denied names, ignored if empty
   * `ondemand` - if true then process also ondemand platforms
   
`whiteList` and `blackList` are case-insensitive, and can be part of platform name

## Usage

Simple:
```
@Library('SHS.Platforms') _
node {
    def pl = new org.SHS.Platforms(this)
    pl.get()
    pl.forEach ({ dist ->
        print("works in ${dist.docker.image_basename}")
    })
}
```

With toolchain:
```
@Library('SHS.Platforms') _
node {
    def pl = new org.SHS.Platforms(this)
    pl.get()
    pl.forEach ({ dist, cmake_toolchain ->
        print("compile in ${dist.docker.image_basename} with arg ${cmake_toolchain}")
    })
}
```

With white/black lists:
```
@Library('SHS.Platforms') _
node {
    def pl = new org.SHS.Platforms(this)
    pl.get()
    pl.forEach ({ dist ->
			print("works in ${dist.docker.image_basename}")
		},
		stagePrefix: "Build ",
		stageSuffix: " soft",
		whiteList: ["ubuntu", "debian", "osx"],
		blackList: ["20.04", "11"]
	)
}
```