docs/Bottles.md

   1 ---
   2 last_review_date: "1970-01-01"
   3 ---
   4
   5 # Bottles (Binary Packages)
   6
   7 Bottles are produced by installing a formula with `brew install --build-bottle <formula>` and then bottling it with `brew bottle <formula>`. This generates a bottle file in the current directory and outputs the bottle DSL for insertion into the formula file.
   8
   9 ## Usage
  10
  11 When the formula being installed defines a bottle matching your system, it will be downloaded and installed automatically when you run `brew install <formula>`.
  12
  13 Bottles will not be used if:
  14
  15 - the user requests it (by specifying `--build-from-source`),
  16 - the formula requests it (with `pour_bottle?`),
  17 - any options are specified during installation (bottles are all compiled with default options),
  18 - the bottle is not up to date (e.g. missing or mismatched checksum),
  19 - or the bottle's `cellar` is neither `:any` (it requires being installed to a specific Cellar path) nor equal to the current `HOMEBREW_CELLAR` (the required Cellar path does not match that of the current Homebrew installation).
  20
  21 ## Creation
  22
  23 Bottles for `homebrew/core` formulae are created by [BrewTestBot](BrewTestBot.md) when a pull request is submitted. If the formula builds successfully on each supported platform and a maintainer approves the change, BrewTestBot updates its `bottle do` block and uploads each bottle to [GitHub Packages](https://github.com/orgs/Homebrew/packages).
  24
  25 By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit x86 operating systems). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimised for something else, you can pass the `--bottle-arch=` option to build for another architecture; for example, `brew install foo --build-bottle --bottle-arch=penryn`. Just remember that if you build for a newer architecture, some of your users might get binaries they can't run and that would be sad!
  26
  27 ## Format
  28
  29 Bottles are simple gzipped tarballs of compiled binaries. The formula name, version, target operating system and rebuild version is stored in the filename, any other metadata is in the formula's bottle DSL, and the formula definition is located within the bottle at `<formula>/<version>/.brew/<formula>.rb`.
  30
  31 ## Bottle DSL (Domain Specific Language)
  32
  33 Bottles are specified in formula definitions by a DSL contained within a `bottle do ... end` block.
  34
  35 A simple (and typical) example:
  36
  37 ```ruby
  38 bottle do
  39   sha256 arm64_big_sur: "a9ae578b05c3da46cedc07dd428d94a856aeae7f3ef80a0f405bf89b8cde893a"
  40   sha256 big_sur:       "5dc376aa20241233b76e2ec2c1d4e862443a0250916b2838a1ff871e8a6dc2c5"
  41   sha256 catalina:      "924afbbc16549d8c2b80544fd03104ff8c17a4b1460238e3ed17a1313391a2af"
  42   sha256 mojave:        "678d338adc7d6e8c352800fe03fc56660c796bd6da23eda2b1411fed18bd0d8d"
  43 end
  44 ```
  45
  46 A full example:
  47
  48 ```ruby
  49 bottle do
  50   root_url "https://example.com"
  51   rebuild 4
  52   sha256 cellar: "/opt/homebrew/Cellar", arm64_big_sur: "a9ae578b05c3da46cedc07dd428d94a856aeae7f3ef80a0f405bf89b8cde893a"
  53   sha256 cellar: :any,                   big_sur:       "5dc376aa20241233b76e2ec2c1d4e862443a0250916b2838a1ff871e8a6dc2c5"
  54   sha256                                 catalina:      "924afbbc16549d8c2b80544fd03104ff8c17a4b1460238e3ed17a1313391a2af"
  55   sha256                                 mojave:        "678d338adc7d6e8c352800fe03fc56660c796bd6da23eda2b1411fed18bd0d8d"
  56 end
  57 ```
  58
  59 ### Root URL (`root_url`)
  60
  61 Optionally contains the URL root used to determine bottle URLs.
  62
  63 By default this is omitted and Homebrew's default bottle URL root is used. This may be useful for taps that wish to provide bottles for their formulae or cater to a non-default `HOMEBREW_CELLAR`.
  64
  65 ### Cellar (`cellar`)
  66
  67 Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built.
  68
  69 Most compiled software contains references to its compiled location, preventing it from being simply relocated anywhere on disk. A value of `:any` or `:any_skip_relocation` means that the bottle can be safely installed in any Cellar as it did not contain any references to the Cellar in which it was originally built. This can be omitted if the bottle was compiled for the given OS/architecture's default `HOMEBREW_CELLAR`, as is done for all bottles built by BrewTestBot.
  70
  71 ### Rebuild version (`rebuild`)
  72
  73 Optionally contains the rebuild version of the bottle.
  74
  75 Sometimes bottles may need be updated without bumping the version or revision of the formula, e.g. if a new patch was applied. In such cases `rebuild` will have a value of `1` or more.
  76
  77 ### Checksum (`sha256`)
  78
  79 Contains the SHA-256 hash of the bottle for the given OS/architecture.
  80
  81 ## Formula DSL
  82
  83 An additional bottle-related method is available in the formula DSL.
  84
  85 ### Pour bottle (`pour_bottle?`)
  86
  87 Optionally returns a boolean to indicate whether a bottle should be used when installing this formula.
  88
  89 For example a bottle may break if a related formula has been compiled with non-default options, so this method could check for that case and return `false`.
  90
  91 A full example:
  92
  93 ```ruby
  94 pour_bottle? do
  95   reason "The bottle needs to be installed into #{Homebrew::DEFAULT_PREFIX}."
  96   satisfy { HOMEBREW_PREFIX.to_s == Homebrew::DEFAULT_PREFIX }
  97 end
  98 ```
  99
 100 Commonly used `pour_bottle?` conditions can be added as preset symbols to the `pour_bottle?` method, allowing them to be specified like this:
 101
 102 ```ruby
 103 pour_bottle? only_if: :default_prefix
 104 pour_bottle? only_if: :clt_installed
 105 ```