## 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/dtree.pl):

> 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 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:

- mkopt_msvc.mk - Microsoft Visual C++ compiler, optimized mode.
- mkopt_gcc.mk - GNU G++ compiler, optimized mode.
- mkdbg_msvc.mk - Microsoft Visual C++ compiler, debug mode.
- mkdbg_gcc.mk - GNU G++ compiler, debug mode.

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

> Figure 3. mkopt_msvcc.mk
>     # ================================================
>     # 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

> Figure 4. mkopt_gcc.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.

> 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 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.

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