Add new documentation for homebrew tap

README.md

@@ -64,18 +64,34 @@ For different linux environments, you have these choices:
 
 ### macOS
 
-For macOS there is a [Homebrew](https://brew.sh) package
-[available](https://formulae.brew.sh/formula/cbmc). Once you have installed
-Homebrew, simply run
+For macOS there is a package available in [Homebrew/core](https://formulae.brew.sh/formula/cbmc).
+Assuming you have homebrew installed, you can run
 
-    brew install cbmc
+```sh
+$ brew install cbmc
+```
 
-to install cbmc, or if you already have it installed via homebrew
+to install CBMC, or if you already have it installed via homebrew
 
-    brew upgrade cbmc
+```sh
+$ brew upgrade cbmc
+```
 
 to get an up-to-date version.
 
+Homebrew will always update formulas to their latest version available, so you may
+periodically see an upgraded version of CBMC being downloaded regardless of whether
+you explicitly requested that or not. If you would rather this didn't happen, you
+can pin the CBMC version with:
+
+```sh
+$ brew pin cbmc
+```
+
+If instead of the latest version, you would want to install a historic version, you
+can do so with a [homebrew tap](https://github.com/diffblue/homebrew-cbmc) that we
+maintain. Instructions for that are available in the [documentation](doc/ADR/homebrew_tap.md)
+
 Report bugs
 ===========
 

doc/ADR/README.md

@@ -9,3 +9,4 @@ of the system and the surrounding infrastructure.
 ## Release & Packaging
 
 * [Release Process](release_process.md)
+* [Homebrew tap](homebrew_tap.md)

doc/ADR/homebrew_tap.md

@@ -0,0 +1,111 @@
+# Homebrew tap instructions
+
+CBMC archives versions into a tap which you can use to quickly download and
+build various historical versions.
+
+The tap is available at https://github.com/diffblue/homebrew-cbmc.
+
+Any version installed from the tap will need to be built from source locally.
+
+## Managing `brew tap`-based CBMC installations
+
+* Add the CBMC tap using the following command:
+
+  ```sh
+  $ brew tap diffblue/cbmc
+  ```
+
+* Install any of the available CBMC versions in the following manner:
+
+  ```sh
+  $ brew install diffblue/cbmc/[email protected]
+  ```
+
+* To remove the version of CBMC installed you need to issue
+
+  ```sh
+  $ brew remove diffblue/cbmc/[email protected]
+  ```
+
+* To remove the tap altogether, you need to issue
+
+  ```sh
+  $ brew untap diffblue/cbmc
+  ```
+
+## CBMC maintainer instructions
+
+* You can clone the [CBMC tap](https://github.com/diffblue/homebrew-cbmc)
+  locally by issuing:
+
+  ```sh
+  $ brew tap diffblue/cbmc
+  ```
+
+  That instruction is going to clone the above tap repository locally.
+  Afterwards, you can proceed with installing the formulas present,
+  edit them, etc.
+
+  If you wish to set up a new tap for any reason, you can
+  use `brew tap-new` like the following example:
+
+  ```sh
+  $ brew tap-new <developer>/homebrew_cbmc
+  ```
+
+* For any edit, the second step is to `cd` into the repository.
+  To do that easily, it's best to ask Homebrew to give you the
+  location of the repository:
+
+  ```sh
+  $ cd $(brew --repo diffblue/cbmc)
+  ```
+
+* You can extract versions of CBMC previously available in `homebrew/core`
+  to the tap with the following instruction:
+
+  ```sh
+  $ brew extract cbmc diffblue/cbmc --version=<ver>
+  ```
+
+  For example `$ brew extract cbmc diffblue/cbmc --version=5.54.0` will
+  have as an end result a new file under `Formula/[email protected]` that will
+  contain the formula that we had submitted for that version of CBMC in the
+  `homebrew/core` repository.
+
+* If you want to edit a specific version formula, you can do that by issueing
+
+  ```sh
+  $ brew edit [email protected]
+  ```
+
+  with the appropriate version tag. This will open the formula on the default
+  editor in your system to allow you to make changes.
+
+  These changes are only going to be reflected locally - but you can `cd` to the
+  repository, commit and then push to the tap (this is allowed only for people
+  who have permission to push to the tap - mainly, the Diffblue open source team).
+
+## Notes
+
+* Bootstrapping the repository with `brew tap --new` created two github actions
+  `.github/workflows/publish.yml` and `.github/workflows/tests.yml` which we are
+  not using at the moment but could serve to make future automation easier.
+
+## Known Limitations
+
+* Different CBMC versions can co-exist in the same machine, but homebrew needs
+  a symbolic link to be established because of how it manages the `$PATH` and
+  installation directories for binaries.
+* If already have a version of CBMC from the tap installed, and you want to
+  install another version, then you need to take an extra step after installation
+  to setup the appropriate symlinks by using the `brew link` instruction:
+
+  ```sh
+  $ cbmc --version   # version installed by brew
+  5.54.0
+  $ brew install diffblue/cbmc/[email protected]
+  $ brew link --overwrite [email protected]
+  $ cbmc --version
+  5.55.0
+  ```