Difference between revisions of "JBrowseDev/Installation"

From GMOD
Jump to: navigation, search
m (See also)
m (See also)
Line 98: Line 98:
 
=See also=
 
=See also=
  
* [[JBrowseDev/Current]]
+
* [[JBrowseDev/Current|Documentation Page for the Current Version of JBrowse]]
 
* [[JBrowse Tutorial|JBrowse Tutorial from the 2010 GMOD Summer School]]
 
* [[JBrowse Tutorial|JBrowse Tutorial from the 2010 GMOD Summer School]]
  

Revision as of 22:30, 29 July 2011

This pages describes the current installation procedure required to install JBrowse on Mac OS X or Linux operating systems.

Downloading JBrowse

A copy of the most recent version of JBrowse can be downloaded from the JBrowse project repository at GitHub. Alternatively, it can also be downloaded using git:

git clone git://github.com/jbrowse/jbrowse.git

If the prerequisites are met, JBrowse should work immediately. The configure script and makefile are only required for the use of wig-to-json.pl to add quantitative tracks to JBrowse.

Prerequisites

1. JBrowse requires Perl v5.10.0 or later. An installer can be downloaded from the Perl Home Page. If this does not work, you can download the source code and install perl through the command line.

If you had to download a new version of Perl, you will want this version to be used by default. First, find the path to the directory that contains the new perl executable. If you didn't specify this directory when you were installing perl, you should be able to find the default installation directory by looking at the documentation. Next, create (or open) the shell configuration file in your home directory:

pico $HOME/.bash_profile

Note: For Linux, the relevant startup configuration file might be '.bashrc' instead of '.bash_profile'. If you do not use bash, you will need to edit the configuration file(s) appropriate for your shell.

Insert this line into that file, substituting '<path to the newest version of perl>' with the path to the new perl executable:

export PATH=<path to the newest version of perl>:$PATH

Note: This is the command that is used in bash. Depending on your shell, you may have to use setenv instead of export.

Save this file, then close and reopen your terminal. To make sure that the newest version of perl is now being used by default, use this command:

perl --version

2. JBrowse must be unpacked into a directory that is served by Apache. Essentially, this means that the directory that JBrowse is installed in (placed in) must be accessible via your web browser. This is very simple to do on OS X. First, navigate to System Preferences > Sharing and make sure that Web Sharing is on. Then, move the JBrowse directory to your Sites folder. You should now be able to view JBrowse at the url:

localhost/~<your account name>/<name of JBrowse directory>

As an example, the url might look like:

localhost/~stephen/jbrowse-1.2.1

For Linux, the default directory served by Apache is normally '/var/www'.

3. JBrowse requires installation of a number of perl modules. This should be done through the Comprehensive Perl Archive Network (CPAN), a large repository for shared perl modules. CPAN has an associated shell program that will allow you to download and install JBrowse's dependencies.

To access this shell program, open up a terminal and type 'perl -MCPAN -e shell'. If you have never used cpan before, you will be prompted to configure CPAN. During the configuration process, you will be asked a series of questions about your preferences. If you do not know what an option means, you can usually use the provided default argument.

If you have sufficient privileges, reopen the CPAN shell as the root user by typing 'sudo perl -MCPAN -e shell' in a terminal. You will be prompted for the root password. Once you have opened the CPAN shell as root, install BioPerl by typing 'install CJFields/BioPerl-1.6.1.tar.gz'. CPAN will automatically install BioPerl on your computer. After this is complete, install the other dependencies in the same way. Here is a complete list of what you will need to download and install from CPAN:

  • CJFields/BioPerl-1.6.1.tar.gz
  • JSON
  • JSON::XS (optional, for speed)
  • Heap::Simple
  • Heap::Simple::Perl
  • Heap::Simple::XS
  • PerlIO::gzip
  • Devel::Size

Common Issues

Restricted Permissions

If you do not have administrator privileges, you will need to install the JBrowse dependencies locally, that is, for your account only. This should be straightforward for the perl installation (simply change the install location to one that you have read and write access to), but is a bit more involved for the CPAN-installed perl modules.

To reconfigure cpan, open the CPAN shell and type 'o conf init'. You will need to provide an answer to the "Parameters for the './Build' command?" prompt. One possible answer would be:

--extra-linker-flags -L<path to home directory>/local

This will cause all modules to be installed in a directory called 'local' that is in your home directory. Of critical importance is that your user account has read and write access to this directory.

There is one more change to be made. Perl needs to be aware of the new installation directory for your perl modules. This involves editing the PERL5LIB variable. Open your shell configuration file with a text editor, e.g. with the command:

pico $HOME/.bash_profile

Note: For Linux, the relevant startup configuration file might be '.bashrc' instead of '.bash_profile'. If you do not use bash, you will need to edit the configuration file(s) appropriate for your shell.

and insert the line:

export PERL5LIB=$PERL5LIB:<path to home directory>/local

Note: This is the command that is used in bash. Depending on your shell, you may have to use setenv instead of export.

Changes to the PERL5LIB variable will take effect in any new shell that you open. To check whether the PERL5LIB variable has been successfully changed, use the command:

echo $PERL5LIB

Missing Module or Loadable Object

You might encounter an error of the type:

Can't locate some/perl/module.pm in @INC (INC contains <list of paths>)

If you see this error, it normally means one of two things. Either (1) you have not installed the perl module, or (2) you have installed the perl module, but it is not in a directory where perl expects it to be. If the absolute path to the module's directory (try 'locate your/perl/module.pm') is not a member of the list of paths in @INC, you can either move the module and its associated files and directories to another directory that is a member of @INC, or you can add the module's current directory to @INC by appending its absolute path to the PERL5LIB variable in ~/.bash_profile (See the previous topic for instructions).

You might also encounter an error of this type:

Can't locate loadable object for some/perl/module.pm in @INC (INC contains <list of paths>)

If you encounter this error, it means that perl found the module it was looking for, but it didn't find all of the files that were associated with that module. This error often occurs when there is XS code that does not get compiled, or whose compiled object file is not in a directory that is visible to perl (i.e. in a directory that isn't listed in @INC). If you moved or copied the perl module and its associated files to a different directory, be sure that there aren't any object files that you missed. If you don't find any object files in the directory that you copied the perl module from, try reinstalling the module through the CPAN shell. Look carefully through the CPAN log, first for errors in the compilation of the XS code, and then for possible reasons for any errors (e.g. a missing library that cannot be installed through CPAN).

Installing Modules for an Older Version of Perl

It might be possible to type 'cpan' from your shell to open CPAN. However, it is recommended that you open CPAN using the perl interpreter ('perl -MCPAN -e shell'), because the shell associated with the 'cpan' command might be intended for a version of perl other than the version that you are using with JBrowse (e.g., it might install version 5.8.8 modules when the version of perl that you are actually using is 5.10.0). Modules for a different version of perl will be installed in the wrong library directory with respect to you current version of perl, and even if you move them to the correct directory, they might not be compatible with your current version of perl. If 'perl --version' and 'cpan --version' indicate the same perl version, it is fine to use 'cpan' to access the CPAN shell. Otherwise, use 'perl -MCPAN -e shell'.

See also

External Links