Documentation

zoë peterson edited this page Aug 21, 2017 · 22 revisions

The instructions and screenshots from this document are made using IntelliJ IDEA Ultimate 2016.1.2 but similar steps can be taken to replicate the functionality on other supported IDEs as well.

The theme used is named Darcula and it's part of the default IDE installation.

The code color scheme is a custom made one, named Darcula - dlsniper and it's part of the plugin as of April 18th, 2016. You can learn how to use it by visiting this section

Some assumptions are made about your working environment:

  • The IDE is launched from command line (or your environment can properly pass existing environment values to the IDE)
  • Go is installed under the default location (e.g. /usr/local/go on Linux)
  • GOPATH is set to a single directory (e.g. /home/florinp/golang)
  • GOPATH/bin and GOROOT/bin are present in you PATH

The IntelliJ Platform offers a great deal of keyboard shortcuts and a number of ways to customize them as such, this document will usually prefer the mouse interaction and let the reader discover the shortcuts corresponding the various actions.


Installing the plugin

The plugin is compatible with IntelliJ Platform 2016.1 and newer. You can install it by using the plugin manager from your IDE.

Pre-release builds are available as well in two forms: nightly and alphas. At the time of writing, alpha builds are usual released usually at around four weeks intervals while nightly builds are released every night.

To use them, you'll need to do the following:

  1. Follow the instructions
  2. Paste the url for the version you desire:

As always, remember that this is an alpha release and while efforts are made to ensure the best possible experience, sometimes things might be broken.

NOTE The above links are not meant to be used in browsers. As such, don't report issues about them not working or being inaccessible unless you are getting an error from the IDE itself.


Setting up a project from existing sources

Due to the nature of different IDE's based on the Idea platform, there are two ways to achieve this based on what IDE you use. The procedure is the same for most IDE's except Android Studio, which is explained in: Setting up a project from existing sources in Android Studio.

IntelliJ, PHPStorm, PyCharm and WebStorm

First install the pllugin the you can proceed to setup a go project from existing sources.

Import project option

Then select the existing project directory.

Select the existing project directory

Select Next until you are greeted with the SDK selection dialog

SDK selector dialog

After you configured the Go SDK, you can then proceed with the rest of the project setup.

Once the wizard finishes, please allow for some time for the IDE to index all your data from the Go SDK and GOPATH. Usually it can take up to a couple of minutes for it to finish (speed might vary based on many factors such as disk speed / CPU usage, what other language plugins and source types you have installed etc.). While the indexing is in progress some of the features like code completion, inspections or running applications are suspended.

IDE indexing

Android Studio

Unlike most other IntelliJ-based IDE's, Android Studio does not allow you to configure the SDK once you have opened a project, so the steps are a bit different.

First, go to File menu -> Open... and browse to your project folder. Once you have selected it, click on the OK button to load it in the IDE.

Then, either create a .go file, or open an existing .go file in the editor. You will see a message telling you that the type of the current module is not Go. Choose to change the module type to Go, and you will see the message disappear.

Now, you need to manually load the Go SDK before you can assign it to your project. Go to the Project Structure (located at File -> Project Structure...) and choose the SDKs tab. It is likely that you don't see Go as an SDK. If you don't, click on Add new SDK, set the SDK type to Go, and browse to your the location you have Go installed in.

Once you've added Go as an SDK, switch to the Project tab and choose Go (<version number here>) as the SDK for this project and click on OK. Now, everything must be working.

Setting up a project from scratch

From the welcome screen of IntelliJ IDEA simply choose Create New Project, select Go as project type, on the next screen select the Go version that you want to use in your project and on the final screen select how the project will be named and in which directory will it be placed. It is recommended that you create the project under your GOPATH as you'd expect it for the user to import it.

For example, if you want to create a new project called Demo and your GOPATH is pointing to /home/florin/golang/ then you might want to create the project under /home/florin/golang/src/github.com/dlsniper/demo as your users will the be able to use github.com/dlsniper/demo as import path for it.

If you don't have a Go version in the selection screen it's most likely because it's the first time you are using a Go project. As such, see the next section on how to create a new Go SDK for the plugin to be able to use.


Setting up the Go SDK

When you are greeted with the SDK selection dialog, if you don't have a Go SDK already selected, you need to select Configure.

SDK selector dialog

Select the Go installation directory.

Go SDK directory

Setting up the Go AppEngine SDK

Setting up the Go AppEngine SDK follows the same steps as the normal Go SDK.

If you extracted the archive for Go AppEngine SDK to /usr/local/go_appengine then please point the SDK root directory to /usr/local/go_appengine in your IDE and it will recognize the SDK correctly.


Changing the Go Libraries (Go packages)

Make sure that your GOPATH is reflected in the plugin settings.

If it's the first time you open a project, you are prompted to check the Go Libraries. Clicking on the Go Libraries configuration link will open up a window where you can make sure that your GOPATH settings are reflected there.

Go Libraries configuration dialog


Running your application

The plugin allows you to run your app via two methods:

  • go run
  • go build

Running using go run

If you want to run your application via this method, you need to navigate to Run | Edit Configurations.

There, you should select the green + to add a new configuration, then select Go Single File.

In the right side of the configuration dialog you'll be able to chose the file which holds the main() function and customize some of the details, such as working directory and environment variables. You can also give a name to this run configuration and then select OK.

After creating a new run configuration, all you need to do is navigate to Run and select the Run 'Your Run Configuration Name' option. In case you have multiple run configurations, you can chose which configuration to run by selecting Run... from the Run menu and then picking the desired configuration name from the list.


Running using go build

The same steps apply for this configuration as the one with go run.

The only difference is that instead of creating a Go Single File run configuration you must select Go Application from the list of run configuration types when creating the run configuration.


Running tests

Running tests in IntelliJ IDEA is as simple as creating a new run configuration just as you'd do for normally running your application.

Test coverage

In addition to just running the tests, if you select Run 'Your Test Run Configuration Name' with Coverage you'll be able to also receive the test coverage output in the IDE.

Running all the tests in a directory

In order to run all tests from the a certain directory you must select the directory option when creating a Go test configuration, then specify the full path to the directory you want to run the tests from.

Running all the tests in a package

Running tests from a package is almost the same as running the tests from a directory with the exception you can just type the fully qualified import path of the package instead of the directory path.

For example, you'd like to test the package subpackage from the package github.com/dlsniper/demo you'd need to type github.com/dlsniper/demo/subpackage. The IDE will assist you with autocompletion for the package path.

Running tests using a filter

If you want to run only part of the test suite then you can specify the test you'd like -run=TestMyFunc in the Program Arguments section of the run configuration.


Structure view of the project

You can view the structure of a certain file by navigating to the View | Tool Windows | Structure View.

Project structure view


Using code completion

Using code completion features is as straight forward as starting to type what you what and the plugin will present you various options depending on the context you are in.

Example completion


Using code navigation

You can navigate your way around the code in multiple ways.

To navigate to the definition of the function / member / method / variable / constant by using Navigate | Declaration or by using CTRL + click (on Mac, CMD + click) interaction.

Code navigation example 1

Code navigation example 2

Code navigation example 1


Using renaming refactoring functionality

You can easily rename a function, variable or constant by accessing Refactor | Rename.... All the instances of the refactor target will be highlighted. When you've finished renaming your target you can press enter your changes will be applied. If you decide to stop, you can press escape and your changes will be undone.

Rename refactoring


Formatting the source code

Formatting the source code is a very important aspect in working with Go code. Your code is automatically formatted as you type.

NOTE

Currently this facility doesn't provide the same formatting as go fmt or goimports. As such please read the following section in order to understand how you can format the code manually or using a GIT commit hook from within the IDE.

Invoking code formatting manually

If you'd like to format the code you are working on, you should select Code | Go Tools | Go fmt file or Code | Go Tools | Goimports file.

Running go fmt on GIT commit

You can also run go fmt before you commit your changes by ticking the box in the commit changes dialog of the IDE.

go fmt on git commit


Finding usage occurrences

You can find the usages of a certain element by accessing Edit | Find | Find usages. A tool window will appear highlighting every usages that the plugin is able to find.

Find usages example


Changing default color scheme

The Go plugin for IntelliJ IDEA provides you with a wealth of configuration options when it comes to syntax highlighting.

If you'd like to change it to better suit your needs you can access these by navigating to File | Settings | Editor | Colors & Fonts | Go.

You'll need to create your own custom schema before changing the settings. After that you need to select what you want to have changed, uncheck the Use inherited attribute check and you can customize the appearance as you wish.

Syntax highlight options


Creating your Go file template

TODO // Document this when https://github.com/go-lang-plugin-org/go-lang-idea-plugin/issues/1596 is done (or I learn how to use the feature).


Creating / using Live templates for Go code

The plugin already includes some useful live templates for enhancing your coding speed but should you need to create one of your own, you can do so by accessing File | Settings | Editor | Live Templates.

Live templates 1

There you'll be presented with a list of Live Templates groups. Chose Go, or create your own, and then the green + on the right side of the list.

Live templates 2

Select Live template from the list.

Live templates 3

Type the abbreviation, which also serves as a keyword that you'll use when typing your code. It can be as long as you need it to be. Also, a description of the live template should be inserted to be more meaningful when presented in the auto-complete options.

Live templates 4

You can then proceed to type the code you want to be created in the Template text: section.

Live templates 5

After that, you can select where the live template should be active, usually it's a Go block

Live templates 6

Once this is done, you can then proceed back to your code and start typing the abbreviation you just added for the Live Template.

Live templates 7

Pressing Tab will expand it to the full text in the Template text: section and you'll be able to type in any placeholders that you've set in the template. Like for refactoring, when you've finished typing, press Enter for changes to take effect or Esc do dismiss the changes.

Live templates 8

Debugging a Go project

The plugin uses delve in order to provide the debugging features for your app.

Note that Go 1.6 or newer compiled apps are known to be best supported by it.

Note that delve is under active development and not all platforms / architectures are not supported. At the time of writing 32 bit platforms are not supported as well as FreeBSD.

For help with delve, you can consult with the delve wiki.

Contributions to delve will also help improving the debugging functionality in the plugin so check the issues list and see how you can contribute to it.

To start using the debugging you will need to create a Go application run configuration and after that use Run -> Debug '<name-of-the-configuration>' and that's it.

You can create breakpoints by clicking on the left gutter of the editor and you can use commands like Step Over and Step into. Watching variables is also possible.

Some expression evaluation support is present in delve.

Please note that features like Run to cursor or better / nicer display of structs/slices are not supported yet.

You can read the full manual on how to use the debugging features of the IntelliJ Platform here: https://www.jetbrains.com/idea/help/debugging.html but some features might not be available yet.

If you encounter any issues with the plugin while debugging, please report them to our bug tracker and try to provide as much information as possible / a way to reproduce it. Source code with steps to reproduce the issues would be the best, where possible.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.