2. Downloading PLearn

After having been hosted for several years on SourceForge (under CVS), as of 2005/06/21 PLearn development has been moved to BerliOS (http://developer.berlios.de) that offered the benefits of a faster hosting with the more modern Subversion (SVN) version control system. The latest version is always available through SVN access.

2.1 Anonymous SVN checkout

If you just want to hack PLearn locally, you can do an anonymous checkout (no need for a BerliOS account) with

svn checkout svn://svn.berlios.de/plearn/trunk PLearn

2.2 Developer SVN access

If you are going to be a serious contributor to PLearn, you should create a BerliOS account for yourself, and ask to be added to the developer list. This will give you read/write access to the PLearn repository.

Make sure you first move any older version of PLearn out of the way, for ex. by renaming it PLearn.old You can then check-out a fresh copy of PLearn with the following instruction:

svn checkout svn+ssh://USERNAME@svn.berlios.de/svnroot/repos/plearn/trunk PLearn

where you replace "USERNAME" by your Berlios username. You will be asked for your Berlios password twice.

If you don't want to be bothered with svn asking passwords, clisk on Account Maintenance on the left panel of your BerliOS personal page, and on Edit keys on the bottom of the Maintenance page. You can copy your ssh public key there. (Note: your ssh public key is normally found in your /.ssh/*.pub If it's not there, you can do a ssh-keygen). As for many changes within BerliOS, it may take a while before this is propagated and taken into account.

We also suggest that you edit your ~/.subversion/config and look for the line containing global-ignores: uncomment it and add OBJS in the list of ignored patterns, to avoid being annoyed with these directories when doing a svn status command. You'll also have to uncomment the line [miscellany] three lines above.

2.3 SVN basics

From within your local PLearn directory:

• svn update will update your local version with the latest version in the repository.
• svn commit will commit your changes to the repository.
• svn add will add to the repository the files and directories you pass as argument, recursively, so make sure you really want to add all those directories' full content...
• There is also svn rm, svn mv, and svn cp to reorganize the files.

Unlike CVS, most subversion commands are recursive by default. Check the help for a particular command before using it if you are unsure.

For more details, there is a excellent free subversion book online available at: http://svnbook.red-bean.com/en/1.1/index.html

If you don't have the time to at least peruse the whole book, I would still strongly recommend that you at least read appendix A: Subversion for CVS users: http://svnbook.red-bean.com/en/1.1/apa.html

2.4 Overview of the directory structure

Your checked out PLearn has the following high level directory structure:

• scripts/
  contains mostly python and perl scripts
  • pymake is our build system
  • pytest implements our test suite framework
  • pyskeleton is our “wizard” or “template” system; it uses source code templates in the Skeleton/ directory
  • pypoints allows graphical interactive input of points (for 2D classif or 1D regression)
  • pyplot allows plotting learner outputs (classif decision surface, density plot, etc...)
  • xpdir lists the content of PLearn experiment directories
  • perlgrep, search-replace, and undo-search-replace allow for simple code lookup and transformations.
  • pytansform and the transformations in Transformations/ allow for complex code transformations.
  • cvschangeroot is used to recursively change the locally recorded cvs root. This is useful to indicate that the repository has moved. Note however that we now use a SVN repository for PLearn rather than CVS.
  • ...
• commands/ contains the source code (as .cc files) of PLearn "executables" to be compiled with pymake. If you look at the plearn_*.cc files closely, you will notice that they are all built in the same manner, simply including a number of things they need, and invoking a single function plearn_main. So they only differ in the functionalities they #include. They have been arranged according to the external library dependencies that will be needed to compile and link each of them. In short:
  • plearn_noblas depends only on NSPR, boost (if you don't have blas, it must be compiled with pymake -noblas plearn_noblas )
  • plearn_lapack depends on NSPR, boost, BLAS, LAPACK
  • plearn_curses depends on NSPR, boost, BLAS, LAPACK, ncurses
  • plearn_python depends on NSPR, boost, BLAS, LAPACK, ncurses, python runtime libraries
  Since plearn_noblas has the smallest number of requirements, it should be the easiest to get to compile and link. But several important learning algorithms require LAPACK. plearn_lapack will contain the most useful 99% of PLearn.
• commands/PLearnCommands/ contains the source code for all PLearn commands. These commands are included in the above plearn_* programs and can be invoked with these programs in a command-line fashion.
• commands/language/ contains some programs for manipulating language corpus and WordNet related stuff.
• python_modules/
  The root for python module namespace. Must be in your PYTHONPATH.
  It contains mostly a plearn/ subdirectory, which allows to import plearn.foobar from python.
• doc/
  directory within which Pearn's documentation is generated
• examples/
  contains examples of PLearn scripts
• test_suite
  contains part of the PLearn test suite
• plearn/
  contains all of PLearn's base C++ classes organised in themed subdirectories.
• plearn_learners/
  contains all of PLearn's C++ learner classes organised in themed subdirectories.
• plearn_learners_experimental/
  may contain some very experimental C++ learner classes...
• plearn_torch/
  contains C++ classes to interface with the Torch library ( http://www.torch.ch/ )
• pylearn/
  is the beginning of a BoostPython interface to access PLearn from python, but is currently not the way we call upon PLearn from python.

The plearn* directories contain C++ source code (.h and .cc), and as your root PLearn directory is in the -I directive of the compilation commands, this allows to include relevant files by directives such as, for ex:

#include<plearn/base/Object.h>
#include<plearn/io/PStream.h>
#include<plearn_learners/generic/PLearner.h>