diff --git a/Documentation/.latex2html-init b/Documentation/.latex2html-init new file mode 100644 index 00000000..cc4b5dc6 --- /dev/null +++ b/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 = " +

+Copyright (C) 2000, 2001 Free Software Foundation, Inc. +

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

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

+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 ? " Next: $NEXT_TITLE \n" : undef) . + ($UP_TITLE ? "Up: $UP_TITLE \n" : undef) . + ($PREVIOUS_TITLE ? " Previous: $PREVIOUS_TITLE \n" : undef) . + "

\n" +} + +sub bot_navigation_panel { + "

". + ($NEXT_TITLE ? " Next: $NEXT_TITLE \n" : undef) . + ($UP_TITLE ? "Up: $UP_TITLE \n" : undef) . + ($PREVIOUS_TITLE ? " Previous: $PREVIOUS_TITLE \n" : undef) +} diff --git a/Documentation/GNUmakefile.in b/Documentation/GNUmakefile.in index 8ae3c43f..c886cc35 100644 --- a/Documentation/GNUmakefile.in +++ b/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) diff --git a/Documentation/internals.tex b/Documentation/internals.tex new file mode 100644 index 00000000..4e1920ab --- /dev/null +++ b/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}