This manual is based on the Tcl/Tk Engineering Manual by
John K. Ousterhout. It is available at
http://www.scriptics.com/doc/engManual.ps. Most of this document
is a subset of what his manual specifies, with the goal of being more
practical and up-to-date than the original. For example, it is assumed
that only an ANSI compiler will be used, whereas the Ousterhout's
manual describes conventions that will also work with non-ANSI
compilers. The Tcl/Tk Engineering Manual is still recommended
reading, particularly with respect to the section on code
documentation, which is not reproduced here.
Table of Contents
Overall structure
Each module will be named nsxxx, where xxx is a short
name that describes the module. Each module will have its own
directory, and contain at least the following files:
If a module exports symbols, then a header file by the name of
nsxxx.h should also be in that directory.
Makefile structure
Use this as a template for module makefiles:
Header file structure
Use this as a template for all header files:
Header files never contain static symbols.
Code file structure
Each source code file should contain a related set of procedures. The
most manageable size for files is usually in the range of 500-2000
lines. Code files are divided into pages separated by formfeed
(control-L) characters, which must appear before each function
definition. Closely related function should be placed as close
together as possible.
API functions (Ns_*) come first; exported functions that are not API
calls (Ns*) come after those; static functions come last. Logical
groups of functions can be separated like this:
Use this as a template for all code files:
Source files should never contain extern statements; those belong
in header files (called file.h in the above template).
Function definitions
Function definitions should follow this template:
All functions definitions begin on a new page (which is to say they
should be preceeded by a control-L character). All functions must be
typed: use void if the function returns no result. The second line
gives the function's name and argument list. If there are many
arguments, they should spill onto additional lines as such:
The same rule applies to prototypes.
Parameter order
Function parameters may be divided into three categories. In
parameters only pass information into the function (either directly or
by pointing to information that the function reads). Out
parameters point to things in the caller's memory that the function
modifies. In-out parameters do both. Below is a set of rules
for deciding on the order of parameters to a function:
Naming conventions
Basic syntax rules
Function names contain meaning
Public exported functions that are part of the API should begin with
Ns_, as in:
Functions that are to be used by other files in a module, but are
not meant to be called from outside the module, should begin with Ns,
as in:
Global variables that do not have static scope begin with ns, as in:
C implementations of Tcl commands should be static functions ending
with Cmd, as in:
# @(#) $Header: /cvsroot/aolserver/aolserver3/doc/cdev/eng-manual.html,v 1.1.1.1 2000/03/17 07:10:47 kriston Exp $
#
# Make sure that all variables are defined
#
DIRNAME = nsmodule
ifndef SRCBASE
SRCBASE = $(shell cd ..; pwd)
include ../makevars
endif
#
# Define the output files
#
LIB = nsmodule.so
#
# Set the libraries
#
LIBS=
#
# Set the objects to build
#
OBJS = nsmodule.o
#
# Let the building begin!
#
all: $(LIB)
%.o: %.c
$(CC) -c $(CFLAGS) $(SRCBASE)/$(DIRNAME)/$< -o $@
#
# Build the final target(s)
#
$(LIB): $(OBJS)
$(LDSO) $(LDSOFLAGS) -o $(LIB) $(OBJS)
install: all
cp $(LIB) $(ROOTDIR)/bin
clean:
$(RM) $(LIB) $(OBJS) so_locations
/*
* The contents of this file are subject to the AOLserver Public License
* Version 1.1 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://aolserver.lcs.mit.edu/.
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is AOLserver Code and related documentation
* distributed by AOL.
*
* The Initial Developer of the Original Code is America Online,
* Inc. Portions created by AOL are Copyright (C) 1999 America Online,
* Inc. All Rights Reserved.
*
* Alternatively, the contents of this file may be used under the terms
* of the GNU General Public License (the "GPL"), in which case the
* provisions of GPL are applicable instead of those above. If you wish
* to allow use of your version of this file only under the terms of the
* GPL and not to allow others to use your version of this file under the
* License, indicate your decision by deleting the provisions above and
* replace them with the notice and other provisions required by the GPL.
* If you do not delete the provisions above, a recipient may use your
* version of this file under either the License or the GPL.
*/
/*
* file.h --
*
* Description of file.
*
*/
#ifndef FILE_H
#define FILE_H
static const char *RCSID_FILE_H = "@(#) $Header: /cvsroot/aolserver/aolserver3/doc/cdev/eng-manual.html,v 1.1.1.1 2000/03/17 07:10:47 kriston Exp $, compiled: " __DATE__;
/*
* The following constants...
*/
#define ...
/*
* The following structure defines...
*/
typedef struct ...
/*
* Exported functions
*/
extern ...
#endif /* FILE_H */
/*
*==========================================================================
* ModLog functions begin here
*==========================================================================
*/
/*
* The contents of this file are subject to the AOLserver Public License
* Version 1.1 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://aolserver.lcs.mit.edu/.
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is AOLserver Code and related documentation
* distributed by AOL.
*
* The Initial Developer of the Original Code is America Online,
* Inc. Portions created by AOL are Copyright (C) 1999 America Online,
* Inc. All Rights Reserved.
*
* Alternatively, the contents of this file may be used under the terms
* of the GNU General Public License (the "GPL"), in which case the
* provisions of GPL are applicable instead of those above. If you wish
* to allow use of your version of this file only under the terms of the
* GPL and not to allow others to use your version of this file under the
* License, indicate your decision by deleting the provisions above and
* replace them with the notice and other provisions required by the GPL.
* If you do not delete the provisions above, a recipient may use your
* version of this file under either the License or the GPL.
*/
/*
* file.c --
*
* Description of file.
*/
static const char *RCSID = "@(#) $Header: /cvsroot/aolserver/aolserver3/doc/cdev/eng-manual.html,v 1.1.1.1 2000/03/17 07:10:47 kriston Exp $, compiled: " __DATE__ " " __TIME__;
#include "file.h"
/*
* The following constants...
*/
#define ...
/*
* The following structure defines...
*/
typedef struct ...
/*
* Local functions defined in this file
*/
static int FunctionName(int x);
/*
* Static variables defined in this file
*/
static int nsNumFooBar; /* Number of foobars allocated */
...
/*
*==========================================================================
* API functions
*==========================================================================
*/
(API function definitions go here)
/*
*==========================================================================
* Exported functions
*==========================================================================
*/
(Exported, non-api functions go here)
/*
*==========================================================================
* Static functions
*==========================================================================
*/
(Static functions go here)
^L
/*
*----------------------------------------------------------------------
* FunctionName -
*
* Description of function.
*
* Results:
* This function returns ...
*
* Side effects:
* A new thread will be created.
*
*----------------------------------------------------------------------
*/
static int
FunctionName(int x)
{
...
}
static int
FunctionThatTakesLotsOfParameters(int a, int b, int c, int d, int e,
int f, int g)
{
...
}
int nsThreadTimeout;
char buf[32];
typedef int (Ns_OpProc) (void *argPtr, Ns_Conn *connPtr)
Ns_OpProc *opProc;
extern int Ns_ConnPort(Ns_Conn *conn);
extern void NsDbInit(void);
Ns_Cache *nsAdpCachePtr = NULL;
static int RegisterTagCmd(ClientData ignored, Tcl_Interp *interp,
int argc, char **argv);