diff --git a/Makefile b/Makefile index 9b5850b03..007564e7f 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,8 @@ SOURCE_FILES?=$$(go list ./... | grep -v /vendor/) TEST_PATTERN?=. TEST_OPTIONS?= -setup: ## Install all the build and lint dependencies +# Install all the build and lint dependencies +setup: go get -u github.com/alecthomas/gometalinter go get -u github.com/golang/dep/cmd/dep go get -u github.com/pierrre/gotestcover @@ -10,16 +11,20 @@ setup: ## Install all the build and lint dependencies dep ensure gometalinter --install -test: ## Run all the tests +# Run all the tests +test: gotestcover $(TEST_OPTIONS) -covermode=atomic -coverprofile=coverage.txt $(SOURCE_FILES) -run $(TEST_PATTERN) -timeout=2m -cover: test ## Run all the tests and opens the coverage report +# Run all the tests and opens the coverage report +cover: test go tool cover -html=coverage.txt -fmt: ## gofmt and goimports all go files +# gofmt and goimports all go files +fmt: find . -name '*.go' -not -wholename './vendor/*' | while read -r file; do gofmt -w -s "$$file"; goimports -w "$$file"; done -lint: ## Run all the linters +# Run all the linters +lint: gometalinter --vendor --disable-all \ --enable=deadcode \ --enable=ineffassign \ @@ -35,13 +40,29 @@ lint: ## Run all the linters --deadline=10m \ ./... -ci: test lint ## Run all the tests and code checks +# Run all the tests and code checks +ci: test lint -build: ## Build a beta version of goreleaser +# Build a beta version of goreleaser +build: go build -# Absolutely awesome: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html -help: - @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' +HIGHLIGHT=https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0 + +# Generate the static documentation +static: + @static-docs \ + --in docs \ + --out ../goreleaser.github.io \ + --title GoReleaser \ + --subtitle "Deliver Go binaries as fast and easily as possible" \ + --google UA-106198408-1 \ + --script "$(HIGHLIGHT)/highlight.min.js" \ + --script "$(HIGHLIGHT)/languages/go.min.js" \ + --script "$(HIGHLIGHT)/languages/yaml.min.js" \ + --style "$(HIGHLIGHT)/styles/atom-one-dark.min.css" \ + --inline-script 'hljs.initHighlightingOnLoad();' \ + --inline-style 'pre { padding: 0; }' + .DEFAULT_GOAL := build diff --git a/README.md b/README.md index 72ea68759..4b719fdd9 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,6 @@ --- - GoReleaser builds Go binaries for several platforms, creates a GitHub release and then pushes a Homebrew formula to a tap repository. All that wrapped in your favorite CI. @@ -25,556 +24,10 @@ We appreciate your contribution. Please refer to our [contributing guidelines](C For questions join the [#goreleaser](https://gophers.slack.com/messages/goreleaser/) channel in the [Gophers Slack](https://invite.slack.golangbridge.org/). -# Table of contents +## Documentation -- [Introduction](#introduction) -- [Quick start](#quick-start) -- [Environment setup](#environment-setup) -- [Release customization](#release-customization) -- [Integration with CI](#integration-with-ci) - -## Introduction - -GoReleaser is a release automation tool for Golang projects, the goal is to simplify the build, release and publish steps while providing variant customization options for all steps. - -GoReleaser is built for CI tools; you only need to [download and execute it](#integration-with-ci) in your build script. -You can [customize](#release-customization) your release process by createing a `.goreleaser.yml` file. -We are also working on integrating with package managers, we currently support Home -. - -The idea started with a [simple shell script](https://github.com/goreleaser/old-go-releaser), but it quickly became more complex and I also wanted to publish binaries via Homebrew taps. - -## Quick start - -In this example we will build, archive and release a Golang project. -Create a GitHub repository and add a single main package: -```go -// main.go -package main - -func main() { - println("Ba dum, tss!") -} -``` - -By default GoReleaser will build the current directory, but you can change the build package path in the GoReleaser configuration file. - -```yml -# .goreleaser.yml -# Build customization -builds: - - binary: drum-roll - goos: - - windows - - darwin - - linux - goarch: - - amd64 -``` - -PS: Invalid GOOS/GOARCH combinations will automatically be skipped. - -This configuration specifies the build operating systems to Windows, Linux and MacOS using 64bit architecture, the name of the binaries is `drum-roll`. - -GoReleaser will then archive the result binaries of each Os/Arch into a separate file. The default format is `{{.ProjectName}}_{{.Os}}_{{.Arch}}`. -You can change the archives name and format. You can also replace the OS and the Architecture with your own. -Another useful feature is to add files to archives, this is very useful for integrating assets like resource files. - -```yml -# .goreleaser.yml -# Build customization -builds: - - main: main.go - binary: drum-roll - goos: - - windows - - darwin - - linux - goarch: - - amd64 -# Archive customization -archive: - format: tar.gz - replacements: - amd64: 64-bit - darwin: macOS - linux: Tux - files: - - drum-roll.licence.txt -``` - -This configuration will generate tar archives, contains an additional file `drum-roll.licence.txt`, the archives will be located in: - -- `./dist/drum-roll_windows_64-bit.tar.gz` -- `./dist/drum-roll_macOS_64-bit.tar.gz` -- `./dist/drum-roll_Tux_64-bit.tar.gz` - -Next export a `GITHUB_TOKEN` environment variable with the `repo` scope selected. This will be used to deploy releases to your GitHub repository. Create yours [here](https://github.com/settings/tokens/new). - -```console -$ export GITHUB_TOKEN=`YOUR_TOKEN` -``` - -GoReleaser uses 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: - -```console -$ git tag -a v0.1.0 -m "First release" && git push origin v0.1.0 -``` - -**Note**: we recommend the use of [semantic versioning](http://semver.org/). We -are not enforcing it though. We do remove the `v` prefix and then enforce -that the next character is a number. So, `v0.1.0` and `0.1.0` are virtually the -same and are both accepted, while `version0.1.0` is not. - -If you don't want to create a tag yet but instead simply create a package based on the latest commit, then you can also use the `--snapshot` flag. - -Now you can run GoReleaser at the root of your repository: - -```console -$ goreleaser -``` - -That's it! Check your GitHub project's release page. -The release should look like this: - -[![image](https://cloud.githubusercontent.com/assets/245435/23342061/fbcbd506-fc31-11e6-9d2b-4c1b776dee9c.png) -](https://github.com/goreleaser/goreleaser/releases) - -## Environment setup - -### GitHub Token - -GoReleaser requires a GitHub API token with the `repo` scope checked to deploy the artefacts to GitHub. You can create one [here](https://github.com/settings/tokens/new). -This token should be added to the environment variables as `GITHUB_TOKEN`. Here is how to do it with Travis CI: [Defining Variables in Repository Settings](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings). - -### A note about `main.version` - -GoReleaser always sets a `main.version` ldflag. You can use it in your -`main.go` file: - -```go -package main - -var version = "master" - -func main() { - println(version) -} -``` - -`version` will be the current Git tag (with `v` prefix stripped) or the name of the snapshot if you're using the `--snapshot` flag. - -## GoReleaser customization - -GoReleaser provides multiple customizations via the `.goreleaser.yml` file. -You can generate it by running `goreleaser init` or start from scratch. The -defaults are sensible and fit for most projects. - -We'll cover all customizations available bellow: - -### Project name - -```yml -# .goreleaser.yml -# The name of the project. It is used in the name of the brew formula, archives, -# etc. Defaults to the name of the git project. -project_name: myproject -``` - -### Build customization - -```yml -# .goreleaser.yml -builds: - # You can have multiple builds, its a common yaml list - - - # Path to main.go file or main package. - # Default is `.` - main: ./cmd/main.go - - # Name of the binary. - # Default is the name of the project directory. - binary: program - - # Custom build tags. - # Default is empty - flags: -tags dev - - # Custom ldflags template. - # This is parsed with Golang template engine and the following variables - # are available: - # - Date - # - Commit - # - Tag - # - Version (Tag with the `v` prefix stripped) - # The default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}` - # Date format is `2006-01-02_15:04:05` - ldflags: -s -w -X main.build={{.Version}} - - # Custom environment variables to be set durign the builds. - # Default is empty - env: - - CGO_ENABLED=0 - - # GOOS list to build in. - # For more info refer to https://golang.org/doc/install/source#environment - # Defaults are darwin and linux - goos: - - freebsd - - windows - - # GOARCH to build in. - # For more info refer to https://golang.org/doc/install/source#environment - # Defaults are 386 and amd64 - goarch: - - amd64 - - arm - - arm64 - - # GOARM to build in when GOARCH is arm. - # For more info refer to https://golang.org/doc/install/source#environment - # Defaults are 6 - goarm: - - 6 - - 7 - - # List of combinations of GOOS + GOARCH + GOARM to ignore. - # Default is empty. - ignore: - - goos: darwin - goarch: 386 - - goos: linux - goarch: arm - goarm: 7 - - # Hooks can be used to customize the final binary, for example, to run - # generator or whatever you want. - # Default is both hooks empty. - hooks: - pre: rice embed-go - post: ./script.sh -``` - -### Archive customization - -```yml -# .goreleaser.yml -archive: - # You can change the name of the archive. - # This is parsed with Golang template engine and the following variables - # are available: - # - ProjectName - # - Tag - # - Version (Tag with the `v` prefix stripped) - # - Os - # - Arch - # - Arm (ARM version) - # The default is `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}` - name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" - - # Archive format. Valid options are `tar.gz`, `zip` and `binary`. - # If format is `binary` no archives are created and the binaries are instead uploaded directly. - # In that case name_template the below specified files are ignored. - # Default is `tar.gz` - format: zip - - # Can be used to archive on different formats for specific GOOSs. - # Most common use case is to archive as zip on Windows. - # Default is empty - format_overrides: - - goos: windows - format: zip - - # Replacements for GOOS and GOARCH on the archive name. - # The keys should be valid GOOS or GOARCH values followed by your custom - # replacements. - replacements: - amd64: 64-bit - 386: 32-bit - darwin: macOS - linux: Tux - - # Additional files/globs you want to add to the archive. - # Defaults are any files matching `LICENCE*`, `LICENSE*`, - # `README*` and `CHANGELOG*` (case-insensitive) - files: - - LICENSE.txt - - README.md - - CHANGELOG.md - - docs/* - - design/*.png -``` - -### Release customization - -```yml -# .goreleaser.yml -release: - # Repo in which the release will be created. - # Default is extracted from the origin remote URL. - github: - owner: user - name: repo - - # If set to true, will not auto-publish the release. - # Default is false - draft: true -``` - -You can also specify a release notes file in markdown format using the -`--release-notes` flag. - -### Snapshot customization - -```yml -# .goreleaser.yml -snapshot: - # Allows you to change the name of the generated snapshot - # releases. The following variables are available: - # - Commit - # - Tag - # - Timestamp - # Default: SNAPSHOT-{{.Commit}} - name_template: SNAPSHOT-{{.Commit}} -``` - -### Checksums file customization - -```yml -# .goreleaser.yml -checksum: - # You can change the name of the checksums file. - # This is parsed with Golang template engine and the following variables - # are available: - # - ProjectName - # - Tag - # - Version (Tag with the `v` prefix stripped) - # The default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt` - name_template: "{{ .ProjectName }}_checksums.txt" -``` - -### Homebrew tap customization - -The brew section specifies how the formula should be created. -Check [the Homebrew documentation](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) and the [formula cookbook](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md) for details. - -```yml -# .goreleaser.yml -brew: - # Reporitory to push the tap to. - github: - owner: user - name: homebrew-tap - - # Folder inside the repository to put the formula. - # Default is the root folder. - folder: Formula - - # Caveats for the user of your binary. - # Default is empty. - caveats: "How to use this binary" - - # Your app's homepage - # Default is empty - homepage: "https://example.com/" - - # Your app's description - # Default is empty - description: "Software to create fast and easy drum rolls." - - # Dependencies of your package - dependencies: - - git - - zsh - - # Packages that conflict with your package - conflicts: - - svn - - bash - - # Packages that run as a service. Default is empty. - plist: | - - ... - - # So you can brew test your formula. Default is empty. - test: | - system "#{bin}/program --version" - ... - - # Custom install script for brew. Default is 'bin.install "program"' - install: | - bin.install "program" - ... -``` - -By defining the `brew` section, GoReleaser will take care of publishing the Homebrew tap. -Assuming that the current tag is `v1.2.3`, the above config will generate a `program.rb` formula in the `Formula` folder of `user/homebrew-tap` repository: - -```rb -class Program < Formula - desc "How to use this binary" - homepage "https://github.com/user/repo" - url "https://github.com/user/repo/releases/download/v1.2.3/program_v1.2.3_macOs_64bit.zip" - version "v1.2.3" - sha256 "9ee30fc358fae8d248a2d7538957089885da321dca3f09e3296fe2058e7fff74" - - depends_on "git" - depends_on "zsh" - - def install - bin.install "program" - end -end -``` - -Note that GoReleaser does not yet generate a valid homebrew-core formula. The generated formulas -are meant to be published as [homebrew taps](https://docs.brew.sh/brew-tap.html), not in any -of the official homebrew repositories. - -### FPM build customization - -GoReleaser can be wired to [fpm]() to generate `.deb`, `.rpm` and other archives. Check its -[wiki](https://github.com/jordansissel/fpm/wiki) for more info. - -[fpm]: https://github.com/jordansissel/fpm - -```yml -# .goreleaser.yml -fpm: - # Your app's vendor - # Default is empty - vendor: Drum Roll Inc. - # Your app's homepage - # Default is empty - homepage: https://example.com/ - - # Your app's maintainer (probably you) - # Default is empty - maintainer: Drummer - - # Your app's description - # Default is empty - description: Software to create fast and easy drum rolls. - - # Your app's license - # Default is empty - license: Apache 2.0 - - # Formats to generate as output - formats: - - deb - - rpm - - # Dependencies of your package - dependencies: - - git - - zsh - - # Packages that conflict with your package - conflicts: - - svn - - bash - - # Files or directories to add to your package (beyond the binary) - files: - "scripts/etc/init.d/": "/etc/init.d" - -``` - -Note that GoReleaser will not install `fpm` nor any of its dependencies for you. - -### Snapcraft build customization - -GoReleaser can generate `snap` packages. [Snaps](http://snapcraft.io/) are a new packaging format that will let you publish your project directly to the Ubuntu store. From there it will be installable in all the [supported Linux distros](https://snapcraft.io/docs/core/install), with automatic and transactional updates. - -You can read more about it in the [snapcraft docs](https://snapcraft.io/docs/). - -```yml -# .goreleaser.yml -snapcraft: - - # The name of the snap. This is optional and defaults to the project name. - name: drumroll - - # Single-line elevator pitch for your amazing snap. - # 79 char long at most. - summary: Software to create fast and easy drum rolls. - - # This the description of your snap. You have a paragraph or two to tell the - # most important story about your snap. Keep it under 100 words though, - # we live in tweetspace and your description wants to look good in the snap - # store. - description: | - This is the best drum roll application out there. - Install it and awe! - - # A guardrail to prevent you from releasing a snap to all your users before - # it is ready. - # `devel` will let you release only to the `edge` and `beta` channels in the - # store. `stable` will let you release also to the `candidate` and `stable` - # channels. More info about channels here: - # https://snapcraft.io/docs/reference/channels. - grade: stable - - # Snaps can be setup to follow three different confinement policies: - # `strict`, `devmode` and `classic`. A strict confinement where the snap - # can only read and write in its own namespace is recommended. Extra - # permissions for strict snaps can be declared as `plugs` for the app, which - # are explained later. More info about confinement here: - # https://snapcraft.io/docs/reference/confinement). - confinement: strict - - # Each binary built by GoReleaser is an app inside the snap. In this section - # you can declare extra details for those binaries. It is optional. - apps: - - # The name of the app must be the same name of the binary built. - drumroll: - - # If your app requires extra permissions to work outside of its default - # confined space, delcare them here. - # You can read the documentation about the available plugs and the - # things they allow: - # https://snapcraft.io/docs/reference/interfaces). - plugs: ["home", "network"] - - # If you want your app to be autostarted and to always run in the - # background, you can make it a simple daemon. - daemon: simple -``` - -Note that GoReleaser will not install `snapcraft` nor any of its dependencies for you. - -### Custom release notes - -You can have a markdown file previously created with the release notes, and -pass it down to goreleaser with the `--release-notes=FILE` flag. - -## Integration with CI - -You may want to wire this to auto-deploy your new tags on [Travis](https://travis-ci.org), for example: - -```yaml -# .travis.yml -after_success: - - test -n "$TRAVIS_TAG" && curl -sL https://git.io/goreleaser | bash -``` - -Here is how to do it with [CircleCI](https://circleci.com): - -```yml -# circle.yml -deployment: - tag: - tag: /v[0-9]+(\.[0-9]+)*(-.*)*/ - owner: user - commands: - - curl -sL https://git.io/goreleaser | bash -``` - -*Note that if you test multiple versions or multiple OSes you probably want to make sure GoReleaser is just run once* +Documentation can be found in the [docs folder](docs) and live +at https://goreleaser.com ### Stargazers over time diff --git a/docs/000-introduction.md b/docs/000-introduction.md new file mode 100644 index 000000000..f9e9c47fa --- /dev/null +++ b/docs/000-introduction.md @@ -0,0 +1,14 @@ +--- +title: Introduction +--- + +GoReleaser is a release automation tool for Golang projects, the goal is to simplify the build, release and publish steps while providing variant customization options for all steps. + +GoReleaser is built for CI tools; you only need to [download and execute it](#integration-with-ci) in your build script. +You can [customize](#release-customization) your release process by createing a `.goreleaser.yml` file. + +The idea started with a +[simple shell script](https://github.com/goreleaser/old-go-releaser), +but it quickly became more complex and I also wanted to publish binaries via +Homebrew taps, which would made the script even more hacky, so I let go of +that and rewrote the whole thing in Go. diff --git a/docs/010-quick-start.md b/docs/010-quick-start.md new file mode 100644 index 000000000..44fc08d2f --- /dev/null +++ b/docs/010-quick-start.md @@ -0,0 +1,113 @@ +--- +title: Quick Start +--- + +In this example we will build, archive and release a Golang project. +Create a GitHub repository and add a single main package: + +```go +// main.go +package main + +func main() { + println("Ba dum, tss!") +} +``` + +By default GoReleaser will build the current directory, but you can change +the build package path in the GoReleaser configuration file. + +```yml +# .goreleaser.yml +# Build customization +builds: + - binary: drum-roll + goos: + - windows + - darwin + - linux + goarch: + - amd64 +``` + +PS: Invalid GOOS/GOARCH combinations will automatically be skipped. + +This configuration specifies the build operating systems to Windows, Linux and +MacOS using 64bit architecture, the name of the binaries is `drum-roll`. + +GoReleaser will then archive the result binaries of each Os/Arch into a +separate file. The default format is `{{.ProjectName}}_{{.Os}}_{{.Arch}}`. +You can change the archives name and format. You can also replace the OS +and the Architecture with your own. +Another useful feature is to add files to archives, this is very useful for +integrating assets like resource files. + +```yml +# .goreleaser.yml +# Build customization +builds: + - main: main.go + binary: drum-roll + goos: + - windows + - darwin + - linux + goarch: + - amd64 +# Archive customization +archive: + format: tar.gz + replacements: + amd64: 64-bit + darwin: macOS + linux: Tux + files: + - drum-roll.licence.txt +``` + +This configuration will generate tar archives, containing an additional +file called `drum-roll.licence.txt`. The archives will be located in the `dist`` +folder: + +- `./dist/drum-roll_windows_64-bit.tar.gz` +- `./dist/drum-roll_macOS_64-bit.tar.gz` +- `./dist/drum-roll_Tux_64-bit.tar.gz` + +Next export a `GITHUB_TOKEN` environment variable with the `repo` scope +selected. This will be used to deploy releases to your GitHub repository. +Create yours [here](https://github.com/settings/tokens/new). + +```console +$ export GITHUB_TOKEN=`YOUR_TOKEN` +``` + +GoReleaser uses 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: + +```console +$ git tag -a v0.1.0 -m "First release" +$ git push origin v0.1.0 +``` + +**Note**: @e recommend the use of [semantic versioning](http://semver.org/). We +are not enforcing it though. We do remove the `v` prefix and then enforce +that the next character is a number. So, `v0.1.0` and `0.1.0` are virtually the +same and are both accepted, while `version0.1.0` is not. + +If you don't want to create a tag yet but instead simply create a package +based on the latest commit, then you can also use the `--snapshot` flag. + +Now you can run GoReleaser at the root of your repository: + +```console +$ goreleaser +``` + +That's it! Check your GitHub project's release page. +The release should look like this: + + + + diff --git a/docs/020-environment.md b/docs/020-environment.md new file mode 100644 index 000000000..720f28690 --- /dev/null +++ b/docs/020-environment.md @@ -0,0 +1,33 @@ +--- +title: Environment Setup +--- + +### GitHub Token + +GoReleaser requires a GitHub API token with the `repo` scope checked to +deploy the artefacts to GitHub. You can create one +[here](https://github.com/settings/tokens/new). + +This token should be added to the environment variables as `GITHUB_TOKEN`. +Here is how to do it with Travis CI: +[Defining Variables in Repository Settings](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings). + +### A note about `main.version` + +GoReleaser always sets a `main.version` ldflag. You can use it in your +`main.go` file: + +```go +package main + +var version = "master" + +func main() { + println(version) +} +``` + +`version` will be the current Git tag (with `v` prefix stripped) or the name of +the snapshot if you're using the `--snapshot` flag. + +You can override this by changing the `ldflags` option in the `build` section. diff --git a/docs/030-customization.md b/docs/030-customization.md new file mode 100644 index 000000000..cddd28e8e --- /dev/null +++ b/docs/030-customization.md @@ -0,0 +1,9 @@ +--- +title: Customization +--- + +GoReleaser provides multiple customizations via the `.goreleaser.yml` file. +You can generate it by running `goreleaser init` or start from scratch. The +defaults are sensible and fit for most projects. + +We'll cover all customizations available bellow. diff --git a/docs/040-project.md b/docs/040-project.md new file mode 100644 index 000000000..20b185c24 --- /dev/null +++ b/docs/040-project.md @@ -0,0 +1,12 @@ +--- +title: Custom project name +--- + +The project name is used in the name of the brew formula, archives, etc. +If none is given, it will be infered from the name of the git project. + + +```yaml +# .goreleaser.yml +project_name: myproject +``` diff --git a/docs/050-build.md b/docs/050-build.md new file mode 100644 index 000000000..95c3d9d30 --- /dev/null +++ b/docs/050-build.md @@ -0,0 +1,80 @@ +--- +title: Custom builds +--- + +Builds can be customized in multiple ways. You can change which `GOOS` and +`GOARCH` would be built, the name of the binary, flags, ldflags, hooks and etc. + +Here is a full commented `builds` section: + +```yml +# .goreleaser.yml +builds: + # You can have multiple builds defined as a common yaml list + - + # Path to main.go file or main package. + # Default is `.` + main: ./cmd/main.go + + # Name of the binary. + # Default is the name of the project directory. + binary: program + + # Custom build tags. + # Default is empty + flags: -tags dev + + # Custom ldflags template. + # This is parsed with Golang template engine and the following variables + # are available: + # - Date + # - Commit + # - Tag + # - Version (Tag with the `v` prefix stripped) + # The default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}` + # Date format is `2006-01-02_15:04:05` + ldflags: -s -w -X main.build={{.Version}} + + # Custom environment variables to be set durign the builds. + # Default is empty + env: + - CGO_ENABLED=0 + + # GOOS list to build in. + # For more info refer to https://golang.org/doc/install/source#environment + # Defaults are darwin and linux + goos: + - freebsd + - windows + + # GOARCH to build in. + # For more info refer to https://golang.org/doc/install/source#environment + # Defaults are 386 and amd64 + goarch: + - amd64 + - arm + - arm64 + + # GOARM to build in when GOARCH is arm. + # For more info refer to https://golang.org/doc/install/source#environment + # Defaults are 6 + goarm: + - 6 + - 7 + + # List of combinations of GOOS + GOARCH + GOARM to ignore. + # Default is empty. + ignore: + - goos: darwin + goarch: 386 + - goos: linux + goarch: arm + goarm: 7 + + # Hooks can be used to customize the final binary, for example, to run + # generator or whatever you want. + # Default is both hooks empty. + hooks: + pre: rice embed-go + post: ./script.sh +``` diff --git a/docs/060-archive.md b/docs/060-archive.md new file mode 100644 index 000000000..4fbed0d01 --- /dev/null +++ b/docs/060-archive.md @@ -0,0 +1,57 @@ +--- +title: Custom archiving +--- + +The binaries built will be archived within the README and LICENSE files into a +`tar.gz` file. In the `archive` section you can customize the archive name, +files, and format. + +Here is a full commented `archive` section: + +```yml +# .goreleaser.yml +archive: + # You can change the name of the archive. + # This is parsed with Golang template engine and the following variables + # are available: + # - ProjectName + # - Tag + # - Version (Tag with the `v` prefix stripped) + # - Os + # - Arch + # - Arm (ARM version) + # The default is `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}` + name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" + + # Archive format. Valid options are `tar.gz`, `zip` and `binary`. + # If format is `binary` no archives are created and the binaries are instead uploaded directly. + # In that case name_template the below specified files are ignored. + # Default is `tar.gz` + format: zip + + # Can be used to archive on different formats for specific GOOSs. + # Most common use case is to archive as zip on Windows. + # Default is empty + format_overrides: + - goos: windows + format: zip + + # Replacements for GOOS and GOARCH on the archive name. + # The keys should be valid GOOS or GOARCH values followed by your custom + # replacements. + replacements: + amd64: 64-bit + 386: 32-bit + darwin: macOS + linux: Tux + + # Additional files/globs you want to add to the archive. + # Defaults are any files matching `LICENCE*`, `LICENSE*`, + # `README*` and `CHANGELOG*` (case-insensitive) + files: + - LICENSE.txt + - README.md + - CHANGELOG.md + - docs/* + - design/*.png +``` diff --git a/docs/070-checksum.md b/docs/070-checksum.md new file mode 100644 index 000000000..bce44a3e1 --- /dev/null +++ b/docs/070-checksum.md @@ -0,0 +1,22 @@ +--- +title: Custom checksum +--- + +GoRelease generates a `project_1.0.0_checksums.txt` and uploads it to the +release as well, so your users can validate if the downloaded files are +right. + +The `checksum` section allows the customization of the filename: + +```yml +# .goreleaser.yml +checksum: + # You can change the name of the checksums file. + # This is parsed with Golang template engine and the following variables + # are available: + # - ProjectName + # - Tag + # - Version (Tag with the `v` prefix stripped) + # The default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt` + name_template: "{{ .ProjectName }}_checksums.txt" +``` diff --git a/docs/080-snapshots.md b/docs/080-snapshots.md new file mode 100644 index 000000000..f168d7e84 --- /dev/null +++ b/docs/080-snapshots.md @@ -0,0 +1,20 @@ +--- +title: Snapshots +--- + +Sometimes we want to generate a full build of our project for some reason, +but don't want to validate anything nor upload it to anywhere. +GoRelease supports this with a `--snapshot` flag and with a `snapshot` +customization section as well. + +```yml +# .goreleaser.yml +snapshot: + # Allows you to change the name of the generated snapshot + # releases. The following variables are available: + # - Commit + # - Tag + # - Timestamp + # Default: SNAPSHOT-{{.Commit}} + name_template: SNAPSHOT-{{.Commit}} +``` diff --git a/docs/100-fpm.md b/docs/100-fpm.md new file mode 100644 index 000000000..5df9f32d9 --- /dev/null +++ b/docs/100-fpm.md @@ -0,0 +1,51 @@ +--- +title: Custom linux packages +--- + +GoReleaser can be wired to [fpm](https://github.com/jordansissel/fpm) to generate `.deb`, `.rpm` and other archives. Check its +[wiki](https://github.com/jordansissel/fpm/wiki) for more info. + +```yml +# .goreleaser.yml +fpm: + # Your app's vendor + # Default is empty + vendor: Drum Roll Inc. + # Your app's homepage + # Default is empty + homepage: https://example.com/ + + # Your app's maintainer (probably you) + # Default is empty + maintainer: Drummer + + # Your app's description + # Default is empty + description: Software to create fast and easy drum rolls. + + # Your app's license + # Default is empty + license: Apache 2.0 + + # Formats to generate as output + formats: + - deb + - rpm + + # Dependencies of your package + dependencies: + - git + - zsh + + # Packages that conflict with your package + conflicts: + - svn + - bash + + # Files or directories to add to your package (beyond the binary) + files: + "scripts/etc/init.d/": "/etc/init.d" + +``` + +Note that GoReleaser will not install `fpm` nor any of its dependencies for you. diff --git a/docs/110-snapcraft.md b/docs/110-snapcraft.md new file mode 100644 index 000000000..31bf60f3c --- /dev/null +++ b/docs/110-snapcraft.md @@ -0,0 +1,63 @@ +--- +title: Snapcraft +--- + +GoReleaser can generate `snap` packages. [Snaps](http://snapcraft.io/) are a new packaging format that will let you publish your project directly to the Ubuntu store. From there it will be installable in all the [supported Linux distros](https://snapcraft.io/docs/core/install), with automatic and transactional updates. + +You can read more about it in the [snapcraft docs](https://snapcraft.io/docs/). + +```yml +# .goreleaser.yml +snapcraft: + + # The name of the snap. This is optional and defaults to the project name. + name: drumroll + + # Single-line elevator pitch for your amazing snap. + # 79 char long at most. + summary: Software to create fast and easy drum rolls. + + # This the description of your snap. You have a paragraph or two to tell the + # most important story about your snap. Keep it under 100 words though, + # we live in tweetspace and your description wants to look good in the snap + # store. + description: | + This is the best drum roll application out there. + Install it and awe! + + # A guardrail to prevent you from releasing a snap to all your users before + # it is ready. + # `devel` will let you release only to the `edge` and `beta` channels in the + # store. `stable` will let you release also to the `candidate` and `stable` + # channels. More info about channels here: + # https://snapcraft.io/docs/reference/channels. + grade: stable + + # Snaps can be setup to follow three different confinement policies: + # `strict`, `devmode` and `classic`. A strict confinement where the snap + # can only read and write in its own namespace is recommended. Extra + # permissions for strict snaps can be declared as `plugs` for the app, which + # are explained later. More info about confinement here: + # https://snapcraft.io/docs/reference/confinement). + confinement: strict + + # Each binary built by GoReleaser is an app inside the snap. In this section + # you can declare extra details for those binaries. It is optional. + apps: + + # The name of the app must be the same name of the binary built. + drumroll: + + # If your app requires extra permissions to work outside of its default + # confined space, delcare them here. + # You can read the documentation about the available plugs and the + # things they allow: + # https://snapcraft.io/docs/reference/interfaces). + plugs: ["home", "network"] + + # If you want your app to be autostarted and to always run in the + # background, you can make it a simple daemon. + daemon: simple +``` + +Note that GoReleaser will not install `snapcraft` nor any of its dependencies for you. diff --git a/docs/115-release.md b/docs/115-release.md new file mode 100644 index 000000000..10ae7e288 --- /dev/null +++ b/docs/115-release.md @@ -0,0 +1,30 @@ +--- +title: Custom releasing +--- + +GoRelease will create a release in GitHub with the current tag, upload all +the archives and checksums, also generating a changelog from the commit +log between the current and previous tags. + +Let's see what can be customized in the `release` section: + +```yml +# .goreleaser.yml +release: + # Repo in which the release will be created. + # Default is extracted from the origin remote URL. + github: + owner: user + name: repo + + # If set to true, will not auto-publish the release. + # Default is false + draft: true +``` + +## Custom release notes + +You can have a markdown file previously created with the release notes, and +pass it down to goreleaser with the `--release-notes=FILE` flag. +GoReleaser will then skip its own release notes generation, +using the contents of your file instead. diff --git a/docs/120-homebrew.md b/docs/120-homebrew.md new file mode 100644 index 000000000..183cd3dca --- /dev/null +++ b/docs/120-homebrew.md @@ -0,0 +1,90 @@ +--- +title: Custom homebrew tap +--- + +After releasing to GitHub, GoReleaser can generate and publish a homebrew-tap +recipe into a repository that you have access to. + +The brew section specifies how the formula should be created. +You can check the +[Homebrew documentation](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) +and the +[formula cookbook](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md) +for more details. + +```yml +# .goreleaser.yml +brew: + # Reporitory to push the tap to. + github: + owner: user + name: homebrew-tap + + # Folder inside the repository to put the formula. + # Default is the root folder. + folder: Formula + + # Caveats for the user of your binary. + # Default is empty. + caveats: "How to use this binary" + + # Your app's homepage + # Default is empty + homepage: "https://example.com/" + + # Your app's description + # Default is empty + description: "Software to create fast and easy drum rolls." + + # Dependencies of your package + dependencies: + - git + - zsh + + # Packages that conflict with your package + conflicts: + - svn + - bash + + # Packages that run as a service. Default is empty. + plist: | + + ... + + # So you can brew test your formula. Default is empty. + test: | + system "#{bin}/program --version" + ... + + # Custom install script for brew. Default is 'bin.install "program"' + install: | + bin.install "program" + ... +``` + +By defining the `brew` section, GoReleaser will take care of publishing the +Homebrew tap. +Assuming that the current tag is `v1.2.3`, the above config will generate a +`program.rb` formula in the `Formula` folder of `user/homebrew-tap` repository: + +```rb +class Program < Formula + desc "How to use this binary" + homepage "https://github.com/user/repo" + url "https://github.com/user/repo/releases/download/v1.2.3/program_v1.2.3_macOs_64bit.zip" + version "v1.2.3" + sha256 "9ee30fc358fae8d248a2d7538957089885da321dca3f09e3296fe2058e7fff74" + + depends_on "git" + depends_on "zsh" + + def install + bin.install "program" + end +end +``` + +**Important**": Note that GoReleaser does not yet generate a valid +homebrew-core formula. The generated formulas are meant to be published as +[homebrew taps](https://docs.brew.sh/brew-tap.html), and in their current +form will not be accepted in any of the official homebrew repositories. diff --git a/docs/140-ci.md b/docs/140-ci.md new file mode 100644 index 000000000..030c31669 --- /dev/null +++ b/docs/140-ci.md @@ -0,0 +1,25 @@ +--- +title: CI integration +--- + +You may want to wire this to auto-deploy your new tags on [Travis](https://travis-ci.org), for example: + +```yaml +# .travis.yml +after_success: + - test -n "$TRAVIS_TAG" && curl -sL https://git.io/goreleaser | bash +``` + +Here is how to do it with [CircleCI](https://circleci.com): + +```yml +# circle.yml +deployment: + tag: + tag: /v[0-9]+(\.[0-9]+)*(-.*)*/ + owner: user + commands: + - curl -sL https://git.io/goreleaser | bash +``` + +*Note that if you test multiple versions or multiple OSes you probably want to make sure GoReleaser is just run once* diff --git a/docs/999-links.md b/docs/999-links.md new file mode 100644 index 000000000..5503eab79 --- /dev/null +++ b/docs/999-links.md @@ -0,0 +1,13 @@ +--- +title: Links +--- + +- Follow the progress on [GitHub repository](https://github.com/goreleaser/goreleaser) +- Follow [@caarlos0](https://twitter.com/caarlos0) on Twitter for updates +- [Slack](https://gophers.slack.com/messages/goreleaser/) to chat about GoReleaser, +quetions and etc. Join using [this link](https://invite.slack.golangbridge.org/). +- [Contributing Guidelines](https://github.com/goreleaser/goreleaser/blob/master/CONTRIBUTING.md) + +This project adheres to the Contributor Covenant +[code of conduct](https://github.com/goreleaser/goreleaser/blob/master/CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. diff --git a/docs/apple-touch-icon-144-precomposed.png b/docs/apple-touch-icon-144-precomposed.png new file mode 100644 index 000000000..c1aefd7ad Binary files /dev/null and b/docs/apple-touch-icon-144-precomposed.png differ diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 000000000..77b2a8e7f Binary files /dev/null and b/docs/favicon.ico differ