Circos > Documentation > Tutorials > Configuration > Perl And Modules
Loading
Circos at the EMBO NGS workshop in Tunis, Sept 15–25.

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, myself and invited authors from the Points of View series.

0 — Configuration and Installation

6. 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, Paulo Nuin's Installing Circos on Mac OS X, Wang's install zlib/libpng/jpeg/freetype/libgd/GD on Mavericks as well as my own guide for installation of libpng, freetype, libgd and GD on Mac OS X Mavericks. 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.

Checking for Perl

Checking for Perl on UNIX

For UNIX and Mac OS X users, Perl is likely already installed on your system, as part of the base installation.

To check this, run this command at the terminal

> which perl

If you have perl installed and the executable is in your PATH (it is unlikely that Perl is installed but not in your PATH, the which command will return something like

> which perl
/usr/bin/perl
# or perhaps
/usr/local/bin/perl

or some other location, depending on your installation. If the which command returns nothing, it's likely that you do not have Perl installed.

To check the version of installed Perl

> perl -v
This is perl, v5.10.0 built for ...

Anything earlier than 5.8 should be upgraded.

Circos will use the perl binary in your PATH. If you are on a UNIX system, whatever which returns

> which perl

will be the interpreter that is used.

managing multiple perl installations on UNIX

You can have installations of various versions of Perl, helpful if you want to test out a new version without disturbing production versions.

For example, I have Perl 5.8, 5.10, 5.14 and 5.18 installed in

~/perl/perl.5.8.7
~/perl/perl.5.10.0
~/perl/perl.5.14.2
~/perl/perl.5.18.1

To easily call any of these versions, I have symbolic links set up from ~/bin, which is in my PATH

~/bin/perl58  -> ~/perl/perl/5.8.7/bin/perl
~/bin/perl510 -> ~/perl/perl/5.10.0/bin/perl
~/bin/perl514 -> ~/perl/perl/5.14.2/bin/perl
~/bin/perl518 -> ~/perl/perl/5.18.1/bin/perl

For example,

# use Perl 5.10
> perl510 script.pl
# use Perl 5.14
> perl514 script.pl

My production Perl is 5.14.2, so

~/bin/perl -> ~/bin/perl514

which calls Perl 5.14 when I use the perl command.

# run the production version, Perl 5.14
> perl script.pl

If you are managing multiple versions of Perl, you'll need to install modules for each version of Perl you have installed. This is inconvenient but required because the modules compiled by one version may not be compatible with another.

Using the CPAN shell makes installation relatively painless. Make sure you call it with the right version!

# install with production version, Perl 5.14
> perl -MCPAN -e shell
...
cpan[1]> install Config::General

# install with 5.10
> perl510 -MCPAN -e shell
...
cpan[1]> install Config::General

Checking for Perl on Windows

If you are running Windows, it is unlikely that you have Perl installed. Perl installation is described in the Perl and Modules section.

To check the version of installed Perl,

C:> perl -v
This is perl, v5.10.0 built for ...

Installing Perl Modules

Even if you already have perl, chances are good that you are going to need a few additional modules to make Circos run. 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 likely need to install some modules, such as

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

To list all the required modules and check whether they are installed, use -modules.

> circos -modules
ok       1.26 Carp
ok       0.37 Clone
ok       2.50 Config::General
ok       3.33 Cwd
ok      2.145 Data::Dumper
ok       2.52 Digest::MD5
ok       2.76 File::Basename
ok       3.33 File::Spec::Functions
ok       0.22 File::Temp
ok       1.49 FindBin
ok       0.39 Font::TTF::Font
ok       2.43 GD
ok        0.2 GD::Polyline
ok       2.37 Getopt::Long
ok       1.14 IO::File
ok       0.33 List::MoreUtils
ok       1.38 List::Util
ok       0.01 Math::Bezier
ok       1.59 Math::BigFloat
ok       0.06 Math::Round
ok       0.08 Math::VecStat
ok    1.01_02 Memoize
ok       1.13 POSIX
ok       0.95 Params::Validate
ok       1.36 Pod::Usage
ok       1.03 Readonly
ok 2010010201 Regexp::Common
ok       2.49 SVG
ok       1.16 Set::IntSpan
ok     1.6607 Statistics::Basic
ok       2.30 Storable
ok       1.11 Sys::Hostname
ok       2.02 Text::Balanced
ok       0.53 Text::Format
ok     1.9725 Time::HiRes

Installing Perl 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 Perl 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 Perl 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.

Installing libpng, freetype, libgd and GD

About half of the support questions in the Google Group are about installing Perl's GD module, which is the interface to the libgd system graphics library.

The installation process is not robust because of dependencies and the possibility of their being different versions of these dependencies on your system. Below I show the process of installing GD on a new Mac OS Mavericks system (10.9.4).

Below I link to my local copies of the versions of each library that I installed. These are mature libraries and newer versions are likely to be minor bug releases. The exception is GD—I was unable to successfully compile v2.56 (boot_GD symbol warning which I could not fix). However v2.53 worked.

> tar xvfz libpng-1.6.14.tar.gz
> cd libpng-1.6.14
> ./configure —prefix=/usr/local
> make
> make install

> tar xvfz jpegsrc.v9.tar.gz
> cd jpeg-9
> ./configure —prefix=/usr/local
> make
> make install

> tar xvfz freetype-2.4.0.tar.gz
> cd freetype-2.4.0
> ./configure —prefix=/usr/local
> make
> make install

You should now have libraries in /usr/local/lib as we as some header files in /usr/local/include.

-rwxr-xr-x  1 root  wheel   650336 21 Nov 11:15 libfreetype.6.dylib
-rw-r--r--  1 root  wheel  3676456 21 Nov 11:15 libfreetype.a
lrwxr-xr-x  1 root  wheel       19 21 Nov 11:15 libfreetype.dylib -> libfreetype.6.dylib
-rwxr-xr-x  1 root  wheel      957 21 Nov 11:15 libfreetype.la
-rwxr-xr-x  1 root  wheel   275736 21 Nov 11:14 libjpeg.9.dylib
-rw-r--r--  1 root  wheel  1492952 21 Nov 11:14 libjpeg.a
lrwxr-xr-x  1 root  wheel       15 21 Nov 11:14 libjpeg.dylib -> libjpeg.9.dylib
-rwxr-xr-x  1 root  wheel      920 21 Nov 11:14 libjpeg.la
lrwxr-xr-x  1 root  wheel       10 21 Nov 11:13 libpng.a -> libpng16.a
lrwxr-xr-x  1 root  wheel       14 21 Nov 11:13 libpng.dylib -> libpng16.dylib
lrwxr-xr-x  1 root  wheel       11 21 Nov 11:13 libpng.la -> libpng16.la
-rwxr-xr-x  1 root  wheel   240580 21 Nov 11:13 libpng16.16.dylib
-rw-r--r--  1 root  wheel  1077240 21 Nov 11:13 libpng16.a
lrwxr-xr-x  1 root  wheel       17 21 Nov 11:13 libpng16.dylib -> libpng16.16.dylib
-rwxr-xr-x  1 root  wheel      924 21 Nov 11:13 libpng16.la
drwxr-xr-x  6 root  wheel      204 21 Nov 11:15 pkgconfig/

Now install libgd, linking to the libraries installed above

> tar xvfz libgd-2.1.0.tar.gz
> cd libgd-2.1.0
> ./configure --with-png=/usr/local --with-freetype=/usr/local --with-jpeg=/usr/local —prefix=/usr/local

…
** Configuration summary for libgd 2.1.0:

   Support for Zlib:                 yes
   Support for PNG library:          yes
   Support for JPEG library:         yes
   Support for VPX library:          no
   Support for TIFF library:         no
   Support for Freetype 2.x library: yes
   Support for Fontconfig library:   no
   Support for Xpm library:          no
   Support for pthreads:             yes
…

> make
> make install

You now have libgd in /usr/local/lib

-rwxr-xr-x  1 root  wheel   389372 19 Nov 14:47 libgd.3.dylib
-rw-r--r--  1 root  wheel  1217200 19 Nov 14:47 libgd.a
lrwxr-xr-x  1 root  wheel       13 19 Nov 14:47 libgd.dylib -> libgd.3.dylib
-rwxr-xr-x  1 root  wheel     1139 19 Nov 14:47 libgd.la

as well as some binaries in /usr/local/bin. In particular, you have /usr/local/bin/glib-config, which provides the configuration for your libgd installation

The --with-* parameters during the configure stage of gdlib installation sets the sources of the dependencies that will be build into gdlib. If you used a different -prefix in compiling these dependencies (see above), adjust these parameters accordingly. For example, if you compiled libpng with -prefix=/my/path then use --with-png=/my/path/.

> /usr/local/bin/gdlib-config —all

GD library  2.1.0
includedir: /usr/local/include
cflags:     -I/usr/local/include
ldflags:     -L/usr/local/lib
libs:       -ljpeg -lz  -L/usr/local/lib -lpng16 -L/usr/local/lib -lfreetype -lz -liconv
libdir:     /usr/local/lib
features:   GD_JPEG GD_FREETYPE GD_PNG GD_GIF GD_GIFANIM GD_OPENPOLYGON

You must have GD_FREETYPE and GD_PNG for Circos to run. The other features, such as support for JPEG and TIFF are optional. In this example, I’ve included the JPEG library in the installation.

Now, install the Perl interface to libgd — the GD module.

> tar xvfz GD-2.53.tar.gz
> perl Makefile.PL

Configuring for libgd version 2.1.0.
Checking for stray libgd header files...none found.

Included Features:          GD_JPEG GD_FREETYPE GD_PNG GD_GIF GD_GIFANIM GD_OPENPOLYGON
GD library used from:       /usr/local
Checking if your kit is complete...
Looks good
Writing Makefile for GD
Writing MYMETA.yml and MYMETA.json

During the installation GD will look for libgd-config (see above) for libgd configuration. 

> make
> make install

> perl -MGD -e 'print $GD::VERSION,”\n”’
> 2.53

Test that the modules are installed using

> circos -modules
…
ok       0.39 Font::TTF::Font
ok       2.53 GD
ok        0.2 GD::Polyline
ok       2.39 Getopt::Long
ok       1.16 IO::File
…

Errors

Missing modules

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

*** REQUIRED MODULE(S) MISSING ***

You are missing one or more Perl modules, or these modules failed to load. Use CPAN to install it as described in this tutorial

http://www.circos.ca/documentation/tutorials/configuration/perl_and_modules

missing List::MoreUtils

In the rare case that the internal error checking doesn't catch the missing module, you'll see something like this.

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

In this case Perl is complaining that the module List::MoreUtils cannot be found, which you'll need to install.

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 as /usr/bin/make), but are having trouble installing the module with CPAN, install (or attempt to, paying close attention to the errors) 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
# pay attention to any the build errors in the next step
> Build make