diff --git a/README.md b/README.md index c9408309dfd..50aff58fb1e 100644 --- a/README.md +++ b/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 =========== diff --git a/doc/ADR/README.md b/doc/ADR/README.md index 87f319852d3..56976c3c294 100644 --- a/doc/ADR/README.md +++ b/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) diff --git a/doc/ADR/homebrew_tap.md b/doc/ADR/homebrew_tap.md new file mode 100644 index 00000000000..ebd34ff3265 --- /dev/null +++ b/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/cbmc@5.54.0 + ``` + +* To remove the version of CBMC installed you need to issue + + ```sh + $ brew remove diffblue/cbmc/cbmc@5.54.0 + ``` + +* 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 /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= + ``` + + For example `$ brew extract cbmc diffblue/cbmc --version=5.54.0` will + have as an end result a new file under `Formula/cbmc@5.54.0.rb` 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 cbmc@5.54.0 + ``` + + 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/cbmc@5.55.0 + $ brew link --overwrite cbmc@5.55.0 + $ cbmc --version + 5.55.0 + ```