User:Digiku/Cross-platform deployment (Version 2)

An installation package generated for MacOS by Deployer.

You can easily deploy your SRB2 builds to OS X and Linux by using Travis-CI. SRB2's codebase includes a Deployer utility script to upload Travis-CI builds to FTP or Launchpad PPA. This occurs automatically and you do not need to have the host OS installed to take advantage of this system.

AppVeyor will also build 32-bit and 64-bit Windows installers with a limited configuration; see #Windows Deployment with AppVeyor.

How to Use

To use this system, set up Travis-CI for your SRB2 fork on GitHub. Then, set the below parameters as Environment Variables in your Travis-CI repo settings.

Environment variables are encrypted and stored securely, and they are not printed on the log. You may use them to store passwords.

Pull request builds do not have access to these parameters, and so Deployer will only operate on commit builds.

Overview of Changes

Simpler configuration with less settings and more sensible defaults.
GitHub Releases deployment is added. Set the variable DPL_GITHUB_TOKEN with a Personal Access Token
DPUT deployment is removed. DPL_PGP_KEY... and DPL_SSH_KEY... are removed, as are all variables relevant to Debian package builds.

Version 2 is intended to be simpler to configure. Set the following in your Travis-CI settings:

Asset Staging

Assets may be collected from an arbitrary number of 7z archives. The collection of assets will be bundled into the packages.

Parameter	Description	v1 Equivalent
`ASSET_ARCHIVE_PATHS`	A list of one or more URLs separated by semicolon. The URLs point to 7z archives, all of which will be extracted into the asset staging folder (`{repo_root}/assets/installer`) Default: `https://github.com/mazmazz/SRB2/releases/download/SRB2_assets_220/srb2-2.2.4-assets.7z;https://github.com/mazmazz/SRB2/releases/download/SRB2_assets_220/srb2-2.2.4-optional-assets.7z`	`ASSET_ARCHIVE_PATH` `ASSET_ARCHIVE_OPTIONAL_PATH` `ASSET_ARCHIVE_OPTIONAL_GET`
`ASSET_FILES_HASHED=srb2.srb patch.dta ...`	List of filenames that must be MD5-checked by the game. Used by CMAKE to generate the MD5 hashes. Default: `srb2.pk3 zones.pk3 player.dta patch.pk3`	`ASSET_FILES_HASHED`
`ASSET_FILES_DOCS=README.txt LICENSE.txt ...`	List of documentation filenames. These are bundled with all package builds, including the binary-only package. Default: `README.txt LICENSE.txt LICENSE-3RD-PARTY.txt README-SDL.txt`	`ASSET_FILES_DOCS`

Job Management

In Version 2, Deployer is now on-by-default for release tags, branch names with a trigger word, and commit messages with a trigger word.

Unlike Version 1, there is no separation of Test, Main (Program), and Asset buildbots. Each deploying buildbot can output a binary-only, binary-and-asset, and installer build by using the #Package Targets settings, below.

The deployer jobs can be configured by the following:

Parameter	Description	v1 Equivalent
`DPL_BRANCH_TRIGGER`	Branch trigger word. If the branch name contains this word, then the build will be deployed. Default: `deployer`	`DPL_BRANCHES`
`DPL_COMMIT_TRIGGER`	Commit trigger word. If the commit message contains this word in the form [word], then the build will be deployed. Specify this word without the square brackets. Default: `deployer`	`DPL_TRIGGER`
`DPL_TAG_ENABLED`	Toggle whether to deploy on release tag. Set to 0 to disable. Enabled by default.	`DPL_TAG_ENABLED`
`DPL_FORCE_ON` `DPL_FORCE_ON_GITHUB` `DPL_FORCE_ON_FTP`	Set to 1 to always deploy builds, whether or not it's a release tag or it matches the trigger words. You can set this per branch in your Travis-CI settings. `GITHUB` will force-enable just for GitHub Releases. `FTP` will force-enable just for FTP.	`DPL_JOB_ENABLE_ALL` `_DPL_JOB_ENABLED`
`DPL_FORCE_OFF` `DPL_FORCE_OFF_GITHUB` `DPL_FORCE_OFF_FTP`	Set to 1 to never deploy builds, even if it is a release tag or a trigger job. You can set this per branch in your Travis-CI settings. This setting takes priority over `DPL_FORCE_ON`, if both of them are set. `GITHUB` will force-disable just for GitHub Releases. `FTP` will force-disable just for FTP.	`DPL_ENABLED=0`

Package Targets

You may configure one or more package targets as follows:

Parameter	Description	v1 Equivalent
`DPL_UPLOAD_BINARY` `DPL_UPLOAD_BINARY_GITHUB` `DPL_UPLOAD_BINARY_FTP`	Set to 1 to upload a 7z with just the program binary, no assets. Enabled by default. `GITHUB` will enable just for GitHub Releases. `FTP` will enable just for FTP.	`DPL_TERMINATE_MAIN=0`
`DPL_UPLOAD_ASSETS` `DPL_UPLOAD_ASSETS_GITHUB` `DPL_UPLOAD_ASSETS_FTP`	Set to 1 to upload a 7z with the program binary including all assets. `GITHUB` will enable just for GitHub Releases. `FTP` will enable just for FTP.	`DPL_TERMINATE_ASSETS=0`
`DPL_UPLOAD_INSTALLER` `DPL_UPLOAD_INSTALLER_GITHUB` `DPL_UPLOAD_INSTALLER_FTP`	Set to 1 to upload an installer binary. `GITHUB` will enable just for GitHub Releases. `FTP` will enable just for FTP.	`DPL_TERMINATE_MAIN=0`
`DPL_ARCHIVE_NAME`	Name for the package(s). Defaults to `{release_tag}-{os_name}` if building a tag, or otherwise `srb2-{os_name}-{branch_name}-{commit}-{job_id}`. You can use Travis-CI environment variables.

FTP Deployment

Parameters to upload builds to FTP.

To operate on Linux, you need to change your FTP server settings to allow differing IP addresses for data and control connections! This is a security concern. Consider using GitHub releases instead. More info at Travis-CI.

Builds are uploaded via FTP in a folder structure. By default, this is:

ftp://user:[email protected]:21/path/to/upload/
    +-- author/ (e.g., STJr)
        +-- repo-name/ (e.g., SRB2)
            +-- branch-name/
                +-- [job id]-[name] (e.g., 461111231-184.1-osx)
                    +-- commit.txt
                    +-- deploy/
                        +-- {files}

Parameter	Description
`DPL_FTP_PROTOCOL=ftp`	Protocol to use at the beginning of the FTP URI, e.g., `ftp, sftp, ftpes`. Only tested with `ftp`; other protocols may need additional implementation. Default: `ftp`
`DPL_FTP_USER=username`	FTP username login. Never commit this to `.travis.yml`; always specify this in your Travis-CI settings.
`DPL_FTP_PASS=password`	FTP password login. Never commit this to `.travis.yml`; always specify this in your Travis-CI settings.
`DPL_FTP_HOSTNAME=example.com`	Domain name for the FTP URI.
`DPL_FTP_PORT=21`	Port number for the FTP URI. Default: `21`
`DPL_FTP_PATH=path/to/upload`	Base path for uploads. Do not include the trailing slash. You may use TRAVIS environment variables. Default: `/$TRAVIS_REPO_SLUG/$TRAVIS_BRANCH/$TRAVIS_JOB_ID-$TRAVIS_OS_NAME`

GitHub Releases Deployment

Set these permissions when generating a Personal Access Token on GitHub.

Parameters to upload builds to GitHub Releases.

You will need to generate a Personal Access Token to use this target. Go to your user settings > Developer Settings > Personal Access Tokens. Enable all repo permissions. Copy the token value to your Travis-CI user settings.

This target is not supported on Windows.

Parameter	Description
`DPL_GITHUB_TOKEN`	Token value to use. If this is not set, then deployment to GitHub Releases will be disabled.