Getting the Code

Download

Select the appropriate stable release from here or check out directly from the repository by following the instructions below.

Note: If you are not interested in developing your own applications against the Darwin libraries and simply want to run the existing applications then you can download pre-compiled binaries from the downloads page.

Repository

Use GitHub Shell to check out the latest copy of the code from:

git clone https://github.com/sgould/drwn.git $DARWIN

where $DARWIN is the directory you want to put the code in. To update previously cloned code use:

cd $DARWIN

git pull

Building the Code

The following provides a brief list of steps required for building the code. These instructions assume you are familiar with the Microsoft Visual Studio development environment. More detailed instructions are given below. We use the symbol $DARWIN to represent the directory in which you are installing the codebase.

Make sure you have Visual Studio C++ installed (see Essential Software)
Download Eigen 3.1.4 (or later) and unzip the archive (see Essential Software)
- Move the unzipped folder to the $DARWIN/external folder and rename it eigen3
- A common problem is to copy the parent folder. Make sure the folder Eigen exists directly below $DARWIN/external/eigen3
Optionally download OpenCV-2.4.9.exe and save it to $DARWIN/external. This is a self-extracting archive. Running it should decompress OpenCV into folder $DARWIN/external/opencv (see Optional Software)
Open $DARWIN/src/drwnlibs.sln
Select the configuration (e.g., Release x64 or Debug win32)
Build the libraries.

Warning
By default Visual Studio C++ performs multi-threaded compilation. This can cause problems when compiling in Debug mode since debug information is stored to the same database file. The simplest way to solve this is to turn off multi-threaded building (see Frequently Asked Questions below).
Open $DARWIN/src/drwnapps.sln and build either Debug or Release applications (these should match the library configuration).

The Darwin libraries and applications will now be built (in the $DARWIN/bin folder). To build the projects you will need to open and build the Visual Studio C++ solution file in the corresponding project directory, e.g., $DARWIN/projects/tutorial/tutorial.sln.

Essential Software

The following list provides links to software that is required for building the Darwin libraries and applications from source code.

Visual Studio C++ 2010 Express or later (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express)
Eigen (http://eigen.tuxfamily.org/) installed as directed above.

Optional Software

The following provides links to software that is optional when building the Darwin libraries and applications from source code. If this software is not installed then some functionality may not be available.

GitHub Windows Client (http://windows.github.com/)
OpenCV 2.4.9 (http://opencv.org/) installed in the external/opencv directory
- make sure both the "$DARWIN\external\opencv\build\x86\vc10\bin" directory is added to your Windows PATH variable (see Frequently Asked Questions below)
- if you install a later version of OpenCV you will need to modify the linked libraries within each Darwin project
wxWidgets 2.9.4 (http://www.wxwidgets.org/) installed in the $DARWIN/external/wx directory
Perl (http://www.activestate.com/Products/activeperl/) for running regression tests

Detailed Installation Instructions

Darwin is a C++ software framework consisting of a several component libraries and application code as described in the introduction (on the Darwin homepage). On Windows the code can be compiled using Microsoft Visual Studio C++. These instructions provide a detailed description for compiling Darwin on a Windows system. The Frequently Asked Questions below provides answers to common questions that may be helpful in troubleshooting compilation problems.

Visual Studio

The first thing you will need (after obtaining the Darwin code) is to install the Visual Studio C++ compiler. This is freely available software from Microsoft and can be downloaded and installed by following the instructions at http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express

Note: Multi-threaded compiling is enabled by default. This can result in errors when compiling multiple projects in Debug mode. To turn off multi-threaded compilation, open Visual Studio and select the menu item "Tools | Options". Select "Projects and Solutions | Build and Run". Set "maximum number of parallel project builds" to 1.

Third-party Libraries

Like any large project Darwin also depends on some third-party software libraries. We have tried to keep these to a minimum. As such, only RapidXML and Eigen are required for the core framework components (specifically drwnBase, drwnIO, drwnML, drwnPGM). For convenience RapidXML is distributed with the source code. The Eigen template library for linear algebra, however, must be installed separately. Other third-party libraries, such as OpenCV, are only necessary if you require certain additional functionality (e.g., drwnVision requires OpenCV).

All third-party libraries should be installed in the $DARWIN/external directory, where $DARWIN is the folder where you have downloaded and decompressed the Darwin source code (e.g., C:/darwin). The Eigen template library for linear algebra should be downloaded from the Eigen website. Make sure you download version 3.1.4 or above. Create a folder called $DARWIN/external/eigen3 and decompress the Eigen code into this folder.

Warning: Make sure that $DARWIN/external/eigen3 contains the Eigen source directly and not a single subdirectory containing the Eigen source. You can check this by verifying that $DARWIN/external/eigen3/Eigen exists and contains the Eigen template library headers. A common mistake is to for this code to be one level deeper in the directory hierarchy, resulting in compilation errors.

OpenCV, which is optional, should be installed in $DARWIN/external/opencv. Download the OpenCV-2.4.9.exe self-extracting archive from http://sourceforge.net/projects/opencvlibrary/files/opencv-win and save it to $DARWIN/external. Running this application with the default options will then create the directory $DARWIN/external/opencv and decompress the OpenCV libaries into it.

Warning: Installing a different version of OpenCV will result in linker errors. See the Frequently Asked Questions below for information on how to update projects for later OpenCV versions.

Compiling the Darwin Libraries

You are now ready to compile the Darwin libraries. The five libraries (drwnBase, drwnIO, drwnML, drwnPGM and drwnVision) are bundled together into a Visual Studio Solution file called $DARWIN/src/drwnlibs.sln. Open this file in Visual Studio and you will see five projects corresponding to the five libraries. The libraries can be compiled in either Debug or Release mode. The mode can be changed for all projects at once via the Configuration Manager.

To compile all libraries right-click on "Solution 'drwnlibs'" and select "Build Solution" (alternatively hit the shortcut F7). Visual Studio will start compiling the code. The libraries are written to the $DARWIN/bin directory. If compiling in Debug mode library names will have the letter 'd' appended to them (e.g., drwnBased.lib).

Warning: If you have not installed OpenCV you will get error messages when Visual Studio tries to compile the drwnVision library. It is safe to ignore these messages.

You can also compile each library separately by right-clicking on the library and choosing Build from the drop-down menu.

Compiling the Darwin Applications and Projects

Once the libraries have been build you are ready to compile the applications and projects. Open the file $DARWIN/src/drwnapps.sln in Visual Studio. The solution will show a number of applications. Compile these by right-clicking on "Solution 'drwnapps'" and selecting "Build Solution" (alternatively hit F7). This will compile all the applications and place the executables in the $DARWIN/bin directory.

Note: You should compile the applications in the same mode (Debug or Release) as the libraries.

You can also compile each application separately by right-clicking on the corresponding project and choosing Build from the drop-down menu.

Warning: If OpenCV was not installed the computer vision applications will produce error messages when compiled. It is safe to ignore these messages.

You can go through the HelloWorld Darwin Tutorial by opening the $DARWIN/projects/tutorial/tutorial.sln file. Likewise, projects such as rosetta, multiSeg and patchMatch can be compiled by opening the Visual Studio solution file in the corresponding project directory.

Frequently Asked Questions

"How do I start the GitHub Shell?"

From the Start menu select "All Programs | GitHub, Inc | Git Shell".

"How do I turn off MSVC multi-threaded building?"

Select the menu item "Tools | Options". Select "Projects and Solutions | Build and Run". Set "maximum number of parallel project builds" to 1.

"How to I build executables that can be distributed?"

Under "Properties | C/C++ | Code Generation" set "Runtime Library" to Multithreaded (/MT) to statically link the Visual Studio runtime libraries. Alternatively ask users to install the Visual C++ Redistribution package.

"Why do I get the error Cannot open include file: 'Eigen/Core'?"

You have installed the Eigen linear algebra package in the wrong location. Make sure the directory "$DARWIN/external/eigen3/Eigen" exists.

"Why do I get the error Cannot open include file: 'cv.h'?"

Either you have chosen to not install OpenCV or you have installed it in the wrong location. If you have chosen not to install OpenCV then you can ignore this error. However, you will not have access to functionality in the drwnVision library, which depends on OpenCV.

If you want the drwnVision library functionality then make sure OpenCV is installed in $DARWIN/external/opencv.

Note that at runtime the "$DARWIN\external\opencv\build\x86\vc10\bin" directory must be included in your system's PATH environment variable (this can be done via the Windows Control Panel).

"How do I add a directory to the Windows PATH variable?"

Open the Window's "System Properties" dialog box and select the "Advanced" tab. On most Windows installations you can press the Window-Break (or Windows-Pause) and select "Advanced system settings". Click the "Environment Variables..." button. Select the Path system variable and click "Edit..." (if the variable does not exist then click "New...". Add full directory paths as necessary, separated by a semi-colon (;).

"How do I link Darwin to another version of OpenCV?"

If you download a later version of OpenCV you can get Darwin to compile against it by changing the OpenCV library names in the "Property Page | Linker | Input" field.

"Why do I get 'LINK: fatal error LINK1104: can not open drwnBase.lib' when compiling applications or projects?"

Check the "$DARWIN\bin" directory. Most likely you are compiling the libraries in Debug mode and the applications in Release mode. Debug libraries end in d (so "drwnBased.lib" instead of "drwnBase.lib"). See Compiling the Darwin Libraries above.

"How do I compile for x64 platforms?"

The default installation of Visual Studio Express 2010 does not allow you to compile 64-bit applications. See this post from Microsoft for further details.