This article covers how to create and publish a Go (Golang) package.
These instructions were written for a Mac. But they should easily translate to instructions for Linux or Windows.
Step 1. Install Go
If you need to install Go first:
- Browse to https://go.dev/doc/install
- Run the installer
- Open up a terminal or command window to get to the command line
- Run this command (exclude the $, which is meant to represent the command line prompt):
- $ go version
Step 2. Install a code editor
I prefer to edit Go projects in Visual Studio Code. If you don't have that IDE (Integrated Development Environment) installed, but would like to give it a try:
- Browse to: https://code.visualstudio.com/
- Download and run the installer
- To open it up on a Mac:
- From the command line, browse to the root folder of a project
- Run this command (exclude the $, include the period (.) at the end):
- $ code .
Step 3. Add Go support to Visual Studio Code
If you are using Visual Studio Code, be sure to add Go support:
- Browse to: https://code.visualstudio.com/docs/languages/go
- Install the extensions to support Go
Step 4. Create a github account
To share your package with the world you need an account on a service where you can share git repos in the cloud. I prefer to use github, but any similar service will do.
If you do not have an account and you would like to set one up on github:
- Browse to: https://github.com/
Step 5. Create a new project folder
At the command line create and/or browse to a folder where you keep your projects:
- Add a new project folder
- On a Mac I do it like this:
- $ mkdir go-lib
- $ cd go-lib
Step 6: Initialize a Go project
On the command line, adjust this command for your git service and username:
- $ go mod init github.com/mitchallen/go-lib
You should see a response similar to this:
go: creating new go.mod: module github.com/mitchallen/go-lib
On a Mac you can verify the file was created doing this:
- $ ls -ls
- $ cat go.mod
You should see something like this:
module github.com/mitchallen/go-lib go 1.18
Step 7. Create the library files
You need to create some empty files to update in later steps:
On a Mac you can do it like this:
- $ touch README.md
- $ touch LICENSE
- $ touch init.go
- $ touch go-lib.go
- $ touch go-lib_test.go
Notice that the test file ends with underscore (_) test (_test.go).
This is how the default test tool knows that the file contains tests.
Step 8. Edit init.go
Paste this code into init.go and save it:
The code above includes an init function. The init function in Go is a special (and optional) function that is called when the package that it is in is imported. In this case I'm just using it to log a message. But you could use it for things like initializing a random seed, etc.
Step 9. Edit go-lib.go
Paste this code into go-lib.go and save it:
The code above contains a few simple functions to add and subtract numbers.
The names of the functions begin with a capital letter so that they can be exported for use by other packages and programs.
If you want to keep a function private, start the function name with a lower case.
Step 10. Edit go-lib_test.go
Paste this code into go-lib_test.go and save it:
By default Go comes with rudimentary test capabilities that looks for files ending with "_test.go".
The code above illustrates how to create basic tests for the package functions.
Step 11. Run the tests
You can run the tests using the following command:
- $ go test
If everything passed, tidy up a bit by running:
- $ go mod tidy
Then run the tests again, just to be sure:
- $ go test
For more verbose output try this:
- $ go test -v
Sometimes test results are cached. To make sure they are not, use this command:
- $ go test -count 1
- $ go test -v -count 1
For more information on testing, run this command:
- $ go help testflag
Step 12. Update the README file
Fill in the README.md file with this, adjusting for your git repo path and username:
Step 13. Fill in the license file
Without the license file pkg.go.dev won't display your documentation.
I use the MIT License. You can copy this text and adjust the copyright info line for yourself:
MIT License Copyright 2022 Mitch Allen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Step 14. Publish the repo
- Initialize the project for git:
- $ git init
- Add the files to git:
- Note that you need to include the period at the end of this command:
- $ git add .
- Commit the files
- $ git commit -m "init commit"
- Create the repo
- Go to your git cloud provider (like github) and create a new repo
- Follow the instructions of your provider for creating the new repo
Here is an example of how I created a repo for my package using github:
- Browse to: https://github.com/new
- Repository name: go-lib
- Leave Public checked
- Click: Create repository
Next github prints out some instructions.
I followed the …or push an existing repository from the command line instructions.
Those instruction will be adjusted for your username:
- $ git remote add origin https://github.com/mitchallen/go-lib.git
- $ git branch -M main
- $ git push -u origin main
Step 15. Tag the repo
To publish different versions of your package you need to tag it like this:
- $ git tag v0.1.0
- $ git push origin --tags
You need to update the tags after pushing or merging everything to the main branch.
Step 16. Publish the package
Technically when you create a public repo with your package you have already published it where Go can find it. Unlike other packager managers you don't need to upload it anywhere. The repo is where Go will retrieve your package from.
But if you want to list it as part of a catalog, you can use the go list command.
See the instructions here:
To publish so others can find it, adjust this command for the path of your repo:
- $ GOPROXY=proxy.golang.org go list -m email@example.com
Every time you tag a new build you should run this command, adjusting for the new tag.
Verify the package was published by adjusting this browser search query for your git service username:
It can take a while for package listings to update, so don't worry if you don't see it right away.
Step 17. Test the package
To test the package, import it into a demo program.
- Create a new project folder:
- $ mkdir go-lib-demo
- $ cd go-lib-demo
- Initialize the demo:
- $ go mod init example.com/my-golib-demo
- Get the package:
- $ go get firstname.lastname@example.org
- Create a test file:
- $ touch demo.go
- Edit demo.go
- Paste in this code, adjust for your git repo username and save it:
- Run the file:
- $ go run demo.go
In this article you learned how to:
- Create a Go (Golang) package
- Test the package
- Publish the package
- List the package in a directory
- Test the package by installing it in another project