## Cheat Sheet
-> `goreleaser` builds Go binaries for serveral platforms, creates a GitHub release
-> and then pushes a Homebrew formula to a tap repository. All that wrapped in your
-> favourite CI.
+> `goreleaser` makes it easy to build versioned Go binaries for Mac, Linux, Windows, and
+> Raspberry Pi, and to publish the ChangeLog and binaries to common release platforms
+> including GitHub, Gitea, Gitlab, and Homebrew.
+
+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:
+
+- Basic Usage & Versioning
+- Publishing Builds to GitHub
+- Publishing to Gitea and Gitlab
+- Building for RPi et al
+- Building from one or more `cmd/`s
+- Cross-Compiling with cgo
+- Full `.goreleaser.yml` example
+
+## Basic Usage & Versioning
To create an example `.goreleaser.yaml` file, and test the configuration:
goreleaser --snapshot --skip-publish --rm-dist
```
-You'll need to export a `GITHUB_TOKEN` or `GITLAB_TOKEN` environment variable, which should
-contain a valid GitHub token with the `repo` scope or GitLab token with `api` scope. It will
-be used to deploy releases to your GitHub/GitLab repository. You can create a token
-[here](https://github.com/settings/tokens/new) for GitHub or
-[here](https://gitlab.com/profile/personal_access_tokens) for GitLab.
+- `--snapshot` allows "dirty" builds (when the repo has uncommitted changes)
+- `--skip-publish` will NOT publish to GitHub, etc
+- `--rm-dist` will automatically remove the `./dist/` directory
+
+The default `.goreleaser.yml` works well for projects for which `package main` is at the root.
+
+GoReleaser provides version information. Here's a good, generic way to print it out:
+
+```go
+package main
+
+var (
+ // these will be replaced by goreleaser
+ version = "0.0.0"
+ date = "0001-01-01T00:00:00Z"
+ commit = "0000000"
+)
+
+func main() {
+ if len(os.Args) >= 2 && "version" == strings.TrimPrefix(os.Args[1]) {
+ fmt.Printf("YOUR_CLI_NAME v%s %s (%s)\n", version, commit[:7], date)
+ }
+
+ // ...
+}
+```
+
+### How to Publish Builds to GitHub
+
+You'll need a **Personal Access Token** with the `repo` scope. \
+You can get one at <https://github.com/settings/tokens/new>.
+
+You can export the environment variable:
```bash
export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"
```
-or
+Or place the token in `~/.config/goreleaser/github_token.txt` and update `.goreleaser.yml` accordingly:
-```bash
-export GITLAB_TOKEN="YOUR_GITLAB_TOKEN"
+```yml
+env_files:
+ github_token: ~/.config/goreleaser/github_token.txt
```
-GoReleaser will use the latest [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your
-repository. Create a tag and push it to GitHub:
+Running GoReleaser without `--snapshot` must use the latest
+[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
+of your repository. Create a tag and push it to Git:
```bash
-git tag -a v0.1.0 -m "First release"
-git push origin v0.1.0
+git tag -a v1.0.0 -m "First release"
+git push origin v1.0.0
```
-Now you can run GoReleaser at the root of your repository:
+Running GoReleaser without `--skip-publish` will publish the builds:
```bash
-goreleaser
+goreleaser --rm-dist
+```
+
+Check the console output to make sure that there are no messages about a failed publish. \
+If all is well you should the git tag on the releases page updated with a ChangeLog and the published binaries.
+
+### How to Publish to Gitea and others
+
+Gitea Token: https://try.gitea.io/user/settings/applications
+
+```yml
+env_files:
+ gitea_token: ~/.config/goreleaser/gitea_token
+gitea_urls:
+ api: https://try.gitea.io/api/v1/
+```
+
+GitLab Token: https://gitlab.com/profile/personal_access_tokens
+
+```yml
+env_files:
+ gitlab_token: ~/.config/goreleaser/gitlab_token
+gitlab_urls:
+ api: https://gitlab.com/api/v1/
+```
+
+Also see https://goreleaser.com/environment/
+
+### How to Build for Raspberry Pi (ARM)
+
+All of the Raspberry Pis are ARM processors and can run Linux. Most can run Windows as well.
+
+- RPi 4 is ARM 64, also known as `aarch64`, `arm64`, and `armv8`.
+- RPi 3 could run `armv7` and `arm64`.
+- RPi 2, RPi Zero, and RPi can run either `armv6` or `armv7`.
+
+To build Go binaries for ARM, you'll need to update the `build` section of your `.goreleases.yml`.
+
+```yml
+builds:
+ - env:
+ - CGO_ENABLED=0
+ goos:
+ - linux
+ - windows
+ - darwin
+ goarch:
+ - 386
+ - amd64
+ - arm
+ - arm64
+ goarm:
+ - 6
+ - 7
+```
+
+For information on other supported build options, such as BSD and ppc, see
+[Go (Golang) GOOS and GOARCH](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63).
+
+### How to Build from the `cmd` Directory
+
+By default GoReleaser assumes that the root of your package is `package main`.
+
+If your `package main` is in a `cmd/` directory or you have multiple commands,
+you should update your `builds` directive accordingly.
+
+```yml
+- builds:
+ - id: command123
+ main: ./cmd/command123/command123.go
+ goos:
+ - linux
+ - windows
+ - darwin
+ goarch:
+ - amd64
+ - arm64
+ - id: other321
+ main: ./cmd/other321/other321.go
+ goos:
+ - linux
+ - windows
+ - darwin
+ goarch:
+ - amd64
+ - arm64
```
-That's all! Check your GitHub/GitLab project's release page.
+### How to Cross-Compile cgo
+
+> [cgo](https://golang.org/cmd/cgo/) is not Go - Dave Cheney
+
+Most Go programs are "pure Go" and will cross-compile `CGO_ENABLED=0` without any special configuration.
+
+Some programs include C libraries, especially SQLite3 or 7z, and require integration with C libraries.
+
+#### Mac Cross-Compilers
+
+From macOS you can easily cross-compile cgo for Windows and Linux.
-### To cross-compile for Windows / Linux
+Install [brew](https://webinstall.dev/brew), if needed:
+
+```bash
+curl -sS https://webinstall.dev/brew | bash
+```
+
+Install mingw and musl-cross: \
+(this may take hours if pre-built binaries are not available)
```bash
brew install mingw-w64
-brew install FiloSottile/musl-cross/musl-cross
+brew install FiloSottile/musl-cross/musl-cross --with-aarch64 --with-arm # --with-mips --with-486
```
+You may want to manually test compiling for multiple platforms before automating it:
+
```bash
GOARCH=amd64 GOOS=darwin go build -o unarr_darwin cmd/unarr/unarr.go
GOARCH=amd64 GOOS=windows CC=x86_64-w64-mingw32-gcc go build -o unarr.exe cmd/unarr/unarr.go
GOARCH=amd64 GOOS=linux CC=x86_64-linux-musl-gcc go build -o unarr_linux_amd64 cmd/unarr/unarr.go
+GOARCH=arm64 GOOS=linux CC=aarch64-linux-musl-gcc go build -o unarr_linux_arm64 cmd/unarr/unarr.go
+GOARCH=arm GOOS=linux CC=arm-linux-musl-gcc go build -o unarr_linux_armv7 cmd/unarr/unarr.go
```
-The linux in question would need the musl libs installed to run a musl bin
+If you have simple instructions for how to set up cross-compiling from Windows or Linux, please let us know.
-```bash
-sudo apt-get install -y musl
-```
+#### Build Changes
-```bash
+You'll need to manually create a different `builds` item for each unique `id`:
+
+```yml
- builds:
- id: unarr-linux-x64
main: ./cmd/unarr/unarr.go
- linux
goarch:
- amd64
+ - id: unarr-linux-aarch64
+ main: ./cmd/unarr/unarr.go
+ env:
+ - CGO_ENABLED=1
+ - CC=aarch64-linux-musl-gcc
+ flags:
+ - "-ldflags"
+ - '-extldflags "-static"'
+ goos:
+ - linux
+ goarch:
+ - arm64
+ - id: unarr-linux-armv7
+ main: ./cmd/unarr/unarr.go
+ env:
+ - CGO_ENABLED=1
+ - CC=arm-linux-musleabi-gcc
+ flags:
+ - "-ldflags"
+ - '-extldflags "-static"'
+ goos:
+ - linux
+ goarch:
+ - arm
+ goarm:
+ - 7
+ - id: unarr-windows-x64
+ main: ./cmd/unarr/unarr.go
+ env:
+ - CGO_ENABLED=1
+ - CC=x86_64-w64-mingw32-gcc
+ flags:
+ - "-ldflags"
+ - '-extldflags "-static"'
+ goos:
+ - linux
+ goarch:
+ - amd64
+```
+
+If you compile without `-static`, you will need the `musl` libraries to run on (non-Alpine) Linuxes:
+
+```bash
+sudo apt-get install -y musl
+```
+
+### Full Example Config
+
+The full file will look something like this:
+
+`.goreleaser.yml`
+
+```yml
+project_name: exampleproject
+before:
+ hooks:
+ - go mod download
+ - go generate ./...
+builds:
+ - env:
+ - CGO_ENABLED=0
+ goos:
+ - linux
+ - windows
+ - darwin
+ goarch:
+ - 386
+ - amd64
+ - arm
+ - arm64
+ goarm:
+ - 6
+ - 7
+archives:
+ - replacements:
+ darwin: Darwin
+ linux: Linux
+ windows: Windows
+ 386: i386
+ amd64: x86_64
+ format_overrides:
+ - goos: windows
+ format: zip
+checksum:
+ name_template: 'checksums.txt'
+snapshot:
+ name_template: "{{ .Tag }}-next"
+changelog:
+ sort: asc
+ filters:
+ exclude:
+ - '^docs:'
+ - '^test:'
```
\ No newline at end of file
projects / webi-installers / .git / commitdiff