Unity Deployment Tools

Continuous deployment tools for open-source Unity3D packages and assets.

Overview

Unity Deployment Tools offers a quick way to setup open source unity packages. It features:

a self-documented and easy to use .ini file to configure all the options;
automated package/asset exporting from unity;
automated deployment to Github Releases;
automated creation and deployment of documentation to Github Pages.

Projects using UDT

UnitySteer

Installation

Download the latest stable release;
Unpack the files into your repository's root directory;
Go to Travis-CI an sign in with Github;
Enable your repository in your account page;
Open .deploy.ini with a text editor (like Notepad++) and modify the options under the [Misc] section as per your preferences.
For additional features check the subsections below;
Simply push a commit and let travis do all the work for you!

Once you're using UDT please consider leaving a comment so that I can add your repo to the list!

Features

These tools are all targeted at the majority of Unity users: the newbies. While more advanced users will also find them useful (automation is always welcome) everything by default is as simple as possible to configure (a simple .ini file) and to use (unzip and copy to your repo).

Some features have requirements (e.g. having a tag associated with the commit) which you have to fulfill before using them. The only exception is the automated building and exporting of the package (this includes no deployment/upload - it is simply to check is the package CAN be built and exported correctly). These requirements are shown at the beggining of each feature description.

Github Releases

Requirements
- Github OAuth Token present;
- Tag present;
- Not on a Pull Request.

Simply open your .deploy.ini file with a text editor (like Notepad++) and modify the [Github] section as per your preferences. That's it, really.

Code Documentation

Requirements
- Github OAuth Token present;
- Tag present;
- Not on a Pull Request.

Documentation for all your code is generated with Doxygen. Example documentation is provided at the Github Pages of this repository, example script taken from Microsoft's XML Documentation Example.

Basic Usage

Documentation generation is enabled by default. Open your .deploy.ini file with a text editor (like Notepad++) and modify the [Docs] section as per your preferences. That's pretty much it, for more things to do with Doxygen check below.

Advanced/Expert

Doxygen must be (for the sheer amount of options) the best documented software I've ever seen.

If you want to customize your docs more than the basic options presented in the .deploy.ini file (these are the same presented in the basic panel of the doxywizard) open the Doxyfile. This is the default doxygen configuration file and every option is very well documented. There are bajillions of them, have fun!

Please note that some options are hardcoded (see deploy_docs.sh).

Known Issues

Build error due to timeout on Travis-CI.

No fix available - Sometimes the connection speed from the Travis-CI worker to the unity servers is just too slow and the build times out. No fix unless Travis somehow allows us to restart the build automatically.

Workaround - Simply restart the build until the connection is faster.

Upcoming Features

Automated compiling and distribution as a .dll file.

Extras

Configuration

These are all the options present in the .ini file.

Note: None corresponds to an empty field.

Misc Section

verbose
- Default:
  
  false
- If set to true, all logs from commands will be shown.
always_run
- Default:
  
  true
- If set to true, Travis will always try to build the package/asset, even when there isn't a tag.
unity_version
- Default:
  
  None
- Place the unity version you wish to build againts here (e.g. unity_version=5.1.0). See supported versions in the readme. If none are specified, version 5.0.1 (the earliest supported) is used.

Docs Section

enable
- Default:
  
  true
- If set to true, will enable generating docs and deploying them to github pages.
branch
- Default:
  
  master
- If you want to generate documentation only from a specific branch.
projectname
- Default:
  
  None
- If you want to name your project something other than the repo name.
username
- Default:
  
  None
- If you want to have a custom username when pushing to gh-pages, fill in. If left blank, defaults to "Travis-CI Doxygen Deployment".
email
- Default:
  
  None
- If you want to have a custom email when pushing to gh-pages, fill in. If left blank, defaults to "doxygen@deployment.to.github.pages".
commit_description
- Default:
  
  None
- If you want to have a custom message for the commit to gh-pages, fill in. If left blank, defaults to "Deploying to GitHub Pages".
description
- Default:
  
  None
- If you want the short description to be something other than your repo description.
include_version
- Default:
  
  false
- If set to true, will include the tag as the documentation version.
logo
- Default:
  
  None
- If you wish your project to have a logo, fill in the relative path to the image.(e.g. if you store it in the .deploy folder, fill in this: ./.deploy/my_logo.png)
include_non_documented
- Default:
  
  true
- If set to true, will include all code even if not documented.
include_privates
- Default:
  
  true
- If set to true, will include private members in the documentation.
include_nav_panel
- Default:
  
  true
- If set to true, will include a sidebar with a navigation panel.
include_search
- Default:
  
  true
- If set to true, will include a search function in each page.
gen_diagrams
- Default:
  
  true
- If set to true, will generate class hierarchy diagrams.

Github Section

enable
- Default:
  
  true
- If set to true, will enable deployment to github if possible.
include_version
- Default:
  
  true
- If set to true, tag will be included after the package name (e.g. UnityDeployTools_v1.1).
packagename
- Default:
  
  None
- If you want to name the deploy zip file something other than your repo name.
conditional_deployment
- Default:
  
  true
- If set to true, tags with "alpha" or "beta" in their name will be deployed.
conditional_prerelease
- Default:
  
  true
- If set to true, tags with "alpha" or "beta" in their name will be set to prerelease.
conditional_draft
- Default:
  
  false
- If set to true, tags with "alpha" or "beta" in their name will be deployed as draft.
conditional_description
- Default:
  
  None
- If filled in, tags with "alpha" or "beta" in their name will have this description. (don't forget this should be in github markdown)
prerelease
- Default:
  
  false
- If set to true, releases will always be set to prerelease. Overrides conditional_prerelease if true.
draft
- Default:
  
  false
- If set to true, releases will always be deployed as a draft. Overrides conditional_draft if true.
title
- Default:
  
  None
- If you want to name the release something other than the tag.
description
- Default:
  
  None
- If you want to add something to the release description. (don't forget this should be in github markdown)
branch
- Default:
  
  None
- If you want to deploy only from a specific branch.

Github OAuth Token

Sign in to Github;
Go to your Settings;
Go to Personal Access Tokens;
Click on Generate new token;
Enter your password;
Give the token a good description. Mine is Travis-CI Unity Deploy Tools;
Give the token these permissions:
- gist;
- read:org;
- repo;
- user:email;
- write:repo_hook
Click on Generate token;
The new token should now appear. NEVER give or show this token to anyone, not even Travis (the encryption process later on does not send the token to Travis, the entire process is local);
Temporarily store your token somewhere local and safe;
Go to Travis-CI and sign in with Github;
Go to your repository settings;
In the Environment Variables section, write "GH_TOKEN" (without the quotes) in the Name field and paste the token in the Value field;
Make sure to leave Display value in build log as OFF and click Add;
It's now safe to delete and forget about that token from before! Only use the secure (encrypted) version from now on.

Supported Unity Versions

5.0.1
5.0.2
5.0.3
5.0.4
5.1.0
5.1.1
5.1.2
5.1.3
5.1.4
5.2.0
5.2.1
5.2.2
5.2.3
5.2.4
5.3.0
5.3.1
5.3.2

Earlier versions are not supported. If a new version has come out and it isn't yet supported, you can follow these instructions to add it:

Set up Git;
Fork and clone this repo;

Create a branch and commit your fixes in it:

Open the unity_supported_versions.json file with a text editor;
Get the download link to the version you want to add;
- Make sure the link refers to the Mac Unity Editor;
- Make sure the link ends in .pkg - .dmg links are not supported.

Add the new version to the dictionary like this:

{
    "5.0.1": "http://download.unity3d.com/download_unity/5a2e8fe35a68/MacEditorInstaller/Unity-5.0.1f1.pkg",
    "5.0.2": "http://download.unity3d.com/download_unity/0b02744d4013/MacEditorInstaller/Unity-5.0.2f1.pkg",
    "5.0.3": "http://download.unity3d.com/download_unity/c28c7860811c/MacEditorInstaller/Unity-5.0.3f2.pkg",
    "5.0.4": "http://download.unity3d.com/download_unity/1d75c08f1c9c/MacEditorInstaller/Unity-5.0.4f1.pkg",
    "5.1.0": "http://download.unity3d.com/download_unity/ec70b008569d/MacEditorInstaller/Unity-5.1.0f3.pkg",
    "new.unity.version": "http://unity.editor.download.link.for.mac.pkg"
}

Push your local branch to your fork;
Create a Pull Request to this fork.

GandaG / unity-deploy-tools