3 homepage: https://goreleaser.com
5 goreleaser: Deliver Go binaries as fast and easily as possible
8 To update or switch versions, run `webi goreleaser@stable` (or `@v0.174`,
13 > `goreleaser` makes it easy to build versioned Go binaries for Mac, Linux,
14 > Windows, and Raspberry Pi, and to publish the ChangeLog and binaries to common
15 > release platforms including GitHub, Gitea, Gitlab, and Homebrew.
17 There's a lot that you can do with GoReleaser. These are the things that we've
18 found the most useful for the majority of projects:
20 - Basic Usage & Versioning
21 - Publishing Builds to GitHub
22 - Publishing to Gitea and Gitlab
23 - Building for RPi et al
24 - Building from one or more `cmd/`s
25 - Cross-Compiling with cgo
26 - Full `.goreleaser.yml` example
28 ## Basic Usage & Versioning
30 To create an example `.goreleaser.yaml` file, and test the configuration:
34 goreleaser --snapshot --skip-publish --rm-dist
37 - `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
38 - `--skip-publish` will NOT publish to GitHub, etc
39 - `--rm-dist` will automatically remove the `./dist/` directory
41 The default `.goreleaser.yml` works well for projects for which `package main`
44 GoReleaser provides version information. Here's a good, generic way to print it
51 // these will be replaced by goreleaser
53 date = "0001-01-01T00:00:00Z"
58 if len(os.Args) >= 2 && "version" == strings.TrimPrefix(os.Args[1]) {
59 fmt.Printf("YOUR_CLI_NAME v%s %s (%s)\n", version, commit[:7], date)
66 ### How to Publish Builds to GitHub
68 You'll need a **Personal Access Token** with the `repo` scope. \
69 You can get one at <https://github.com/settings/tokens/new>.
71 You can export the environment variable:
74 export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
77 Or place the token in the default config location:
80 ~/.config/goreleaser/github_token
83 You can also set `env_files` in `.goreleaser.yml`:
87 github_token: ~/.config/goreleaser/github_token
90 Running GoReleaser without `--snapshot` must use the latest
91 [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
92 Create a tag and push it to Git:
95 git tag -a v1.0.0 -m "First release"
96 git push origin v1.0.0
99 Running GoReleaser without `--skip-publish` will publish the builds:
105 Check the console output to make sure that there are no messages about a failed
107 If all is well you should the git tag on the releases page updated with a ChangeLog
108 and the published binaries.
110 ### How to Publish to Gitea and others
112 Gitea Token: https://try.gitea.io/user/settings/applications
116 gitea_token: ~/.config/goreleaser/gitea_token
118 api: https://try.gitea.io/api/v1/
121 GitLab Token: https://gitlab.com/profile/personal_access_tokens
125 gitlab_token: ~/.config/goreleaser/gitlab_token
127 api: https://gitlab.com/api/v1/
130 Also see https://goreleaser.com/environment/
132 ### How to Build for Raspberry Pi (ARM)
134 All of the Raspberry Pis are ARM processors and can run Linux. Most can run
137 - RPi 4 is ARM 64, also known as `aarch64`, `arm64`, and `armv8`.
138 - RPi 3 could run `armv7` and `arm64`.
139 - RPi 2, RPi Zero, and RPi can run either `armv6` or `armv7`.
141 To build Go binaries for ARM, you'll need to update the `build` section of your
162 For information on other supported build options, such as BSD and ppc, see
163 [Go (Golang) GOOS and GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).
165 ### How to Build from the `cmd` Directory
167 By default GoReleaser assumes that the root of your package is `package main`.
169 If your `package main` is in a `cmd/` directory or you have multiple commands,
170 you should update your `builds` directive accordingly.
175 main: ./cmd/command123/command123.go
185 main: ./cmd/other321/other321.go
196 ### How to Cross-Compile cgo
198 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
200 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without
201 any special configuration.
203 Some programs include C libraries, especially SQLite3 or 7z, and require
204 integration with C libraries.
206 #### Mac Cross-Compilers
208 From macOS you can easily cross-compile cgo for Windows and Linux.
210 Install [brew](https://webinstall.dev/brew), if needed:
213 curl -sS https://webinstall.dev/brew | bash
216 Install mingw and musl-cross: \
217 (this may take hours if pre-built binaries are not available)
220 brew install mingw-w64
221 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
224 You may want to manually test compiling for multiple platforms before automating
228 GOARCH=amd64 GOOS=darwin go build -o unarr_darwin cmd/unarr/unarr.go
229 GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc go build -o unarr.exe cmd/unarr/unarr.go
230 GOARCH=amd64 GOOS=linux CC=x86_64-linux-musl-gcc go build -o unarr_linux_amd64 cmd/unarr/unarr.go
231 GOARCH=arm64 GOOS=linux CC=aarch64-linux-musl-gcc go build -o unarr_linux_arm64 cmd/unarr/unarr.go
232 GOARCH=arm GOOS=linux CC=arm-linux-musl-gcc go build -o unarr_linux_armv7 cmd/unarr/unarr.go
235 If you have simple instructions for how to set up cross-compiling from Windows
236 or Linux, please let us know.
240 You'll need to manually create a different `builds` item for each unique `id`:
244 - id: unarr-linux-x64
245 main: ./cmd/unarr/unarr.go
248 - CC=x86_64-linux-musl-gcc
251 - '-extldflags "-static"'
256 - id: unarr-linux-aarch64
257 main: ./cmd/unarr/unarr.go
260 - CC=aarch64-linux-musl-gcc
263 - '-extldflags "-static"'
268 - id: unarr-linux-armv7
269 main: ./cmd/unarr/unarr.go
272 - CC=arm-linux-musleabi-gcc
275 - '-extldflags "-static"'
282 - id: unarr-windows-x64
283 main: ./cmd/unarr/unarr.go
286 - CC=x86_64-w64-mingw32-gcc
289 - '-extldflags "-static"'
296 If you compile without `-static`, you will need the `musl` libraries to run on
297 (non-Alpine) Linuxes:
300 sudo apt-get install -y musl
303 ### Full Example Config
305 The full file will look something like this:
310 project_name: exampleproject
341 name_template: 'checksums.txt'
343 name_template: '{{ .Tag }}-next'