config

Configuration files

For repeatable builds, it is advisable to use goxc configuration file(s). The base configuration file is called '.goxc.json'.

Generating a config file (goxc -wc)

You can generate a simple config by using goxc -wc -pv=0.0.1 -pr=snapshot.

The -wc ('write config') option can be used in conjunction with the -c=configname option.

A basic configuration file

Here's the most basic configuration file you'd be likely to specify, (as in version 0.6.0).

This can be generated using goxc -wc -pv=0.0.1 -pr=snapshot

	{
		"ConfigVersion": "0.9",
		"PackageVersion": "0.0.1",
		"PrereleaseInfo": "snapshot"
	}

Note that it's best to specify ConfigVersion (like a manifest version), and Settings.PackageVersion, at the very least.

Adding config entries using goxc -wc

It can be tricky to add whole sections to a json file, so goxc supports adding options via the commandline: you can keep adding options and calling -wc again to build up a complete picture.

So, to remove the 'go-test' task from the default config, you could call goxc -tasks-=go-test -wc

The configuration file (.goxc.json) is now:

	{
		"ConfigVersion": "0.9",
		"PackageVersion": "0.0.1",
		"PrereleaseInfo": "snapshot",
		"TasksExclude": [
			"go-test"
		]
	}

*Note: that json arrays (such as tasks) are not 'additive' in -wc.

i.e. If you specify -tasks-=go-test on the commandline, it will replace (not append to) the TaskExclude array specified in .goxc.json *

Multiple config files

goxc allows you to have several configurations, with some inheritance to share things like version numbers. It takes a few minutes to get your head around them, but the sytem is very flexible.

• The 'base' file is simply called '.goxc.json'.
• All other configurations inherit settings from the base file.
• You can specify a 'config name' by using goxc -c=, for .goxc.json.
• You can also specify a config name during a 'write' operation. e.g. goxc -c=darwin -os=darwin -wc
• There is one special config name 'default', which is self-explanatory.
• Finally, each config file can have a 'local override file'.

Local override file

goxc allows local override files (typically ignored from source control), named .goxc.local.json (e.g. .goxc.local.json).

This allows different developers to specify different build options for a particular workspace.

By convention the .goxc.local.json file should not be stored in scm (source control e.g. git/hg/svn...). The .goxc.local.json file could be used to store version information for forked repos and unofficial builds, so that pull requests are unaffected. Don't forget to put '*.goxc.local.json' in your scm ignore file.

The .goxc.local.json file takes precedence (overrides) over the non-local file (but cli flags override any json files).

The 'write config' option (-wc) intentionally ignores content of .goxc.local.json files.

An example of what you might put in the .goxc.local.json file.

User-level config file for goxc -t

goxc -t (build toolchain) is not really associated with the current directory, so, goxc -t uses the $HOME folder.

If you'd prefer goxc to use the current directory's config file, you can just specify goxc -t . instead.

The defaults

Here's a list of [most of] the defaults applied in version 0.8.x

This can be used as a reference, to see what options are available.

PLEASE DO NOT USE THIS CONFIG. MUCH BETTER TO USE A MINIMAL CONFIG INSTEAD

	{
		"FormatVersion": "0.8",
		"ArtifactsDest": "",
		"Tasks": [
			"default"
		],
		"TasksExclude": [],
		"TasksAppend": [],
		"BuildConstraints": "",
		"Arch": "",
		"Os": "",
		"OutPath": "",
		"Resources": {
			"Include": "INSTALL*,README*,LICENSE*",
			"Exclude": "*.go"
		},
		"PackageVersion": "unknown",
		"BranchName": "",
		"PrereleaseInfo": "",
		"BuildName": "",
		"Verbosity": "",
		"TaskSettings": {
			"archive": {
				"os": {
					"linux": "TarGz"
				}
			},
			"bintray": {
				"apihost": "https://api.bintray.com/",
				"apikey": "",
				"downloadshost": "https://dl.bintray.com/",
				"downloadspage": "bintray.md",
				"repository": "",
				"subject": "",
				"user": ""
			},
			"codesign": {
				"id": ""
			},
			"downloads-page": {
				"fileheader": "---\nlayout: default\ntitle: Downloads\n---\n\n",
				"filename": "downloads.md"
			},
			"go-fmt": {
				"dir": "./..."
			},
			"go-test": {
				"dir": "./..."
			},
			"pkg-build": {
				"metadata": {
					"maintainer": "unknown"
				},
				"metadata-deb": {
					"Depends": ""
				},
				"rmtemp": true
			}
		}
	}