3 homepage: https://goreleaser.com
5 goreleaser: Deliver Go binaries as fast and easily as possible
8 ### Updating `goreleaser`
10 `webi goreleaser@stable`
12 Use the `@beta` tag for pre-releases.
16 > `goreleaser` makes it easy to build versioned Go binaries for Mac, Linux,
17 > Windows, and Raspberry Pi, and to publish the ChangeLog and binaries to common
18 > release platforms including GitHub, Gitea, Gitlab, and Homebrew.
20 There's a lot that you can do with GoReleaser. These are the things that we've
21 found the most useful for the majority of projects:
23 - Basic Usage & Versioning
24 - Publishing Builds to GitHub
25 - Publishing to Gitea and Gitlab
26 - Building for RPi et al
27 - Building from one or more `cmd/`s
28 - Cross-Compiling with cgo
29 - Full `.goreleaser.yml` example
31 ## Basic Usage & Versioning
33 To create an example `.goreleaser.yaml` file, and test the configuration:
37 goreleaser --snapshot --skip-publish --rm-dist
40 - `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
41 - `--skip-publish` will NOT publish to GitHub, etc
42 - `--rm-dist` will automatically remove the `./dist/` directory
44 The default `.goreleaser.yml` works well for projects for which `package main`
47 GoReleaser provides version information. Here's a good, generic way to print it
54 // these will be replaced by goreleaser
56 date = "0001-01-01T00:00:00Z"
61 if len(os.Args) >= 2 && "version" == strings.TrimPrefix(os.Args[1]) {
62 fmt.Printf("YOUR_CLI_NAME v%s %s (%s)\n", version, commit[:7], date)
69 ### How to Publish Builds to GitHub
71 You'll need a **Personal Access Token** with the `repo` scope. \
72 You can get one at <https://github.com/settings/tokens/new>.
74 You can export the environment variable:
77 export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
80 Or place the token in the default config location:
83 ~/.config/goreleaser/github_token
86 You can also set `env_files` in `.goreleaser.yml`:
90 github_token: ~/.config/goreleaser/github_token
93 Running GoReleaser without `--snapshot` must use the latest
94 [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
95 Create a tag and push it to Git:
98 git tag -a v1.0.0 -m "First release"
99 git push origin v1.0.0
102 Running GoReleaser without `--skip-publish` will publish the builds:
108 Check the console output to make sure that there are no messages about a failed
110 If all is well you should the git tag on the releases page updated with a ChangeLog
111 and the published binaries.
113 ### How to Publish to Gitea and others
115 Gitea Token: https://try.gitea.io/user/settings/applications
119 gitea_token: ~/.config/goreleaser/gitea_token
121 api: https://try.gitea.io/api/v1/
124 GitLab Token: https://gitlab.com/profile/personal_access_tokens
128 gitlab_token: ~/.config/goreleaser/gitlab_token
130 api: https://gitlab.com/api/v1/
133 Also see https://goreleaser.com/environment/
135 ### How to Build for Raspberry Pi (ARM)
137 All of the Raspberry Pis are ARM processors and can run Linux. Most can run
140 - RPi 4 is ARM 64, also known as `aarch64`, `arm64`, and `armv8`.
141 - RPi 3 could run `armv7` and `arm64`.
142 - RPi 2, RPi Zero, and RPi can run either `armv6` or `armv7`.
144 To build Go binaries for ARM, you'll need to update the `build` section of your
165 For information on other supported build options, such as BSD and ppc, see
166 [Go (Golang) GOOS and GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).
168 ### How to Build from the `cmd` Directory
170 By default GoReleaser assumes that the root of your package is `package main`.
172 If your `package main` is in a `cmd/` directory or you have multiple commands,
173 you should update your `builds` directive accordingly.
178 main: ./cmd/command123/command123.go
188 main: ./cmd/other321/other321.go
199 ### How to Cross-Compile cgo
201 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
203 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without
204 any special configuration.
206 Some programs include C libraries, especially SQLite3 or 7z, and require
207 integration with C libraries.
209 #### Mac Cross-Compilers
211 From macOS you can easily cross-compile cgo for Windows and Linux.
213 Install [brew](https://webinstall.dev/brew), if needed:
216 curl -sS https://webinstall.dev/brew | bash
219 Install mingw and musl-cross: \
220 (this may take hours if pre-built binaries are not available)
223 brew install mingw-w64
224 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
227 You may want to manually test compiling for multiple platforms before automating
231 GOARCH=amd64 GOOS=darwin go build -o unarr_darwin cmd/unarr/unarr.go
232 GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc go build -o unarr.exe cmd/unarr/unarr.go
233 GOARCH=amd64 GOOS=linux CC=x86_64-linux-musl-gcc go build -o unarr_linux_amd64 cmd/unarr/unarr.go
234 GOARCH=arm64 GOOS=linux CC=aarch64-linux-musl-gcc go build -o unarr_linux_arm64 cmd/unarr/unarr.go
235 GOARCH=arm GOOS=linux CC=arm-linux-musl-gcc go build -o unarr_linux_armv7 cmd/unarr/unarr.go
238 If you have simple instructions for how to set up cross-compiling from Windows
239 or Linux, please let us know.
243 You'll need to manually create a different `builds` item for each unique `id`:
247 - id: unarr-linux-x64
248 main: ./cmd/unarr/unarr.go
251 - CC=x86_64-linux-musl-gcc
254 - '-extldflags "-static"'
259 - id: unarr-linux-aarch64
260 main: ./cmd/unarr/unarr.go
263 - CC=aarch64-linux-musl-gcc
266 - '-extldflags "-static"'
271 - id: unarr-linux-armv7
272 main: ./cmd/unarr/unarr.go
275 - CC=arm-linux-musleabi-gcc
278 - '-extldflags "-static"'
285 - id: unarr-windows-x64
286 main: ./cmd/unarr/unarr.go
289 - CC=x86_64-w64-mingw32-gcc
292 - '-extldflags "-static"'
299 If you compile without `-static`, you will need the `musl` libraries to run on
300 (non-Alpine) Linuxes:
303 sudo apt-get install -y musl
306 ### Full Example Config
308 The full file will look something like this:
313 project_name: exampleproject
344 name_template: 'checksums.txt'
346 name_template: '{{ .Tag }}-next'