ccdoc - Porting
Joe Linoff
$Revision: 1.4 $
$Date: 2001/09/24 20:23:00 $


This document describes how to port ccdoc to a new platform. To see the status of current ports click here.

The basic steps behind a port are

  1. Download the source files (src.tar.gz).
  2. Create a porting makefile (bin*.mk)
  3. Fix any problems in the source.
  4. Build and test.
  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/dtree.pl):

ccdoc_v08 ---+---> CVS    
|
+---> doc -----+---> CVS
| |
| +---> downloads -----+---> bin_opt_gcc_MSWin32
| | |
| | +---> bin_opt_msvc_MSWin32
| |
| +---> users_guide -------> CVS
| |
| +---> webdocs -----------> CVS
|
+---> src ---------> CVS
|
+---> test ----+---> CVS
| |
| +---> logs --------------> CVS
|
+---> utils -------> CVS

As you can see, there are four top level directories (ignoring CVS): doc, src, test and utils. The doc directory contains the documentation and the release data. 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.

All of the porting and development work in ccdoc occurs in the src directory.


Make Targets

^ < >

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

% gmake 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.
 depend Generate the include dependencies.
     in mkdepend.mk which is included by
     mktargs.mk.
 doc Generate the ccdoc documentation.
 help Help message.
 insert Insert the help and copyright info into
     the source code.
 insert_help
     Insert the help info into the source code.
     from help.txt.
 insert_copyright
     Insert the copyright info into the source code
     from copyright.txt.
 test Test the program (build if necessary).
Available makefile files:
 mkdbg_gcc.mk Debug, GNU g++ compiler.
     mkopt_gcc.mk Optimized, GNU g++ compiler.
     mkdbg_msvc.mk Debug, MS Visual C++ compiler.
     mkopt_msvc.mk Optimized, MS Visual C++ compiler.
     mkdbg_sun.mk Debug, Solaris CC compiler.
     mkopt_sun.mk Optimized, Solaris CC compiler.
Sample usages:
 % make -f mkopt_gcc.mk all
     % make -f mkopt_gcc.mk test
     % make -f mkopt_gcc.mk doc
Notes:
 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 mkdbg_sun.mk all
 The Makefile file handles the vanilla targets. The
     mkdepend.mk file has the dependencies. The mktargs.mk
     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.


Porting Makefile

^ < >

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 mktargs.mk 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/platform.pl.

The porting makefiles that I created for windows are:

Shown below is the contents of the mkopt_msvc.mk file:

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

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

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 mkopt_msvc.mk file:

% make mkopt_msvc.mk 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.