Guide News Images In Literature Software Documentation Presentations Support Circos Online

get started best practices tutorials course samples download

Circos > Documentation > Tutorials > Configuration > Perl And Modules

20 imperatives of information design — BioVis 2012

Configuration Quick Start Ideograms Highlights Ticks And Labels Links 2D Tracks Scaling Recipes Image Maps Utilities Reference

Unix Vs Windows Distribution And Installation Configuration Files Data Files Perl And Modules Runtime Parameters Debugging Errors Png Output Svg Output

Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.
If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.
Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong from the Points of View series.

0 — Directory Structure and Configuration

5. Perl and Modules

If you are having trouble with installation of Perl or modules, use online resources that explain the details of how to download Perl, get it working (Linux, Mac OS X, Windows [win32.perl.org wiki, ActiveState, Strawberry]), and how to install modules (UNIX, Windows). If you're still stuck, post your questions to the Circos group.

Need to install modules? See A Guide to Installing Modules and its corresponding tutorial for Windows users.

Having trouble with libgd and GD? See the Perl Monks libgd/GD Tutorial or Paulo Nuin's Installing Circos on Mac OS X. There are some useful threads in the Google Group about this.

Need to run Bash shell batch files in Windows? You'll need to install a UNIX command line shell, like Cygwin.

Stumped by an error? A good strategy is to Google the error message (e.g. mkdir /usr/local/share/man: permission denied) to find the solution.

Want to learn more about Perl? Try learn.perl.org.

To run Circos, you need Perl. Perl, like languages such as Python or Ruby, is an interpreted language. This means that you do not need to compile the Circos code — it is read in by the Perl executable (that ships with, or has been installed, for your operating system), which in turn interprets it, compiles it and runs the code.

Perl Modules

Perl modules are third-party code that adds functionality to the core language. Your installation of Perl will include core modules. In addition to these, you'll need to install the following modules to run Circos.

Config::General (v2.50 or later)
Font::TTF
GD
List::MoreUtils
Math::Bezier
Math::Round
Math::VecStat
Params::Validate
Readonly
Regexp::Common
Set::IntSpan (v1.16 or later)
Text::Format

On UNIX, to list all the required modules (many in the list will be core modules, and therefore already part of the Perl distribution), run

# this script only works on UNIX, not Windows
> cd bin
> ./list.modules

and to test which ones you are missing,

# this script only works on UNIX, not Windows
> cd bin
> ./test.modules
ok   Carp
ok   Clone
ok   Config::General
ok   Cwd
ok   Data::Dumper
ok   Digest::MD5
ok   File::Basename
ok   File::Spec::Functions
ok   File::Temp
ok   FindBin
ok   Font::TTF::Font
ok   GD
ok   GD::Image
ok   GD::Polyline
ok   Getopt::Long
ok   IO::File
ok   List::MoreUtils
ok   List::Util
ok   Math::Bezier
ok   Math::BigFloat
ok   Math::Round
ok   Math::VecStat
ok   Memoize
ok   POSIX
ok   Params::Validate
ok   Pod::Usage
ok   Readonly
ok   Regexp::Common
ok   Set::IntSpan
ok   Storable
ok   Sys::Hostname
ok   Text::Balanced
ok   Text::Format
ok   Time::HiRes

Installing Modules on UNIX

To install these modules, use the CPAN module to quickly download, compile and install them. CPAN will follow dependencies and generally do the right thing. Windows users should use their Perl's installation package manager (see below).

> perl -MCPAN -e shell
...
cpan[1]>install Math::Bezier
...

If the process above fails, or you prefer to do it yourself, download each module from CPAN. Many module installation tutorials are already available.

Modules use either the Makefile.PL system, or the Build system. For purposes here, these are equivalent but require slightly different commands.

To install a module that uses the Makefile.PL system, such as Set::IntSpan.

# download module
> wget http://search.cpan.org/CPAN/authors/id/S/SW/SWMCD/Set-IntSpan-1.16.tar.gz
# unpack archive
> tar xvfz Set-IntSpan-1.16.tar.gz
> cd Set-IntSpan-1.16
# configure and compile
> perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Set::IntSpan
> make
cp IntSpan.pm blib/lib/Set/IntSpan.pm
Manifying blib/man3/Set::IntSpan.3
> make test
» make test
PERL_DL_NONLAZY=1 /home/martink/perl/5.10.0/bin/perl "-MExtUtils::Command::MM" 
   "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/binary.t .... ok       
t/bsearch.t ... ok       
...
t/spans.t ..... ok       
t/subclass.t .. ok     
t/unary.t ..... ok     
All tests successful.
Files=18, Tests=1931,  0 wallclock secs ( 0.28 usr  0.03 sys +  0.36 cusr  0.06 csys =  0.73 CPU)
Result: PASS
# install (keep in mind file permission requirements, as described below)
> make install

Modules like Params::Validate use the Build system and are installed as follows.

# download module
> wget http://search.cpan.org/CPAN/authors/id/D/DR/DROLSKY/Params-Validate-0.95.tar.gz
# unpack archive
> tar xvfz Params-Validate-0.95.tar.gz
> cd Params-Validate-0.95
# configure and compile
> perl Build.PL
Creating new 'MYMETA.yml' with configuration results
Creating new 'Build' script for 'Params-Validate' version '0.95'
> ./Build
Building Params-Validate
cc -Ic -I/home/martink/perl/5.10.0/lib/5.10.0/x86_64-linux/CORE -DXS_VERSION="0.95" 
   -DVERSION="0.95" -fPIC -c -fno-strict-aliasing -pipe -D_LARGEFILE_SOURCE 
   -D_FILE_OFFSET_BITS=64 -I/usr/include/gdbm -O2 -o lib/Params/Validate.o lib/Params/Validate.c
ExtUtils::Mkbootstrap::Mkbootstrap('blib/arch/auto/Params/Validate/Validate.bs')
cc -shared -O2 -o blib/arch/auto/Params/Validate/Validate.so lib/Params/Validate.o
> ./Build test
t/01-validate.t ............ ok     
t/02-noop.t ................ ok     
t/03-attribute.t ........... ok    
...
t/30-hashref-alteration.t .. ok   
t/kwalitee.t ............... skipped: This test is only run for the module author
t/pod-coverage.t ........... skipped: This test is only run for the module author
t/pod.t .................... skipped: This test is only run for the module author
All tests successful.
Files=32, Tests=497,  1 wallclock secs ( 0.10 usr  0.04 sys +  0.78 cusr  0.13 csys =  1.05 CPU)
Result: PASS
# install (keep in mind file permission requirements, as described below)
> ./Build install

Installing Modules on Mac OS X

CPAN should work seamlessly. Many users have difficulty with the GD module, which has numerous dependencies. Paulo Nuin has a nice blog entry that shows how he handled his Mac OS X Circos installation.

Installing Modules on Windows

Both Strawberry Perl and ActiveState Perl have package managers that help you install, update and remove modules. Where possible, use the manager to install modules instead of the CPAN shell.

Errors

Missing modules

If you are missing a module, you'll see an error like the following when you run Circos.

Can't locate Config/General.pm in @INC (@INC contains: /usr/lib/perl5/5.8.0/i386-linux
-thread-multi/usr/lib/perl5/5.8.0/usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-multi
/usr/lib/perl5/site_perl/5.8.0 /usr/lib/perl5/site_perl/usr/lib/perl5/vendor_perl
/5.8.0/i386-linux-thread-multi /usr/lib/perl5/vendor_perl/5.8.0/usr/lib/perl5/vendor_
perl .) at ./bin/circos line 121.

In this case Perl is complaining that the module Config::General cannot be found. You'll need to install Config::General (see above).

On UNIX, use the bin/test.modules script (see above) to see which modules you are missing.

Permission errors

On UNIX systems, if during installation you obtain a file or directory creation permission error, you are likely attempting to write the module files into your system's perl install tree which is owned by root (administrative user).

...
Running make test
PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e"  
"test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/run....ok
All tests successful.
Files=1, Tests=68,  1 wallclock secs ( 0.27 cusr +  0.26 csys =  0.53  
CPU)
   /usr/bin/make test -- OK
Running make install
mkdir /usr/local/share/man: Permission denied at /System/Library/Perl/
5.8.8/ExtUtils/Install.pm line 112
make: *** [pure_site_install] Error 13
   /usr/bin/make install  -- NOT OK

Repeat the installation as root (administrator)

> sudo su
> perl -MCPAN -e shell
...

`make` on Mac OS X

If modules won't install because your system complains that it doesn't have make,

bash: make command not found

you need to install Xcode development tools, an optional component available on your Mac OS X DVD. Be aware that there have been reports of Xcode 4 causing problems with Perl.

To test whether you have make

> which make
/usr/bin/make

Sometimes an unsuccessful make can be due to an error during the compilation.

Could not make: Unknown error

If you know you have Xcode (which make confirms this, typically /usr/bin/make), install the module manually. For example, if Params::Validate was giving problems,

> wget http://search.cpan.org/CPAN/authors/id/D/DR/DROLSKY/Params-Validate-0.95.tar.gz
> tar xvfz Params-Validate-0.95.tar.gz
> cd Params-Validate-0.95
> ./Build
# note the build error in the next step
> Build make