OSE - Tools User Guide

Graham Dumpleton
Dumpleton Software Consulting Pty Limited
PO BOX 3150
Parramatta, 2124
N.S.W, Australia
email: grahamd@nms.otc.com.au

Table of Contents

Mksrc Program
OSE - Tools User GuideMksrc Program

Mksrc Program

1 What is Mksrc

The mksrc program is used to create files following a predefined template. The files will contain a comment block listing the name of the file, authors and a copyright notice. In the case of header files, the contents will be surrounded by a `#ifndef' guard. Depending on the type of file, other information and skeletal implementation information can be incorporated into the file. The types of files which can currently be created include header files, source files and makefiles.

The program determines what type of file it should create, by matching patterns against the name of the file you wish to create. The default patterns recognised and the file types they correspond to are given below.

--------------------------------------------------
Filename Pattern                       File Type    
--------------------------------------------------
*.h *.hh *.hxx *.hpp *.H               Header file  
*.c *.cc *.cxx *.cpp *.C               Source file  
makeit.mk Makeit.mk makefile Makefile  Makefile     
--------------------------------------------------
To obtain a full list of the patterns which the mksrc program understands, execute mksrc with the `-dump' option. For example:

  mksrc -dump
To create files, list the names of the files on the command line when executing mksrc. For example:

  mksrc foo.hh foo.cc bar.hh
The output of the mksrc program for certain file types can be customised by providing additional options to mksrc. Options for customising the output, will always be of the form `-DVARIABLE' or `-DVARIABLE=VALUE'. For example, to create a C++ source file which includes a main() routine, you would run:

  mksrc -DMAIN foo.cc
A list of the variables which can be set for a particular file type, can be found by listing the `-help' option on the command line when running mksrc. For example:

  mksrc -help foo.cc
This will not result in the file being created, but will display the help file associated with that type of file.

If you need to always define certain flags, you can list those options in the environment variable MKSRC_FLAGS. For example:

  MKSRC_FLAGS="-DORGANISATION=\"ACME Software Corporation\""

2 Configuration File

The mksrc program can be used to create files from a predefined template. However, the mksrc program does not actually create these files; instead, mksrc is a front end, calculating which program should be run to generate a file, and then running that program. Information as to which program should be run is stored in a configuration file. The default configuration file is shown below.

  *.h        mkheader    mkheader.hlp
*.hh mkheader mkheader.hlp
*.hxx mkheader mkheader.hlp
*.hpp mkheader mkheader.hlp
*.H mkheader mkheader.hlp

*.c mksource mksource.hlp
*.cc mksource mksource.hlp
*.cxx mksource mksource.hlp
*.cpp mksource mksource.hlp
*.C mksource mksource.hlp

makeit.mk mkmakefile mkmakefile.hlp
Makeit.mk mkmakefile mkmakefile.hlp
makefile mkmakefile mkmakefile.hlp
Makefile mkmakefile mkmakefile.hlp
Each line in the configuration file has three fields. The first field is a wildcard pattern, that is matched against the name of the file you wish to create, to work out which program should be run to create the file. The second field is the name of the program to run, to create a file matching the pattern listed in the first field. If the name of the program is not defined using an absolute pathname, it is expected that the program resides in the same directory as the configuration file. The third field is the name of a help file, for the program listed in the second field. The help file will be displayed when the `-help' option is used, together with the name of the file you want to create. The help file will describe the various symbols which can be defined, to customise what the program listed in the second field generates. The listing of a help file in the third column is optional. Any text appearing after the character `#', is regarded as a comment, and is discarded before interpreting the line.

If you asked mksrc to create a file called `obj1.cc', it will apply the patterns listed in the first field of each line in order, until it finds one which matches. In this case, the pattern `*.cc' will match. Once mksrc has found a pattern which matches the name of the file you want to create, it will run the program listed in the second column, in this case the program called mksource. The name of the file you wish to create, along with any symbol definitions, will be passed as command line arguments to the program, when it is run by mksrc. If you asked mksrc to create more than one file, the program to create the file will be run more than once, each time being supplied a different file name.

For example, if you had originally run \code{mksrc} with the options:

  mksrc -DLIBNAME=MYLIB -DDIRNAME=part1 h1.hh o1.cc o2.cc
the following commands would in turn be run by mksrc.

  mkheader -DLIBNAME=MYLIB -DDIRNAME=part1 h1.cc
mksource -DLIBNAME=MYLIB -DDIRNAME=part1 o1.cc
mksource -DLIBNAME=MYLIB -DDIRNAME=part1 o2.cc

3 Adding New File Types

If you want to add new file types, you can define your own configuration file. This file must be called `mksrc.cf' and follow the format described above. For example, you may wish to add support for generation of Yacc and Lex files.

  *.y  mkyacc
*.l mklex
So that mksrc can find your configuration file and the associated programs, you must set the environment variable MKSRC_PATH to the name of the directory containing your configuration file. If you need to specify more than one directory, each directory should be separated by a `:'. For example:

  MKSRC_PATH="$HOME/lib:/home/projects/simulator/mksrc"
You do not need to define the location of the default configuration file; it will be searched automatically, after all the other configuration files have been read. If there is a file called `mksrc.cf' in the directory in which you run mksrc, it will be read before all other files, even if that directory isn't listed in the MKSRC_PATH variable.

When mksrc is run, it will try matching the patterns in each of the configuration files against the name of the file you wish to create. Once a pattern matching the name of the file has been found, the search will stop and the program for that pattern will be used to generate the file. If you have defined a pattern, which is the same as one which appears in a later file, your pattern will override the other pattern. Therefore, you could provide your own program for creating header files. For example:

  *.h  mymkheader

4 Grouping Patterns

If you override a pattern in your own configuration file, you lose the ability to use the program for the pattern you have overridden. If you know that a pattern will be overridden, you can add an additional tag to the start of the original pattern so you can still access it. For example, the default configuration file contains the following lines, in addition to those already listed above.

  ose/*.h        mkheader    mkheader.hlp
ose/*.hh mkheader mkheader.hlp
ose/*.hxx mkheader mkheader.hlp
ose/*.hpp mkheader mkheader.hlp
ose/*.H mkheader mkheader.hlp

ose/*.c mksource mksource.hlp
ose/*.cc mksource mksource.hlp
ose/*.cxx mksource mksource.hlp
ose/*.cpp mksource mksource.hlp
ose/*.C mksource mksource.hlp

ose/makeit.mk mkmakefile mkmakefile.hlp
ose/Makeit.mk mkmakefile mkmakefile.hlp
ose/makefile mkmakefile mkmakefile.hlp
ose/Makefile mkmakefile mkmakefile.hlp
The tag in this case is `ose'. It is placed before the pattern, and separated from it by a `/' character. The tag has the effect of grouping the patterns into a scope. The patterns will only be matched against the name of the file you want to create, when you tell mksrc to search the scope defined by that tag. For example, if you had overridden the pattern `*.h', you can still access the pattern provided in the default configuration by running mksrc as follows:

  mksrc -group ose header.h
When you define your own patterns, which override the defaults, you should add additional definitions which add them to a specific group. This way, if your definitions are later overridden, you can still access them. For example:

  *.h          mymkheader

mystuff/*.h mymkheader
Grouping patterns using a tag, is also useful if you need to use a different format for a file at different times. For example, if you use a number of different graphics libraries, where the structure of the main() program loop for each is different, you could include the following in your configuration file.

  xmain/*.c  mkxmainprogram  # creates Xt main loop
ivmain/*.c mkivmainprogram # creates InterViews main loop

5 Creation of Files

When mksrc runs a program to create a file, it will pass on the name of the file to be created, and any arguments to mksrc that match the patterns `-D*=*' and `-D*'. The purpose of the `-D' options is to define special symbols, or customise what is output by the program creating the file. How your program interprets the options, depends on what you want your program to do. An example of how you can implement a program to create a new type of file is given below. This example is the mkmakefile program which is supplied.

  #! /bin/sh

# Set some defaults.

AUTHOR=${MKSRC_AUTHOR-"???"}
ORGANISATION=${ORGANISATION-"WIZZ BANG SOFTWARE"}
YEAR=${YEAR-19`date +%y`}

FILENAME=""

# Usage message.

USAGE()
{
P=`basename $0`
echo "Usage: $P [ -DNAME -DNAME=VALUE ] filename" 1>&2
exit 1
}

# Parse the command line.

while test "$#" != 0
do
case "$1" in
-D*=*)
EVAL="`echo $1 | sed -e `s/^-D//' \
-e `s/=/=\"/' -e `s/$/\"/'`"
eval ${EVAL}
;;
-D*)
EVAL="`echo $1 | sed -e `s/^-D//'`"
eval ${EVAL}=1
;;
-*)
USAGE
;;
*)
if test "${FILENAME}" != ""
then
USAGE
fi
FILENAME=$1
;;
esac
shift
done

# Check that a filename has been given and that the file
# doesn't exist.

if test "${FILENAME}" = ""
then
USAGE
fi

if test -f "${FILENAME}"
then
echo "`basename $0`: ${FILENAME} already exists" 1>&2
exit 1
fi

# Do it.

echo "`basename $0`: ${FILENAME}"

cat >> ${FILENAME} << EOT
# Copyright ${YEAR} ${ORGANISATION}

# Makeit Initialisation.

MODULES := c cc ose

include makeit/init.mk

# Module Initialisation/Definitions.

SUBDIRS :=

PROGRAMS :=
EXCLUDE :=
NONLIBSRC :=

CPPFLAGS :=
CFLAGS :=
C++FLAGS :=
LDFLAGS :=
LDLIBS :=

include makeit/modules.mk

# Additional Dependencies/Rules.

EOT