Revision as of 14:10, 27 October 2010

GBrowse runs well on both PowerPC and Intel Macs running OS X. These instructions describe how to install GBrowse on these platforms.

Note: One of the 2009 security updates from Apple caused problems for Perl, which affect cpan and installation of Perl packages. See: Fixing Perl on OSX

Prerequisites

You MUST have the Mac OS developer tools installed in order to install GBrowse on a Mac, since make is required. See step 1 of The Manual Way section below for more information.

GBrowse has a number of prerequisites, including BioPerl, GD (which requires libgd), and the MySQL database. You can install these prerequisites using the Fink precompiled binary package manager, or from source code.

If you are using MySQL databases, GBrowse also requires the Perl modules to talk to MySQL, DBI and DBD::mysql, which are often not present in the Perl installations on new Macs. These can be installed using CPAN. As of 8-1-2007, there are some problems with the CPAN installers for mysql on the Mac.

The Fink Way

1. Make sure you have installed the most recent version of Fink,available from http://fink.sourceforge.net.
2. Open up a command window, and install the following Fink packages:

  % fink install mysql  (optional, only if you want to to run a mysql backend)
  % fink install gd2 gd2-bin

You can also get a Mac installer for MySQL.

If you install mysql via fink, you will probably want to make it an application that starts when the machine boots. To do this, you can execute the command:

  % sudo daemonic enable mysql

which creates a startup script for mysql in /Library/StartupItems/. Once daemonic has been run, you can also use the startup scripts to start mysql on the command line (with some fiddling with the daemonic script, stop and restart options can be added as well):

  % sudo /Library/StartupItems/daemonic-mysql/daemonic-mysql start

Also, if you use fink to install any perl modules (for instance, fink install dbi-pm586 will install DBI.pm), you should modify your Apache configuration file, /etc/httpd/httpd.conf (Note, in Mac OSX 10.5 Leopard the file is located at /etc/apache2/httpd.conf). In that file, find and uncomment (that is, remove the '#' symbols) these two lines:

  #LoadModule env_module         libexec/httpd/mod_env.so
...
  #AddModule mod_env.c

and add this line near the bottom of the file:

  #added to allow for fink installed perl libs to be found
  SetEnv PERL5LIB /sw/lib/perl5:/sw/lib/perl5/darwin

Now restart the webserver either via the system preferences panel for network services, or via this command:

  sudo /System/Library/StartupItems/Apache/Apache restart

You do not need to install BioPerl, GD, or any other Perl packages using fink. Go directly to Installing GBrowse using the net installer. In case of error you can use uninstaller

The Manual Way

1. Make sure you have installed Mac OS X Developer tools that come on the distribution CD. Include X11 and the X11 SDK in the tools you install. To confirm that you have the tools, open a command window and type:

      % which gcc
      % which autoconf
      % which xmkmf
      % which pkg-config

If any of these commands returns with the error message "command not found," then you should (re)install the developer tools.

2. Install MySQL (optional; only if you want to run a mysql backend)

Go to http://www.mysql.org/downloads/mysql/5.0.html#macosx-dmg, download and run the appropriate OSX installer for your version of the operating system. Note that there are separate installers for OS X versions 10.3 and upward on PowerPC 32-bit, 64-bit and Intel platforms. You may need to take care here. Joan Pontius reports that you must use the 32-bit MySQL server and DBD::mysql version 2.9007 in order for the Perl that is preinstalled on MacOS X systems to work nicely with MySQL. You can get the correct DBD::mysql version at CPAN.

3. Install libgd

This is where many people get stuck because MacOSX is ships with an older version of libgd that does not work properly with GBrowse. To add to the confusion, OSX 10.3 and earlier has older developer tools that can't build the new libgd correctly.

Worry not; just follow the recipe.

1. Make sure your PATH environment variable includes /usr/local/bin by running the command:

      % echo $PATH

If you do not see </tt>/usr/local/bin</tt> listed, either create or edit a file called .bash_login in your home folder (note the leading ".", which hides this file from directory listings), and add the following line to the bottom:

      export PATH="/usr/local/bin:$PATH"

2. Make sure that you have at least version 2.58 of the autoconf tool installed. Run the command:

      % autoconf -V

This will print out the version number. It must be 2.58 or higher. If the version is too low, then upgrade autoconf like this:

Download version 2.58 or higher from http://ftp.gnu.org/gnu/autoconf/. It's best to use 2.58 because it is known to work.

Unpack autoconf, enter the distribution directory and type:

          % ./configure --prefix=/usr
          % make
          % sudo make install

3. Install libpng

Get the latest libpng from libpng.org. Look for the version "with config script."

Unpack libpng, enter the distribution directory and type:

          % ./configure
          % make
          % sudo make install

4. Install libgd

Get the latest libgd from http://www.libgd.org.

Unpack libgd, enter the distribution directory and type:

          % ./configure
          % make
          % sudo make install

If "make" fails with errors about not being able to compile gdft.c, then reconfigure with the following commands:

          % ./configure --without-fontconfig --without-freetype
          % make
          % sudo make install

Do not try to fix this problem by reinstalling freetype unless you are very brave; you will likely to make things worse. Freetype support is not needed for GBrowse.

Installing GBrowse using the net installer

Whether you installed the non-Perl prerequisites with Fink or manually, you will now use the GBrowse net installer to install BioPerl, GD and other perl-based prerequisites. You will need a working Internet connection for this step.

Download the gbrowse_netinstall.pl script from the GBrowse distribution. Run the following command as the root user or using "sudo":

  % perl gbrowse_netinstall.pl

See the main install page for a description of command line options for the netinstall script.

This will install the correct versions of GD, BioPerl, and all dependencies. During the process you will be asked to respond to various questions. It is generally safe to choose the defaults with one major exception: if you installed libgd with fink (ie, gd2), you need to answer the question about the location of libgd with '/sw/lib' instead of the default.

If this installer fails, it may be because the perl module LWP::Simple is not present. To install it, execute the command:

  % sudo cpan
  cpan> install LWP::Simple

and then rerun the GBrowse net install script.

Activate Apache

You may need to turn on the local web server if it isn't activated already:

    Apple Menu -> System Preferences ->  Sharing.
    Activate "Personal Web Sharing".

You may also wish to adjust your firewall settings to control access to your machine's web server from the Internet.

Test the browser

Open http://localhost/gbrowse and click the link for the example yeast chromosome 1 database.

Install Perl MySQL driver

Optional; only if you want to run the Mysql backend

If you have Mysql running and wish to take advantage of the GBrowse Mysql interface, then you will need to install the Perl DBD::mysql driver.

From the command line, type:

 % perl -MCPAN -e 'install DBD::mysql'

If you get a lot of errors about not having read/write privileges on the test database, download the DBD::mysql package from CPAN, unpack it, and follow the directions for building it manually.

There is one other issue to take care of. The bp_bulk_load_gff.pl file, which is used to load gff files into a mysql database is located in /usr/local/bin/. The script uses /usr/tmp as the temporary directory; but this doesn't exist on the Mac. Edit line 347 of bp_bulk_load_gff.pl to look like this:

 my $tmpdir = $ENV{TMPDIR} || $ENV{TMP} || '/tmp';

AUTHORS

Lincoln D. Stein <steinl@cshl.edu> 20:24, 16 April 2007 (EDT) Adapted from instructions contributed by Yair Benita <y.benita@wanadoo.nl>.

Mac How]