This document describes how to port ccdoc to a new platform.
The basic steps behind a port are
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):
| | |
| | +---> 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:
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 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 and license info into the
source code from copyright.txt.
release
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:
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.
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 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. 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.:
# 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 -incremental:no -stack:8000000 \ -pdb:${BIN_DIR}/ccdoc.pdb
LINK_OUT = -out:
include mktargs.mk
# GCC compiler, optimized mode, any platform.
# ================================================
PERL = perl
PLATFORM = $(shell $(PERL) ../utils/platform.pl)
CCDOC_CID = bin_opt_gcc_${PLATFORM}
BIN_DIR = ../${CCDOC_CID}
OBJ_EXT = o
CXX = g++
CXX_FLAGS = -c -w -O -DCCDOC_OPT -DCCDOC_CID=\"${CCDOC_CID}\"
CXX_OUT = -o
LINK_TARG = ${BIN_DIR}/ccdoc.exe
LINK = g++
LINK_FLAGS = -g
LINK_OUT = -o
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 -f 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.