Skip to content

Install

Jump to bottom
Randall C. O'Reilly edited this page Jan 25, 2024 · 1 revision

See https://goki.dev/docs/gi/gettingstarted/ for installation instructions -- this page will be maintained as a copy also.

The GoGi toolkit can be installed using standard Go procedures, but there are platform-specific dependencies listed by OS in the sections below: Mac | Windows | Linux

Install Go

To install Go itself, see: https://golang.org/doc/install -- MUST BE version 1.18 or higher

Go Modules

Go now uses the module versioning system by default:

  • https://blog.golang.org/using-go-modules
  • https://github.com/golang/go/wiki/Modules
  • all dependencies are specified in the go.mod file, and are automatically installed in ~/go/pkg/mod/<pkg> where <pkg> is the path to the specific package, with a version suffix, e.g., ~/go/pkg/mod/github.com/goki/gi/gi@v1.0.1
  • This is a particularly convenient command for seeing all the available versions of each package, for updating downstream go.mod files:
go list -m -versions github.com/goki...

Getting and Building GoGi

IMPORTANT: Install OS-specific dependencies as listed in the sections below, first! Mac | Windows | Linux

These commands are run in your Terminal / Command Shell:

  • Get the source:
cd <anywhere you want to install. although we strongly suggest installing in a folder in your user directory>
git clone https://github.com/goki/gi

  • This makes a directory called gi, under your current directory.

  • Build and run the widgets example:

cd gi/examples/widgets   # from clone directory above
go build -v   # -v optionally shows you progress as it builds
./widgets

On Windows you may need to do go build -buildmode exe if it doesn't work with just plain go build -- this will be / is fixed at some point but not sure when: https://github.com/golang/go/issues/40795. Also, if ./widgets does not work, you can try start widgets.exe

Additional recommended utilities

The following are additional utilities that you probably want to install, if you'll be doing more development:

stringer

Our version of the go standard stringer utility is here: https://github.com/goki/stringer -- it is used to generate string names for constant values that serve as "enum" types in Go (e.g., for a fixed list of options in a drop-down menu to choose among): -- this version also generates a FromString method that converts a string back into its corresponding numerical value.

The standard go main package install should work:

go install github.com/goki/stringer@latest

This should install the compiled stringer utility in your ~/go/bin folder. That is, go/bin should be in your home directory.

If you try to run the stringer utility and you get the error "command not found" it may be that the PATH variable has not been set properly in your profile. You can try the following at the command line in the terminal window and see if this helps:

export PATH="$HOME/go/bin:$PATH"

And then try to run stringer again. This should make sure that the go/bin folder is on the search PATH. Note that export at the command line only works during your current terminal session. If you quit terminal and start over you would either need to execute this command again or add this command to your profile. Look on the web for commands for adding the command to your profile.

goimports and struct field tag comments

There is a version of goimports that automatically copies GoGi struct field tags including desc to standard comments, to make it easier to access this info in standard editors such as VS Code. See https://goki.dev/docs/general/structfieldcomments/ for info on editor configuration. Basic install:

go install github.com/goki/go-tools/cmd/goimports@latest

Selecting a GPU Device

For systems with multiple GPU devices, by default the discrete device is selected, and if multiple of those are present, the one with the most RAM is used. To see what is available and their properties, use:

vulkaninfo --summary

The following environment variables can be set to specifically select a particular device by name (deviceName):

  • MESA_VK_DEVICE_SELECT (standard for mesa-based drivers) or VK_DEVICE_SELECT -- for graphics or compute usage.
  • VK_COMPUTE_DEVICE_SELECT -- only used for compute, if present -- will override above, so you can use different GPUs for graphics vs compute.

Mac

  • Must use MacOS version 10.12 (Sierra) or higher!

  • Make sure you have xcode command-line tools installed, which are needed for compiling the little bit of objective-c code we need to support the mac environment:

xcode-select --install

  • As of June 2022, the new Vulkan-based version 1.3.0+ requires the vulkan sdk to be installed:

    download the installer for the mac, follow default prompts (latest version should work fine now with latest GoGi).

    • The homebrew molten-vk unfortunately does not seem to work by itself, and there is no formula for the whole SDK.

Windows

You need to download and install git and TDM-GCC if you do not have them already. Make sure you download the appropriate TDM-GCC for your computer (most modern computers use 64 bit).

After install, you need to run this in the Command Shell to set the path variables to use this version of gcc:

cd C:\TDM-GCC-64
mingwvars.bat

Restart your computer after downloading.

Note that the standard Go instructions specify a mingw compatible gcc, but we have found that that gives rise to this error during build:

cc1.exe: sorry, unimplemented: 64-bit mode not compiled in

Here's a reddit thread with more info.

Linux

You need to install these dependencies on Ubuntu / Debian:

sudo apt-get install libgl1-mesa-dev xorg-dev

For CentOS / Fedora:

sudo dnf install libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel mesa-libGL-devel libXi-devel libXxf86vm-devel

See https://github.com/go-gl/glfw for more info. The good news is that this now works on Wayland! :)

Installing Go itself

The standard install involves a tar file and also requires setting a custom PATH variable.

On Ubuntu, you can install the most recent go packages using apt-get: https://github.com/golang/go/wiki/Ubuntu -- but this still requires a custom PATH, and actually seems like more work and complexity than using the standard tar install.

Here's a way to install so you don't need to add a custom PATH:

sudo su
cd /usr/lib
rm go  # in case you've done this already and have a symlink
tar -xzf <path-to-downloaded-go-tar-file>  # creates /usr/lib/go 
mv go go-1.21  # replace 1.21 with current version
ln -s go-1.21 go   # keep it flexible and allow multiple versions to be there

The first time you do this, you can link the go bins to /usr/bin -- don't need to do again when updating version:

sudo su
cd /usr/bin
rm go gofmt godoc  # just in case
ln -s ../lib/go/bin/* .

go.work and GOPATH mode

go.work is useful for concurrent development across multiple packages: https://go.dev/doc/tutorial/workspaces

Some of us old folks still prefer the GOPATH mode, which will be maintained going forward! Here's some tips for using GOPATH:

To turn modules off, and add aliases to turn it back on or off, add these lines to your ~/.bashrc or ~/.bash_profile or whatever is run when your shell starts:

export GO111MODULE=off

gomod() {
    export GO111MODULE=on
}

nogomod() {
    export GO111MODULE=off
}

First, you'll need to set GO111MODULE=off for this to work (see above).

IMPORTANT: only the main packages in examples have all the dependencies, per platform, so you'll want to do the install in one of them -- here we use examples/widgets

  • get the source overall:
$ go get github.com/goki/gi    # ignore warnings about no go files, etc.
  • Go to the examples/widgets directory and make sure all dependencies are installed (and updated)
$ cd ~/go/src/github.com/goki/gi/examples/widgets    # use `$GOPATH` instead of `~/go` if you have that set
$ go get ./...    # you may need to do go get -u ./... if you have existing, out-of-date packages

  • Important: IGNORE any error messages you see from go get (including "no go files..") -- the only thing that matters is what happens with go build! get somehow gets confused with a few things..

  • Build and run it:

$ go build
$ ./widgets
  • There is also a top-level Makefile with install and build targets

GoPi

giv.TextBuf and giv.TextView support syntax highlighting, which uses the GoPi interactive parser where available, and falls back on Chroma for other languages. GoPi only depends on GoKi (for the Ki tree type), and to prevent circular module-level dependencies, it hosts the filecat mimetype and supported file type package, and the core complete completion code. There is also a PiView GUI for creating / editing GoPi parsers, which is in the gide/piv sub-package, and depends on all of GoGi and Gide.

Clone this wiki locally