mirror of
https://github.com/gnustep/tools-make.git
synced 2025-05-11 14:00:38 +00:00
Added new documents
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/tools/make/trunk@10273 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Nicola Pero
parent
0deb7834ae
commit
9016c5887b
3 changed files with 244 additions and 1 deletions
47
Documentation/.latex2html-init
Normal file
47
Documentation/.latex2html-init
Normal file
|
|
@ -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)
|
||||
}
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
192
Documentation/internals.tex
Normal file
192
Documentation/internals.tex
Normal file
|
|
@ -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}
|
||||
Loading…
Reference in a new issue