Compilation with Visual C++

1. Introduction

The goal of this document is to describe the file organization used for the build tree with Visual C++ on Windows. The main sections of this document are:

File organization
How to compile
How to create a new project

In the whole document, CIS is used as example but can be replaced by MRC or any other package name.

The source files are stored in a specific directory (source) and the compiled version in another directory (build). For the distribution, we also need to copy the headers files in the build directory. It is important to remember that the original header files from the source tree are used for the compilation of the library itself, CIS or MRC (this helps during the debug phase). The source directory is organized per module and the build directory contains the following sub-directories for the different binary versions:

An include directory (include)
A static library directory (Lib) containing:
- A release version (Release)
- A debug version (Debug)
A dynamic library directory (Dll) containing:
- A release version (Release)
- A debug version (Debug)

2. File organization

2.a. Main directories (users and developers)

When you work with a package (either CIS or MRC), you have three important directories at the base of the file hierarchy:

source contains the source files organized by modules (equivalent to libraries or applications).
unix contains the files to compile as well as the compiled files for unix like operating systems.
visual-c++ contains the tools to compile as well as the compiled files for an Intel based computer (i.e. PC) running Windows (either NT/2000 or 95/98/me) with Visual C++ installed (version 6.0).
This directory contains a main directory with all the Visual C++ projects and workspaces (projects) as well as a directory for all generated files (build) and a directory for temporary files (tmp).

To simplify the creation and maintainance of the projects and workspaces, we use a C++ application called mkProj. mkProj has been developped with CIS and MRC. The source code as well as the configuration files are in the directory visual-c++/mkproj. Any person who needs to compile CIS and/or MRC will need to compile mkProj first.

If you need to create a binary distribution tree, you just have to compile everything and then copy the include, Lib and Dll directories from the build directory..

2.b. mkProj

mkProj (stands for "make projects") needs to be compiled before anything else. Once the application is compiled, using the Visual-C++ project available for it (debug mode only), the user can start mkproj after leaving Visual-C++. By default, mkProj.exe is in visual-c++/mkproj and will load the configuration file visual-c++/mkproj/config/cis.txt. The GUI allows the user to load a different configuration file (e.g. mrc-2/visual-c++/mkproj/config/mrc.txt. Once the main configuration file is loaded, the user can add some options for the compiler or the linker and click on the "create projects" button.

mkProj can be configured using the text files in mkproj/config directory. The different fields of the configuration files can be modified with any text editor and include the list of source/header files, specific compiler/linker options and test programs. If one need more options, one can modified the source code of mkProj.

Some parts of CIS and MRC rely on proprietary packages which are not available to all programmers and users (e.g. Northern digital Optotrack for cisTracker, MEI dsp based controller card for mrcCard). For these, each user must provides some flags to specify some extra compiler flags (like include path) and linker flags (name of required library, path). The GUI allows to add simple options of the whole package. For more flexibility, one can modify the configuration files. All flags are directly used as is to create the projects, therefore the syntax is the one used in Visual C++. The following two files can be used as exemples: cisTracker.txt and cisCard.txt (note that the character # is used to preceed comments).

2.c. Project files

In the projects directory we have all projects and workspaces.

The file suffix is determined by Visual C++ (.dsp for project and .dsw for workspace). The basename of each project or workspace file should respect the following rules:

<ModuleName>Lib for a static library: cisVecsLib.dsp for the project and cisVecsLib.dsw for the workspace. If this library or executable relies on other projects, these should be included in the workspace.
<ModuleName>Dll for a dynamic library (DLL): cisVecsDll.dsp for the project and see above for workspace.
<ModuleName>Test1 for a test program (Test2, etc. for following test programs or at least a name which starts with Test...): cisVecsTest1.dsp
<ModuleName>Sample1 for a sample program (Sample2, etc. for following sample programs or at least a name which starts with Sample...): cisVecsSample1.dsp

2.d Build files

The result of compilations as well as a copy of all header files is stored in the directory build. This directory is created during the compilation and should only contain automatically generated files.
To avoid mixing object files for dll's and static libraries, we have two directories: Lib and Dll.
In each of these directories, the names are Visual C++ defaults, i.e. Debug for files compiled in debug mode and Release for release files. These directories don't have to be created manually, Visual C++ will create them as needed.

Since all Dlls are in the same directory, it is easier to update your path to run applications based on Dll. Dll's are grouped in the build directory under visual-c++\build\Dll\Debug or visual-c++\build\Dll\Release.

The tree looks like this:

--+---- source (contains all code)
  |
  +---- unix (contains unix makefiles)
  |
  +--+- visual-c++
     |
     +--+- build (everything generated, binary distribution)
     |  |
     |  +---- include (copies of all headers)
     |  |
     |  +--+- Dll (dynamic libs ...)
     |  |  |
     |  |  +---- Debug (... for debug)
     |  |  |
     |  |  +---- Release (... for release)
     |  |
     |  +--+- Lib (static libs ...)
     |     |
     |     +---- Debug (... for debug)
     |     |
     |     +---- Release (... for release)
     |
     +--+- mkproj
     |  |
     |  +---- src (source code and project to compile mkProj)
     |  |
     |  +---- config (text configuration files used by mkProj)
     |  |
     |  +---- Debug/Release (files generated by Visual C++)
     |
     +---- projects (contains projects and workspaces, cisVecsDll.dsp)
     |
     +--+- tmp (temporary files for ...)
        |
        +--+- Dll (... dynamic libs ...)
        |  |
        |  +---- Debug (... for debug)
        |  |
        |  +---- Release (... for release)
        |
        +--+- Lib (... static libs ...)
           |
           +---- Debug (... for debug)
           |
           +---- Release (... for release)

As usual, each directory contains a sub directory CVS and PLEASE DO NOT delete, change or modify it..

3. How to compile

The first step is to compile mkProj. Go in cis-2/visual-c++/mkproj/src and open mkproj.dsw. In Visual C++, select the "build" option and quit. The executable should be cis-2/visual-c++/mkproj/mkproj.exe.

Using mkProj, we need to create the Visual C++ projects. To do so, start mkProj and:

For CIS, the main configuration file name should be set as default. Click the "load configuration" button followed by the "create projects" one. that's it, you can quit mkProj.
For MRC, you have to find the main configuration file. Select the browse option and load mrc-2/visual-c++/mkproj/config/mrc.txt. Then click the "create projects" button and quit.

Once the projects and workspaces have been created, you have two solutions; Compile everything or compile a sub part you are interested in.

To compile everything, you have to open the main workspace file: visual-c++\projects\<PackageName>.dsw. Inside Visual C++, you can select the menu "Build"->"Batch Build", select every project and hit the button "Rebuild All".
To compile a sub part, open the workspace which corresponds to the library you need. You can open the higher level library since its workspace should include all the required dependencies. To compile, select the menu "Build"->"Batch Build", select every project and hit the button "Rebuild All".

4. How to create a new project

To create a new VC++ project, you must first have the code in place in the source tree, i.e. in <PackageRoot>\source\<ModuleName>\include and <PackageRoot>\source\<ModuleName>\src (e.g. cis\source\cisVecs\include). The code itself should respect the programming guidelines.

Then, you will have to add the module name in the main configuration files (cis.txt or mrc.txt) and create a configuration file for the new module. There is no complete documentation of the configuration file syntax, thus the most practical way to create a configuration file is to start from and existing one.

Last modified: Fri Jun 21 17:23:43 Pacific Daylight Time 2002