Documentation
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/goon 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.
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:
- Follow the instructions
- Paste the url for the version you desire:
- alpha: https://plugins.jetbrains.com/plugins/alpha/5047
- nightly: https://plugins.jetbrains.com/plugins/nightly/5047
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.
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.
First install the pllugin the you can proceed to setup a go project from existing sources.
Then select the existing project directory.
Select Next until you are greeted with the SDK selection 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.
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.
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.
When you are greeted with the SDK selection dialog, if you don't have a Go SDK
already selected, you need to select Configure.
Select the Go installation directory.
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.
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.
The plugin allows you to run your app via two methods:
go rungo build
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.
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 in IntelliJ IDEA is as simple as creating a new run configuration just as you'd do for normally running your application.
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.
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 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.
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.
You can view the structure of a certain file by navigating to the
View | Tool Windows | Structure View.
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.
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.
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.
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.
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.
You can also run go fmt before you commit your changes by ticking the box
in the commit changes dialog of the IDE.
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.
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.
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).
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.
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.
Select Live template from the list.
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.
You can then proceed to type the code you want to be created in the
Template text: section.
After that, you can select where the live template should be active, usually
it's a Go block
Once this is done, you can then proceed back to your code and start typing the abbreviation you just added for the Live Template.
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.
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.