goreleaser/README.md

   1 ---
   2 title: goreleaser
   3 homepage: https://goreleaser.com
   4 tagline: |
   5   goreleaser: Deliver Go binaries as fast and easily as possible
   6 ---
   7
   8 ### Updating `goreleaser`
   9
  10 `webi goreleaser@stable`
  11
  12 Use the `@beta` tag for pre-releases.
  13
  14 ## Cheat Sheet
  15
  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.
  19
  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:
  21
  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
  29
  30 ## Basic Usage & Versioning
  31
  32 To create an example `.goreleaser.yaml` file, and test the configuration:
  33
  34 ```bash
  35 goreleaser init
  36 goreleaser --snapshot --skip-publish --rm-dist
  37 ```
  38
  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
  42
  43 The default `.goreleaser.yml` works well for projects for which `package main` is at the root.
  44
  45 GoReleaser provides version information. Here's a good, generic way to print it out:
  46
  47 ```go
  48 package main
  49
  50 var (
  51         // these will be replaced by goreleaser
  52         version = "0.0.0"
  53         date    = "0001-01-01T00:00:00Z"
  54         commit  = "0000000"
  55 )
  56
  57 func main() {
  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)
  60         }
  61
  62         // ...
  63 }
  64 ```
  65
  66 ### How to Publish Builds to GitHub
  67
  68 You'll need a **Personal Access Token** with the `repo` scope. \
  69 You can get one at <https://github.com/settings/tokens/new>.
  70
  71 You can export the environment variable:
  72
  73 ```bash
  74 export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
  75 ```
  76
  77 Or place the token in `~/.config/goreleaser/github_token.txt` and update `.goreleaser.yml` accordingly:
  78
  79 ```yml
  80 env_files:
  81   github_token: ~/.config/goreleaser/github_token.txt
  82 ```
  83
  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:
  87
  88 ```bash
  89 git tag -a v1.0.0 -m "First release"
  90 git push origin v1.0.0
  91 ```
  92
  93 Running GoReleaser without `--skip-publish` will publish the builds:
  94
  95 ```bash
  96 goreleaser --rm-dist
  97 ```
  98
  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.
 101
 102 ### How to Publish to Gitea and others
 103
 104 Gitea Token: https://try.gitea.io/user/settings/applications
 105
 106 ```yml
 107 env_files:
 108   gitea_token: ~/.config/goreleaser/gitea_token
 109 gitea_urls:
 110   api: https://try.gitea.io/api/v1/
 111 ```
 112
 113 GitLab Token: https://gitlab.com/profile/personal_access_tokens
 114
 115 ```yml
 116 env_files:
 117   gitlab_token: ~/.config/goreleaser/gitlab_token
 118 gitlab_urls:
 119   api: https://gitlab.com/api/v1/
 120 ```
 121
 122 Also see https://goreleaser.com/environment/
 123
 124 ### How to Build for Raspberry Pi (ARM)
 125
 126 All of the Raspberry Pis are ARM processors and can run Linux. Most can run Windows as well.
 127
 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`.
 131
 132 To build Go binaries for ARM, you'll need to update the `build` section of your `.goreleases.yml`.
 133
 134 ```yml
 135 builds:
 136   - env:
 137       - CGO_ENABLED=0
 138     goos:
 139       - linux
 140       - windows
 141       - darwin
 142     goarch:
 143       - 386
 144       - amd64
 145       - arm
 146       - arm64
 147     goarm:
 148       - 6
 149       - 7
 150 ```
 151
 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).
 154
 155 ### How to Build from the `cmd` Directory
 156
 157 By default GoReleaser assumes that the root of your package is `package main`.
 158
 159 If your `package main` is in a `cmd/` directory or you have multiple commands,
 160 you should update your `builds` directive accordingly.
 161
 162 ```yml
 163 - builds:
 164   - id: command123
 165     main: ./cmd/command123/command123.go
 166     binary: command123
 167     goos:
 168       - linux
 169       - windows
 170       - darwin
 171     goarch:
 172       - amd64
 173       - arm64
 174   - id: other321
 175     main: ./cmd/other321/other321.go
 176     binary: other123
 177     goos:
 178       - linux
 179       - windows
 180       - darwin
 181     goarch:
 182       - amd64
 183       - arm64
 184 ```
 185
 186 ### How to Cross-Compile cgo
 187
 188 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
 189
 190 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without any special configuration.
 191
 192 Some programs include C libraries, especially SQLite3 or 7z, and require integration with C libraries.
 193
 194 #### Mac Cross-Compilers
 195
 196 From macOS you can easily cross-compile cgo for Windows and Linux.
 197
 198 Install [brew](https://webinstall.dev/brew), if needed:
 199
 200 ```bash
 201 curl -sS https://webinstall.dev/brew | bash
 202 ```
 203
 204 Install mingw and musl-cross: \
 205 (this may take hours if pre-built binaries are not available)
 206
 207 ```bash
 208 brew install mingw-w64
 209 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
 210 ```
 211
 212 You may want to manually test compiling for multiple platforms before automating it:
 213
 214 ```bash
 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
 220 ```
 221
 222 If you have simple instructions for how to set up cross-compiling from Windows or Linux, please let us know.
 223
 224 #### Build Changes
 225
 226 You'll need to manually create a different `builds` item for each unique `id`:
 227
 228 ```yml
 229 - builds:
 230   - id: unarr-linux-x64
 231     main: ./cmd/unarr/unarr.go
 232     env:
 233       - CGO_ENABLED=1
 234       - CC=x86_64-linux-musl-gcc
 235     flags:
 236       - "-ldflags"
 237       - '-extldflags "-static"'
 238     goos:
 239       - linux
 240     goarch:
 241       - amd64
 242   - id: unarr-linux-aarch64
 243     main: ./cmd/unarr/unarr.go
 244     env:
 245       - CGO_ENABLED=1
 246       - CC=aarch64-linux-musl-gcc
 247     flags:
 248       - "-ldflags"
 249       - '-extldflags "-static"'
 250     goos:
 251       - linux
 252     goarch:
 253       - arm64
 254   - id: unarr-linux-armv7
 255     main: ./cmd/unarr/unarr.go
 256     env:
 257       - CGO_ENABLED=1
 258       - CC=arm-linux-musleabi-gcc
 259     flags:
 260       - "-ldflags"
 261       - '-extldflags "-static"'
 262     goos:
 263       - linux
 264     goarch:
 265       - arm
 266     goarm:
 267       - 7
 268   - id: unarr-windows-x64
 269     main: ./cmd/unarr/unarr.go
 270     env:
 271       - CGO_ENABLED=1
 272       - CC=x86_64-w64-mingw32-gcc
 273     flags:
 274       - "-ldflags"
 275       - '-extldflags "-static"'
 276     goos:
 277       - linux
 278     goarch:
 279       - amd64
 280 ```
 281
 282 If you compile without `-static`, you will need the `musl` libraries to run on (non-Alpine) Linuxes:
 283
 284 ```bash
 285 sudo apt-get install -y musl
 286 ```
 287
 288 ### Full Example Config
 289
 290 The full file will look something like this:
 291
 292 `.goreleaser.yml`
 293
 294 ```yml
 295 project_name: exampleproject
 296 before:
 297   hooks:
 298     - go mod download
 299     - go generate ./...
 300 builds:
 301   - env:
 302       - CGO_ENABLED=0
 303     goos:
 304       - linux
 305       - windows
 306       - darwin
 307     goarch:
 308       - 386
 309       - amd64
 310       - arm
 311       - arm64
 312     goarm:
 313       - 6
 314       - 7
 315 archives:
 316   - replacements:
 317       darwin: Darwin
 318       linux: Linux
 319       windows: Windows
 320       386: i386
 321       amd64: x86_64
 322     format_overrides:
 323       - goos: windows
 324         format: zip
 325 checksum:
 326   name_template: 'checksums.txt'
 327 snapshot:
 328   name_template: "{{ .Tag }}-next"
 329 changelog:
 330   sort: asc
 331   filters:
 332     exclude:
 333       - '^docs:'
 334       - '^test:'
 335 ```