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, Windows, and
17 > Raspberry Pi, and to publish the ChangeLog and binaries to common release platforms
18 > including GitHub, Gitea, Gitlab, and Homebrew.
20 There's a lot that you can do with GoReleaser. These are the things that we've found the most useful for the majority of projects:
22 - Basic Usage & Versioning
23 - Publishing Builds to GitHub
24 - Publishing to Gitea and Gitlab
25 - Building for RPi et al
26 - Building from one or more `cmd/`s
27 - Cross-Compiling with cgo
28 - Full `.goreleaser.yml` example
30 ## Basic Usage & Versioning
32 To create an example `.goreleaser.yaml` file, and test the configuration:
36 goreleaser --snapshot --skip-publish --rm-dist
39 - `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
40 - `--skip-publish` will NOT publish to GitHub, etc
41 - `--rm-dist` will automatically remove the `./dist/` directory
43 The default `.goreleaser.yml` works well for projects for which `package main` is at the root.
45 GoReleaser provides version information. Here's a good, generic way to print it out:
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 `~/.config/goreleaser/github_token.txt` and update `.goreleaser.yml` accordingly:
81 github_token: ~/.config/goreleaser/github_token.txt
84 Running GoReleaser without `--snapshot` must use the latest
85 [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
86 of your repository. Create a tag and push it to Git:
89 git tag -a v1.0.0 -m "First release"
90 git push origin v1.0.0
93 Running GoReleaser without `--skip-publish` will publish the builds:
99 Check the console output to make sure that there are no messages about a failed publish. \
100 If all is well you should the git tag on the releases page updated with a ChangeLog and the published binaries.
102 ### How to Publish to Gitea and others
104 Gitea Token: https://try.gitea.io/user/settings/applications
108 gitea_token: ~/.config/goreleaser/gitea_token
110 api: https://try.gitea.io/api/v1/
113 GitLab Token: https://gitlab.com/profile/personal_access_tokens
117 gitlab_token: ~/.config/goreleaser/gitlab_token
119 api: https://gitlab.com/api/v1/
122 Also see https://goreleaser.com/environment/
124 ### How to Build for Raspberry Pi (ARM)
126 All of the Raspberry Pis are ARM processors and can run Linux. Most can run Windows as well.
128 - RPi 4 is ARM 64, also known as `aarch64`, `arm64`, and `armv8`.
129 - RPi 3 could run `armv7` and `arm64`.
130 - RPi 2, RPi Zero, and RPi can run either `armv6` or `armv7`.
132 To build Go binaries for ARM, you'll need to update the `build` section of your `.goreleases.yml`.
152 For information on other supported build options, such as BSD and ppc, see
153 [Go (Golang) GOOS and GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).
155 ### How to Build from the `cmd` Directory
157 By default GoReleaser assumes that the root of your package is `package main`.
159 If your `package main` is in a `cmd/` directory or you have multiple commands,
160 you should update your `builds` directive accordingly.
165 main: ./cmd/command123/command123.go
175 main: ./cmd/other321/other321.go
186 ### How to Cross-Compile cgo
188 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
190 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without any special configuration.
192 Some programs include C libraries, especially SQLite3 or 7z, and require integration with C libraries.
194 #### Mac Cross-Compilers
196 From macOS you can easily cross-compile cgo for Windows and Linux.
198 Install [brew](https://webinstall.dev/brew), if needed:
201 curl -sS https://webinstall.dev/brew | bash
204 Install mingw and musl-cross: \
205 (this may take hours if pre-built binaries are not available)
208 brew install mingw-w64
209 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
212 You may want to manually test compiling for multiple platforms before automating it:
215 GOARCH=amd64 GOOS=darwin go build -o unarr_darwin cmd/unarr/unarr.go
216 GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc go build -o unarr.exe cmd/unarr/unarr.go
217 GOARCH=amd64 GOOS=linux CC=x86_64-linux-musl-gcc go build -o unarr_linux_amd64 cmd/unarr/unarr.go
218 GOARCH=arm64 GOOS=linux CC=aarch64-linux-musl-gcc go build -o unarr_linux_arm64 cmd/unarr/unarr.go
219 GOARCH=arm GOOS=linux CC=arm-linux-musl-gcc go build -o unarr_linux_armv7 cmd/unarr/unarr.go
222 If you have simple instructions for how to set up cross-compiling from Windows or Linux, please let us know.
226 You'll need to manually create a different `builds` item for each unique `id`:
230 - id: unarr-linux-x64
231 main: ./cmd/unarr/unarr.go
234 - CC=x86_64-linux-musl-gcc
237 - '-extldflags "-static"'
242 - id: unarr-linux-aarch64
243 main: ./cmd/unarr/unarr.go
246 - CC=aarch64-linux-musl-gcc
249 - '-extldflags "-static"'
254 - id: unarr-linux-armv7
255 main: ./cmd/unarr/unarr.go
258 - CC=arm-linux-musleabi-gcc
261 - '-extldflags "-static"'
268 - id: unarr-windows-x64
269 main: ./cmd/unarr/unarr.go
272 - CC=x86_64-w64-mingw32-gcc
275 - '-extldflags "-static"'
282 If you compile without `-static`, you will need the `musl` libraries to run on (non-Alpine) Linuxes:
285 sudo apt-get install -y musl
288 ### Full Example Config
290 The full file will look something like this:
295 project_name: exampleproject
326 name_template: 'checksums.txt'
328 name_template: "{{ .Tag }}-next"