diff --git a/docs/README.md b/docs/README.md index 928cd0319..b927fd853 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,8 +7,8 @@ pushes a Homebrew formula to a repository. All that wrapped in your favorite CI. [![Go Report Card](https://goreportcard.com/badge/github.com/goreleaser/goreleaser?style=flat-square)](https://goreportcard.com/report/github.com/goreleaser/goreleaser) [![Powered By: GoReleaser](https://img.shields.io/badge/powered%20by-goreleaser-green.svg?style=flat-square)](https://github.com/goreleaser) -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. -We appreciate your contribution. Please refer to our [contributing guidelines](/CONTRIBUTING.md). +This project adheres to the Contributor Covenant [code of conduct](../CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. +We appreciate your contribution. Please refer to our [contributing guidelines](../CONTRIBUTING.md). # Documentation @@ -22,18 +22,18 @@ We appreciate your contribution. Please refer to our [contributing guidelines](/ 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 a [single command line](#integration-with-ci) in your build script. Therefore, no package is required. -You can define your customization in a `goreleaser.yml` file. For examples, check the [goreleaser.example.yml](https://github.com/goreleaser/goreleaser/blob/master/goreleaser.example.yml) or the [goreleaser.yml](https://github.com/goreleaser/goreleaser/blob/master/goreleaser.yml) used by GoReleaser itself. More on this in [Release customization](#release-customization). +GoReleaser is built for CI tools; you only need a [single command line](#integration-with-ci) in your build script. Therefore, no package is required. +You can define your [customization](#release-customization) in a `goreleaser.yml` file. We are also working on integrating package managers, we currently support Homebrew. -The idea started with a simple shell script ([old GoReleaser](https://github.com/goreleaser/old-go-releaser)), but it quickly became more complex and I also wanted to publish binaries via Homebrew. +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. _So, the all-new GoReleaser was born._ ## Quick start -In this example, we will build, archive and release a Golang project. -For simplicity, create a GitHub repository and add a single main package: +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 @@ -42,7 +42,7 @@ func main() { println("Ba dum, tss!") } ``` -By default, GoReleaser will build the *main.go* file located in your current directory, but you can change the build package path in the GoReleaser configuration file. +By default GoReleaser will build the **main.go** file located in your current directory, but you can change the build package path in the GoReleaser configuration file. ```yml # goreleaser.yml @@ -83,15 +83,15 @@ archive: darwin: macOS linux: Tux files: - - /path/drum-roll.licence.txt + - drum-roll.licence.txt ``` -This configuration will generate tar archives, contains an additional file "drum-roll.licence.txt", the archives will be located in: +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, you need to 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). +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). ```sh export GITHUB_TOKEN=`YOUR_TOKEN` ``` @@ -107,8 +107,8 @@ Now you can run GoReleaser at the root of your repository: curl -s https://raw.githubusercontent.com/goreleaser/get/master/latest | bash ``` -That's it!, check your GitHub release page. -The release on GitHub looks pretty much like this: +That's it! Check your GitHub release page. +The release on will look like this: [![image](https://cloud.githubusercontent.com/assets/245435/21578845/09404c8a-cf78-11e6-92d7-165ddc03ca6c.png) ](https://github.com/goreleaser/goreleaser/releases) @@ -138,58 +138,119 @@ func main() { ## Release customization -GoReleaser provides multiple customizations. We will cover them with the help of [goreleaser.example.yml](https://github.com/goreleaser/goreleaser/blob/master/goreleaser.example.yml). -The _goreleaser.yml_ file is structured like this: +GoReleaser provides multiple customizations. We will cover them with the help of _goreleaser.yml_: + ```yml +# goreleaser.yml +# Build customization build: - ... + # Path to main.go file. + # Default is `main.go` + main: ./cmd/main.go + + # Name of the binary. Default is the name of the project directory. + binary_name: program + + # Custom ldflags. + # Default is `-s -w` + ldflags: -s -w + + # 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 + + +# Archive customization archive: - ... + # You can change the name of the archive. + # This is parsed with Golang template engine and the following variables + # are available: + # - BinaryName + # - Version + # - Os + # - Arch + # The default is `{{.BinaryName}}_{{.Os}}_{{.Arch}}` + name_template: "{{.BinaryName}}_{{.Version}}_{{.Os}}_{{.Arch}}" + + # Archive format. Valid options are `tar.gz` and `zip`. + # Default is `tar.gz` + 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. + # By default, `replacements` replace GOOS and GOARCH values with valid outputs + # of `uname -s` and `uname -m` respectively. + replacements: + amd64: 64-bit + 386: 32-bit + darwin: macOS + linux: Tux + + # Additional files 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 + + +# Release customization release: - ... -brew: - ... -``` + # Repo in which the release will be created. + # Default is extracted from the origin remote URL. + repo: user/repo -| Section | Option | Type | Description | Default | -| --- | --- | --- | --- | --- | -| `build` | main | String | Path to the main Golang file | `main.go` in current directory | -| `build` | binary_name | String | Name to be assigned to the binary file in each archive | Name of the project | -| `build` | ldflags | String | Custom Golang ldlags, used in the "go build" command | `-s -w` | -| `build` | goos | Array | List of the target operating systems | `[darwin, linux]` | -| `build` | goarch | Array | List of the target architectures | `[386, amd64]` | -| `archive` | name_template | String | Archive name pattern, the following variables are available: _BinaryName_ ,_Version_ ,_Os_ ,_Arch_ | `{{.BinaryName}}_{{.Os}}_{{.Arch}` | -| `archive` | format | String | Archive format, the following variables are available: _tar.gz_ and _zip_ | `zip` | -| `archive` | replacements | Map | Replacements for GOOS and GOARCH on the archive name. The keys should be valid GOOS or GOARCH values followed by your custom replacements | | -| `archive` | files | Array | Additional files you want to add to the archive | `LICENCE*`, `LICENSE*`, `README*` and `CHANGELOG*` (case-insensitive) | -| `release` | repo | String | Target release repository "username/repository" | Username and repository of the origin remote URL | -| `brew` | repo | String | Tap repository "username/homebrew-tap-repository" | | -| `brew` | folder | String | Folder inside the repository to put the formula | Root folder | -| `brew` | caveats | String | Caveats for the user of your binary | | -By defining the _brew_ property, GoReleaser will take care of publishing the Homebrew tap. -Add here for example below: -```yml -build: - binary_name: mybin +# The brew section specifies how the formula should be created +# Check this link for details: https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md brew: - repo: user/homebrew-tap-repository + # Reporitory to push the tap to. + repo: user/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" + + # Dependencies of your formula. + # For more info, check https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md + dependencies: + - pkg-config + - jpeg + - boost + - readline + - gtk+ + - x11 + ``` -For example, the above config will generate a mybin.rb formula in the _Formula_ folder of _homebrew-tap-repository_: +By defining the _brew_ property, 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 _homebrew-tap_ repository: ```rb -class Mybin < Formula +class Program < Formula desc "How to use this binary" - homepage "https://github.com/goreleaser/goreleaser" - url "path-to-release-file" - version "current-version" + homepage "https://github.com/user/homebrew-tap" + url "https://github.com/user/repo/releases/download/{version}/program_v1.2.3_macOs_64bit.zip" + version "v1.2.3" sha256 "9ee30fc358fae8d248a2d7538957089885da321dca3f09e3296fe2058e7fff74" def install - bin.install "mybin" + bin.install "program" end end ```