Quick Subversion Checkout and Compilation HOWTO
First, make sure you have the requisite version of subversion installed (you'll need at least 1.1 or later). You can find out what version you have on linux by running 'svn --version'. If you wind up accidentally using an old version of subversion, the sources you get will be unreliable and you will be faced with ridiculously difficult to diagnose problems. Don't do that.
Windows users can also use Tortoise SVN, which integrates with the normal Windows Explorer interface and allows point-and-click SVN operations.
Getting the Sources
Next, check out the sources. subversion is a little disk space intensive, and your initial check out may take a fairly long time. To do this on linux, run:
svn checkout https://svn.resiprocate.org/rep/resiprocate/main resiprocate
This will create a 'resiprocate' subdirectory under whatever your current working directory is. Furthermore, svn commands will work inside and below that directory.
The build system relies on the following external packages, which may or may not be installed on your system by default (names in parentheses indicate common names for packages [e.g. for yum, apt-get, or similar]):
- Gnu Perfect Hash (gperf) - You can get by without this on Windows, but not under MinGW, if you won't be adding headers, methods, or parameters. You might be able to get by on other systems without it, but the make system is as likely as not to hose some source files if you do -- see "Known Issues," below. Consequently, non-Windows users are urged to play it safe and install gperf before attempting to build.
- Open SSL (openssl, openssl-devel)
- You need version 0.9.8 or later if you want to use DTLS
- Windows and MinGW users can compile from source or may be able to save time by downloading the installable version from Shining Light
- POPT (popt) - Windows and MinGW users can use the version under contrib/popt
- Perl Compatible Regular Expression Library (pcre) - Windows and MinGW users can use the version under contrib/pcre
- If you are building Repro, the Resiprocate Proxy, you need Berkeley DB (db4, db4-devel) - Windows and MinGW users can use the version under contrib/db -- NOTE: Repro is built by default; if you don't have BDB installed, your make will fail unless you disable building of repro using the configuration script
- If you plan to use TFM (the testing framework), you'll need Boost
External Library Cheat Sheet
These are commands that may successfully install the various prerequisites for you:
- Mac OS X 10.5 (with MacPorts installed):
- sudo port install gperf openssl popt pcre db42 boost
- sudo aptitude update; sudo aptitude install subversion g++ gperf libssl-dev libpopt-dev libpcre3-dev libdb4.2++-dev libboost-dev
Now, you should be ready to compile the sources.
Unix Systems (Including OS X)
Over resiprocate's history, there have been, at times, two different build systems, which often weren't kept in particularly good sync with each other. Currently (as of 02/2006), only one build system works reliably. To use it, change into the resiprocate directory and set up your Configuration Options with the ./configure command. This guides you through a brief questionnaire; you can accept default values by hitting "enter". (Alternately, use ./configure -m for a menu-based configuration system that works on most vt100-style terminals.)
Once you're finished with the configure, and assuming you have all the prerequisites described above installed, you should be able to just type 'make' and have everything build properly.
(There is some outdated build information at Configuration and Building a stack.)
The make system makes some assumptions about where certain things are installed and what they are called.
- On some systems (e.g. debian), #include <db4/db_cxx.h> may need to be changed to #include <db_cxx.h>
- On some systems (e.g. FC4), it is necessary to create a symbolic link from /usr/lib/libdb.so to the appropriate version of the db4 library (e.g. /usr/lib/libdb-4.3.so)
- On some systems (e.g. FC4), it is necessary to create a symbolic link from /usr/lib/libdb_cxx.so to the appropriate version of the db4 library (e.g. /usr/lib/libdb_cxx-4.3.so)
- If you attempt to build without gperf installed, you may end up with empty resip/stack/ParameterHash.cxx, resip/stack/HeaderHash.cxx, and/or resip/stack/MethodHash.cxx files. You will need to install gperf and delete these files to recover from this situation.
- This can ALSO be remedied by reverting the *Hash.cxx files using your Subversion client and making sure they are newer than the *.gperf files (possibly by using the touch command).
- Under OS X, to link the TFM test programs, you may need to edit build/Makefile.pkg and change "boost_regex" to "boost_regex-mt" on the line that starts with "TFMLIBS_LIBNAME :="
(Cygwin users should follow the Unix instructions above; MinGW users should follow the MinGW instructions below)
There are Visual Studio solution files in SVN, for Visual Studio 2005 (8.0), VS2008 (9.0), and VS2010 (10.0). For 64bit builds you must use the VS2010 solution files.
Base solutions files are:
- reSIProcate_X_Y.sln - main SIP stack and repro proxy
- reTurn/reTurn_X_Y.sln - reTurn server and client API
- tfm/tfm.sln - Visual Studio 2008 only - Testing Framework
- resip/recon/recon_X_Y.sln - recon - Conversation Manager and Music On Hold / Park server
- apps/clicktocall/clicktocall_Y_Y.sln - Click to call application
- apps/ichat-gw/ichat-gw_X_Y.sln - iChat Gateway
- To use TLS or DTLS protocols you'll need OpenSSL. The fastest and easiest way to make this happen is to download the Windows binary installer from http://www.slproweb.com/products/Win32OpenSSL.html. The installed binaries should be placed in contrib/openssl (contrib/opensslx64 for 64-bit), if you don't want to make changes to the Visual Studio project files.
- If you plan on modifying the stack to add new build-in headers or parameteres you'll need gperf. Using pre-built binaries is recommended.
- If you want to build the TFM test drivers or reTurn, you'll need boost. It should be placed in contrib/boost_1_34_1 if you don't want to make any modifications to the Visual Studio project files.
Jori Liesenborgs put together a very nice explanation of how to build reSIProcate for the Pocket PC.
MinGW is a little bit of a strange beast: it's as close as you can get to a real Windows environment using Gnu tools. It is far more minimalistic than Cygwin, and includes only the bare minimum necessary to get applications built. Here's a high-level set of steps you need to take to build under MinGW:
- Install MinGW and MSYS. You will work exclusively inside MSYS. Do not attempt to configure or build from a normal command shell or from cygwin.
- You'll need perl. Cygwin's works fine, as should the ActivePerl version (although this isn't yet verified). If you use the Cygwin version, you'll need to copy over all four of the following files into msys (e.g. into "/usr/local/bin" aka "c:\msys\1.0\local\bin"):
- You'll need OpenSSL. The fastest and easiest way to make this happen is to download the Windows binary installer from http://www.slproweb.com/products/Win32OpenSSL.html. If you put the library anywhere other than c:\openssl, you'll need to modify build/Makefile.osarch accordingly.
- You'll need gperf. This is annoying, but it's just the way things are right now. It looks like the Cygwin binary has some issues with commandline passing of stuff from MSYS, so you can't use it. You'll need to download and compile gperf. I had no problems compiling or installing it under MinGW. Just "./configure; make; make install" from within MSYS.
- If you want to build the TFM test drivers, you'll need boost. Follow the directions at http://www.boost.org/more/getting_started.html to get things set up. MinGW is an explicitly supported platform. Don't get me wrong: Boost is a wild pain in the rear and a complete pig-dog on any platform, but it's no more difficult on MinGW than any other platform.
- Now, you should be able to simply execute a "make all" in the top level directory.
Once that completes without error, you will have the library and a number of test programs compiled. To test the library, you can use the following test drivers. (These programs are also really useful in figuring out how to use the library)
resip/stack/test/testClient debug 'sip:firstname.lastname@example.org;transport=udp'
This command will send an INVITE to the specified address. When the connection is established, testClient will send a BYE and then start the whole process over again. To get out of this loop, Ctrl-C testClient, and establish a connection. You can then send a BYE, which will time out, but the end result will be a disconnection.
resip/stack/test/testServer debug 5 udp
This command will listen on port 5070 for SIP messages, and accept 5 connections. You can then use a user agent to call that testServer 5 times.
- NOTE: I'm sure that these tests are designed to be run together, and talk to eachother, but I have not gotten that to work. Instead, I use a SIP phone to interact with the two tests.
- NOTE: The parameter 'debug' to both of the above programs is incorrect, but will have the desired effect.
Proxy Sanity Test
tfm/sanityTests > sanityTestLog.txt
This comand will run a suite of tests on the repro proxy. It takes a while to run. While running, it will spit out a "." for each successful test, and a random, arbitrary capital letter for each test failure. At this point in time (02/2006), many of these tests fail. If you're feeling restless, you can go in and fix the code and/or tests as appropriate.