The Shurfist Tutorial

From Self Shelf Swap Community Wiki
Jump to: navigation, search



The aim of this tutorial is to help you installing the environment.

What is is a software made for managing small libraries (book and shelves, not software stuff) with a web based interface (we also have a command line interface).

What is not is not the Yet Another Cool Tool You Want To Use. We are not Cool. is a Yet Another Ugly Tool You Don't Want To Use. You don't want to use it anyway.


Are you a developer / shurfer ?

If not, it will be quite hard to manage with the environment. But not impossible if you want to learn. Please find your local hacker for help. Some Perl knowledge is necessary. Some Unix-like operating system knowledge and philosophy too.

Why don't you run GNU/Linux? hasn't been tested on any other Operating Systems than Debian (Lenny, Squeeze) and Ubuntu (10.04 LTS, 12.04 LTS). It hasn't been tested on Window nor Mac OS X, but it should. We plan to support it on Windows (we need a Windows fan for this) cause it's useful. If you feel interested in testing it on any platform, contact us! It is still quite experimental, so use it at your own risks ;)

Dependencies, requirements: Speed and Dirty Way

You need a GNU/Linux distribution. We recommend Debian or a Debian based distribution like Ubuntu or Mint. If you are much more motivated, you can try to use it on another one, and report us any bug.

If you are in a hurry, just copy-and-past this in your terminal (ctrl + c / ctrl + shift + v) :

$ sudo apt-get install make libextutils-pkgconfig-perl perl-doc cpanminus curl libcurl4-gnutls-dev libwww-curl-perl libxml-simple-perl libtemplate-perl libperl6-slurp-perl
$ cpanm --sudo Merror Properties WWW::Curl::Simple Text::Buffer

And skip all the content in this page :D

Dependancies, requirements : Slow Way

If you want to see what is under the box, you can read and follow this step-by-step tutorial.


Most of GNU/Linux OS got it. A friend of mine who masters pythons wants to have fun and un-install Perl from his GNU/Linux but it was a sad story. We will soon get a lot of Perl libraries from CPAN, more known as modules in Perl jargon.

Perl Modules

We would like make an automatized way for installation of all this mess! If you want to contribute to this, please contact us!!!

Try to install the modules via your package manager. If the module is not available trough the package manager, use the CPAN to get the modules and it's own dependencies. You can use a CPAN package manager or compile it by hand. See this page for much more informations about modules installation from the CPAN. For those who don't know it, it's much more safe and the-lazy-way to use the package manager.

Try to install the dependencies in this order to avoid problems.

You will maybe need a C compiler or at least the make utility and the ExtUtils::PkgConfig module will also be usefull:

$ sudo apt-get install make libextutils-pkgconfig-perl

Perl Doc

First, you maybe need to read the doc offline. Shurfists are people who sometimes goes offline. If you are not offline, you will be able to get the most up-to-date documentation because it is directly written into the Perl modules

$ sudo apt-get install perl-doc

Now, you can ask for documentation of modules installed on your computer, just like a man:

$ perldoc perldoc

...this is the documentation for the perldoc module.

$ perldoc perllol

...this is a Tutorial about manipulating Perl arrays of arrays :D .


cpan and cpanm are two pure Perl package managers using directly the CPAN to search, install or update your modules.

We will use cpanm to make installing other modules easier (you'll thank us later). Type these commands:

$ cpan App::cpanminus

CPAN will ask you if you Would you like to configure as much as possible automatically? Say yes. When it asks for what approach do tou want? Choose sudo. We think that this is more in the Debian way to install modules under the directories it have been if this have been installed with apt(this is our way but this is not your, do as you want).

Now say yes for everything and let CPAN make the stuff (it can take some time) and will install the Cpanminus application after asking for your password.

You can use this command for installing any module now, running :

$ cpanm --sudo Module::Name


Merror is an Oriented Object error handling system.

$ cpanm --sudo Merror


We use Properties 1.4 for options files parsing.

$ cpanm --sudo Properties

cURL and WWW::Curl::Simple

We use cURL to get data about books from Open Library. You need both the cURL debian package and two Perl module, the WWW::Curl perl interface to cURL, and WWW::Curl::Simple module, that is a very simplified tool for using cURL.

We need some curl packages from Debian. This can install a (great) number of dependencies :D. You can proceed after to the WWW::Curl::Simple installation...

$ sudo apt-get install curl libcurl4-gnutls-dev libwww-curl-perl 
$ cpanm --sudo WWW::Curl::Simple


When we get RDF data from Open Library, we treat it with XML::Simple, a simple API for maintaining XML and including support for SAX. This module is simply available into the Debian packages repository.

$ sudo apt-get install libxml-simple-perl

Template Toolkit

The Template Toolkit (TT) is a collection of Perl modules which implement a fast, flexible, powerful and extensible template processing system. It is strongly used in our [[1]].

$ sudo apt-get install libtemplate-perl


$ sudo apt-get install libperl6-slurp-perl

Text Buffer

Text::Buffer is an oriented-object-style interface for handling a line-based text buffer. We use it for preprocessing with Template Toolkit.

$ cpanm --sudo Text::Buffer

Pod 2 Wiki

To export the POD documentation to this Wiki, you can generate markup with pod2wiki. Learn how to use it in our documentation.

$ sudo apt-get install libpod-simple-wiki-perl

Another modules

We use these other modules, but you don't need to install it, they are part of the Perl Core:

  • Data::Dumper
  • Encode::Encoder
  • File::Basename
  • IO::File
  • Module::ScanDeps
  • Time::HiRes

Revision control system

version <= 0.02.x

We use Bazaar as a revision control system . See our own tutorial for Bazaar (you will need to configure it). Then, can get the code and you'll be up to date with any changes. You'll be also able to commit your own one. To install it, just type:

$ sudo apt-get install bzr bzr-explorer

bzr is the command line client. bzr-explorer is a very simple to use graphical client.

version >= 0.03

We now use Git and GitHub because this is the most used one today. As tech guys are the only one who has used Launchpad, their is no sense at all to use Launchpas and Bazaar now. Fork us now!


You will see a lot of strange name into the documentation or the project management tools. Dime And A Shoestring, A Chinese Loony And A Rope or The Crud Step. Those nicknames designates sets of versions, most of the time designated with numbers (v0.2.1, 0.3). We don't want to use the number way that is a meaningless jargon in every-days life, so we create these fun version things.


Get the sources

Once Bazaar is configurated, you have to open a terminal and get the sources:

  $ bzr branch lp:bibliothek-project

You will get a trunk directory containing another directory inside, with the name of the current project (for example dime-and-a-shoestring or the-crud-step, etc.).

Apache configuration

Don't forget to put your shurf environment in a place wher your files can be execute by the web server (aka /var/www/ or a userdir directory).

You will need to addd a value for .pl in the /etc/apache2/mods-available/mime.conf's AddHandler directive.

The Shurfist Tutorial Talk

This tutorial has been possible only thanx to the help from Tonton Yéyé who mades the blueprint for it during a chat session. Cheers!!!!

Personal tools