This document will guide you through the steps necessary to install the Generic Genome Browser (GBrowse) on a stock Mac OS X system.
The minimum suggested hardware is:
Mac OS X.2 (Jaguar or above)
500 Mhz G4 or higher
512 MB RAM
1 gigabyte free disk space (more depending on database size)
You have three (3!) options for installing GBrowse on OS X.
1. As a downloadable package
2. Using the build scripts located in the contrib directory
3. Manually, by following the steps in this document
GBrowse is a large and complicated set of software components. Have a look at the software requirements listed below. There are many dependencies which require custom configurations of the install process. It is strongly recommended that you use the package installer which has already resolved many of these difficulties, ensuring that all components work together appropriately.
To install the Package, simply double click on it and follow the included documentation. The package also includes an installer for the MySQL database.
The package installer will:
1. Install all required libraries
2. (Optionally) install the MySQL database
3. Install GBrowse
4. Configure your system for GBrowse, including building a
sample database
Once installed, you may wish to read the sections on ``Populating the database'' below.
GBrowse is distributed with scripts that automate the fetching and building of GBrowse and all of its software dependencies. These scripts are locate in contrib/install_macosx.
For example, to build GBrowse on Mac OS X,
% cd contrib/install_macosx
% make libraries (wait and wait and wait)
% make gbrowse
See the README in contrib/macosx_install for additional details.
Note: Throughout this document, commands to be typed at the command line by the root user begin with a ``$''. Those requiring a non-privileged user begin with a ``%''. When lines to be typed at the command line are too long, they are broken by a backslash (\).
This document primarily deals with a Genome Browser installation that does not rely on Fink. I think that it introduces to much of a ``black-box'' element. In the end, I think it is far easier to build and configure everything yourself in standard unix paths. When something breaks, it's far easier to trouble shoot things that you yourself have built.
You will need the following software packages (the specific versions refered to have been tested for this installation document):
http://www.apple.com/developer
http://www.apple.com/macosx/x11/
http://www.mysql.com
http://www.perl.org
1. Digest::MD5 2.16 or higher
2. GD 2.06 or higher
3. Storable 1.013 or higher
4. DBI 1.19 or higher
5. DBD::mysql 2.0416 or higher
6. Text::Shellwords
7. IO::String
The following are optional
1. XML::Twig 3.04 or higher
2. XML::Dom 1.34 or higher
3. XML::Writer 0.4 or higher
4. XML::Parser 2.30 or higher
5. LWP 5.53 or higher
If these modules are present, the ``Sequence Dumper'' plugin will be able to produce GAME and BSML output. They can be downloaded from CPAN. The LWP module enables loading of remote 3rd party annotations.
1. zlib 1.14 or higher
2. libjpeg 6b or higher
3. libpng 1.25 or higher
4. libgd 2.0.15 or higher
5. expat 1.95.6 or higher
http://www.bioperl.org/
http://www.gmod.org/
Apple has made this incredibly easy with a downloadable package. X11 can also be installed via Fink, but this will not be discussed here. Furthermore, the Apple installation of X11 runs side-by-side with the Mac OS in windows that look and behave exactly like standard Mac OS windows, and is optimized for the graphical capabilities of Mac OS X. Thus, you can run unix applications side-by-side Mac applications!
Once installed, X11 also opens up lots of other useful options for your system. For example, you can easily install the preeminent text editor Xemacs via fink.
X11 can be installed in a variety of ways. This document only describes installations with Apple's X11 package because it is the fastest and easiest way to install X.
NOTE: X11 will come preinstalled with OS X.3 and greater.
Fetch the Apple X11 and X11 SDK installer packages.
http://www.apple.com/macosx/x11/download
The link to the SDK is a little obscure - look in the bottom right-hand corner. First intall the X11 package, followed by the X11 SDK by double clicking each package icon and following the onscreen instructions.
User and group management under Mac OS X is handled by the NetInfo Manager. I'm going to bypass the GUI, instead adding the appropriate users and groups through the command line. The following commands should be run as root (or sudo):
Important Note: These examples assume that the specific user and group IDs are not yet assigned on your system. Change these values accordingly if they are.
This example uses:
uid gid
mysql 2001 2001
The mysql user:
$ niutil -create / /users/mysql $ niutil -createprop / /users/mysql uid 2001 $ niutil -createprop / /users/mysql gid 2001 $ niutil -createprop / /users/mysql name mysql $ niutil -createprop / /users/mysql passwd * $ niutil -createprop / /users/mysql realname mysql $ niutil -createprop / /users/mysql _writers_passwd root $ niutil -createprop / /users/mysql change 0 $ niutil -createprop / /users/mysql home /usr/local/mysql $ niutil -createprop / /users/mysql shell /dev/null
The mysql group:
$ niutil -create / /groups/mysql $ niutil -createprop / /groups/mysql gid 2001 $ niutil -createprop / /groups/mysql passwd *
Note that the mysql user's home directory was set to /usr/local/mysql, a directory that will be created during the installation of MySQL.
% curl -O ftp://ftp.orst.edu/pub/mysql/Downloads/MySQL-4.0/mysql-4.0.13.tar.gz
% gnutar -zxf mysql-4.0.12.tar.gz
% cd mysql-4.0.12
% ./configure --prefix=/usr/local/mysql \
--with-unix-socket-path=/usr/local/mysql/run/mysql_socket \
--with-mysqld-user=mysql \
--with-comment
% make
% sudo make install
% sudo mkdir /usr/local/mysql/run
% sudo /usr/local/mysql/bin/mysql_install_db --force # create var/ for DBs
% sudo chown -R mysql /usr/local/mysql/var /usr/local/mysql/run
% sudo chgrp -R mysql /usr/local/mysql
http://www.mysql.com/downloads/
Find the ``standard'' release in pkg/dmg form and download it from a nearby mirror. Double click the .dmg file and follow the typical installer instructions. The package places everything in standard paths (ie the mysql.sock is found in /etc/).
% sudo chown -R mysql /usr/local/mysql/data
% sudo chgrp -R mysql /usr/local/mysql
% cd /usr/local/mysql
% sudo ./configure # installs the appropriate databases
% sudo /usr/local/mysql/bin/mysqld_safe --user=mysql &
OR (for Fink installs):
% sudo /sw/bin/mysqld_safe &
% mysqladmin -u root password 'new_password'
Install jpegsrc and libpng
% curl -O ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz % gnutar -xzf jpegsrc.v6b.tar.gz % pushd jpeg-6b/ % ./configure % make % sudo make install mandir=/usr/local/share/man % sudo make install-lib % sudo ranlib /usr/local/lib/libjpeg.a % popd
Now you need to compile the libpng code. This allows you to manipulate PNG files.
% curl -O http://www.libpng.org/pub/png/src/libpng-1.2.5.tar.gz % gnutar -xzf libpng-1.2.5.tar.gz % pushd libpng-1.2.5/ % cp scripts/makefile.darwin makefile % make ZLIBINC="/usr/lib" ZLIBLIB="/usr/lib" % sudo make install % sudo ranlib /usr/local/lib/libpng.a % popd
% curl -O http://www.boutell.com/gd/http/gd-2.0.15.tar.gz
% gnutar -zxf gd-2.0.15.tar.gz
% pushd gd-2.0.15
% ./configure CPPFLAGS=-I/usr/X11R6/include/freetype2 \
--prefix=/usr/local --mandir=/usr/local/man \
--bindir=/usr/local/bin --with-freetype=/usr/X11R6/lib \
--inludedir=/usr/local/include
% make
% sudo make install
% popd
% curl -O http://stein.cshl.org/WWW/software/GD/GD.pm.tar.gz % gnutar xvfz GD-2.06.tar.gz % pushd GD-2.06/ % perl Makefile.PL % make % make test % sudo make install % popd
eg: % sudo perl -MCPAN -e shell
cpan> install Bundle::CPAN
Specific instructions for those that cannot be installed in this manner are provided below.
Many modules listed here are prerequisites for other components (primarily BioPerl). Only those marked with an * are required by GBrowse proper.
Module: Install By:
*1. Bundle::LWP CPAN
(installs a variety
of required modules)
*2. GD See above
*3. Storable CPAN
*4. DBI CPAN
*5. DBD::mysql CPAN
6. Text::Shellwords CPAN
7. IO::String CPAN
8. IO::Scalar CPAN
9. File::Temp CPAN
10. Text::Balanced CPAN
11. Parse::RecDescent CPAN
12. Bundle::Bioperl CPAN
DBD::mysql looks for libmysqlclient.dylib in /usr/local/mysql/lib dyld looks for it in /usr/local/mysql/lib/mysql/.
We remedy this conflict in the Makefile
# Fetch DBD-mysql-2.9002 from CPAN
% gnutar xvfz DBD-mysql-2.9002
% cd DBD-mysql-2.9002/
% perl Makefile.PL --cflags=-I'/usr/local/mysql/include' \
--libs="-L/usr/local/mysql/lib -lmysqlclient -lz -lm"
% make
% make test
$ sudo make install
The following modules are optional. If these modules are present, the ``Sequence Dumper'' plugin will be able to produce GAME and BSML output. The LWP module enables loading of remote 3rd party annotations.
Optional Modules:
1. XML::Parser 2.30 or higher
2. XML::Twig 3.04 or higher
3. XML::Dom 1.34 or higher
4. XML::Writer 0.4 or higher
5. XML::Parser::PerlSAX
curl -O http://umn.dl.sourceforge.net/sourceforge/expat/expat-1.95.6.tar.gz gnutar -zxf expat-1.95.6.tar.gz pushd expat-1.95.6/ ./configure make make install popd
% ./configure
% make
% sudo make install
After downloading and untarring XML::Parser from CPAN... % cd XML-Parser-2.31 % perl Makefile.PL EXPATLIB=/usr/local/lib EXPATINCPATH=/usr/local/include % make % make test % sudo make install
The Generic Genome Browser is a CGI script and some Perl modules that use Bio::DB::GFF and Bio::Graphics to create the navigable graphical displays of genomic data. But you know that already, or you wanted have made it this far, no? GBrowse lives at www.gmod.org. Download and unpack the latest version and run the following incantation to install it in the default locations for Apache.
% perl Makefile.PL HTDOCS=/Library/WebServer/Documents
CGIBIN=/Library/WebServer/CGI-Executables
CONF=/etc/httpd
% make
% sudo make install
Here I am using the default Sites folder to store the gbrowse-specific files.
Please see the similarly titled section in the main INSTALL document.
If you followed all examples in this document, you are ready to start using GBrowse. If you placed the GBrowse files in other paths, you need to let Apache know where they are. Specifically, this may required modifying the DocumentRoot, adding a ScriptAlias, or creating a VirtualHost. See the Apache documentation for more information.
You can start Apache by:
% sudo /usr/sbin/apachectl start
You should now be able to browse the yeast genome. Type the following URL into your favorite browser:
http://127.0.0.1/cgi-bin/gbrowse?source=yeast
This will display the genome browser instructions and a search field. Type in ``III'' to start searching chromosome III, or search for ``glucose'' to find a bunch of genes that are involved in glucose metabolism.
Todd W. Harris (harris@cshl.org) Please direct all questions, comments and bug reports relating to this documentation or the Installer package to me.
GBrowse was written largely by Lincoln Stein (lstein@cshl.org), with contributions by members of the Generic Model Organism Database (GMOD) community (http://www.gmod.org/).
You can read more about GBrowse in:
Stein LD, Mungall C, Shu S, Caudy M, Mangone M, Day A, Nickerson E, Stajich JE, Harris TW, Arva A, Lewis S.
The generic genome browser: a building block for a model organism system database. Genome Res. 2002 Oct;12(10):1599-610. http://www.genome.org/cgi/content/full/12/10/1599
Material in this document is copyright 2001-2003 by the Cold Spring Harbor Laboratory. This information is provided ``AS-IS'' without any warranty, expressed or implied.
$Id: INSTALL.MacOSX.pod,v 1.3 2003/12/01 18:15:08 scottcain Exp $