GVM2 manages Go (Golang) application environments and enables switching between them.
BETA: GVM2 is currently in pre-release. That doesn't mean it's not ready for production, it just means it hasn't been tested by a large audience yet. The more the merrier and the faster we get to v1.0. Install it, open issues if you find bugs.
Service | bash 4.3 | zsh 5.0.7 | zsh 5.3+ |
---|---|---|---|
Jenkins CI | []() | []() | []() |
Travis CI | -- | -- |
GVM2 supports Go development through the creation of Go environments where each environment supports isolation of a Go version and associated package dependencies.
The goal of GVM2 is to become the ubiquitous environment manager for Go development in the same way that the RVM environment manager has become an indispensable tool for ruby development.
Perhaps the biggest step forward is the introduction of GVM2 .go-version
and .go-pkgset
files similar to
RVM's .ruby-version
and .ruby-gemset
files. When you add these .go-
files to your project's directory (or even
in a parent directory) GVM2 will automatically update your GOPATH
and related environment variables to reflect the
correct Go version and package dependencies for the current project.
To upgrade a previous installation see the Upgrading section.
NOTE: Before proceeding verify that all dependencies have been installed. See the Dependencies section for more information.
For a fresh installation:
prompt> curl -sSL https://raw.githubusercontent.com/markeissler/gvm2/master/binscripts/gvm-installer | bash
Or if you are using zsh just change bash
to zsh
.
The GVM2 installer will attempt to update your shell init file (.profile
, .bash_profile
, .zlogin
, etc.) by
appending the following line:
[[ -s "$HOME/.gvm/scripts/gvm" ]] && source "$HOME/.gvm/scripts/gvm"
After the installer completes, you should verify that the line has been added to the correct file (e.g. .profile
vs .bash_profile
) since the installer can't guess the peculiarities of your setup!
If you are using RVM as well, then GVM2 should be loaded after RVM. The instructions for RVM will conflict with these instructions. Loading RVM last will result in a broken environment. While GVM2 has been designed to accommodate RVM, the reverse statement is not true.
If you are using both GVM2 and RVM, then you will need to make sure that GVM2 is loaded last:
export PATH="$PATH:$HOME/.rvm/bin"
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"
[[ -s "$HOME/.gvm/scripts/gvm" ]] && source "$HOME/.gvm/scripts/gvm"
If GVM2 is installed after RVM, then the above entries should have been appended to your shell init file in the correct order.
prompt> gvm update
List available updates:
prompt> gvm update --list
NOTE: This command may be renamed to "upgrade" in a forthcoming release.
If you need to upgrade an older version of GVM2 (prior to 0.10.0) or if you'd like to migrate from GVM to GVM2 then you will need to proceed with a manual upgrade.
Essentially, with this method you will move your current install, then re-install GVM2 (latest version), then copy your previous configuration to the new installation. Once you are satisified that the upgrade has been a success you may elect to delete the previous (renamed) installation.
WARNING: Proceed with caution and make sure you follow these steps exactly.
$HOME/.gvm
directory:prompt> builtin cd ~
prompt> mv ~/.gvm ~/.gvm.bak
prompt> curl -sSL https://raw.githubusercontent.com/markeissler/gvm2/master/binscripts/gvm-installer | bash
prompt> cp -Rp ~/.gvm.bak/{archive,environments,gos,pkgsets} ~/.gvm/
Open a new terminal to test.
If everything looks ok, then go ahead and remove the ~/.gvm.bak
directory.
All GVM2 commands offer online help:
Usage: gvm <command> [option]
GVM2 is the Go enVironment Manager
Commands:
alias Manage Go version aliases
check Check for and list missing dependencies
cross Cross compile a Go program
diff View changes to an installed Go directory contents
help Show this message
implode Uninstall GVM2 (You probably don't want to do this)
install Install a Go version
linkthis Create link from package set src directory to working directory
list List currently installed versions of Go
listall List Go versions available for installation
pkgset Manage GVM2 package sets (aka "pkgsets")
pkgenv Edit the environment for a GVM2 package set
uninstall Uninstall a Go version
update Update GVM2 to latest release
use Select which installed Go version to use
version Print the GVM2 version number
Run 'gvm <command> --help' for more information on a command.
Once you've installed GVM2, you will need to install a bootstrap version of Go. The last revision of Go that can be built with C compilers is Go 1.4.; therefore, the very first version of Go that you must install is Go 1.4:
prompt> gvm install go1.4.3
prompt> gvm use go1.4.3
Once those steps have been completed, Go will be in your PATH. Also, $GOROOT
and $GOPATH
will be set automatically.
You can verify success with:
prompt> go version
go version go1.4.3 linux/amd64
Additional options can be specified when installing Go:
Usage: gvm install [version] [options]
-s, --source=SOURCE Install Go from specified source.
-n, --name=NAME Override the default name for this version.
-pb, --with-protobuf Install Go protocol buffers.
-b, --with-build-tools Install package build tools.
-B, --binary Only install from binary.
--prefer-binary Attempt a binary install, falling back to source.
-h, --help Display this message.
A little more background: compiler_note
To list all installed Go versions:
prompt> gvm list
To list all Go source versions available for download:
prompt> gvm listall
Additional options can be specified:
Usage: gvm listall [option]
List Go versions available for installation
Options:
-a, --all List all versions available
-B, --binary List available pre-built versions available
-s, --source List available source versions available
--porcelain Machine-readable output
-q, --quiet Suppress progress messages
-h, --help Show this message
The gvm listall
command will, by default, list all source versions that are available to build on the target
platform. The list will be considerably shorter for macOS due to changes in the build environment as of macOS 10.12
(Sierra). In general, you can install older versions of Go on macOS by installing pre-built versions (binaries).
To list all pre-built versions available for the target platform specify the --binary
option to the gvm listall
command.
NOTE: The installer may default to installing binaries in a forthcoming release.
The gvm listall
command suppresses output of rc and beta tags for pre-built packages simply because they are
not available. The legacy release and weekly tags are suppressed for brevity.
Before you can use Go, you will need to select a Go version. Usually, this step will be automatically handled by GVM2 but you can, at any time, manually select a Go version:
prompt> gvm use go1.4
The Go version that is in use will be the last one you selected or the one that is auto-selected by GVM2. See Auto selection of Go version and GVM2 pkgset for more information.
A package set (pkgset) provides a way for you to isolate dependencies for a project in that all dependencies
installed with go get
will be installed into the currently active pkgset.
Package sets are bound to Go versions. When you switch Go versions (using the gvm use
command), the list of package
sets available will change. The package set in use will be the last one you selected or the one that is auto-selected by
GVM2 depending on the presence of a .go-pkgset
file.
Before you can create or select a package set, you must first select a Go version.
prompt> gvm pkgset create "my-package-set"
prompt> gvm pkgset use "my-package-set"
There are two ways to determine which version of Go is active. The first option is to use the native go version
command:
prompt> go version
go version go1.7.1 darwin/amd64
The second option is to use GVM2:
prompt> gvm list
gvm gos (installed)
go1.4.3
go1.6.3
go1.7
=> go1.7.1
system
In the above example, the active Go version is flagged with the =>
indicator.
prompt> gvm pkgset list
gvm go package sets (go1.7.1)
global
=> gotest_1.7
dataconnect_1.7
spoofexample_1.7
testinghttp_1.7
In the above example, the active Go pkgset is flagged with the =>
indicator.
To completely remove gvm and all installed Go versions and packages:
prompt> gvm implode
If that doesn't work see the troubleshooting steps at the bottom of this page.
Prior to the introduction of the .go-version
and .go-pkgset
files, you had to manually select the Go version and
package set in use, and then those settings remained set until you once again changed them or began a new session. When
juggling several Go projects it can become quite a hassle to not only remember which version and pkgset you should be
using, but also to execute the commands to switch to the correct version and pkgset.
The use of .go-version
and .go-pkgset
files eliminates this problem all together.
The content of a .go-version
file is simple:
prompt> cat ~/dev/my_go_project/.go-version
go1.4
Just a single line consisting of a Go version as reported by the gvm list
command.
The content of a .go-pkgset
file is simple:
prompt> cat ~/dev/my_go_project/.go-pkgset
my-package-set
Again, a single line consisting of a GVM2 package set as reported by the gvm pkgset list
command.
Whenever you change directories (using cd
), GVM2 will search for an applicable .go-version
and .go-pkgset
file. The search will begin in the directory that your are changing to and will then continue all the way up to the top
of your HOME directory. If these files appear anywhere along the path during the upwards traversal, GVM2 will select
the file, parse it and apply it. GVM2 will only consider the first file it encounters.
If the .go-version
and/or the .go-pkgset
files are not found, GVM2 will next attempt to make suitable guesses
for an appropriate environment to select. The order of guessing looks like this:
Go version:
1. default environment
2. system environment
3. highest version of Go installed
GVM pkgset:
global pkgset for the version of Go selected
NOTE: Auto selection is only supported when
gvm
is loaded as a function into your shell. See the Sourcing gvm into your shell (bash, zsh) section for more information.
prompt> xcode-select --install
prompt> sudo apt-get install curl git make binutils bison gcc build-essential
prompt> sudo yum install curl git make bison gcc glibc-devel
prompt> sudo pkg_add -r bash git
WARNING: GVM2 is not currently tested or developed for FreeBSD. Complete support for this platform will likely be restored in the future but is not currently scheduled.
GVM2 works on WSL. Instructions are the same as for Debian/Ubuntu.
NOTE: GVM2 0.10.0 vastly improves performance on WSL over previous releases, however, due to limitations in the current implementation of WSL with regard to file system interaction, performance is still poor when compared to running GVM2 on native Linux (bare metal, VM, Docker container, etc.) or macOS. This behavior is not limited to GVM2. For more information see: Major performance (I/O?) issue in /mnt/* and in ~ (home) #873.
The following example illustrates a typical workflow. The example assumes that "go1.7" has already been installed.
prompt> mkdir my_project
prompt> cd my_project
prompt> gvm use go1.7
prompt> gvm pkgset create "my_project"
prompt> gvm pgkset use "my_project"
prompt> echo "go1.7" > .go-version
prompt> echo "my_project" > .go-pkgset
Because we are creating both the .go-version
and .go-pkgset
files the next time you change into this directory
GVM2 will automatically set both the Go version and pkgset.
Vendoring is a moving target in GVM2 with a specific goal to add support for Godep vendoring. Existing legacy GPKG support will likely be removed.
GVM2 supports vendoring package set-specific native code and related dependencies, which is useful if you need to qualify a new configuration or version of one of these dependencies against a last-known-good version in an isolated manner.
The following environment variables are available once you've selected a package set (gvm pgkset use <package_name>
):
${GVM_OVERLAY_PREFIX}
functions in a manner akin to a root directory hierarchy suitable for auto{conf,make,tools}
where it could be passed in to ./configure --prefix=${GVM_OVERLAY_PREFIX}
and not conflict with any existing
operating system artifacts and hermetically be used by your workspace. This is suitable to use with
C{PP,XX}FLAGS and LDFLAGS
, but you will have to manage these yourself, since each tool that uses them is
different.
${PATH}
includes ${GVM_OVERLAY_PREFIX}/bin
so that any tools you manually install will reside there, available
for you.
${LD_LIBRARY_PATH}
includes ${GVM_OVERLAY_PREFIX}/lib
so that any runtime library searching can be fulfilled
there on FreeBSD and Linux.
${DYLD_LIBRARY_PATH}
includes ${GVM_OVERLAY_PREFIX}/lib
so that any runtime library searching can be fulfilled
there on MacOS.
${PKG_CONFIG_PATH}
includes ${GVM_OVERLAY_PREFIX}/lib/pkgconfig
so that pkg-config
can automatically resolve
any vendored dependencies.
prompt> gvm use go1.1
prompt> gvm pkgset use current-known-good
# Let's assume that this includes some C headers and native libraries, which
# Go's CGO facility wraps for us. Let's assume that these native
# dependencies are at version V.
prompt> gvm pkgset create trial-next-version
# Let's assume that V+1 has come along and you want to safely trial it in
# your workspace.
prompt> gvm pkgset use trial-next-version
# Do your work here replicating current-known-good from above, but install
# V+1 into ${GVM_OVERLAY_PREFIX}.
See examples/native
for a working example.
Contributions are welcome:
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)Please be sure to provide a concise overview of the issue you are trying to resolve. If you are submitting a pull request (PR) to address a bug you've encountered then it is critical you also provide steps to reproduce the problem along with captured output.
GVM2 is the work of Mark Eissler based on the original work of others as noted in the Attributions section below.
GVM2 is a fork of GVM. A lot of work has gone into producing GVM2 which offers a more RVM-like experience. Still, without the prior work of Josh Bussdieker (jbuss, jaja, jbussdieker), previous contributors and, of course, the inspiration provided by the RVM project, this project would probably not exist.
GVM2 is licensed under the MIT open source license.
Without open source, there would be no Internet as we know it today.