We reiterate that building professionals and energy modellers can download the latest TBD version directly from the Guide itself, or under releases, or via NREL's BCL (search for "bridging" or "rd2"). Those instead interested in exploring/tweaking the source code (cloned or forked versions of TBD) can follow the Windows or MacOS Ruby setup described in TBD's README.
The MacOS instructions below specifically target (older) Ruby v2.2.5 environments, needed for developing OpenStudio v2.9.1 measures - the most up-to-date version that remains compatible with SketchUp Make 2017. More recent OpenStudio versions (e.g. v3.6.1) can - to a large degree - safely translate older .osm files. Although TBD (and Topolys) are systematically tested against updated OpenStudio versions (v2.9.1 onwards), the following Ruby v2.2.5 setup is no longer tested or maintained. Nonetheless, it may be of some help for the more adventurous of you.
tested Catalina 10.15.4 up to Big Sur 11.4
OpenStudio v2.9.1 measures require Ruby v2.2.5, which is several iterations behind the default Ruby v2.6 version available on any recently-purchased Mac. Although it is common to develop/test using more than one Ruby version, some effort is nonetheless required for older vintages: v2.2.5 is no longer officially supported, it requires the deprecated OpenSSL-1.0 (not 1.1), etc. To help Mac users (and potentially Linux users as well), the following steps are recommended (although architecture-specific tweaks may be required).
From a Terminal, install Homebrew - nice for package distribution and management. With a few tweaks, it will handle most package downloads, dependencies, etc. Using Homebrew, install OpenSSL-1.0, and then rbenv (which allows users to manage multiple Ruby versions). One way of doing it:
brew install rbenv/tap/openssl@1.0
By tapping, Homebrew provides a way to access third-party repositories that are no longer officially supported by Homebrew, like Ruby v2.2.5 and OpenSSL-1.0. The above instruction tells Homebrew to install compatible versions of OpenSSL-1.0 with rbenv (e.g. 1.0.2t, 1.0.2u).
Next, ensure that Homebrew and rbenv use OpenSSL-1.0 for future, local Ruby development. Edit (or create) a user’s local ~/.zshrc file (instructions here are provided for zsh, the default macOS Terminal shell interface - bash users: adapt!), by pasting-in the following:
eval "$(rbenv init - zsh)"
export PATH="/usr/local/opt/openssl@1.0/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/openssl@1.0/lib"
export CPPFLAGS="-I/usr/local/opt/openssl@1.0/include"
export PKG_CONFIG_PATH="/usr/local/opt/openssl@1.0/lib/pkgconfig"
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.0)"
There’s probably more there than necessary, but it should do the trick for the next few steps, and/or for future work. Quit the Terminal and start a new one, or simply source the zshrc file:
source ~/.zshrc
Make sure the right OpenSSL version is recognized, and then instruct Homebrew to switch over to it:
openssl version
brew switch openssl 1.0.2t
… or whatever Openssl 1.0 version was installed, e.g. 1.0.2u. Then install ruby-build, rbenv and finally Ruby v2.2.5:
brew install ruby-build
brew install rbenv
rbenv install 2.2.5
Install a compatible version of bundler, great for managing Ruby gems and dependencies:
gem install bundler -v 1.17.3
In some cases, (temporarily) switching over to an insecure http connection to rubygems.org (instead of the default https) may be required:
gem source -r https://rubygems.org/
gem source -a http://rubygems.org/
gem install bundler -v 1.17.3
gem source -r http://rubygems.org/
gem source -a https://rubygems.org/
In the Terminal, check the Ruby version:
ruby -v
... should still report the current Ruby version used by macOS (e.g. system or 2.6). To ensure Ruby v2.2.5 is used for developing OpenStudio v2.9.1-compatible measures, instruct rbenv to use Ruby v2.2.5 locally within a user’s chosen directory (e.g. "sandbox291"):
mkdir ~/Documents/sandbox291
cd ~/Documents/sandbox291
rbenv local 2.2.5
ruby -v
… should now report 2.2.5 as the local Ruby version, to be used by default for anything under the "sandbox291" directory tree. To ensure both Ruby versions are operational and safe, run the following checkup twice - once from a user’s home (or ~/), then from within e.g., "sandbox291":
cd ~/
ruby -ropen-uri -e 'eval open("https://git.io/vQhWq").read'
cd ~/Documents/sandbox291
ruby -ropen-uri -e 'eval open("https://git.io/vQhWq").read'
If successful, one should get a Hooray! from both Ruby versions confirming valid communication with Rubygems, yet with their specific RubyGems and OpenSSL versions, as well as their own SSL certificates.
Install OpenStudio v2.9.1.
Then create the file ~/.rbenv/versions/2.2.5/lib/ruby/site_ruby/openstudio.rb, and edit it so it points to your new OpenStudio installation:
require '/Applications/OpenStudio-2.9.1/Ruby/openstudio.rb'
Verify your local OpenStudio and Ruby configuration:
cd ~/Documents/sandbox291
ruby -e "require 'openstudio'" -e "puts OpenStudio::Model::Model.new"
Install the latest version of git (e.g. through Homebrew), and git clone the TBD measure under e.g., "sandbox291".
Run the basic tests to ensure the measure operates as expected.