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 To update or switch versions, run `webi goreleaser@stable` (or `@v0.174`,
   9 `@beta`, etc).
  10
  11 ## Cheat Sheet
  12
  13 > `goreleaser` makes it easy to build versioned Go binaries for Mac, Linux,
  14 > Windows, and Raspberry Pi, and to publish the ChangeLog and binaries to common
  15 > release platforms including GitHub, Gitea, Gitlab, and Homebrew.
  16
  17 There's a lot that you can do with GoReleaser. These are the things that we've
  18 found the most useful for the majority of projects:
  19
  20 - Basic Usage & Versioning
  21 - Publishing Builds to GitHub
  22 - Publishing to Gitea and Gitlab
  23 - Building for RPi et al
  24 - Building from one or more `cmd/`s
  25 - Cross-Compiling with cgo
  26 - Full `.goreleaser.yml` example
  27
  28 ## Basic Usage & Versioning
  29
  30 To create an example `.goreleaser.yaml` file, and test the configuration:
  31
  32 ```bash
  33 goreleaser init
  34 goreleaser --snapshot --skip-publish --rm-dist
  35 ```
  36
  37 - `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
  38 - `--skip-publish` will NOT publish to GitHub, etc
  39 - `--rm-dist` will automatically remove the `./dist/` directory
  40
  41 The default `.goreleaser.yml` works well for projects for which `package main`
  42 is at the root.
  43
  44 GoReleaser provides version information. Here's a good, generic way to print it
  45 out:
  46
  47 ```go
  48 package main
  49
  50 var (
  51         // these will be replaced by goreleaser
  52         version = "v0.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 the default config location:
  78
  79 ```bash
  80 ~/.config/goreleaser/github_token
  81 ```
  82
  83 You can also set `env_files` in `.goreleaser.yml`:
  84
  85 ```yml
  86 env_files:
  87   github_token: ~/.config/goreleaser/github_token
  88 ```
  89
  90 Running GoReleaser without `--snapshot` must use the latest
  91 [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
  92 Create a tag and push it to Git:
  93
  94 ```bash
  95 git tag -a v1.0.0 -m "First release"
  96 git push origin v1.0.0
  97 ```
  98
  99 Running GoReleaser without `--skip-publish` will publish the builds:
 100
 101 ```bash
 102 goreleaser --rm-dist
 103 ```
 104
 105 Check the console output to make sure that there are no messages about a failed
 106 publish. \
 107 If all is well you should the git tag on the releases page updated with a ChangeLog
 108 and the published binaries.
 109
 110 ### How to Publish to Gitea and others
 111
 112 Gitea Token: https://try.gitea.io/user/settings/applications
 113
 114 ```yml
 115 env_files:
 116   gitea_token: ~/.config/goreleaser/gitea_token
 117 gitea_urls:
 118   api: https://try.gitea.io/api/v1/
 119 ```
 120
 121 GitLab Token: https://gitlab.com/profile/personal_access_tokens
 122
 123 ```yml
 124 env_files:
 125   gitlab_token: ~/.config/goreleaser/gitlab_token
 126 gitlab_urls:
 127   api: https://gitlab.com/api/v1/
 128 ```
 129
 130 Also see https://goreleaser.com/environment/
 131
 132 ### How to Build for Raspberry Pi (ARM)
 133
 134 All of the Raspberry Pis are ARM processors and can run Linux. Most can run
 135 Windows as well.
 136
 137 - RPi 4 is ARM 64, also known as `aarch64`, `arm64`, and `armv8`.
 138 - RPi 3 could run `armv7` and `arm64`.
 139 - RPi 2, RPi Zero, and RPi can run either `armv6` or `armv7`.
 140
 141 To build Go binaries for ARM, you'll need to update the `build` section of your
 142 `.goreleases.yml`.
 143
 144 ```yml
 145 builds:
 146   - env:
 147       - CGO_ENABLED=0
 148     goos:
 149       - linux
 150       - windows
 151       - darwin
 152     goarch:
 153       - 386
 154       - amd64
 155       - arm
 156       - arm64
 157     goarm:
 158       - 6
 159       - 7
 160 ```
 161
 162 For information on other supported build options, such as BSD and ppc, see
 163 [Go (Golang) GOOS and GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).
 164
 165 ### How to Build from the `cmd` Directory
 166
 167 By default GoReleaser assumes that the root of your package is `package main`.
 168
 169 If your `package main` is in a `cmd/` directory or you have multiple commands,
 170 you should update your `builds` directive accordingly.
 171
 172 ```yml
 173 - builds:
 174     - id: command123
 175       main: ./cmd/command123/command123.go
 176       binary: command123
 177       goos:
 178         - linux
 179         - windows
 180         - darwin
 181       goarch:
 182         - amd64
 183         - arm64
 184     - id: other321
 185       main: ./cmd/other321/other321.go
 186       binary: other123
 187       goos:
 188         - linux
 189         - windows
 190         - darwin
 191       goarch:
 192         - amd64
 193         - arm64
 194 ```
 195
 196 ### How to Cross-Compile cgo
 197
 198 > [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
 199
 200 Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without
 201 any special configuration.
 202
 203 Some programs include C libraries, especially SQLite3 or 7z, and require
 204 integration with C libraries.
 205
 206 #### Mac Cross-Compilers
 207
 208 From macOS you can easily cross-compile cgo for Windows and Linux.
 209
 210 Install [brew](https://webinstall.dev/brew), if needed:
 211
 212 ```bash
 213 curl -sS https://webinstall.dev/brew | bash
 214 ```
 215
 216 Install mingw and musl-cross: \
 217 (this may take hours if pre-built binaries are not available)
 218
 219 ```bash
 220 brew install mingw-w64
 221 brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
 222 ```
 223
 224 You may want to manually test compiling for multiple platforms before automating
 225 it:
 226
 227 ```bash
 228 GOARCH=amd64 GOOS=darwin                              go build -o unarr_darwin cmd/unarr/unarr.go
 229 GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc   go build -o unarr.exe cmd/unarr/unarr.go
 230 GOARCH=amd64 GOOS=linux   CC=x86_64-linux-musl-gcc    go build -o unarr_linux_amd64 cmd/unarr/unarr.go
 231 GOARCH=arm64 GOOS=linux   CC=aarch64-linux-musl-gcc   go build -o unarr_linux_arm64 cmd/unarr/unarr.go
 232 GOARCH=arm   GOOS=linux   CC=arm-linux-musl-gcc       go build -o unarr_linux_armv7 cmd/unarr/unarr.go
 233 ```
 234
 235 If you have simple instructions for how to set up cross-compiling from Windows
 236 or Linux, please let us know.
 237
 238 #### Build Changes
 239
 240 You'll need to manually create a different `builds` item for each unique `id`:
 241
 242 ```yml
 243 - builds:
 244     - id: unarr-linux-x64
 245       main: ./cmd/unarr/unarr.go
 246       env:
 247         - CGO_ENABLED=1
 248         - CC=x86_64-linux-musl-gcc
 249       flags:
 250         - '-ldflags'
 251         - '-extldflags "-static"'
 252       goos:
 253         - linux
 254       goarch:
 255         - amd64
 256     - id: unarr-linux-aarch64
 257       main: ./cmd/unarr/unarr.go
 258       env:
 259         - CGO_ENABLED=1
 260         - CC=aarch64-linux-musl-gcc
 261       flags:
 262         - '-ldflags'
 263         - '-extldflags "-static"'
 264       goos:
 265         - linux
 266       goarch:
 267         - arm64
 268     - id: unarr-linux-armv7
 269       main: ./cmd/unarr/unarr.go
 270       env:
 271         - CGO_ENABLED=1
 272         - CC=arm-linux-musleabi-gcc
 273       flags:
 274         - '-ldflags'
 275         - '-extldflags "-static"'
 276       goos:
 277         - linux
 278       goarch:
 279         - arm
 280       goarm:
 281         - 7
 282     - id: unarr-windows-x64
 283       main: ./cmd/unarr/unarr.go
 284       env:
 285         - CGO_ENABLED=1
 286         - CC=x86_64-w64-mingw32-gcc
 287       flags:
 288         - '-ldflags'
 289         - '-extldflags "-static"'
 290       goos:
 291         - linux
 292       goarch:
 293         - amd64
 294 ```
 295
 296 If you compile without `-static`, you will need the `musl` libraries to run on
 297 (non-Alpine) Linuxes:
 298
 299 ```bash
 300 sudo apt-get install -y musl
 301 ```
 302
 303 ### Full Example Config
 304
 305 The full file will look something like this:
 306
 307 `.goreleaser.yml`
 308
 309 ```yml
 310 project_name: exampleproject
 311 before:
 312   hooks:
 313     - go mod download
 314     - go generate ./...
 315 builds:
 316   - env:
 317       - CGO_ENABLED=0
 318     goos:
 319       - linux
 320       - windows
 321       - darwin
 322     goarch:
 323       - 386
 324       - amd64
 325       - arm
 326       - arm64
 327     goarm:
 328       - 6
 329       - 7
 330 archives:
 331   - replacements:
 332       darwin: Darwin
 333       linux: Linux
 334       windows: Windows
 335       386: i386
 336       amd64: x86_64
 337     format_overrides:
 338       - goos: windows
 339         format: zip
 340 checksum:
 341   name_template: 'checksums.txt'
 342 snapshot:
 343   name_template: '{{ .Tag }}-next'
 344 changelog:
 345   sort: asc
 346   filters:
 347     exclude:
 348       - '^docs:'
 349       - '^test:'
 350 ```