go/goreleaser
go/goreleaser
1
0
Fork 0
mirror of https://github.com/goreleaser/goreleaser.git synced 2025-02-07 13:31:37 +02:00
Code Issues Releases Activity

docs: clarify build docs a bit

Browse Source
This commit is contained in:
Carlos A Becker 2022-09-18 13:57:48 -03:00
parent 91c6f75b8f
commit 7ea12d2ac5
No known key found for this signature in database
GPG Key ID: E61E2F7DC14AB940
1 changed files with 71 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
www/docs/customization/build.md
View File

@ -112,14 +112,20 @@ builds:
- gomips: hardfloat - gomips: hardfloat
- goamd64: v4 - goamd64: v4
# Optionally override the matrix generation and specify only the final list of targets. # Optionally override the matrix generation and specify only the final list
# Format is `{goos}_{goarch}` with optionally a suffix with `_{goarm}`, `_{goamd64}` or `_{gomips}`. # of targets.
#
# Format is `{goos}_{goarch}` with their respective suffixes when
# applicable: `_{goarm}`, `_{goamd64}`, `_{gomips}`.
# #
# Special values: # Special values:
# - go_118_first_class: evaluates to the first-class targets of go1.18. Since GoReleaser v1.9. # - go_118_first_class: evaluates to the first-class targets of go1.18.
# - go_first_class: evaluates to latest stable go first-class targets, currently same as 1.18. Since GoReleaser v1.9. # Since GoReleaser v1.9.
# - go_first_class: evaluates to latest stable go first-class targets,
# currently same as 1.18. Since GoReleaser v1.9.
# #
# This overrides `goos`, `goarch`, `goarm`, `gomips`, `goamd64` and `ignores`. # This overrides `goos`, `goarch`, `goarm`, `gomips`, `goamd64` and
# `ignores`.
targets: targets:
- go_first_class - go_first_class
- go_118_first_class - go_118_first_class
@ -161,17 +167,23 @@ builds:
# Default is false # Default is false
skip: false skip: false
# By default, GoReleaser will create your binaries inside `dist/${BuildID}_${BuildTarget}`, which is an unique directory per build target in the matrix. # By default, GoReleaser will create your binaries inside
# `dist/${BuildID}_${BuildTarget}`, which is an unique directory per build
# target in the matrix.
# You can set subdirs within that folder using the `binary` property. # You can set subdirs within that folder using the `binary` property.
# #
# However, if for some reason you don't want that unique directory to be created, you can set this property. # However, if for some reason you don't want that unique directory to be
# If you do, you are responsible for keeping different builds from overriding each other. # created, you can set this property.
# If you do, you are responsible for keeping different builds from
# overriding each other.
# #
# Defaults to `false`. # Defaults to `false`.
no_unique_dist_dir: true no_unique_dist_dir: true
# By default, GoReleaser will check if the main filepath has a main function. # By default, GoReleaser will check if the main filepath has a main
# This can be used to skip that check, in case you're building tests, for example. # function.
# This can be used to skip that check, in case you're building tests, for
# example.
# #
# Default: false. # Default: false.
# Since: v1.9. # Since: v1.9.
@ -255,7 +267,8 @@ builds:
- windows - windows
``` ```
The binary name field supports [templating](/customization/templates/). The following build details are exposed: The binary name field supports [templating](/customization/templates/). The
following build details are exposed:
<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ --> <!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->
@ -288,11 +301,12 @@ GOVERSION=$(go version) goreleaser
## Build Hooks ## Build Hooks
Both pre and post hooks run **for each build target**, regardless of whether Both pre and post hooks run **for each build target**, regardless of whether
these targets are generated via a matrix of OSes and architectures these targets are generated via a matrix of OSes and architectures or defined
or defined explicitly. explicitly.
In addition to simple declarations as shown above _multiple_ hooks can be declared In addition to simple declarations as shown above _multiple_ hooks can be
to help retaining reusability of config between different build environments. declared to help retaining reusability of config between different build
environments.
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
@ -331,9 +345,11 @@ builds:
- second-script.sh - second-script.sh
``` ```
All properties of a hook (`cmd`, `dir` and `env`) support [templating](/customization/templates/) All properties of a hook (`cmd`, `dir` and `env`) support
with `post` hooks having binary artifact available (as these run _after_ the build). [templating](/customization/templates/) with `post` hooks having binary artifact
Additionally the following build details are exposed to both `pre` and `post` hooks: available (as these run _after_ the build).
Additionally the following build details are exposed to both `pre` and `post`
hooks:
<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ --> <!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->
@ -353,9 +369,9 @@ Environment variables are inherited and overridden in the following order:
## Go Modules ## Go Modules
If you use Go 1.11+ with go modules or vgo, when GoReleaser runs it may If you use Go 1.11+ with go modules or vgo, when GoReleaser runs it may try to
try to download the dependencies. Since several builds run in parallel, it is download the dependencies. Since several builds run in parallel, it is very
very likely to fail. likely to fail.
You can solve this by running `go mod tidy` before calling `goreleaser` or You can solve this by running `go mod tidy` before calling `goreleaser` or
by adding a [hook][] doing that on your `.goreleaser.yaml` file: by adding a [hook][] doing that on your `.goreleaser.yaml` file:
@ -378,25 +394,34 @@ This is useful in scenarios where two tags point to the same commit.
## Reproducible Builds ## Reproducible Builds
To make your releases, checksums and signatures reproducible, you will need to make some (if not all) of the following modifications to the build defaults in GoReleaser: To make your releases, checksums and signatures reproducible, you will need to
make some (if not all) of the following modifications to the build defaults in
GoReleaser:
* Modify `ldflags`: by default `main.Date` is set to the time GoReleaser is run (`{{.Date}}`), you can set this to `{{.CommitDate}}` or just not pass the variable. * Modify `ldflags`: by default `main.Date` is set to the time GoReleaser is run
* Modify `mod_timestamp`: by default this is empty string, set to `{{.CommitTimestamp}}` or a constant value instead. (`{{.Date}}`), you can set this to `{{.CommitDate}}` or just not pass the
* If you do not run your builds from a consistent directory structure, pass `-trimpath` to `flags`. variable.
* Remove uses of the `time` template function. This function returns a new value on every call and is not deterministic. * Modify `mod_timestamp`: by default this is empty string, set to
`{{.CommitTimestamp}}` or a constant value instead.
* If you do not run your builds from a consistent directory structure, pass
`-trimpath` to `flags`.
* Remove uses of the `time` template function. This function returns a new value
on every call and is not deterministic.
## Import pre-built binaries ## Import pre-built binaries
!!! success "GoReleaser Pro" !!! success "GoReleaser Pro"
The prebuilt builder is a [GoReleaser Pro feature](/pro/). The prebuilt builder is a [GoReleaser Pro feature](/pro/).
Since GoReleaser Pro v0.179.0, it is possible to import pre-built binaries into the GoReleaser lifecycle. Since GoReleaser Pro v0.179.0, it is possible to import pre-built binaries into
the GoReleaser lifecycle.
Reasons you might want to do that include: Reasons you might want to do that include:
- You want to build your binaries in different machines due to CGO - You want to build your binaries in different machines due to CGO
- You want to build using a pre-existing `Makefile` or other tool - You want to build using a pre-existing `Makefile` or other tool
- You want to speed up the build by running several builds in parallel in different machines - You want to speed up the build by running several builds in parallel in
different machines
In any case, its pretty easy to do that now: In any case, its pretty easy to do that now:
@ -427,14 +452,16 @@ builds:
path: output/mybin_{{ .Os }}_{{ .Arch }}_{{ with .Amd64 }}_{{ . }}{{ end }}/mybin path: output/mybin_{{ .Os }}_{{ .Arch }}_{{ with .Amd64 }}_{{ . }}{{ end }}/mybin
``` ```
This example config will import into your release pipeline the following binaries: This example config will import into your release pipeline the following
binaries:
- `output/mybin_linux_amd64` - `output/mybin_linux_amd64`
- `output/mybin_linux_arm64` - `output/mybin_linux_arm64`
- `output/mybin_darwin_amd64_v1` - `output/mybin_darwin_amd64_v1`
- `output/mybin_darwin_arm64` - `output/mybin_darwin_arm64`
The other steps of the pipeline will act as if those were built by GoReleaser itself. The other steps of the pipeline will act as if those were built by GoReleaser
itself.
There is no difference in how the binaries are handled. There is no difference in how the binaries are handled.
!!! tip !!! tip
@ -460,17 +487,24 @@ If you'd like to see this in action, check [this example on GitHub](https://gith
## A note about folder names inside `dist` ## A note about folder names inside `dist`
By default, GoReleaser will create your binaries inside `dist/${BuildID}_${BuildTarget}`, which is an unique directory per build target in the matrix. By default, GoReleaser will create your binaries inside
`dist/${BuildID}_${BuildTarget}`, which is an unique directory per build target
in the matrix.
Those names have no guarantees of remaining the same from one version to another. Those names have no guarantees of remaining the same from one version to
If you really need to access them from outside GoReleaser, you should be able to consistently get the path of a binary by parsing `dist/artifacts.json`. another. If you really need to access them from outside GoReleaser, you should
be able to consistently get the path of a binary by parsing
`dist/artifacts.json`.
You can also set `builds.no_unique_dist_dir` (as documented earlier in this page), but in that case you are responsible for preventing name conflicts. You can also set `builds.no_unique_dist_dir` (as documented earlier in this
page), but in that case you are responsible for preventing name conflicts.
### Why is there a `_v1` suffix on `amd64` builds? ### Why is there a `_v1` suffix on `amd64` builds?
Go 1.18 introduced the `GOAMD64` option, and `v1` is the default value for that option. Go 1.18 introduced the `GOAMD64` option, and `v1` is the default value for that
option.
Since you can have GoReleaser build for multiple different `GOAMD64` targets, it adds that suffix to prevent name conflicts. Since you can have GoReleaser build for multiple different `GOAMD64` targets, it
The same thing happens for `arm` and `GOARM`, `mips` and `GOMIPS` and others. adds that suffix to prevent name conflicts. The same thing happens for `arm` and
`GOARM`, `mips` and `GOMIPS` and others.