On this page... (show)

  1. 1. Prepare a development environment
  2. 2. Build the subversion version of simuPOP
    1. 2.1 distutils
    2. 2.2 distribute
    3. 2.3 scons
  3. 3. Build standalone executables for debugging purposes
  4. 4. Using MSVC to build standalone versions of simuPOP
  5. 5. Send a patch to the mailing list
  6. 6. More readings

1.  Prepare a development environment

You will first need a subversion client. A subversion client is mostly likely already available under *nix system. For windows, you may want to install tortoiseSVN.

  • Souce code: Check out simuPOP source using command,
% svn co svn://svn.code.sf.net/p/simupop/code/trunk simuPOP
If you are using TortoiseSVN, right-click and select SVN checkout ...
  • Boost C++ library: If you do not have the Boost C++ library, you can either
    • Download the boost C++ library from the boost website, decompress it to simuPOP's source directory. It should appear as a directory such as boost_1_49_0.
    • Install the library and its header files. For example, under Ubuntu, you could install packages libboost-iostreams-dev, libboost-serialization-dev, libboost-regex-dev using command apt-get.
  • SWIG: If not already installed, download and install SWIG. Swig version 1.3.36 and later is recommended. Under windows, you need to install swigwin, and add the path to the executable to an environment variable $PATH (Control Panel -> system -> advanced -> Environment Variables).
  • Scons: Although the standard Python setup.py process can be used, it is recommended that you download and install scons to build simuPOP. Unlike the Python distutil.py module, scons is a real build system that can build several files at the same time, and ignore files that have already been built. Under windows, you need to add c:\pythonXX\scripts to environment variable $PATH.
  • C++ Compiler: Get a C++ compiler. This is usually not a problem for Linux/Solaris/MacOS systems because GNU gcc/c++ is widely available on these operating systems. Under windows, you will need to can get a copy of Visual Studio 2008 Professional (needs service pack 1). The free Visual C++ Express edition from here could be used for simuPOP 1.0.5 or earlier but not 1.0.6 or later because it does not support openMP. Note that Visual Studio 2008 only works with Python 2.6 and you will have to purchase a copy of Visual Stuidio.NET 2003 for previous versions of Python.
  • Python header files: The Python header files are usually installed with Python but you should install python-devel or similar packages if this file is unavailable.
  • zlib header files (*nix systems only): zlib and its header file zlib.h are usually available under a *nix system. However, for a Ubuntu system, you will need to install the zlib1g-dev package to get this header file. Please install package build-essential if you still get missing header files.

2.  Build the subversion version of simuPOP

simuPOP can be compiled by python distutil module, python distribute module or scons. They have their own advantage and disadvantages:

2.1  distutils

For all versions of python, you can compile simuPOP using command

% python setup.py install

and Python will call swig to generate Python wrappers and build simuPOP. The problem with this approach is that you will have to compile all files each time when you modified the source code, which can be very slow.

2.2  distribute

If you installed python distribute module, you can run

% python setup.py develop

to build and install simuPOP. This will create a link in the python dist-package directory that links back to the source directory. The compiled modules will be put in the src directory. In order to test simuPOP in place, you will need to create a symbolic link

% ln -s src simuPOP

so that the source directory appears to contain the simuPOP package (with __init__.py underneath). This method works for all versions of Python but does not support parallel build.

2.3  scons

If you have scons installed, you can run

% scons install

Several command line options are available, they are

  • -j n: running n concurrent processes.
  • prefix=/path/to/local/dir: install simuPOP to a local directory.
  • One or more of std, op, la, laop, ba and baop: These correspond to the standard, long and short allele and their optimized versions. scons will only build specified modules if their names are provided in the command line. When you are testing a program, it is a good idea to build only the standard module to save building time.

This method is most flexible and fast, but it does not support Python 3.x.

3.  Build standalone executables for debugging purposes

Under the control of a macro STANDALONE_EXECUTABLE, simuPOP can be linked to a main.cpp file and execute as a standalone application. This allows easier profiling and debugging although it can be cumbersome to write C/C++ versions of test scripts in main.cpp. Also, because the standalone version does not involve a Python interpreter, features related to Python (such as evaluation of Python expression) are unavailable in such executables. Anyway, to build such executables, you can use

  • scons std_exe

or other targets such as op_exe. The executables are saved in directory build in names such as simuPOP_std_exe. These files will not be installed with simuPOP.

4.  Using MSVC to build standalone versions of simuPOP

Before use Visual Studio 2008 to run SimuPOP, you should check the parameter and run command as follows:

  • Run ‘scons install’
  • Open the visual studio project, ‘simPOP.vcproj’.
  • Check properties in the visual studio project as follows:
    • Go to simuPOP Property Pages -> Configuration Properties: C/C++ -> General -> Addition Include directories: “.;gsl;boost_1_45_0;win32;"win32\zlib-1.2.3";C:\Python27\include”
    • Linker -> General -> Additional Library Directories: “build\std_common;C:\Python27\libs”
    • Linker -> Input -> Additional Dependencies: “python27.lib common.lib”
  • Check the version of Python and boost version. If they are not the same as your machine, change them.
  • Run the visual studio 2008 in release mode with your platform (x64 or win32)

5.  Send a patch to the mailing list

After you have modified simuPOP source and added your own feature, it might be a good idea to merge your changes to the simuPOP trunk (main branch) so that it can become part of the official simuPOP release. In addition to the possibility of benefiting other users, the immediate benefit to you is that your code will be examined more carefully, and if it gets accepted, you do not have to patch future simuPOP versions when you upgrade simuPOP.

The process to generate a patch is as easy as

% svn diff > patch.diff

Simply email this patch to the simuPOP mailing list with a detailed explanation.

6.  More readings

You can refer to page DevelopmentNotes for more details on how simuPOP manages its documentation and releases.