Some Tips for the supported compilers

• Linux/GCC
• Microsoft Visual C++

Linux/GCC

Requirements

To compile the CVR-Lib using all its power, you will need the following:

• C++ Compiler GCC 3.4.5 or higher is required. The corresponding STL implementation is required
• Viewer classes use the GTK toolkit, at least version 2.0. On your system you will need to have the developer's package installed.
• GNU Make version 3.79.1 or higher is required to build the library.
• autoconf version 2.52 or higher is required to build the configure script, used to detect which features are installed that the CVR-Lib can make use of. The related aclocal must have version 1.5 or higher.
• Many Linux distributions provide the BASH shell as standard shell. This fact is also assumed here and bash should be the shell you use while calling the configure scripts and the make files.
• PERL is required to interpret some script files that simplify the development with/for the CVR-Lib. All major Linux distributions have PERL packages, but you can also get it from here.

You may also need:

• Doxygen. All the CVR-Lib is documented using this great tool. If you want to generate the complete HTML documentation you will need it and also the Graphviz graph drawing software required by Doxygen to generate the class trees.
• LAPACK to use more efficiently some complex mathematical operations (e.g. eigenvalue/eigenvector computation, LDA). For this to be available you need to install the packages lapack, blas and the f2c compiler which should come with your distribution. See also LAPack based functors. The Fortran compiler with which the lapack was compiled is also necessary (usually provided with the GCC complete package or as g77).

Compile the CVR-Lib

First, check if the configure script already exists in your cvrlib/linux directory. If not, of if you are not sure that this is the correct one, just execute in your BASH terminal

cd cvrlib/linux
make -f Makefile.cvs

After that, you can configure your installation with

./configure

You can of course customize your installation with several options (type ./configure --help for more information).

Now you can compile the debug and release libraries and testers with

make

You can at this point make use of your local copy of the library. The cvrlib/tester/cvrTester.cpp file can be used to try out small programs. You can create two executable test programs with:

make dtester rtester

This will create in cvrlib/bin two executable files:

• dtester is your program in the debug version, with all necessary debugging information, without optimizations and the most important thing, with all possible boundary check mechanisms activated (which make the code much slower as usual!).
• rtester is your tester program in the release version, which runs much faster than the debug one.
• the target ptester can also be used if you want to profile your code.

Every *.cpp file in the cvrlib/linux/workbench directory will also be compiled and linked to the tester/rtester programs, so that you can build more complex test applications.

You can also install the library in your system, assuming you have write privileges for the --prefix directory given in the configure script (if nothing was given, /usr/local is the default). Just try:

make install

The Makefile

The Makefile in cvrlib/linux/Makefile provides many options and targets. Use the targets as usual, i.e. just type

make target

in your xterm, konsole, or whatsoever bash-terminal you are using. Using make without target is equivalent to calling target all-debug and all-release, thus building the library and testers in debug and release version.

The most useful targets are:

• dtester to compile the tester application in debug mode.
• rtester to compile the tester application in release mode.
• ptester to compile the tester application in profile mode.
• bins to compile the debug and release versions of the tester application.
• libd to compile the complete library in debug version.
• libr to compile the complete library in release version.
• libp to compile the complete library in profile version.
• libsd to compile the math library, the library without viewers and the complete library in debug version.
• libsr to compile the math library, the library without viewers and the complete library in release version.
• libsp to compile the math library, the library without viewers and the complete library in profile version.
• all-debug like libd and dtester.
• all-release like libr and rtester.
• all-profile like libp and ptester.
• clean to remove all temporary object files, i.e. the libraries and tester applications will not be removed.
• clean-libs to remove all libraries, but not the temporary object files.
• clean-docs to remove all documentation generated by Doxygen.
• clean-all to remove all generated data: documentation, object files, libraries, even the backup files generated by Emacs (*~).
• distclean like clean-all and additionally removes the Makefiles.
• install to install the library in the prefix specified to the configure script (type ./configure --help for more information).
• doxydoc to generate the documentation using Doxygen. It assumes your system has the latest Doxygen version and the Graphviz tool dot.
• dep to generate the dependencies. You will need this target each time you add new files to the library and you notice your file is not compiled even if something changed that your file directly or indirectly includes.

With the variable DEBUGEXC set to -D_DEBUG_EXCEPTION you can control if the cvr::exceptions will write to std::err a text message that should help you to debug your programs. However, this can (or should) be set in your extrapaths.mk file, in order to survive your next "configure" (see the next section for more information).

Using external libraries and header files

For the use of many frame-grabbers and other hardware related classes, it is usually required that some special hardware drivers or hardware related libraries can be linked with the CVR-Lib. For these and many other special cases it is desirable to have a simple way to indicate:

• Additional include paths, where special header files can be found
• Additional library paths, where specific libraries can be found
• Additional libraries, that should be linked with the CVR-Lib in order to provide specific functionality.

Include paths are required by almost any frame-grabber or camera utility, except if you provide that all headers can be found in the standard system include paths.

Library paths are only necessary if you also specify some libraries to be linked with, which are not located in the standard library directories (e.g. /usr/lib or /usr/local/lib).

The mechanism provided by the CVR-Lib should "survive" a ./configure, since otherwise you would need to make changes to the Makefile each time you get a newer library version or you just want to reconfigure some options.

You just need to create a file called "extrapaths.mk", in which following variables are expected:

• EXTRAINCLUDEPATH for additional include paths
• EXTRALIBPATH for additional library paths
• EXTRALIBS for additional libraries

For example, to use the cvr::microEnablePulnix frame-grabber/camera functor, you should include in "extrapaths.mk" following three lines

EXTRAINCLUDEPATH = -I/usr/src/menable/include
EXTRALIBPATH = -L/usr/src/menable/lib
EXTRALIBS =  -lpulnixchanneltmc6700 -lmenable

Please note the standard GCC flags used to indicate:

• -I path to headers
• -L path to libraries
• -l libraries.

There is a template for such a file in the linux directory: "extrapaths_template.mk". It contains examples for the Philips ToUCam and for Pulnix + MicroEnable framegrabber.

Examples

In the directory cvrlib/examples you can find several directories with simple code examples using the CVR-Lib. You can copy any Makefile in a project of your own, in order to use the CVR-Lib without much overhead.

---

Microsoft Visual C++

Requirements

The CVR-Lib makes use of some C++ features and system functionality that makes following requirements necessary:

• Microsoft Visual C++. The CVR-Lib does not support the incompatibilities of older Visual C++ versions like Version 6.0 or .NET 2002 with respect to the ANSI C++. Version .NET 2003 can compile the CVR-Lib without problems, and support for later versions is continuously improving.
• GTK+. In order to provide a system independent widget set, the GTK+ Library was chosen. These are required only for the visualization classes, and you could modify your projects to avoid their use, but all default projects will assume you want to exploit them. You can get the original GTK+ libraries from here. You will need the three toolkit layers: glib, gdk and gtk. At this time, we use the version 1.3 of the toolkit. You also find sources and binaries of GTK within the Windows Installer Package.
• ws2_32.lib If not already in your system, just search the Internet for it. It is easy to find. (Also provided in the Installer)
• psapi.lib This should come with your Visual C++, but can also be found on the Internet. (Also provided in the Installer)
• pdh.lib The Performance Data Helper library can be found here, or search the Microsoft Knowledge Base for article "Q284996". (Also provided in the Installer)
• PERL is required to create automatically the library and some example project files. (It can also be found in one of the Installer Packages)

If you use the CVR-Lib Installer for Windows all required libraries can be directly installed from there.

creation

A project that uses the CVR-Lib can either be created manually or you can let a PERL-script do the job for you. Nevertheless you should read the section about the manual creation of a project to see which settings are required.

There are always two possibilities to work with the CVR-Lib: either as source code or as static library. The first method is required if you want to make changes to existing library sources. The second is preferable if you only want to use the library or to develop new classes.

Automatic creation of a new project

In cvrlib\win you will find the folders console_src, console_lib and tester.

Each contains a PERL script that generates a console project (.dsp and .dsw files) with default settings. If the project files already exist, then the scripts will only perform an update. A relative path to the sources is assumed, i.e. if you want to move your project's location, you will have to change settings manually.

The console_lib project assumes you have already created and installed the library. To do this go to the directory cvrlib\win\buildLib and execute the batch file buildLib.bat. Don't forget to set up your environment variables using the VCVARS32.BAT file provided in your Visual C++ distribution (usually in directory VC98\Bin.

These scripts assume you have installed the GTK+ libraries. We recommend you to install them, in order to use the visualization classes of the CVR-Lib. Using the Windows Installer, this is simply a check box in the offered packages.

For example, let us assume, you are in the installation path of the library. You can create a simple tester project with:

cd cvrlib\win\tester
perl tester.pl --new

After that, you can open the tester.dsw file with the Visual Studio and compile both, debug and release versions, as usual.

Manual creation of a new project.

The following instructions apply, if you create a new project and want to adjust settings manually.

• Working with sources: Include all the CVR-Lib sources directly in your project.
  • Add all CVR-Lib sources to the file view of your project workspace.
  • Indicate under Project->Settings->C/C++->Preprocessor for all configurations the directory path to all the cvr-headers. The directories you should provide are cvrlib\src\basics, cvrlib\src\imgProc, cvrlib\src\ioBasics, cvrlib\src\io, cvrlib\src\io\png, cvrlib\src\io\jpeg, cvrlib\src\basics, cvrlib\src\math, cvrlib\src\viewer, cvrlib\src\system, where cvrlib should be replaced with the absolute or relative path of your cvrlib directory.
  • Activate Project->Settings->C/C++->C++ Language:Enable RTTI.
  • You will also need to enlarge the heap used by the compiler with the option /Zm200. To to this just type this option in the small edit box at the bottom of the dialog window in Project->Settings->C/C++->General.
• Working with static library: compile the CVR-Lib to a static library (i.e. a *.lib file) and link that to your project.
  • Call the buildLib.bat batch file located in cvrlib\win\buildLib (Perl must be installed!). This will build the libraries in cvrlib\lib. Additionally all header-files will be collected and placed in cvrlib\lib\headerFiles.
  • Under Project->Settings->Link->General add cvrlib.lib to the debug configuration and rcvrlib.lib to the release configuration.
  • Under Project->Settings->C/C++->Preprocessor indicate the directory path to cvrlib\lib\headerFiles for all configurations.
  • Activate Project->Settings->C/C++->C++ Language:Enable RTTI.
  • Note: by default the lib is built with the option /MD resp. /MDd, i.e. the multi-threaded-dll run-time libraries are used. This means that MFC must be linked dynamically. However, if you need to use MFC in a static lib (not recommended), then you must set the variable v_buildDLLversion=0 in the Perl script createMakefile.pl beforehand.
• General: The cvr::viewer and other visualization classes are based on the GNU GIMP-Toolkit (GTK). To use it, you will need to access its header files and static linked libraries, and you will need to grant your system access to the DLL-libraries. You can get the original GTK+ libraries from here, or if you are in the techinfo.rwth-aachen.de domain, you can get a (maybe outdated) package with all required libraries from here. If you can get this last file, unpack it into the folder cvrlib\win. Otherwise, you should get the glib, gdk and gtk libraries from here, and install them in the directories cvrlib\win\gtk+, cvrlib\win\gtk+\gdk and cvrlib\win\glib.
  • Indicate under Project->Settings->C/C++->Preprocessor for all configurations the gtk directories. Those are cvrlib\win\gtk+, cvrlib\win\gtk+\gdk, cvrlib\win\glib
  • under Project->Settings->Link->Input you can specify the path to the gtk-*.lib files, e.g. cvrlib\win\lib
  • under Project->Settings->Link->General specify the following libraries to be linked with: glib-1.3.lib, gdk-1.3.lib, gtk-1.3.lib, gmodule-1.3.lib, gthread-1.3.lib
  • also the following libraries are required ws2_32.lib, psapi.lib and pdh.lib, with their respective DLLs. The last one (performance data helper) can be found here, or search the Microsoft Knowledge Base for article "Q284996".
  • don't forget to copy the *.dll libraries in your SYSTEM directory, or to specify the directory cvrlib\win\lib in your PATH-variable. The required seven GTK+ related DLL-Libraries are: gdk-1.3.dll, glib-1.3.dll, gmodule-1.3.dll, gnu-intl.dll, gthread-1.3.dll, gtk-1.3.dll, pthread.dll. And the pdh.dll is required to.

The cvr::processInfo class requires for Windows the libraries pdh.lib and pdh.dll, which are assumed to be in your default path. The cvr::url class requires the libraries ws2_32.lib and ws2_32.dll, which should be already in your default path.

Also check the CVR-Lib Tutorial which contains many screenshots of the installer for windows.