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     goos:
 167       - linux
 168       - windows
 169       - darwin
 170     goarch:
 171       - amd64
 172       - arm64
 173   - id: other321
 174     main: ./cmd/other321/other321.go
 175     goos:
 176       - linux
 177       - windows
 178       - darwin
 179     goarch:
 180       - amd64
 181       - arm64
 182 ```
 183
 184 ### How to Cross-Compile cgo
 185
 186 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
 187
 188 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without any special configuration.
 189
 190 Some programs include C libraries, especially SQLite3 or 7z, and require integration with C libraries.
 191
 192 #### Mac Cross-Compilers
 193
 194 From macOS you can easily cross-compile cgo for Windows and Linux.
 195
 196 Install [brew](https://webinstall.dev/brew), if needed:
 197
 198 ```bash
 199 curl -sS https://webinstall.dev/brew | bash
 200 ```
 201
 202 Install mingw and musl-cross: \
 203 (this may take hours if pre-built binaries are not available)
 204
 205 ```bash
 206 brew install mingw-w64
 207 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
 208 ```
 209
 210 You may want to manually test compiling for multiple platforms before automating it:
 211
 212 ```bash
 213 GOARCH=amd64 GOOS=darwin                              go build -o unarr_darwin cmd/unarr/unarr.go
 214 GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc   go build -o unarr.exe cmd/unarr/unarr.go
 215 GOARCH=amd64 GOOS=linux   CC=x86_64-linux-musl-gcc    go build -o unarr_linux_amd64 cmd/unarr/unarr.go
 216 GOARCH=arm64 GOOS=linux   CC=aarch64-linux-musl-gcc   go build -o unarr_linux_arm64 cmd/unarr/unarr.go
 217 GOARCH=arm   GOOS=linux   CC=arm-linux-musl-gcc       go build -o unarr_linux_armv7 cmd/unarr/unarr.go
 218 ```
 219
 220 If you have simple instructions for how to set up cross-compiling from Windows or Linux, please let us know.
 221
 222 #### Build Changes
 223
 224 You'll need to manually create a different `builds` item for each unique `id`:
 225
 226 ```yml
 227 - builds:
 228   - id: unarr-linux-x64
 229     main: ./cmd/unarr/unarr.go
 230     env:
 231       - CGO_ENABLED=1
 232       - CC=x86_64-linux-musl-gcc
 233     flags:
 234       - "-ldflags"
 235       - '-extldflags "-static"'
 236     goos:
 237       - linux
 238     goarch:
 239       - amd64
 240   - id: unarr-linux-aarch64
 241     main: ./cmd/unarr/unarr.go
 242     env:
 243       - CGO_ENABLED=1
 244       - CC=aarch64-linux-musl-gcc
 245     flags:
 246       - "-ldflags"
 247       - '-extldflags "-static"'
 248     goos:
 249       - linux
 250     goarch:
 251       - arm64
 252   - id: unarr-linux-armv7
 253     main: ./cmd/unarr/unarr.go
 254     env:
 255       - CGO_ENABLED=1
 256       - CC=arm-linux-musleabi-gcc
 257     flags:
 258       - "-ldflags"
 259       - '-extldflags "-static"'
 260     goos:
 261       - linux
 262     goarch:
 263       - arm
 264     goarm:
 265       - 7
 266   - id: unarr-windows-x64
 267     main: ./cmd/unarr/unarr.go
 268     env:
 269       - CGO_ENABLED=1
 270       - CC=x86_64-w64-mingw32-gcc
 271     flags:
 272       - "-ldflags"
 273       - '-extldflags "-static"'
 274     goos:
 275       - linux
 276     goarch:
 277       - amd64
 278 ```
 279
 280 If you compile without `-static`, you will need the `musl` libraries to run on (non-Alpine) Linuxes:
 281
 282 ```bash
 283 sudo apt-get install -y musl
 284 ```
 285
 286 ### Full Example Config
 287
 288 The full file will look something like this:
 289
 290 `.goreleaser.yml`
 291
 292 ```yml
 293 project_name: exampleproject
 294 before:
 295   hooks:
 296     - go mod download
 297     - go generate ./...
 298 builds:
 299   - env:
 300       - CGO_ENABLED=0
 301     goos:
 302       - linux
 303       - windows
 304       - darwin
 305     goarch:
 306       - 386
 307       - amd64
 308       - arm
 309       - arm64
 310     goarm:
 311       - 6
 312       - 7
 313 archives:
 314   - replacements:
 315       darwin: Darwin
 316       linux: Linux
 317       windows: Windows
 318       386: i386
 319       amd64: x86_64
 320     format_overrides:
 321       - goos: windows
 322         format: zip
 323 checksum:
 324   name_template: 'checksums.txt'
 325 snapshot:
 326   name_template: "{{ .Tag }}-next"
 327 changelog:
 328   sort: asc
 329   filters:
 330     exclude:
 331       - '^docs:'
 332       - '^test:'
 333 ```