Added new documents

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/tools/make/trunk@10273 72102866-910b-0410-8b05-ffd578937521

Documentation/.latex2html-init

@@ -0,0 +1,47 @@
+
+# Workaround for a bug in latex2html which does not seem to 
+# manage the \tableofcontents command correctly
+&ignore_commands( <<_IGNORED_CMDS_);
+tableofcontents
+_IGNORED_CMDS_
+
+$ASCII_MODE = 1;
+
+$BODYTEXT = "BGCOLOR=\"\#FFFFFF\" text=\"\#000000\" link=\"\#0000FF\" vlink=\"\#4444FF\" alink=\"\#3388FF\""; 
+
+$SHOW_SECTION_NUMBERS = 1;
+
+$MAX_SPLIT_DEPTH = 4;
+
+$INFO = "
+<P>
+Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+<P>
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+<P>
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+<P>
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions.
+"; 
+
+
+sub top_navigation_panel {
+    ($NEXT_TITLE ? "<B> Next: $NEXT_TITLE </B>\n" : undef) . 
+    ($UP_TITLE ? "<B>Up: $UP_TITLE  </B>\n" : undef) . 
+    ($PREVIOUS_TITLE ? "<B> Previous: $PREVIOUS_TITLE </B>\n" : undef) .
+    "<BR> <P>\n"
+}
+
+sub bot_navigation_panel {
+    "<HR>".			
+    ($NEXT_TITLE ? "<B> Next: $NEXT_TITLE </B>\n" : undef) . 
+    ($UP_TITLE ? "<B>Up: $UP_TITLE </B>\n" : undef) . 
+    ($PREVIOUS_TITLE ? "<B> Previous: $PREVIOUS_TITLE </B>\n" : undef) 
+}

Documentation/GNUmakefile.in

@@ -36,9 +36,10 @@ GNUSTEP_TEXI2HTML       = texi2html
 GNUSTEP_TEXI2HTML_FLAGS = -split_chapter -expandinfo
 GNUSTEP_DVIPS           = dvips
 GNUSTEP_DVIPS_FLAGS     =
+TAR                     = @TAR@
 
 # The documents to be generated
-DOCUMENT_NAME = make gnustep-howto machines faq
+DOCUMENT_NAME = make gnustep-howto machines faq internals
 
 # The text documents to be generated
 DOCUMENT_TEXT_NAME = INSTALL README NEWS GNUstep-HOWTO
@@ -65,6 +66,9 @@ gnustep-howto_TEXI_FILES = \
 gnustep-howto.texi \
 version.texi
 
+internals_LATEX_FILES = \
+internals.tex
+
 INSTALL_TEXI_FILES = version.texi
 INSTALL_TEXT_MAIN = install.texi
 INSTALL_DOC_INSTALL_DIR = Developer/Makefiles/ReleaseNotes/$(VERSION)

Documentation/internals.tex

@@ -0,0 +1,192 @@
+\documentclass[a4paper]{article}
+%
+% Comment the following line out if you don't have the geometry 
+% package on your system.
+%
+\usepackage[includemp=no]{geometry}
+%
+%
+%
+\begin{document}
+\title{GNUstep Makefile Package Internals}
+\author{Nicola Pero n.pero@mi.flashnet.it}
+\date{last days of June 2001}
+\maketitle
+\tableofcontents
+
+\section{Introduction}
+This short document attempts to explain simply how the gnustep
+makefile package works internally.  Since the mechanism involves
+recursive invocations of make on the same makefiles (each time with
+different targets and variables), it might be very confusing at the
+beginning.  In this document we concentrate on understanding the main
+flow of processing, ignoring most of the little details.  This should
+hopefully allow you to start reading and understanding the
+gnustep-make source code, and then you can learn about the little
+details by yourself.
+
+\section{From `make' to the internal-all rule}
+
+Imagine for example that in your \texttt{ GNUmakefile} you include both
+\texttt{tool.make} and \texttt{library.make}, as in the following example:
+\begin{verbatim}
+include $(GNUSTEP_MAKEFILES)/common.make
+
+TOOL_NAME = decrypt
+decrypt_OBJC_FILES = decrypt.m
+
+LIBRARY_NAME = libDvd
+libDvd_OBJC_FILES = decss.m
+
+include $(GNUSTEP_MAKEFILES)/tool.make
+include $(GNUSTEP_MAKEFILES)/library.make
+\end{verbatim} % $ fool emacs's buggy tex mode
+Then you type `make' on the command line.  We want to understand what
+happens.
+
+Make will process your \texttt{GNUmakefile}, which includes
+\texttt{tool.make}, and that will include \texttt{rules.make}.  In
+\texttt{rules.make} make finds the first rule (the one which is
+executed), which is
+\begin{verbatim}
+all:: before-all internal-all after-all
+\end{verbatim}
+This means that make will build by default that target \texttt{ all},
+and that building that target requires building the
+\texttt{before-all}, \texttt{internal-all} and \texttt{after-all}
+targets.  We ignore the \texttt{before-all} and \texttt{after-all}
+targets for now, and only concentrate on the core target, which is
+\texttt{internal-all}.
+
+\section{From the internal-all rule to the \%.variables rule}
+Make needs to build this target \texttt{internal-all}.  In
+\texttt{rules.make} this target appears as
+\begin{verbatim}
+internal-all::
+\end{verbatim}
+because of the double colons (that is, because it is
+\texttt{internal-all::} rather than \texttt{internal-all:}) this
+target can have multiple totally separated rules.  Each rule must be a
+double colon rule, and is processed separately from the other rules
+(even if they refer to the same target).
+
+The real rules for \texttt{internal-all} are included by the specific 
+makefiles; in our example, \texttt{tool.make} includes
+\begin{verbatim}
+internal-all:: $(TOOL_NAME:=.all.tool.variables)
+\end{verbatim} %$
+now - in our case - because \texttt{TOOL\_NAME} is \texttt{decrypt}, then
+this rule actually means
+\begin{verbatim} 
+internal-all:: decrypt.all.tool.variables
+\end{verbatim}
+This means that to build \texttt{internal-all}, make has to build (at
+least) the \texttt{decrypt.all.tool.variables} target.
+\texttt{library.make} includes the completely analogous rule
+\begin{verbatim}
+internal-all:: $(LIBRARY_NAME:=.all.library.variables) 
+\end{verbatim} %$
+which in our case means 
+\begin{verbatim}
+internal-all:: libDvd.all.library.variables
+\end{verbatim}
+This rule is completely separated from the other one; to build
+\texttt{internal-all}, make has to build the two different targets:
+\begin{verbatim}
+decrypt.all.tool.variables
+libDvd.all.library.variables
+\end{verbatim}
+
+The rule for building these targets is in the \texttt{rules.make} file, 
+it is the \texttt{\%.variables} rule:
+\begin{verbatim}
+%.variables:
+        @(target=$(basename $(basename $*)); \
+        operation=$(subst .,,$(suffix $(basename $*))); \
+        type=$(subst -,_,$(subst .,,$(suffix $*))); \
+        $(MAKE) -f $(MAKEFILE_NAME) --no-print-directory --no-keep-going \
+            TARGET_TYPE=$${type} \
+            OPERATION=$${operation} TARGET=$${target} \
+            PROCESS_SECOND_TIME=yes $${target}.build \
+            OBJCFLAGS="$(OBJCFLAGS)" CFLAGS="$(CFLAGS)" \
+            OPTFLAG="$(OPTFLAG)" )
+\end{verbatim}
+This rule matches all targets ending in \texttt{.variables}.  The rule 
+parses the \texttt{.variables} string - for example when the rule 
+is applied to 
+\begin{verbatim}
+decrypt.all.tool.variables
+\end{verbatim}
+then (remember that \texttt{\$*} is the stem of the rule,
+\texttt{decrypt.all.tool} in this case) it extracts
+\begin{verbatim}
+target=decrypt
+operation=all
+type=tool
+\end{verbatim}
+and then it runs a make subprocess with the \texttt{OPERATION} and 
+\texttt{TYPE} variables set, and a target built from the \texttt{target} 
+by appending \texttt{.build}.
+
+\section{The second make invocation}
+In our case, the \texttt{\%.variables} rules is executed twice, so it
+runs two separate make processes:
+\begin{verbatim}
+make OPERATION=all TYPE=tool    decrypt.build PROCESS_SECOND_TIME=yes ...
+make OPERATION=all TYPE=library libDvd.build  PROCESS_SECOND_TIME=yes ...
+\end{verbatim}
+where we have omitted the less interesting variables (as signified by the 
+\texttt{...}).
+
+What this means is that for each target/type/operation, a separate
+make process is run.  For example, if you have two tools,
+\texttt{decrypt} and \texttt{crypt}, and you want to both compile and install
+them, it will run four make subprocesses:
+\begin{verbatim}
+make OPERATION=all     TYPE=tool decrypt.build PROCESS_SECOND_TIME=yes ...
+make OPERATION=all     TYPE=tool crypt.build   PROCESS_SECOND_TIME=yes ...
+make OPERATION=install TYPE=tool decrypt.build PROCESS_SECOND_TIME=yes ...
+make OPERATION=install TYPE=tool crypt.build   PROCESS_SECOND_TIME=yes ...
+\end{verbatim}
+This is the `second make invocation'.  The make package knows that it
+is being invoked for the second time, because of the
+\texttt{PROCESS\_SECOND\_TIME} flag.
+
+\section{The \%.build rule}
+Let's examine what happens in the make subprocess - for example in the
+\texttt{decrypt.build} make subprocess.  Make looks for a rule to
+build \texttt{decrypt.build}.  The rule is found in
+\texttt{rules.make}; it is the \texttt{\%.build} rule.  This rule is
+too long to quote it here; but basically it runs yet another make
+subprocess (which is the one which finally does the work).  This last
+make subprocess is run more or less as follows:
+\begin{verbatim}
+make INTERNAL_tool_NAME=decrypt \
+     internal-tool-all \
+     OBJC_FILES="{the list of OBJC_FILES specified using decrypt_OBJC_FILES
+                  in the makefile}" ...
+\end{verbatim}
+where \texttt{...} stands for a lot of other variables, including all
+variables needed to perform the final stage: \texttt{OBJC\_FILES},
+\texttt{C\_FILES}, \texttt{JAVA\_FILES},
+\texttt{ADDITIONAL\_INCLUDE\_DIRS} etc.  Note that each make
+subprocess will get passed different, specific, variables.  If
+gnustep-make wants to modify these variables in some way, it does it
+at this stage, before passing them to the submake process.  For
+example, some library flags are filtered through the
+\texttt{WHICH\_LIB\_SCRIPT}.
+
+\section{The third make subprocess}
+This last make subprocess is the one which really builds the target.
+Because of the \texttt{INTERNAL\_tool\_NAME} variable being a
+non-empty string (while it was empty in all previous invocations),
+\texttt{tool.make} will include the actual rules to build the tool; in
+particular, the \texttt{internal-tool-all} rule, which is then
+executed and builds the tool.  All variables such as
+\texttt{OBJC\_FILES} or the library flags are now available directly in
+the makefiles, they have already been prepared and preprocessed, so
+that the rules in \texttt{tool.make} can just plainly use these
+variables naively to perform their job (compiling, installing, or
+whatever).
+
+\end{document}