Installing Perl, DBD::mysql and Ensembl on OSX

by ·1 Comment

Over the past few months a number of users have asked us how to install Ensembl and its dependencies on OSX. Over the past 4 years I have had to do this quite a number of times and thought it best to share my personal best practice. There are alternatives to this methodology involving supplementing the stock OSX Perl with extra libraries or using ActiveState for OSX. I recommend neither method. Apple never developed a package management tool that works well with Perl libraries and so upgrades carry a level of risk. As for ActiveState they do not currently support DBD::mysql on OSX. Instead we will install a new version of Perl using Perlbrew; a Perl installation management tool.

This guide will require admin rights on your mac and assumes some understanding of the terminal. If you do not feel confident enough then try using our Virtual Machine instead.

Pre-Flight Checks

You must have Xcode and GCC installed on your mac. Check by running the following command and see if you get a response similar to the one pasted below

> gcc -v
Using built-in specs.
Target: i686-apple-darwin11
Configured with: /private/var/tmp/llvmgcc42/llvmgcc42-2336.11~182/src/configure --disable-checking --enable-werror --prefix=/Applications/Xcode.app/Contents/Developer/usr/llvm-gcc-4.2 --mandir=/share/man --enable-languages=c,objc,c++,obj-c++ --program-prefix=llvm- --program-transform-name=/^[cg][^.-]*$/s/$/-4.2/ --with-slibdir=/usr/lib --build=i686-apple-darwin11 --enable-llvm=/private/var/tmp/llvmgcc42/llvmgcc42-2336.11~182/dst-llvmCore/Developer/usr/local --program-prefix=i686-apple-darwin11- --host=x86_64-apple-darwin11 --target=i686-apple-darwin11 --with-gxx-include-dir=/usr/include/c++/4.2.1
Thread model: posix
gcc version 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2336.11.00)

Later versions of OSX (Mavericks 10.9) are intelligent enough to instal the GCC tools automatically once you have confirmed. If you are on an earlier version of OSX and do not get this prompt then following the instructions below (this will require admin privileges)

  1. Install Xcode from the Apple AppStore
  2. Run it Applications
  3. Install the command line utilities by clicking on Xcode in the menu
    • Preferences
    • Downloads
    • Click “Install” by the Command Line Tools section

Additional information (with screenshots) is available from this Stack Overflow answer.

Installing Perlbrew

Firstly you need to install Perlbrew. This will create a directory called perl5 in your home directory. It will also ask to add commands to your shell’s profile (either .bashrc, .cshrc or .bash_profile) to bring the perlbrew binary onto your path. To install use the following commands:

> curl -L http://install.perlbrew.pl | bash

# Add this to the end of your ~/.bash_profile
> echo 'source $HOME/perl5/perlbrew/etc/bashrc' >> ~/.bash_profile

Now install Perl 5.14.4 (you will have to wait a bit). The following command was run on a Mountain Lion installation (10.8.4). You must install a new version of Perl. Modifying the system version of Perl (including installing module updates) on OSX is a very bad idea and can cause unintentional side effects. To be safe always install your own version:

> perlbrew install -j 5 --as 5.14.4 \
--thread --64all -Duseshrplib perl-5.14.4

Fetching perl 5.14.4 as /Users/user/perl5/perlbrew/dists/perl-5.14.4.tar.bz2
Installing /Users/user/perl5/perlbrew/build/perl-5.14.4 into ~/perl5/perlbrew/perls/5.14.4

This could take a while. You can run the following command on another shell to track the status:

tail -f ~/perl5/perlbrew/build.perl-5.14.4.log

5.14.4 is successfully installed.

Later versions of OSX and Perl can sometimes fail during this compilation process citing issues with locale settings. Should you see this run the following command (stops any testing against the new Perl binary):

> perlbrew install --notest --as 5.14.4 --thread \
--64all -Duseshrplib perl-5.14.4

Now install cpanminus. This is our CPAN package manager and makes working with it a breeze.

> perlbrew install-cpanm

Now we will switch to using the new version of Perl by default and ensure that the switch worked.

> perlbrew switch 5.14.4
> perl -v | grep 'This is'
This is perl 5, version 14, subversion 4 (v5.14.4) built for darwin-thread-multi-2level

Installing MySQL Client Libraries

DBD::mysql requires access to libmysqlclient.18.dylib and the MySQL C headers to compile. MySQL’s Connector/C distribution ships with these files. However I have always found more success using a server installation and like having a personal MySQL server to develop against. This guide will only cover using a MySQL Server installation.

  1. Go to http://dev.mysql.com/downloads/mysql/
  2. Select a version compatible with your Mac
  3. I selected Mac OS X ver. 10.7 (x86,64bit), DMG archive MySQL Community Server 5.6.12. You may find a later version. Make sure to change all other commands accordingly
  4. Mount the DMG
  5. Install mysql-5.6.12-osx10.7-x86_64.pkg and double click the MySQL.prefPane
  6. Check you can start-up MySQL (required for DBD::mysql installation tests)
  7. Go to System Preferences > MySQL > Start MySQL Server
  8. Enter your system admin password

Installing core dependencies

Basic dependencies can be installed using the cpanm command. For core Ensembl that amounts to database bindings so lets bring in DBI.

> cpanm DBI

Should you wish to run any core test suites you will also need the following packages:

> cpanm Test::Differences Test::Exception Test::Perl::Critic

Installing DBD::mysql

Congratulations on getting this far. Now for the tricky bit. By default the required dynamic library is not available on OSX’s default search paths. You can solve by using one of the following 3 options. Once the library is available to OSX you can install DBD::mysql with the following command (ensure your MySQL server is running otherwise the library’s test suite will fail). I prefer to use the second option and symbolically link the library into /usr/lib but this does require admin rights.

> cpanm DBD::mysql

Option 1). Add MySQL’s lib directory onto the DYLD_LIBRARY_PATH

Works well for all command line terminals, does not require admin but will not work if you’re going to use a GUI based application to run Ensembl scripts.

> export DYLD_LIBRARY_PATH=/usr/local/mysql/lib/:$DYLD_LIBRARY_PATH

Option 2). Symbolically link the required library into /usr/lib

Works well for all applications but requires admin rights to create the symbolic link in /usr/lib

> sudo ln -s /usr/local/mysql/lib/libmysqlclient.18.dylib /usr/lib/libmysqlclient.18.dylib

Option 3). Add the library to install_name_tool

A more official OSX way of doing it but will require re-updating the library whenever you upgrade your MySQL installation. Also requires admin rights.

> sudo install_name_tool -id /usr/local/mysql-5.6.12-osx10.7-x86_64/lib/libmysqlclient.18.dylib /usr/local/mysql-5.6.12-osx10.7-x86_64/lib/libmysqlclient.18.dylib

Installing Ensembl

Nearly there. My best advice is to follow the installation instructions hosted on the Ensembl website. Once finished you should verify the installation is good. Ensembl ships with a program called ping_ensembl.pl. We will use this to check we can connect to Ensembl’s UK based MySQL servers and can find the species human.

> perl ~/src/ensembl/misc-scripts/ping_ensembl.pl
Installation is good. Connection to Ensembl works and you can query the human core database

The script will also try to diagnose any problems with missing dependencies. Remember should you need to install any additional dependencies use cpanm.

Congratulations

If you made it this far you should have a fully functional installation of Perl able to query Ensembl. More information on the API is available from our website along with tutorials covering the core, variation, comparative genomics and regulation APIs.

Should you have any issues then please do not hesitate to contact Helpdesk or follow our debug my Ensembl installation guide.