By default, Golang Build looks at the user‘s shell environment to find the values for various Go environment variables, including GOPATH.
In some situations the automatic detection may not be able to properly read the desired configuration. In other situations, it may be desirable to provide different configuration for different Sublime Text projects.
By default Golang Build tries to detect all of your Go configuration by invoking your login shell. It will pull in your PATH, GOPATH, and any other environment variables you have set.
Generally, autodetecting the shell environment is sufficient for most users with a standard Go environment. If your Go configuration is more complex, or you wish to customize command flags, Golang Build will read settings from the following sources:
Settings are loaded using the following precedence, from most-to-least specific:
To set variables for use in Sublime Text windows, you will want to edit your golang.sublime-settings file. This can be accessed via the menu:
Settings are placed in a json structure. Common settings include:
PATH - a string containing a list of directories to search for executables within. On Windows these are separated by ;. OS X and Linux use : as a directory separator.GOPATH - a string containing one or more Go workspace paths. Like PATH, on Windows multiple paths are separated by ;, on OS X and Linux they are separated by :.Other Go environment variables will be used if set. Examples include: GOOS, GOARCH, GOROOT and GORACE. The go command documentation has a complete list.
{ "PATH": "/Users/jsmith/go/bin", "GOPATH": "/Users/jsmith/go" }
For users that are working on different operating systems, it may be necessary to segement settings per OS. All settings may be nested under a key of one of the following strings:
{ "osx": { "PATH": "/Users/jsmith/go/bin", "GOPATH": "/Users/jsmith/go" }, "windows": { "PATH": "C:\\Users\\jsmith\\go\\bin", "GOPATH": "C:\\Users\\jsmith\\go" }, "linux": { "PATH": "/home/jsmith/go/bin", "GOPATH": "/home/jsmith/go" }, }
When working on Go projects that use different environments, it may be necessary to define settings in a Sublime Text project file. The Project menu in Sublime Text provides the interface to create and edit project files.
Within projects, all Go settings are placed under the "settings" key and then further under a subkey named "golang".
{ "folders": { "/Users/jsmith/projects/myproj" }, "settings": { "golang": { "PATH": "/Users/jsmith/projects/myproj/env/bin", "GOPATH": "/Users/jsmith/projects/myproj/env" } } }
Project-specific settings may also utilize the OS-specific settings feature.
{ "folders": { "/Users/jsmith/projects/myproj" }, "settings": { "golang": { "osx": { "PATH": "/Users/jsmith/projects/myproj/env/bin", "GOPATH": "/Users/jsmith/projects/myproj/env" }, "linux": { "PATH": "/home/jsmith/projects/myproj/env/bin", "GOPATH": "/home/jsmith/projects/myproj/env" } } } }
When working with the build system, it may be necessary to set flags to pass to the go executable. Utilizing the various settings locations discussed in the Settings Load Order section, each build variant may have its flags customized. The settings names are:
build:flags for “go build”run:flags for “go run”test:flags for “go test”install:flags for “go install”clean:flags for “go clean”cross_compile:flags for “go build” with GOOS and GOARCHget:flags for “go get”Any valid flag may be passed to the go executable via these settings.
Each setting must have a value that is a list of strings. Each list element contains a single command line argument.
A flag without a value would be formatted as:
{ "build:flags": ["-x"] }
Multiple flags are formatted as separate strings:
{ "build:flags": ["-x", "-a"] }
If a flag accepts a value, the value should be added as a second string:
{ "build:flags": ["-p", "4"] }
Strings arguments may contain spaces. The Golang Build package will ensure they are properly quoted when invoking the go executable.
{ "build:flags": ["-ldflags", "-L/usr/local/lib -L/opt/lib"] }
All flags are inserted at the end of the command line arguments, except in the case of go get, where they are placed before the URL to get.
The most common location to set flag settings will be in a project file:
{ "folders": { "/Users/jsmith/projects/myproj" }, "settings": { "golang": { "build:flags": ["-a"], "install:flags": ["-a"], "get:flags": ["-u"] } } }
As with the GOPATH and PATH settings, these flag settings may be set on a per-OS basis, even within project files.
An example of settings for just OS X, within a project file:
{ "folders": { "/Users/jsmith/projects/myproj" }, "settings": { "golang": { "osx": { "build:flags": ["-a", "-race"], "install:flags": ["-a", "-race"], "get:flags": ["-u"] } } } }
If flags should be applied to all Go builds, irrespective of project, the settings may be added to the global Sublime Text settings:
{ "build:flags": ["-a", "-race"] }
Do note that settings do not combine from the global Sublime Text settings and project settings. Instead, any settings in a more specific location will override those in a less specific location.
The default behavior of the build commands is to execute the go tool in the directory containing the file currently being edited. This behavior is consistent with other Sublime Text build systems and is what users typically expect.
With Go projects, you may want to override this default for commands such as go install. Consider a project containing a single executable command (defined by a Go package containing a main function) in the directory:
$GOPATH/src/github.com/username/projectname/mycommand
The project contains a large set of library packages that are used by the mycommand program. These libraries are located in:
$GOPATH/github.com/username/projectname/users $GOPATH/github.com/username/projectname/events
Running go install from within these two directories will result in the creation of the .a files in the $GOPATH/pkg directory.
However, it may be more desirable to always have go install compile and install the mycommand program into your $GOPATH/bin directory, regardless of the location of the source file you are currently editing.
To achieve this, you can use the flag override mechanism in your project configuration file:
{ "folders": [ { "path": "/Users/jsmith/workspace/src" } ], "settings": { "golang": { "install:flags": ["-v", "github.com/myusername/myproject/mycommand"] } } }
This configuration will cause the following command to be used when running the Go: Install build command:
> Environment: > GOPATH=/Users/jsmith/workspace-shared:/Users/jsmith/workspace > Directory: /Users/jsmith > Command: /Users/jsmith/go15/bin/go install -v github.com/myusername/myprojectname/mycommand > Output: github.com/myusername/myprojectname/mycommand > Elapsed: 0.955s > Result: Success
Another common command to use a custom flag with is Go: Run. With the Run build variant, the file to execute may be specified as either an absolute file path, or relative to the $GOPATH/src/ directory.
{ "folders": [ { "path": "/Users/jsmith/workspace/src" } ], "settings": { "golang": { "run:flags": ["-v", "github.com/myusername/myproject/main.go"] } } }
If the file path is relative to $GOPATH/src/, it will be automatically expanded so the go tool will process it properly. In the case that $GOPATH has multiple entries, the first with a matching filename will be used.