DevelopmentEnvironment modified by Mike Jackson

Mike Jackson — Wed, 10 Apr 2013 10:46:14 -0000

How to set up your development environment

These instructions have been tested on Windows XP (service pack 3) and Windows 7 Enterprise (6.1).

Tool set

The ALE tool set, and their licences, is as follows. None of these preclude open or closed source development.

We describe what you need to actually download shortly.

Microsoft Visual Studio Professional or Visual C++ Express (free)
CMake - build tool needed for VTK.
- BSD-style licence - http://www.cmake.org/cmake/project/license.html
- No CMake classes are used in ALE executables.
VTK - visualisation toolkit.
- BSD licence - http://www.vtk.org/VTK/project/license.html
OpenGL - This is needed for certain GUIs (including VTK ones) on Windows (See, for example, the VTK FAQ)
- See README.TXT in ftp://ftp.microsoft.com/softlib/mslfiles/Opengl95.exe
OpenGL(R) 1.1 Release for Windows(R) 95, "The OpenGL runtime libraries for Windows 95 are not bundled with the Windows 95 operating system currently, but application developers may freely redistribute from this SDK along with their applications to other Windows 95 systems."
wxWidgets - widget toolkit. A set of widget classes that make building GUIs far easier.
- L-GPL with exclusion - http://www.wxwidgets.org/about/newlicen.htm
- "The wxWindows Licence is essentially the L-GPL (Library General Public Licence), with an exception stating that derived works in binary form may be distributed on the user's own terms. This is a solution that satisfies those who wish to produce GPL'ed software using wxWidgets, and also those producing proprietary software."
- In the download README - "If you use TIFF image handler, please see src/tiff/COPYRIGHT for libtiff licence details ... If you use JPEG image handler, documentation for your program should contain following sentence: "This software is based in part on the work of the Independent JPEG Group". See src/jpeg/README for details." We don't use these specific features.
vtkRenderWindowInteractor - class to allow VTK windows in wxWidgets GUIs.
- Custom licence link cited in source code. Analogous to VTK BSD licence - http://www.kitware.com/Copyright.htm
Wu's color quantization C code - C code for doing minimum variance quantization of images.
- Wu's color quantization C code. This is free to download and use and has been used in open source and commercial (e.g. MATLAB) products.
JPEG library - a library to load/save JPEGs. This is optional. One project in the ALE solution uses this library as a test harness for Wu's color quantization C code. It is ''not'' needed to compile and run ALE.
- Custom licence - http://www.ijg.org/files/README
- "We are releasing this software for both noncommercial and commercial use. Companies are welcome to use it as the basis for JPEG-related products. We do not ask a royalty, although we do ask for an acknowledgement in product literature (see the README file in the distribution for details)."
niftilib - library for loading/saving Nifti and Analyze files.
- Public domain.
ParaView - graphics toolkit. We use files to support loading/saving Nifti/Analyze files via VTK classes.
- VTK BSD licence - http://www.kitware.com/Copyright.htm

Download the tool set

Download and install Microsoft Visual Studio or the, free, Microsoft Visual C++ Express:

We have used Microsoft Visual C++ Express 2010, Microsoft Visual Studio 2010 Professional (10.0.30319.1 RTMRel).
Microsoft Visual C++ Express can be freely downloaded from http://www.microsoft.com/express/Downloads. It needs to be freely registered within 30 days. See How to register Microsoft Visual C++ Express.

In what follows we refer to Visual C++ to mean either Visual C++ Express or Visual Studio.

Download and install the CMake build tool:

Download from http://www.cmake.org. We used version 2.8 at http://www.cmake.org/files/v2.8/cmake-2.8.2-win32-x86.exe
Follow the installer instructions

Download VTK:

Download from http://www.vtk.org/VTK/resources/software.html#latest. We used VTK 5.6.0 at http://www.vtk.org/files/release/5.6/vtk-5.6.0.zip

Download OpenGL:

If you have Windows XP,
- Download from ftp://ftp.microsoft.com/softlib/mslfiles/Opengl95.exe.
- This creates a directory with the required DLLs and libraries.
If you have Windows 7 then the libraries should be in C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\Lib

Download wxWidgets:

Download from http://www.wxwidgets.org/downloads/#latest_stable. We used wxWidgets 2.8.11's wxMSW installer for Windows at http://sourceforge.net/projects/wxwindows/files/2.8.11/wxMSW-2.8.11-Setup.exe/download.
Double-click on the exe (wxMSW-2.8.11-Setup.exe) to unZIP the source.

(Optional) Download JPEG library:

Visit http://www.ece.sunysb.edu/~cvl/e358/f2001/jpeg-windows.html
Download all the files: jconfig.h, jmorecfg.h, jpeglib.h, jpeg.lib, jpeg2jpeg.c, testimg.jpg.
Put these in a directory on your PC e.g. C:\jpeglib.
If the above files are not at the URL then the source can be downloaded at http://www.ijg.org.

What about vtkRenderWindowInteractor, Wu's color quantization C code, niftilib and ParaView?

We have copies of these so there's '''no''' need to download them.
Their locations in SVN and where they come from are listed in SVN at: ale/cpp/trunk/README.txt

Build VTK

Run CMake.
In Where is the source code field, enter VTK source directory that you have downloaded and unZIPped e.g. C:/vtk-5.6-src
In Where to build the binaries field, enter a directory where you want the VTK binaries to go e.g. C:/vtk-5.6-bin
Using the +Add Entry button enter the following flags with the following values.
- Make sure that for each the Type is set to STRING.
- Do '''not''' use BOOL for the ON/OFF flags as it will not work.

Flag	Value
VTK_WRAP_JAVA	OFF
VTK_WRAP_TCL	OFF
VTK_WRAP_PYTHON	OFF
VTK_USE_RENDERING	ON
VTK_PARALLEL	OFF
CMAKE_INSTALL_PREFIX	Enter a directory in which you want the built VTK files to go e.g. `C:/vtk-5.6-mt`
CMAKE_BACKWARDS_COMPATIBILITY	2.4
BUILD_SHARED_LIBS	OFF. Note, if ON then shared libraries are built. This means references to symbols placed in executables and removes duplication. If OFF then static libraries are built. Required symbols are copied from libraries to executables allowing them to be stand-alone. We use the OFF, static libraries, option.
BUILD_EXAMPLES	OFF

Now, again using the +Add Entry button, enter the following flags with the following values. These are required to enable the building of static libraries and so stand-alone EXE applications using VTK:

Flag	Value
CMAKE_CXX_FLAGS_DEBUG	/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1
CMAKE_CXX_FLAGS_MINSIZEREL	/MT /O1 /Ob1 /D NDEBUG
CMAKE_CXX_FLAGS_RELEASE	/MT /O2 /Ob2 /D NDEBUG
CMAKE_CXX_FLAGS_RELWITHDEBINFO	/MT /Zi /O2 /Ob1 /D NDEBUG
CMAKE_C_FLAGS_DEBUG	/D_DEBUG /MTd /Zi /Ob0 /Od /RTC1
CMAKE_C_FLAGS_MINSIZEREL	/MT /O1 /Ob1 /D NDEBUG
CMAKE_C_FLAGS_RELEASE	/MT /O2 /Ob2 /D NDEBUG
CMAKE_C_FLAGS_RELWITHDEBINFO	/MT /Zi /O2 /Ob1 /D NDEBUG

Click Configure
Select the build system:
- If using Visual Studio 2010 or Visual C++ Express 2010 then select "Visual Studio 10"
Wait for Configuration to complete - this may take several minutes
Check that BUILD_SHARED_LIBS is still OFF. If not then set it to off and re-click Configure
Click Configure '''again'''
Click Generate
Eventually this will create a project file in C:\vtk-5.6-bin\VTk.sln
Double-click this and Visual C++ should open
Set the build mode to Release using the drop-down menu at the top of the page, next to the green arrow icon
In the Solution Explorer on the left hand side, right click on ALL BUILD and select Build
Wait for '''a long time''' (> 1 hour) for it to build. There should be 0 errors.
Set the build mode to Release using the drop-down menu at the top of the page
In the Solution Explorer on the left hand side, right click on INSTALL and select Build
Wait for '''a long time''' for it to build. There should be 0 errors.
Look in C:\vtk-5.6\bin and you should see bin, include and lib directories

Build wxWidgets

When you double-click on the wxWidgets exe (wxMSW-2.8.11-Setup.exe) you'll end up with two Visual C++ workspaces:
- build\msw\wx.dsw for static libraries.
- build\msw\wx_dll.dsw for dynamic libraries.
We use static libraries so open build/msw/wx.dsw in Visual C++.
You may be asked if you want to convert from Visual Studio 2006. If so then click Yes to All.
- This works for Visual Studio 2010.
- This does not work for Visual C++ Express 2010. You can use Visual C++ Express 2008 to convert the file. Just load it in, click Yes to All then exit and load up the converted solution file in Visual C++ Express 2010.
You will see a solution with a list of projects.
Each project comes with a number of options e.g. Debug or Release modes, ANSI or Unicode character sets, Static or Dynamic linking.
We use Unicode character sets, static linking and Release mode so:
- Select Unicode Release ('''not''' Universal Unicode Release) from the drop-down menu by the green arrow icon.
- We want static linking so, you will need to set the runtime library flag for '''every''' project:
  - Right-click the project name in the Solution Explorer
  - Make sure Unicode Release is selected from the drop-down menu by the green arrow icon
  - Click Configuration Properties
  - Click C/C++
  - Click Code Generation
  - For property Runtime Library, change it from /MD to /MT
- ''Make sure you do this for every project''
Now, compile each project in the following order (you can try to build the whole solution but it may not get the compilation order right):
- wxjpeg, wxpng, wxtiff, wxzlib
- wxregex, wxexpat, base, net
- odbc, core, gl, html, xml
- media, qa, adv, dbgrid, xrc, aui, richtext
Assuming you unZIPped wxWidgets to C:\wxWidgets-2.8.11, the libraries will be placed in C:\wxWidgets-2.8.11\lib\vc_lib.

Set environment variables

To help portability, our Microsoft Visual C++ project file does not have hard-coded paths but instead relies on environment variables to make it more portable.

You can set environment variables by selecting Start => Control Panel, then double-clicking System, selecting the Advanced tab, clicking the Environment Variables button, and using the New button in the User variables area.

Set the following variables:

OPENGLDIR - path to the OpenGL directory, e.g. C:\OpenGL
WXWIDGETSDIR - path to the wxWidgets directory built above, e.g. C:\wxWidgets-2.8.11
VTKDIR - path to the VTK directory built above, e.g. C:\vtk-5.6-mt
VTKINCLUDEDIR - relative path to the VTK include files in the above e.g. %VTKDIR%\include\vtk-5.6
VTKLIBDIR - relative path to the VTK library files in the above, e.g. %VTKDIR%\lib\vtk-5.6
JPEGLIBDIR - path the JPEG library, (this is optional, see above) e.g. C:\jpeglib

Debug versions

The above instructions build Release versions of libraries and applications i.e. those with the /MT flag enabled. To build Debug versions, with the /MTd flag enabled, which, when used with the Visual C++ debugger provide information on memory leaks and other useful information you can follow the above instructions with the following changes:

VTK:
- When building the ALL BUILD and INSTALL projects in Visual C++, ensure the build configuration is set to Debug, not Release.
wxWidgets.
- Run wxMSW-2.8.11-Setup.exe and deploy to a new directory e.g. C:\wxWidgets-2.8.11-mtd
- Set the runtime library flag for each project to /MTd, and not /MT.
- Make sure Unicode Debug is selected from the drop-down menu by the green arrow icon
Set environment variables:
- WXWIDGETSMTDDIR - path to the wxWidgets directory built above, e.g. C:\wxWidgets-2.8.11-mtd
- VTKMTDDIR - path to the VTK directory built above, e.g. C:\vtk-5.6-mtd
- VTKMTDINCLUDEDIR - relative path to the VTK include files in the above e.g. %VTKDIR%\include\vtk-5.6
- VTKMTDLIBDIR - relative path to the VTK library files in the above, e.g. %VTKDIR%\lib\vtk-5.6

References

VTK build instructions:

http://code.hkpeterpeter.googlepages.com/vtk_build_vc.pdf linked from
http://vtkblog.blogspot.com/2007/04/install-build-vtk-from-source-in-visual.html. Some errors in the text were corrected.
The recommendation to use /MT for static libraries with VTK in http://www.vtk.org/Wiki/User_talk:Sylvain#Build_VTK_for_Release. The flag values cited above are the C/C++ flags in the C:\vtk-5.6-bin\CMakeCache.txt CMake file in a default VTK build with MD replaced by MT.

wxWidgets build instructions:

Recent changes to DevelopmentEnvironment