github.com/joselitofilho/goreleaser@v0.155.1-0.20210123221854-e4891856c593/www/docs/customization/build.md (about)

     1  ---
     2  title: Builds
     3  ---
     4  
     5  Builds can be customized in multiple ways.
     6  You can specify for which `GOOS`, `GOARCH` and `GOARM` binaries are built
     7  (goreleaser will generate a matrix of all combinations), and you can change
     8  the name of the binary, flags, environment variables, hooks and etc.
     9  
    10  Here is a commented `builds` section with all fields specified:
    11  
    12  ```yaml
    13  # .goreleaser.yml
    14  builds:
    15    # You can have multiple builds defined as a yaml list
    16    -
    17      # ID of the build.
    18      # Defaults to the project name.
    19      id: "my-build"
    20  
    21      # Path to project's (sub)directory containing Go code.
    22      # This is the working directory for the Go build command(s).
    23      # Default is `.`.
    24      dir: go
    25  
    26      # Path to main.go file or main package.
    27      # Default is `.`.
    28      main: ./cmd/main.go
    29  
    30      # Binary name.
    31      # Can be a path (e.g. `bin/app`) to wrap the binary in a directory.
    32      # Default is the name of the project directory.
    33      binary: program
    34  
    35      # Custom flags templates.
    36      # Default is empty.
    37      flags:
    38        - -tags=dev
    39        - -v
    40  
    41      # Custom asmflags templates.
    42      # Default is empty.
    43      asmflags:
    44        - -D mysymbol
    45        - all=-trimpath={{.Env.GOPATH}}
    46  
    47      # Custom gcflags templates.
    48      # Default is empty.
    49      gcflags:
    50        - all=-trimpath={{.Env.GOPATH}}
    51        - ./dontoptimizeme=-N
    52  
    53      # Custom ldflags templates.
    54      # Default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}} -X main.builtBy=goreleaser`.
    55      ldflags:
    56       - -s -w -X main.build={{.Version}}
    57       - ./usemsan=-msan
    58  
    59      # Custom environment variables to be set during the builds.
    60      # Default is empty.
    61      env:
    62        - CGO_ENABLED=0
    63  
    64      # GOOS list to build for.
    65      # For more info refer to: https://golang.org/doc/install/source#environment
    66      # Defaults are darwin and linux.
    67      goos:
    68        - freebsd
    69        - windows
    70  
    71      # GOARCH to build for.
    72      # For more info refer to: https://golang.org/doc/install/source#environment
    73      # Defaults are 386, amd64 and arm64.
    74      goarch:
    75        - amd64
    76        - arm
    77        - arm64
    78  
    79      # GOARM to build for when GOARCH is arm.
    80      # For more info refer to: https://golang.org/doc/install/source#environment
    81      # Default is only 6.
    82      goarm:
    83        - 6
    84        - 7
    85  
    86      # GOMIPS and GOMIPS64 to build when GOARCH is mips, mips64, mipsle or mips64le.
    87      # For more info refer to: https://golang.org/doc/install/source#environment
    88      # Default is empty.
    89      gomips:
    90        - hardfloat
    91        - softfloat
    92  
    93      # List of combinations of GOOS + GOARCH + GOARM to ignore.
    94      # Default is empty.
    95      ignore:
    96        - goos: darwin
    97          goarch: 386
    98        - goos: linux
    99          goarch: arm
   100          goarm: 7
   101        - goarm: mips64
   102          gomips: hardfloat
   103  
   104      # Set a specific go binary to use when building. It is safe to ignore
   105      # this option in most cases.
   106      # Default is "go"
   107      gobinary: "go1.13.4"
   108  
   109      # Set the modified timestamp on the output binary, typically
   110      # you would do this to ensure a build was reproducible. Pass
   111      # empty string to skip modifying the output.
   112      # Default is empty string.
   113      mod_timestamp: '{{ .CommitTimestamp }}'
   114  
   115      # Hooks can be used to customize the final binary,
   116      # for example, to run generators.
   117      # Those fields allow templates.
   118      # Default is both hooks empty.
   119      hooks:
   120        pre: rice embed-go
   121        post: ./script.sh {{ .Path }}
   122  
   123      # If true, skip the build.
   124      # Useful for library projects.
   125      # Default is false
   126      skip: false
   127  ```
   128  
   129  !!! tip
   130      Learn more about the [name template engine](/customization/templates/).
   131  
   132  Here is an example with multiple binaries:
   133  
   134  ```yaml
   135  # .goreleaser.yml
   136  builds:
   137    - main: ./cmd/cli/cli.go
   138      id: "cli"
   139      binary: cli
   140      goos:
   141        - linux
   142        - darwin
   143        - windows
   144  
   145    - main: ./cmd/worker/worker.go
   146      id: "worker"
   147      binary: worker
   148      goos:
   149        - linux
   150        - darwin
   151        - windows
   152  
   153    - main: ./cmd/tracker/tracker.go
   154      id: "tracker"
   155      binary: tracker
   156      goos:
   157        - linux
   158        - darwin
   159        - windows
   160  ```
   161  
   162  The binary name field supports [templating](/customization/templates/). The following build details are exposed:
   163  
   164  | Key     | Description                      |
   165  |---------|----------------------------------|
   166  | .Os     | `GOOS`                           |
   167  | .Arch   | `GOARCH`                         |
   168  | .Arm    | `GOARM`                          |
   169  | .Ext    | Extension, e.g. `.exe`           |
   170  | .Target | Build target, e.g. `darwin_amd64`|
   171  
   172  ## Passing environment variables to ldflags
   173  
   174  You can do that by using `{{ .Env.VARIABLE_NAME }}` in the template, for
   175  example:
   176  
   177  ```yaml
   178  builds:
   179    - ldflags:
   180     - -s -w -X "main.goversion={{.Env.GOVERSION}}"
   181  ```
   182  
   183  Then you can run:
   184  
   185  ```sh
   186  GOVERSION=$(go version) goreleaser
   187  ```
   188  
   189  ## Build Hooks
   190  
   191  Both pre and post hooks run **for each build target**, regardless of whether
   192  these targets are generated via a matrix of OSes and architectures
   193  or defined explicitly.
   194  
   195  In addition to simple declarations as shown above _multiple_ hooks can be declared
   196  to help retaining reusability of config between different build environments.
   197  
   198  ```yaml
   199  builds:
   200    -
   201      id: "with-hooks"
   202      targets:
   203       - "darwin_amd64"
   204       - "windows_amd64"
   205      hooks:
   206        pre:
   207         - first-script.sh
   208         - second-script.sh
   209        post:
   210         - upx "{{ .Path }}"
   211         - codesign -project="{{ .ProjectName }}" "{{ .Path }}"
   212  ```
   213  
   214  Each hook can also have its own work directory and environment variables:
   215  
   216  ```yaml
   217  builds:
   218    -
   219      id: "with-hooks"
   220      targets:
   221       - "darwin_amd64"
   222       - "windows_amd64"
   223      hooks:
   224        pre:
   225         - cmd: first-script.sh
   226           dir: "{{ dir .Dist}}"
   227           env:
   228            - HOOK_SPECIFIC_VAR={{ .Env.GLOBAL_VAR }}
   229         - second-script.sh
   230  ```
   231  
   232  All properties of a hook (`cmd`, `dir` and `env`) support [templating](/customization/templates/)
   233  with `post` hooks having binary artifact available (as these run _after_ the build).
   234  Additionally the following build details are exposed to both `pre` and `post` hooks:
   235  
   236  | Key     | Description                            |
   237  |---------|----------------------------------------|
   238  | .Name   | Filename of the binary, e.g. `bin.exe` |
   239  | .Ext    | Extension, e.g. `.exe`                 |
   240  | .Path   | Absolute path to the binary            |
   241  | .Target | Build target, e.g. `darwin_amd64`      |
   242  
   243  Environment variables are inherited and overridden in the following order:
   244  
   245   - global (`env`)
   246   - build (`builds[].env`)
   247   - hook (`builds[].hooks.pre[].env` and `builds[].hooks.post[].env`)
   248  
   249  ## Go Modules
   250  
   251   If you use Go 1.11+ with go modules or vgo, when GoReleaser runs it may
   252   try to download the dependencies. Since several builds run in parallel, it is
   253   very likely to fail.
   254  
   255   You can solve this by running `go mod download` before calling `goreleaser` or
   256   by adding a [hook][] doing that on your `.goreleaser.yml` file:
   257  
   258   ```yaml
   259   before:
   260     hooks:
   261     - go mod download
   262   # rest of the file...
   263   ```
   264  
   265   [hook]: /customization/hooks
   266  
   267  ## Define Build Tag
   268  
   269  GoReleaser uses `git describe` to get the build tag. You can set
   270  a different build tag using the environment variable `GORELEASER_CURRENT_TAG`.
   271  This is useful in scenarios where two tags point to the same commit.
   272  
   273  ## Reproducible Builds
   274  
   275  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:
   276  
   277  * 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.
   278  * Modify `mod_timestamp`: by default this is empty string, set to `{{.CommitTimestamp}}` or a constant value instead.
   279  * If you do not run your builds from a consistent directory structure, pass `-trimpath` to `flags`.
   280  * Remove uses of the `time` template function. This function returns a new value on every call and is not deterministic.