Specification for platforms file

Generic format

This is the general description of the platform format. This will be used when selecting the right supported languages and toolchains based on platform. In this way, we have the flexibility of having a separate lifecycles file and toolchains file on a per platform basis.

{
    "supported_platforms": {
        "somePlatform": {
            "someOS": {
                "language": [
                    "groovy",
                    "java",
                    "python",
                    "ruby"
                ],
                "toolchain": [
                    "env",
                    "gemset",
                    "rvm",
                    "python",
                    "jdk"
                ]
            }
        }
    },
    "restrictions": {
        "somePlatform": {
            "only_organizations": [
                "samrocketman",
                "someorg"
            ],
            "only_projects": [
                "org/project"
            ]
        }
    }
}

Generic format Legend

1. supported_platforms - Is a full index of all platforms supported by a build system. A platform consists of a name, the operating system, languages supported on that OS, and software build toolchains supported on that OS. Validation: this key is required. The name of the key can't change. The value of the key is a HashMap.
2. somePlatform - Is the name of a platform. This can be called anything. It is recommended to be named in a way that makes sense for the infrastructure. For instance, a platform might be called docker because it is all docker containers (with multiple operating systems). Validation: key is optional. The name of the key is variable (e.g. docker). The value of the key is a HashMap. 1. someOS - Is the name of an operating system. This can be called anything. It is recommended to be named in a way that makes sense for the infrastructure. For instance, an operating system might be Ubuntu 14.04 so a recommended name might be ubuntu1404. Validation: key is optional. The name of the key is variable (e.g. ubuntu1404). The value of the key is a HashMap.
   1. language - What languages can be built on this platform and OS? This key specifies what languages are supported. Validation: key is required if someOS is present. The name of the key can't change. The value of the key is an ArrayList of Strings.
   2. toolchain - What toolchains are available on this platform and OS? This key specifies what toolchains are supported. Validation: key is required if someOS is present. The name of the key can't change. The value of the key is an ArrayList of Strings.
3. restrictions - sometimes you don't want just anybody to be able to build on a platform. Restrictions restrict who is allowed to build on this platform. Validation: this key is required. The name of the key can't change. The value of the key is a HashMap.
4. somePlatform - is the name of the restricted platform. Restrict who can use this platform. Validation: key is optional. A key of the same name must exist in supported_platforms key. The name of the key is variable (e.g. docker). The value of the key is a HashMap. 1. only_organizations - All projects within this white list of organizations or usernames can make use of this platform. Validation: This key is optional. The value of this key is an ArrayList. 1. only_projects - Only specific projects in this white list can make use of this platform. Validation: This key is optional. The value of this key is an ArrayList.

A more specific toolchain example

{
    "supported_platforms": {
        "docker": {
            "centos6x": {
                "language": [
                    "groovy",
                    "java",
                    "python",
                    "ruby"
                ],
                "toolchain": [
                    "env",
                    "gemset",
                    "rvm",
                    "python",
                    "jdk"
                ]
            },
            "ubuntu1404": {
                "language": [
                    "groovy",
                    "java",
                    "python",
                    "ruby"
                ],
                "toolchain": [
                    "env",
                    "gemset",
                    "rvm",
                    "python",
                    "jdk"
                ]
            }
        },
        "metal": {
            "centos6x": {
                "language": [
                    "groovy",
                    "java",
                    "python",
                    "ruby"
                ],
                "toolchain": [
                    "env",
                    "gemset",
                    "rvm",
                    "python",
                    "jdk"
                ]
            }
        }
    },
    "restrictions": {
        "metal": {
            "only_organizations": [
                "samrocketman",
                "someorg"
            ],
            "only_projects": [
                "org/project"
            ]
        }
    }
}

When someone loads a platform for the first time in the Job DSL code. They should set a default platform, operating system, and agent stability. The agent stability is a simple concept that just allows stable agents to be for the majority of the build system and unstable agents for toolchain and language experimentation.

import jervis.lang.lifecycleGenerator
def x = new lifecycleGenerator()
x.loadPlatforms('/path/to/platform.json')
x.default_platform = 'docker'
x.default_os = 'ubuntu1404'
x.stability = 'stable'

Example yaml files and outputs

A simple ruby YAML file.

language: ruby

If a platform is not specified in the YAML then the default platform will be used. If a user wishes to override the default platform then they will need to do so via the jenkins YAML key.

language: ruby
language: "ruby"
jenkins:
  unstable: true
  platform: "docker"
  os: "centos6x"