%  devmake.tex from ObjectProDSP 0.2
%  Copyright (C) 1994 1995, Mountain Math Software. All rights reserved.
%  
%  This file is part of ObjectProDSP, a tool for Digital Signal
%  Processing design, development and implementation. It is free
%  software provided you use and distribute it under the terms of
%  version 2 of the GNU General Public License as published
%  by the Free Software Foundation. You may NOT distribute it or
%  works derived from it or code that it generates under ANY
%  OTHER terms.  In particular NONE of the ObjectProDSP system is
%  licensed for use under the GNU General Public LIBRARY License.
%  Mountain Math Software plans to offer a commercial version of
%  ObjectProDSP for a fee. That version will allow redistribution
%  of generated code under standard commercial terms.
%  
%  This program is distributed in the hope that it will be useful,
%  but WITHOUT ANY WARRANTY; without even the implied warranty of
%  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
%  GNU General Public License for more details.
%  
%  You should have received a copy of version 2 of the GNU General
%  Public License along with this program. See file COPYING. If not
%  or if you wish information on commercial versions and licensing
%  write Mountain Math Software, P. O. Box 2124, Saratoga, CA 95070,
%  USA, or send us e-mail at: support@mtnmath.com.
%  
%  You may also obtain the GNU General Public License by writing the
%  Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
%  USA.  However if you received a copy of this program without the
%  file COPYING or without a copyright notice attached to all text
%  files, libraries and executables please inform Mountain Math Software.
%  
%  ObjectProDSP is a trademark of Mountain Math Software.
%  
\section{Building \Dpp{} and {\protect\tt makemake}}
\label{Sec:makemake}

The \DppNm{Makefile}s used to generate utilities and \Dpp{} executables are
created by a custom \DppNm{makemake} utility. This utility is less
flexible then \DppNm{imake} but very much faster. It knows about much
of the structure of \Dpp{} such as the relationship between
\DppNm{.usr} files, \DppNm{.C} files and menu files. It
does not use the C preprocessor to expand source so
it is sometimes necessary
to create dummy headers to prevent warning messages about missing
files that are conditionally included. 

It is outside the
current scope of this manual to fully document this utility.
Figure~\PageRef{Fig:MakeMakeOpt} is a terse synopsis of its
options. Some of these are obsolete or for future expansion.

\renewcommand{\outtokcaption}{\protect\protect\DppNmn{makemake}
	command line options }
\renewcommand{\outtoklabel}{Fig:MakeMakeOpt}
\input{makemakeopt.tex}

In this section we will describe how you invoke \DppNm{makemake},
where its gets its input from and what you need to do add or
delete a directory
or \DppNm{.usr} file to the existing structure. To add a
\DppNm{.C} or \DppNm{.h} file to a directory in which such
files already exist you only need to add them and regenerate
the \DppNm{Makefile}s.

\subsection{Project description}

In each directory in which an executable is constructed there
is a file \DppNm{do\-make\-make} which invokes \DppNm{makemake}
to create all needed \DppNm{Makefiles}. The \DppNm{Makefile}
created in this main directory
is made dependent on \DppNm{do\-make\-make} so subsequent
\DppNm{Makefile}'s will be updated if you change \DppNm{do\-make\-make}.

The master directory is the first argument for the \DppNm{-m} option
in \DppNm{makemake}. Subsequent arguments indicate additional
directories with \DppNm{.C} files. Directories with \DppNm{.C}
files can also be designated with the \DppNm{-l}~option. 
Libraries are constructed in these directories.

The \DppNm{Makefile}s created are independent. The master
\DppNm{Makefile} for the main directory will by default invoke all
other \DppNm{Makefile}s. If you do {\tt make Target}\index{Target}
\index{make Target} then none of the other \DppNm{make}s will be done.
If you change a single file you only need to do a \DppNm{make}
for the directory in which that file occurs and a {\tt make Target}
in the main directory. Of course if you change a header file it is
generally necessary to run \DppNm{make} on all the \DppNm{Makefile}s.

Most often the \DppNm{-sc} option is used
so the compiles are done in a subdirectory off the directory containing
the source code. This allows the same source to be used
to generate multiple libraries and executables with different
compile time flags.
The master \DppNm{do\-make\-make}~is in this subdirectory of
the directory specified by the first argument to \DppNm{-m}.
A single \DppNm{makemake} can generate \DppNm{Makefile}s
for many different directories. If \DppNm{-sc} is used
a subdirectory will be created for every directory under 
the \DppNm{-m} and \DppNm{-l}~options.

Typically a number of files are read by \DppNm{do\-make\-make}.
These include script files in {\tt \$OPD\_ROOT/\-scripts}
\index{scripts directory} and various \DppNm{head}, \DppNm{inc} and
\DppNm{tail} files in various directories.
File \DppNm{SYSTEM} in the \DppNm{scripts} directory determines
the operating system the make is for. This influences what \DppNm{head}
and \DppNm{tail} files will be incorporated in the \DppNm{Makefile}
by defining a suffix for this search.
Comments in the \DppNm{Makefile} show what files are included and
at what point.

The algorithm for selecting these files is as follows.
\begin{enumerate}
\item{\DppNm{Makefile\_head*}} --- include all with searched suffixes in
searched directories at the start of the \DppNm{Makefile}.
\item{\DppNm{Makefile\_inc*}} --- include all with searched suffixes in
searched directories at the end of the \DppNm{Makefile}.
\item{\DppNm{Makefile\_tail*}} --- include exactly one file. If multiple files
with searched suffixes are present choose the first one in the search sequence.
This is the last part of the \DppNm{Makefile}.
\end{enumerate}

The search sequence looks in generic places (such as the 
\DppNm{scripts} directory) first and in specific places last.
This sequence is {\it inverted} when only a single file is included
for \DppNm{Makefile\_tail}. In all other cases all matching files are
included.

The serach sequence for directories is as follows.

\begin{enumerate}
\item{\verb"$OPD_ROOT/scripts"}.
\item{Directory that is the first argument to \DppNm{-m} (main directory).}
\item{\DppNm{-sc} specified subdirectory of main directory.}
\item{The directory for which this \DppNm{Makefile} is being generated
(from a \DppNm{-m} or \DppNm{-l} argument).}
\item{The \DppNm{-sc} subdirectory of the directory for which this
\DppNm{Makefile} is being generated. (The \DppNm{Makefile} is placed in this
subdirectory.)}
\end{enumerate}

The serach sequences for suffixes is as follows.

\begin{enumerate}
\item NULL suffix.
\item {\tt .}{\it name} where {\it name} is the first line in file
\DppNm{\$OPD\_ROOT/\-scripts/\-SYSTEM}.
\end{enumerate}

The search first looks for all suffixes in a directory and then moves
on to the next directory.

\subsection{Building \protect\Dpp{}}

{\tt README} in \DppNm{\$OPD\_ROOT/\-build} contains
instructions for building \Dpp{} from the source distribution.
Tables~\PageRef{Tab:WhereBuildDoc} through \PageRef{Tab:WhereBuildUtil}
gives the directories for
building specific components of \Dpp{}. 
You should only need to go to one of these directories and enter
\DppNm{make} to update one of these components. 

\begin{table}
\begin{tabular}{|lll|} \hline
Directory & Object  & Purpose\\
\DppNm{\$OPD\_ROOT/doc/} & \DppNm{\$OPD\_ROOT/doc/} & \\  \hline 
\DppNm{build} & {\it all {\tt .dvi} files} & \\
\DppNm{devman} & \DppNm{devman/devman.dvi} & \DppDev{} \\
\DppNm{overview} & \DppNm{overview/overview.dvi} & \DppTut{} \\
				&  \DppNm{overview/nodeman.dvi} & \DppLib{} \\
\DppNm{roff} & \DppNm{.hlp} files  & \DppNm{groff} to \DppNm{.hlp}
	and \DppNm{.tex} format \\
\DppNm{roff/mmake} & \DppNm{doc/roff/Makefile} & create {\tt Makefile} from
	lists of help files\\
\DppNm{userman} & \DppNm{userman/userman.dvi} & \DppUser{} \\
\hline
\end{tabular}
\caption{Directories for creating documentation}
\label{Tab:WhereBuildDoc}
\end{table}





\begin{table}
\begin{tabular}{|lll|} \hline
Directory & Object  & Purpose\\
\DppNm{\$OPD\_ROOT/src/} & \DppNm{\$OPD\_ROOT/bin/} & \\  \hline 
\DppNm{gui/build/iv} & \DppNm{opd\_gui\_exe} & user interface process \\
\DppNm{dsp/build/fltgui} & \DppNm{opd\_dsp\_exe} & floating point DSP process \\
\DppNm{dsp/build/int16gui} & \DppNm{opd\_dsp\_exe} & 16 bit integer DSP process \\
\DppNm{start\_up} & \DppNm{opd} & executable to start both processes \\
\DppNm{genlib/opdgen/opdgeno} & \DppNm{\$OPD\_ROOT/lib/} & generic library \\
& \DppNm{Libopdgen} & \\
\DppNm{\$OPD\_ROOT/build} & {\it everything} & \\
\hline
\end{tabular}
\caption{Directories for creating interactive libraries and executables}
\label{Tab:WhereBuildExe}
\end{table}



\begin{table}
\begin{tabular}{|lll|} \hline
Directory & Object  & Purpose\\
\DppNm{\$OPD\_ROOT/src/dsp/lib/Target/} & \DppNm{\$OPD\_ROOT/lib/} & \\  \hline 
\DppNm{tarflt} &  \DppNm{LibTarLnxFlt} & stand alone float libraries \\
 & \DppNm{TarnobenchmFlt} & \\
\DppNm{tarint} &  \DppNm{LibTarLnxInt16} & stand alone 16 bit libraries \\
 & \DppNm{TarnobenchmInt16} & \\
\hline
\end{tabular}
\caption{Directories for creating target libraries}
\label{Tab:WhereBuildTarget}
\end{table}

\begin{table}
\begin{tabular}{|lll|} \hline
Directory & Object  & Purpose\\
\DppNm{\$OPD\_ROOT/src/util/} & {\$OPD\_ROOT/bin/} & \\  \hline 
\DppNm{hyphen} & \DppNm{cp\_part} & copy selected part of file \\
	& \DppNm{hyphen} & add hyphenation for \LaTeX{} \\
 	& \DppNm{toc\_depth} & \LaTeX{} table of contents filter \\
\DppNm{indextex/ix} & \DppNm{indextex} & create index for \LaTeX{} \\
\DppNm{makemake/mk} & \DppNm{makemake} & \DppNm{Makefile} generator \\
\DppNm{maketex/mktex} & \DppNm{maketex} & create lists of files in a directory \\
\DppNm{mkmenu/menuo} & \DppNm{domenus} & create menu data base code \\
\DppNm{mknode} & \DppNm{mknode/mkndoeo} & translate \IntPp{} source \\
\DppNm{nametrans} & \DppNm{nametrns} & adds conditional include to header \\
 &  & used in \DppNm{\$OPD\_ROOT/bin/headcnv} \\
\DppNm{rofftotex} & \DppNm{rofftotex} & limited \DppNm{roff mm} to
	\LaTeX{} translator \\
\hline
\end{tabular}
\caption{Directories for creating utilities}
\label{Tab:WhereBuildUtil}
\end{table}


\subsection{Validation}

\subsubsection{\protect\Dpp{} directory structure}

Table~\PageRef{Tab:DirStruct} gives the top level \Dpp{} directory
structure.


\begin{table}
\begin{tabular}{|ll|} \hline
Directory under \DppNm{\$OPD\_ROOT} & Contents \\ \hline
\DppNm{bin} & executables \\
\DppNm{build} & master build directory for everything \\
\DppNm{doc} & documentation \\
\DppNm{doc/build} & master build directory for documentation \\
\DppNm{doc/mac} & documentation macros \\
\DppNm{doc/scripts} & documentation script files \\
\DppNm{doc/trademarks} & restricted use macros \\
\DppNm{examp} & \Dpp{} examples \\
\DppNm{help} & interactive help files \\
\DppNm{lib} & libraries \\
\DppNm{src} & source code \\
\DppNm{src/dsp} & DSP source code \\
\DppNm{src/dsp/build} & master directory for DSP process \\
\DppNm{src/dsp/lib} & libraries for interactive and stand alone DSP code\\
\DppNm{src/dsp/lib/target} & root for stand alone code \\
\DppNm{src/dsp/lib/target/build} & master directory for stand alone libraries \\
\DppNm{src/dsp\_gui} & classes common to both processes \\
\DppNm{src/gui} & user interface process source code \\
\DppNm{src/gui/build} & master directory for user interface process \\
\DppNm{src/include} & include files for writing nodes \\
\DppNm{src/menus} & menus and menu builds for both processes \\
\DppNm{src/genlib} & generic library source code \\
\DppNm{src/start\_up} & start up code that initiates both processes \\
\DppNm{src/util} & utilities source code \\
\DppNm{validate} & validation log, action files, and \DPP{} programs \\
\hline
\end{tabular}
\caption{Top level \Dpp{} directory structure}
\label{Tab:DirStruct}
\end{table}

\subsubsection{Validation}

The validation shell script \\
\DppNm{\$OPD\_ROOT/scripts/master\_validate.sh} \\
controls the creation of base line test data and
the execution of tests against that data. 

%\subsection{Adding directories and deleting \protect\DppNmn{.usr} files}


