ccdoc home page
CcDoc Porting Guide
Joe Linoff
$Revision: 1.2 $
$Date: 2003/02/26 18:45:35 $

This document describes how to port ccdoc to a new platform.

The basic steps behind a port are

  1. Download the source files (src.tar.gz).
  2. Create two porting makefiles for debug and optimized targets of the form mkdbg_<compiler>.mk and mkopt_<compiler> where the if you are using a <compiler> is the name of your compiler. If you are using the gcc compiler or any other compiler that is already supported, you do not need to do this.
  3. Fix any problems in the source.
  4. Build and test by cd'ing into the src directory and typing 'make -f mkopt_<compiler> all'.
  5. Ship the new executable (or the path to it) and description of the changes to me, as described on the "Submit a Port" page.
  6. I will then add it to the downloads page.

Before going into the details of how to create a porting makefile, some basic information about the physical structure of ccdoc is presented. First, the directory structure is described and then the make targets are described. After that there is a discussion of how to create the porting makefile and build the program.

Directory Structure

^ < >

The directory structure of ccdoc is shown below (this picture was generated using ccdoc_v08/utils/

Figure 1. The ccdoc directory structure
 ccdoc ---+---> doc -----+---> htdocs --------+---> introduction 
| | |
| | +---> users_guide
| |
| +---> issues
| |
| +---> users_guide
+---> src
+---> test
+---> utils

As you can see, there are four top level directories: doc, src, test and utils. The doc directory contains the documentation. The src directory contains the source code and the make files. The test directory contains the test data and the utils directory contains various utilities.

The release information is generated by the release target.

All of the porting and development work in ccdoc occurs in the src directory. That is where all of the make targets are run.

Make Targets

^ < >

In the source directory you can get additional information on make targets by typing "make" or "gmake". Here is the output:

Figure 2. "make help"
CCDOC Makefile Help

Available targets:

all Build the program and run the tests.

backup Backup the source to a taz file.

bld Build the program only.

clean Clean up for a specific architecture.

cleanall Clean up for all architectures.

depend Generate the include dependencies.
in which is included by

doc Generate the ccdoc documentation.

help Help message.

insert Insert the help and copyright info into
the source code.

Insert the help info into the source code.
from help.txt.

Insert the copyright and license info into the
source code from copyright.txt.

rel Create the release in ../release directory
and create the tar ball ../release/tarball.taz.

test Test the program (build if necessary).

Available makefile files: Debug, GNU g++ compiler. Optimized, GNU g++ compiler. Debug, MS Visual C++ compiler. Optimized, MS Visual C++ compiler. Debug, Solaris CC compiler. Optimized, Solaris CC compiler.

Sample usages:

% make -f all
% make -f test
% make -f doc


To make a purify or quantify version of the program,
set the LINK_PREFIX to the appropriate value as shown
in the example below:

% setenv LINK_PREFIX purify
% make -f all

The Makefile file handles the vanilla targets. The file has the dependencies. The
file contains the complex targets.

The other mk<dbg>_* and mk<opt>_* files define the
personality of the compiler and the linker. They also
where output (binary) directory.

The Porting Makefile: mkopt_<compiler>.mk

^ < >

The porting makefile is a file with a mkopt or mkdbg prefix and a .mk suffix that describes the platform dependent variables that the Makefile and files need to build the program. The name of the porting makefile that you create should contain information about the compiler. The platform should be handled automatically by utils/ If it isn't you will need to update that file.

The porting makefiles that I created for windows are:

Shown below are contents of the optimized platform makefiles for the Microsoft Visual C++ compiler and the GNU G++ compiler.:

Figure 3.
# ================================================
# MSVC compiler, optimized mode, windows platform.
# ================================================
PERL = perl
PLATFORM = $(shell $(PERL) ../utils/
CCDOC_CID = bin_opt_msvc_${PLATFORM}
OBJ_EXT = obj
CXX = cl
CXX_FLAGS = -Fd${BIN_DIR}/ccdoc.pdb -TP -nologo \ -c -O2 -GX -DCCDOC_OPT -DCCDOC_CID=\"${CCDOC_CID}\"
LINK_TARG = ${BIN_DIR}/ccdoc.exe
LINK = link
LINK_FLAGS = -nologo -incremental:no -stack:8000000 \ -pdb:${BIN_DIR}/ccdoc.pdb
LINK_OUT = -out:



Figure 4.
# ================================================
# GCC compiler, optimized mode, any platform.
# ================================================
PERL = perl
PLATFORM = $(shell $(PERL) ../utils/
CCDOC_CID = bin_opt_gcc_${PLATFORM}
CXX = g++
CXX_OUT = -o
LINK_TARG = ${BIN_DIR}/ccdoc.exe
LINK = g++


Here is a brief description of the variables that you need to change. The other variables are derived from these.

Table 1. Porting Make Variables
Variable Description
CCDOC_CID The name of the binary directory. You need to change the msvc string to your compiler string.
CXX The name of the C++ compiler.
CXX_FLAGS The compiler flags for debug or optimized mode.
CXX_OUT The flag used for describing the output file. For the MSVC compiler, there should be no spaces after -Fo. For unix compilers there should be a space after -o.
LINK The name of the linker. In most cases this will be the same as CXX.
LINK_FLAGS The linker flags for debug or optimized mode.
LINK_OUT The flag used for describing the output file. For the MSVC compiler, there should be no spaces after -out:. For unix linkers there should be a space after -o.
OBJ_EXT The object file extension. For unix this should be o.
PERL The name of the perl executable.

Building the Program

^ < >

Once the porting makefile has been created, you attempt to build the program using the all target. If the build fails, correct the source and try again. If the build passes you have finished porting.

Here is a sample run for the file:

% make -f all

It is important to note here that you may have to strip out the line feeds from the source code in order to get things to work properly. This is because I develop ccdoc on a windows platform under the cygwin/gnu environment.

$Id: porting_guide.htm,v 1.2 2003/02/26 18:45:35 jlinoff Exp $