developers-guide-osx.md

Metabase OS X App

NOTE: These instructions are only for packaging a built Metabase uberjar into Metabase.app. They are not useful if your goal is to work on Metabase itself; for development, please see our developers' guide.

Prereqs

1. Install XCode.

2. Run ./bin/build to build the latest version of the uberjar.

3. Update Perl. I'm not sure these steps are actually needed, so feel free to try skipping it and come back to it if it fails:

     # Upgrade Perl
     brew install perl
     
     # Add new version of perl to your $PATH
     # (replace "5.24.0_1" below with whatever version you installed)
     echo 'export PATH="/usr/local/Cellar/perl/5.24.0_1/bin:$PATH"' >> ~/.bash_profile
     source ~/.bash_profile
     
     # Double-check that we're using the newer version of CPAN
     # (If this is your first time running CPAN, use the default config settings when prompted)
     cpan --version # You should see a line like "running under Perl version 5.24.0."

4. Next, you'll need to run the following commands before building the app:

     # Fetch and initialize git submodule
     git submodule update --init
     
     # Install libcurl (needed by WWW::Curl::Simple (I think))
     brew install curl && brew link curl --force
     
     # The new version of LLVM is snippy so have CPAN pass compiler flags to fix errors
     # (Make sure this file exists first. If you didn't upgrade Perl in the step above, 
     # it might be in a different location; perhaps called "Config.pm". 
     # You may need to run "cpan" (no arguments) to generate an appropriate initial config. 
     # As above, you can go with the defaults).
     sed -i '' -e "s/'make_arg' => q\[\]/'make_arg' => q\[CCFLAGS=\"-Wno-return-type\"\]/" ~/.cpan/CPAN/MyConfig.pm
   
     # Install Perl modules used by ./bin/osx-setup and ./bin/osx-release
     # You may have to run this as sudo if you didn't upgrade perl as described in step above
     cpan install File::Copy::Recursive JSON Readonly String::Util Text::Caml WWW::Curl::Simple
     
     # Copy JRE and uberjar
     ./bin/osx-setup

./bin/osx-setup will build run commands to build the uberjar for you if needed. Run ./bin/osx-setup again at any time in the future to copy the latest version of the uberjar into the project.

(If the script fails near the end, you can just copy the JARs in question to OSX/Resources/metabase.jar and OSX/Resources/reset-password.jar.)

Releasing

A handy Perl script called ./bin/osx-release takes care of all of the details for you. Before you run it for the first time, you'll need to set up a few additional things:

# Install aws command-line client (if needed)
brew install awscli

# Configure AWS Credentials
# You'll need credentials that give you permission to write the metabase-osx-releases S3 bucket.
# You just need the access key ID and secret key; use the defaults for locale and other options.
aws configure --profile metabase

# Copy & Edit Config file. Alternative ask Cam for a copy of his
cp bin/config.json.template bin/config.json
emacs bin/config.json

# Obtain a copy of the private key used for signing the app (ask Cam)
# and put a copy of it at ./dsa_priv.pem
cp /path/to/private/key.pem OSX/dsa_priv.pem

You'll probably also want an Apple Developer ID Application Certificate in your computer's keychain. You'll need to generate a Certificate Signing Request from Keychain Access, and have Sameer go to the Apple Developer Site and generate one for you, then load the file on your computer.

After that, you are good to go:

# Bundle entire app, and upload to s3
./bin/osx-release