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