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

docs: clarify prebuilt.path and binary

Browse Source 
closes #4143
This commit is contained in:
Carlos Alexandro Becker 2023-06-26 18:11:07 +00:00
parent 7671b54056
commit c9eff90a62
No known key found for this signature in database
GPG Key ID: E61E2F7DC14AB940
1 changed files with 128 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

245
www/docs/customization/builds.md
View File

@ -11,7 +11,7 @@ Here is a commented `builds` section with all fields specified:
# .goreleaser.yaml # .goreleaser.yaml
builds: builds:
# You can have multiple builds defined as a yaml list # You can have multiple builds defined as a yaml list
- - #
# ID of the build. # ID of the build.
# #
# Default: Binary name # Default: Binary name
@ -183,7 +183,7 @@ builds:
# Set the modified timestamp on the output binary, typically # Set the modified timestamp on the output binary, typically
# you would do this to ensure a build was reproducible. Pass # you would do this to ensure a build was reproducible. Pass
# empty string to skip modifying the output. # empty string to skip modifying the output.
mod_timestamp: '{{ .CommitTimestamp }}' mod_timestamp: "{{ .CommitTimestamp }}"
# Hooks can be used to customize the final binary, # Hooks can be used to customize the final binary,
# for example, to run generators. # for example, to run generators.
@ -241,8 +241,8 @@ builds:
- goos: darwin - goos: darwin
goarch: arm64 goarch: arm64
goamd64: v1 goamd64: v1
goarm: '' goarm: ""
gomips: '' gomips: ""
ldflags: ldflags:
- foo - foo
tags: tags:
@ -256,9 +256,11 @@ builds:
``` ```
!!! tip !!! tip
Learn more about the [name template engine](/customization/templates/). Learn more about the [name template engine](/customization/templates/).
!!! info !!! info
First-class build targets are gathered by running: First-class build targets are gathered by running:
```sh ```sh
go tool dist list -json | jq -r '.[] | select(.FirstClass) | [.GOOS, .GOARCH] | @tsv' go tool dist list -json | jq -r '.[] | select(.FirstClass) | [.GOOS, .GOARCH] | @tsv'
@ -300,13 +302,13 @@ 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/ -->
Key |Description | Key | Description |
-------|--------------------------------- | ------- | --------------------------------- |
.Os |`GOOS` | .Os | `GOOS` |
.Arch |`GOARCH` | .Arch | `GOARCH` |
.Arm |`GOARM` | .Arm | `GOARM` |
.Ext |Extension, e.g. `.exe` | .Ext | Extension, e.g. `.exe` |
.Target|Build target, e.g. `darwin_amd64` | .Target | Build target, e.g. `darwin_amd64` |
## Passing environment variables to ldflags ## Passing environment variables to ldflags
@ -339,18 +341,17 @@ environments.
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
builds: builds:
- - id: "with-hooks"
id: "with-hooks"
targets: targets:
- "darwin_amd64" - "darwin_amd64"
- "windows_amd64" - "windows_amd64"
hooks: hooks:
pre: pre:
- first-script.sh - first-script.sh
- second-script.sh - second-script.sh
post: post:
- upx "{{ .Path }}" - upx "{{ .Path }}"
- codesign -project="{{ .ProjectName }}" "{{ .Path }}" - codesign -project="{{ .ProjectName }}" "{{ .Path }}"
``` ```
Each hook can also have its own work directory and environment variables: Each hook can also have its own work directory and environment variables:
@ -358,21 +359,21 @@ Each hook can also have its own work directory and environment variables:
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
builds: builds:
- - id: "with-hooks"
id: "with-hooks"
targets: targets:
- "darwin_amd64" - "darwin_amd64"
- "windows_amd64" - "windows_amd64"
hooks: hooks:
pre: pre:
- cmd: first-script.sh - cmd: first-script.sh
dir: "{{ dir .Dist}}" dir:
# Always print command output, otherwise only visible in debug mode. "{{ dir .Dist}}"
# Since: v1.5 # Always print command output, otherwise only visible in debug mode.
output: true # Since: v1.5
env: output: true
- HOOK_SPECIFIC_VAR={{ .Env.GLOBAL_VAR }} env:
- second-script.sh - HOOK_SPECIFIC_VAR={{ .Env.GLOBAL_VAR }}
- second-script.sh
``` ```
All properties of a hook (`cmd`, `dir` and `env`) support All properties of a hook (`cmd`, `dir` and `env`) support
@ -381,40 +382,39 @@ available (as these run _after_ the build).
Additionally the following build details are exposed to both `pre` and `post` Additionally the following build details are exposed to both `pre` and `post`
hooks: hooks:
<!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ --> <!-- to format the tables, use: https://tabletomarkdown.com/format-markdown-table/ -->
Key |Description | Key | Description |
-------|-------------------------------------- | ------- | -------------------------------------- |
.Name |Filename of the binary, e.g. `bin.exe` | .Name | Filename of the binary, e.g. `bin.exe` |
.Ext |Extension, e.g. `.exe` | .Ext | Extension, e.g. `.exe` |
.Path |Absolute path to the binary | .Path | Absolute path to the binary |
.Target|Build target, e.g. `darwin_amd64` | .Target | Build target, e.g. `darwin_amd64` |
Environment variables are inherited and overridden in the following order: Environment variables are inherited and overridden in the following order:
- global (`env`) - global (`env`)
- build (`builds[].env`) - build (`builds[].env`)
- hook (`builds[].hooks.pre[].env` and `builds[].hooks.post[].env`) - hook (`builds[].hooks.pre[].env` and `builds[].hooks.post[].env`)
## Go Modules ## Go Modules
If you use Go 1.11+ with go modules or vgo, when GoReleaser runs it may try to If you use Go 1.11+ with go modules or vgo, when GoReleaser runs it may try to
download the dependencies. Since several builds run in parallel, it is very download the dependencies. Since several builds run in parallel, it is 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:
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
before: before:
hooks: hooks:
- go mod tidy - go mod tidy
# rest of the file... # rest of the file...
``` ```
[hook]: /customization/hooks [hook]: /customization/hooks
## Define Build Tag ## Define Build Tag
@ -428,20 +428,21 @@ 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 make some (if not all) of the following modifications to the build defaults in
GoReleaser: GoReleaser:
* Modify `ldflags`: by default `main.Date` is set to the time GoReleaser is run - 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 (`{{.Date}}`), you can set this to `{{.CommitDate}}` or just not pass the
variable. variable.
* Modify `mod_timestamp`: by default this is empty string — which means it'll be - Modify `mod_timestamp`: by default this is empty string — which means it'll be
the compilation time, set to `{{.CommitTimestamp}}` or a constant value the compilation time, set to `{{.CommitTimestamp}}` or a constant value
instead. instead.
* If you do not run your builds from a consistent directory structure, pass - If you do not run your builds from a consistent directory structure, pass
`-trimpath` to `flags`. `-trimpath` to `flags`.
* Remove uses of the `time` template function. This function returns a new value - Remove uses of the `time` template function. This function returns a new value
on every call and is not deterministic. 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/).
It is also possible to import pre-built binaries into the GoReleaser lifecycle. It is also possible to import pre-built binaries into the GoReleaser lifecycle.
@ -458,30 +459,38 @@ In any case, its pretty easy to do that now:
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
builds: builds:
- - # Set the builder to prebuilt
# Set the builder to prebuilt builder: prebuilt
builder: prebuilt
# When builder is `prebuilt` there are no defaults for goos, goarch, # When builder is `prebuilt` there are no defaults for goos, goarch,
# goarm, gomips, goamd64 and targets, so you always have to specify them: # goarm, gomips, goamd64 and targets, so you always have to specify them:
goos: goos:
- linux - linux
- darwin - darwin
goarch: goarch:
- amd64 - amd64
- arm64 - arm64
goamd64: goamd64:
- v1 - v1
# prebuilt specific options # prebuilt specific options
prebuilt: prebuilt:
# Path must be the template path to the binaries. # Path must be the template path to the binaries.
# GoReleaser removes the `dist` folder before running, so you will likely # GoReleaser removes the `dist` folder before running, so you will likely
# want to put the binaries elsewhere. # want to put the binaries elsewhere.
# This field is required when using the `prebuilt` builder. # This field is required when using the `prebuilt` builder.
path: output/mybin_{{ .Os }}_{{ .Arch }}{{ with .Amd64 }}_{{ . }}{{ end }}/mybin path: output/mybin_{{ .Os }}_{{ .Arch }}{{ with .Amd64 }}_{{ . }}{{ end }}/mybin
# Use 'binary' to set the final name of your binary.
# This is the name that will be used in archives et al.
binary: bin/mybin
``` ```
!!! tip
You can think of `prebuilt.path` as being the "external path" and the
`binary` as being the "internal path to binary".
This example config will import into your release pipeline the following This example config will import into your release pipeline the following
binaries: binaries:
@ -495,6 +504,7 @@ itself.
There is no difference in how the binaries are handled. There is no difference in how the binaries are handled.
!!! tip !!! tip
A cool tip here, specially when using CGO, is that you can have one A cool tip here, specially when using CGO, is that you can have one
`.goreleaser.yaml` file just for the builds, build each in its own machine `.goreleaser.yaml` file just for the builds, build each in its own machine
with [`goreleaser build --single-target`](/cmd/goreleaser_build/) and with [`goreleaser build --single-target`](/cmd/goreleaser_build/) and
@ -504,11 +514,13 @@ There is no difference in how the binaries are handled.
builds in different machines in parallel. builds in different machines in parallel.
!!! warning !!! warning
GoReleaser will try to stat the final path, if any error happens while GoReleaser will try to stat the final path, if any error happens while
doing that (e.g. file does not exist or permission issues), doing that (e.g. file does not exist or permission issues),
GoReleaser will fail. GoReleaser will fail.
!!! warning !!! warning
When using the `prebuilt` binary, there are no defaults for `goos`, When using the `prebuilt` binary, there are no defaults for `goos`,
`goarch`, `goarm`, `gomips` and `goamd64`. `goarch`, `goarm`, `gomips` and `goamd64`.
You'll need to either provide them or the final `targets` matrix. You'll need to either provide them or the final `targets` matrix.
@ -560,19 +572,18 @@ attempt to configure any additional logic.
GoReleaser will: GoReleaser will:
* set the correct file extension for the target OS. - set the correct file extension for the target OS.
* package the generated header file (`.h`) in the release bundle. - package the generated header file (`.h`) in the release bundle.
Example usage: Example usage:
```yaml ```yaml
# .goreleaser.yaml # .goreleaser.yaml
builds: builds:
- - id: "my-library"
id: "my-library"
# Configure the buildmode flag to output a shared library # Configure the buildmode flag to output a shared library
buildmode: "c-shared" # or "c-archive" for a static library buildmode: "c-shared" # or "c-archive" for a static library
``` ```
## Complex template environment variables ## Complex template environment variables
@ -596,26 +607,26 @@ set `CC` and `CCX` to the right one:
```yaml ```yaml
# .goreleaser.yml # .goreleaser.yml
builds: builds:
- id: mybin - id: mybin
binary: mybin binary: mybin
main: . main: .
goos: goos:
- linux - linux
- darwin - darwin
- windows - windows
goarch: goarch:
- amd64 - amd64
- arm64 - arm64
env: env:
- CGO_ENABLED=0 - CGO_ENABLED=0
- CC_darwin_amd64=o64-clang - CC_darwin_amd64=o64-clang
- CCX_darwin_amd64=o64-clang+ - CCX_darwin_amd64=o64-clang+
- CC_darwin_arm64=aarch64-apple-darwin20.2-clang - CC_darwin_arm64=aarch64-apple-darwin20.2-clang
- CCX_darwin_arm64=aarch64-apple-darwin20.2-clang++ - CCX_darwin_arm64=aarch64-apple-darwin20.2-clang++
- CC_windows_amd64=x86_64-w64-mingw32-gc - CC_windows_amd64=x86_64-w64-mingw32-gc
- CCX_windows_amd64=x86_64-w64-mingw32-g++ - CCX_windows_amd64=x86_64-w64-mingw32-g++
- 'CC={{ index .Env (print "CC_" .Os "_" .Arch) }}' - 'CC={{ index .Env (print "CC_" .Os "_" .Arch) }}'
- 'CCX={{ index .Env (print "CCX_" .Os "_" .Arch) }}' - 'CCX={{ index .Env (print "CCX_" .Os "_" .Arch) }}'
``` ```
### Using `if` statements ### Using `if` statements
@ -625,19 +636,19 @@ This example uses `if` statements to set `CC` and `CCX`:
```yaml ```yaml
# .goreleaser.yml # .goreleaser.yml
builds: builds:
- id: mybin - id: mybin
binary: mybin binary: mybin
main: . main: .
goos: goos:
- linux - linux
- darwin - darwin
- windows - windows
goarch: goarch:
- amd64 - amd64
- arm64 - arm64
env: env:
- CGO_ENABLED=0 - CGO_ENABLED=0
- >- - >-
{{- if eq .Os "darwin" }} {{- if eq .Os "darwin" }}
{{- if eq .Arch "amd64"}}CC=o64-clang{{- end }} {{- if eq .Arch "amd64"}}CC=o64-clang{{- end }}
{{- if eq .Arch "arm64"}}CC=aarch64-apple-darwin20.2-clang{{- end }} {{- if eq .Arch "arm64"}}CC=aarch64-apple-darwin20.2-clang{{- end }}
@ -645,7 +656,7 @@ builds:
{{- if eq .Os "windows" }} {{- if eq .Os "windows" }}
{{- if eq .Arch "amd64" }}CC=x86_64-w64-mingw32-gcc{{- end }} {{- if eq .Arch "amd64" }}CC=x86_64-w64-mingw32-gcc{{- end }}
{{- end }} {{- end }}
- >- - >-
{{- if eq .Os "darwin" }} {{- if eq .Os "darwin" }}
{{- if eq .Arch "amd64"}}CXX=o64-clang+{{- end }} {{- if eq .Arch "amd64"}}CXX=o64-clang+{{- end }}
{{- if eq .Arch "arm64"}}CXX=aarch64-apple-darwin20.2-clang++{{- end }} {{- if eq .Arch "arm64"}}CXX=aarch64-apple-darwin20.2-clang++{{- end }}