Bring in a chapter about the doc build process. This has been hanging
around my tree for ages, and I've lost the details from the original submitter. I *think* it was Neil Blakey-Milner <nbm@mithrandr.moria.org> but I could be wrong.
This commit is contained in:
Nik Clayton
parent
0200f776a4
commit
2e3f17940f
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=7438
2 changed files with 1002 additions and 0 deletions
501
en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
Normal file
501
en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml
Normal file
|
|
@ -0,0 +1,501 @@
|
|||
<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
|
||||
|
||||
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
||||
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
||||
modification, are permitted provided that the following conditions
|
||||
are met:
|
||||
|
||||
1. Redistributions of source code (SGML DocBook) must retain the above
|
||||
copyright notice, this list of conditions and the following
|
||||
disclaimer as the first lines of this file unmodified.
|
||||
|
||||
2. Redistributions in compiled form (transformed to other DTDs,
|
||||
converted to PDF, PostScript, RTF and other formats) must reproduce
|
||||
the above copyright notice, this list of conditions and the
|
||||
following disclaimer in the documentation and/or other materials
|
||||
provided with the distribution.
|
||||
|
||||
THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
|
||||
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
|
||||
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
||||
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
||||
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
|
||||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
$Id: chapter.sgml,v 1.1 2000-06-23 00:37:15 nik Exp $
|
||||
-->
|
||||
|
||||
<chapter id="doc-build">
|
||||
<title>The Documentation Build Process</title>
|
||||
|
||||
<para>This chapter's main purpose is to clearly explain <emphasis>how
|
||||
the documentation build process is organised</emphasis>, and
|
||||
<emphasis>how to affect modifications to this process</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>After you have finished reading this chapter you should:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Know what you need to build the FDP documentation, in
|
||||
addition to those mentioned in the <link
|
||||
linkend="tools">SGML tools chapter</link>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Be able to read and understand the
|
||||
<application>make</application> instructions that are present in
|
||||
each document's <filename>Makefile</filename>s, as well as an
|
||||
overview of the <filename>doc.project.mk</filename> includes.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Be able to customize the build process by using
|
||||
<application>make</application> variables and
|
||||
<application>make</application> targets.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<sect1>
|
||||
<title>The FreeBSD Documentation Build Toolset</title>
|
||||
|
||||
<para>Here are your tools. Use them every way you can.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The primary build tool you will need is
|
||||
<application>make</application>, but specifically
|
||||
<application>Berkeley Make</application>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Package building is handled by FreeBSD's
|
||||
<application>pkg_create</application>. If you are not using
|
||||
FreeBSD, you will either have to live without packages, or
|
||||
compile the source yourself.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><application>gzip</application> is needed to create
|
||||
compressed versions of the document.
|
||||
<application>bzip2</application> compression and
|
||||
<application>zip</application> archives are also supported.
|
||||
<application>tar</application> is supported, but package
|
||||
building demands it.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><application>install</application> is the default method
|
||||
to install the documentation. There are alternatives,
|
||||
however.</para
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<note>
|
||||
<para>It is unlikely you will not be able to find these last two, they
|
||||
are mentioned for completeness.</para>
|
||||
</note>
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Understanding Makefiles in the Documentation tree</title>
|
||||
|
||||
<para>There are three main types of <filename>Makefile</filename>s
|
||||
in the FreeBSD Documentation Project tree.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><link linkend="sub-make">Subdirectory
|
||||
<filename>Makefile</filename>s</link> simply pass
|
||||
commands to those directories below them.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><link linkend="doc-make">Documentation
|
||||
<filename>Makefile</filename>s</link> describe the
|
||||
document(s) that should be produced from this directory.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><link linkend="make-includes"><application>Make</application>
|
||||
includes</link> are the glue that perform the document production,
|
||||
and are usually of the form
|
||||
<filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><application>Make</application> syntax is quickly revised as
|
||||
the we explore these types.</para>
|
||||
|
||||
<sect2 id="sub-make">
|
||||
<title>Subdirectory Makefiles</title>
|
||||
|
||||
<para>These directories usually take the form of:</para>
|
||||
|
||||
<programlisting>SUBDIR =articles
|
||||
SUBDIR+=books
|
||||
|
||||
COMPAT_SYMLINK = en
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/..
|
||||
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
|
||||
|
||||
<para>In quick summary, the first four non-empty lines define the
|
||||
<application>make</application> variables,
|
||||
<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
|
||||
and <makevar>DOC_PREFIX</makevar>.</para>
|
||||
|
||||
<para>The first <makevar>SUBDIR</makevar> statement, as well as
|
||||
the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
|
||||
assign a value to a variable, overriding any previous
|
||||
value.</para>
|
||||
|
||||
<para>The second <makevar>SUBDIR</makevar> statement shows how a
|
||||
value is appended to the current value of a variable. The
|
||||
<makevar>SUBDIR</makevar> variable is now <literal>articles
|
||||
books</literal>.</para>
|
||||
|
||||
<para>The <makevar>DOC_PREFIX</makevar> assignment shows how a
|
||||
value is assigned to the variable, but only if it is not already
|
||||
defined. This is useful if <makevar>DOC_PREFIX</makevar> is not
|
||||
where this <filename>Makefile</filename> thinks it is - the user
|
||||
can override this and provide the correct value.</para>
|
||||
|
||||
<para>Now what does it all mean? <makevar>SUBDIR</makevar>
|
||||
mentions which subdirectories below this one the build process
|
||||
should pass any work on to.</para>
|
||||
|
||||
<para><makevar>COMPAT_SYMLINK</makevar> is specific to
|
||||
compatibility symlinks (amazingly enough) for languages to their
|
||||
official encoding (<filename>doc/en</filename> would point to
|
||||
<filename>en_US.ISO-8859-1</filename>).</para>
|
||||
|
||||
<para><makevar>DOC_PREFIX</makevar> is the path to the root of the
|
||||
FreeBSD Document Project tree. This is not always that easy to
|
||||
find, and is also easily overridable, to allow for flexibility.
|
||||
<makevar>.CURDIR</makevar> is a <application>make</application>
|
||||
builtin variable with the path to the current directory.</para>
|
||||
|
||||
<para>The final line includes the FreeBSD Documentation Project's
|
||||
project-wide <application>make</application> system file
|
||||
<filename>doc.project.mk</filename> which is the glue which
|
||||
converts these variables into build instructions.</para>
|
||||
|
||||
</sect2>
|
||||
<sect2 id="doc-make">
|
||||
<title>Documentation Makefiles</title>
|
||||
|
||||
<para>These <filename>Makefile</filename>s set a bunch of
|
||||
<application>make</application> variables that describe how to
|
||||
build the documentation contained in that directory.</para>
|
||||
|
||||
<para>Here is an example:</para>
|
||||
|
||||
<programlisting>MAINTAINER=nik@FreeBSD.org
|
||||
|
||||
DOC?= book
|
||||
|
||||
FORMATS?= html-split html
|
||||
|
||||
INSTALL_COMPRESSED?= gz
|
||||
INSTALL_ONLY_COMPRESSED?=
|
||||
|
||||
# SGML content
|
||||
SRCS= book.sgml
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/../../..
|
||||
|
||||
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
|
||||
|
||||
<para>The <makevar>MAINTAINER</makevar> variable is a very
|
||||
important one. This variable provides the ability to claim
|
||||
ownership over a document in the FreeBSD Documentation
|
||||
Project, whereby you gain the responsibility for maintaining
|
||||
it.</para>
|
||||
|
||||
<para><makevar>DOC</makevar> is the name (sans the
|
||||
<filename>.sgml</filename> extension) of the main document
|
||||
created by this directory. <makevar>SRCS</makevar> lists all
|
||||
the individual files that make up the document. This should
|
||||
also include important files in which a change should result
|
||||
in a rebuild.</para>
|
||||
|
||||
<para><makevar>FORMATS</makevar> indicates the default formats
|
||||
that should be built for this document.
|
||||
<makevar>INSTALL_COMPRESSED</makevar> is the default list of
|
||||
compression techniques that should be used in the document
|
||||
build. <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
|
||||
default, should be non-empty if only compressed documents are
|
||||
desired in the build.</para>
|
||||
|
||||
<note>
|
||||
<para>We covered optional variable assignments in the
|
||||
<link linkend="sub-make">previous section</link>.</para>
|
||||
</note>
|
||||
|
||||
<para>The <makevar>DOC_PREFIX</makevar> and include statements
|
||||
should be familiar already.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="make-includes">
|
||||
<title>FreeBSD Documentation Project make includes</title>
|
||||
|
||||
<para>This is best explained by inspection of the code. Here are
|
||||
the system include files:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><filename>doc.project.mk</filename> is the main project
|
||||
include file, which includes all the following include files, as
|
||||
necessary.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.subdir.mk</filename> handles traversing of
|
||||
the document tree during the build and install processes.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.install.mk</filename> provides variables
|
||||
that affect ownership and installation of documents.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.docbook.mk</filename> is included if
|
||||
<makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
|
||||
and <makevar>DOC</makevar> is set.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<sect2>
|
||||
<title>doc.project.mk</title>
|
||||
|
||||
<para>By inspection:</para>
|
||||
|
||||
<programlisting>DOCFORMAT?= docbook
|
||||
MAINTAINER?= doc@FreeBSD.org
|
||||
|
||||
PREFIX?= /usr/local
|
||||
PRI_LANG?= en_US.ISO_8859-1
|
||||
|
||||
.if defined(DOC)
|
||||
.if ${DOCFORMAT} == "docbook"
|
||||
.include "doc.docbook.mk"
|
||||
.endif
|
||||
.endif
|
||||
|
||||
.include "doc.subdir.mk"
|
||||
.include "doc.install.mk"</programlisting>
|
||||
|
||||
<sect3>
|
||||
|
||||
<title>Variables</title>
|
||||
|
||||
<para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar>
|
||||
are assigned default values, if these are not set by the
|
||||
document make file.</para>
|
||||
|
||||
<para><makevar>PREFIX</makevar> is the prefix under which the
|
||||
<link linkend="tools">documentation building tools</link> are
|
||||
installed. For normal package and port installation, this is
|
||||
<filename>/usr/local</filename>.</para>
|
||||
|
||||
<para><makevar>PRI_LANG</makevar> should be set to whatever
|
||||
language and encoding is natural amongst users these documents are
|
||||
being built for. US English is the default.</para>
|
||||
|
||||
<note>
|
||||
<para><makevar>PRI_LANG</makevar> in no way affects what documents
|
||||
can, or even will, be built. It's main use is creating links to
|
||||
commonly referenced documents into the FreeBSD documentation
|
||||
install root.</para>
|
||||
</note>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Conditionals</title>
|
||||
|
||||
<para>The <literal>.if defined(DOC)</literal> line is an example of
|
||||
a <application>make</application> conditional which, like in
|
||||
other programs, defines behaviour if some condition is true or
|
||||
if it is false. <literal>defined</literal> is a function which
|
||||
returns whether the variable given is defined or not.</para>
|
||||
|
||||
<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
|
||||
tests whether the <makevar>DOCFORMAT</makevar> variable is
|
||||
<literal>"docbook"</literal>, and in this case, includes
|
||||
<filename>doc.docbook.mk</filename>.</para>
|
||||
|
||||
<para>The two <literal>.endif</literal>s close the two above
|
||||
conditionals, marking the end of their application.</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>doc.subdir.mk</title>
|
||||
|
||||
<para>This is too long to explain by inspection, you should be
|
||||
able to work it out with the knowledge gained from the previous
|
||||
chapters, and a little help given here.</para>
|
||||
|
||||
<sect3>
|
||||
<title>Variables</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><makevar>SUBDIR</makevar> is a list of subdirectories
|
||||
that the build process should go further down
|
||||
into.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><makevar>ROOT_SYMLINKS</makevar> is the name of
|
||||
directories that should be linked to the document
|
||||
install root from their actual locations, if the current
|
||||
language is the primary language (specified by
|
||||
<makevar>PRI_LANG</makevar>).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><makevar>COMPAT_SYMLINK</makevar> is described in the
|
||||
<link linkend="sub-make">Subdirectory Makefile</link>
|
||||
section.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Targets and macros</title>
|
||||
|
||||
<para>Dependencies are described by
|
||||
<literal><replaceable>target</replaceable>:
|
||||
<replaceable>dependency1 dependency2 ...</replaceable></literal>
|
||||
tuples, where to build <literal>target</literal>, you need to build
|
||||
the given dependencies first.</para>
|
||||
|
||||
<para>After that descriptive tuple, instructions on how to build
|
||||
the target may be given, if the conversion process between the
|
||||
target and it's dependencies are not previously defined, or if
|
||||
this particular conversion is not the same as the default
|
||||
conversion method.</para>
|
||||
|
||||
<para>A special dependency <literal>.USE</literal> defines
|
||||
the equivalent of a macro.</para>
|
||||
|
||||
<programlisting>_SUBDIRUSE: .USE
|
||||
.for entry in ${SUBDIR}
|
||||
@${ECHO} "===> ${DIRPRFX}${entry}"
|
||||
@(cd ${.CURDIR}/${entry} && \
|
||||
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
|
||||
.endfor</programlisting>
|
||||
|
||||
<para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now a
|
||||
macro which will execute the given commands when it is listed
|
||||
as a dependency.</para>
|
||||
|
||||
<para>What sets this macro apart from other targets? Basically,
|
||||
it is executed <emphasis>after</emphasis> the instructions
|
||||
given in the build procedure it is listed as a dependency to,
|
||||
and it doesn't adjust <makevar>.TARGET</makevar>, which is the
|
||||
variable which contains the name of the target currently
|
||||
being built.</para>
|
||||
|
||||
<programlisting>clean: _SUBDIRUSE
|
||||
rm -f ${CLEANFILES}</programlisting>
|
||||
|
||||
<para>In the above, <maketarget>clean</maketarget> will use the
|
||||
<maketarget>_SUBDIRUSE</maketarget> macro after it has
|
||||
executed the instruction
|
||||
<command>rm -f ${CLEANFILES}</command>. In effect, this causes
|
||||
<maketarget>clean</maketarget> to go further and further down
|
||||
the directory tree, deleting built files as it goes
|
||||
<emphasis>down</emphasis>, not on the way back up.</para>
|
||||
|
||||
<sect4>
|
||||
<title>Provided targets</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><maketarget>install</maketarget> and
|
||||
<maketarget>package</maketarget> both go down the
|
||||
directory tree calling the real versions of themselves
|
||||
in the subdirectories.
|
||||
(<maketarget>realinstall</maketarget> and
|
||||
<maketarget>realpackage</maketarget>
|
||||
respectively)</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><maketarget>clean</maketarget> removes files created
|
||||
by the build process (and goes down the directory tree
|
||||
too). <maketarget>cleandir</maketarget> does the same,
|
||||
and also removes the object directory, if any.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect4>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>More on conditionals</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>exists</literal> is another condition
|
||||
function which returns true if the given file exists.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>empty</literal> returns true if the given
|
||||
variable is empty.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>target</literal> returns true if the given
|
||||
target does not already exist.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Looping constructs in make (.for)</title>
|
||||
|
||||
<para><literal>.for</literal> provides a way to repeat a set of
|
||||
instructions for each space-seperated element in a variable.
|
||||
It does this by assigning a variable to contain the current
|
||||
element in the list being examined.</para>
|
||||
|
||||
<programlisting>_SUBDIRUSE: .USE
|
||||
.for entry in ${SUBDIR}
|
||||
@${ECHO} "===> ${DIRPRFX}${entry}"
|
||||
@(cd ${.CURDIR}/${entry} && \
|
||||
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
|
||||
.endfor</programlisting>
|
||||
|
||||
<para>In the above, if <makevar>SUBDIR</makevar> is empty, no
|
||||
action is taken; if it has one or more elements, the
|
||||
instructions between <literal>.for</literal> and
|
||||
<literal>.endfor</literal> would repeat for every element,
|
||||
with <makevar>entry</makevar> being replaced with the value of
|
||||
the current element.</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
Local Variables:
|
||||
mode: sgml
|
||||
sgml-declaration: "../chapter.decl"
|
||||
sgml-indent-data: t
|
||||
sgml-omittag: nil
|
||||
sgml-always-quote-attributes: t
|
||||
sgml-parent-document: ("../book.sgml" "part" "chapter")
|
||||
End:
|
||||
-->
|
||||
|
||||
501
en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml
Normal file
501
en_US.ISO_8859-1/books/fdp-primer/doc-build/chapter.sgml
Normal file
|
|
@ -0,0 +1,501 @@
|
|||
<!-- Copyright (c) 1999 Neil Blakey-Milner, All rights reserved.
|
||||
|
||||
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
||||
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
||||
modification, are permitted provided that the following conditions
|
||||
are met:
|
||||
|
||||
1. Redistributions of source code (SGML DocBook) must retain the above
|
||||
copyright notice, this list of conditions and the following
|
||||
disclaimer as the first lines of this file unmodified.
|
||||
|
||||
2. Redistributions in compiled form (transformed to other DTDs,
|
||||
converted to PDF, PostScript, RTF and other formats) must reproduce
|
||||
the above copyright notice, this list of conditions and the
|
||||
following disclaimer in the documentation and/or other materials
|
||||
provided with the distribution.
|
||||
|
||||
THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
|
||||
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
|
||||
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
||||
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
||||
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
|
||||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
$Id: chapter.sgml,v 1.1 2000-06-23 00:37:15 nik Exp $
|
||||
-->
|
||||
|
||||
<chapter id="doc-build">
|
||||
<title>The Documentation Build Process</title>
|
||||
|
||||
<para>This chapter's main purpose is to clearly explain <emphasis>how
|
||||
the documentation build process is organised</emphasis>, and
|
||||
<emphasis>how to affect modifications to this process</emphasis>.
|
||||
</para>
|
||||
|
||||
<para>After you have finished reading this chapter you should:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Know what you need to build the FDP documentation, in
|
||||
addition to those mentioned in the <link
|
||||
linkend="tools">SGML tools chapter</link>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Be able to read and understand the
|
||||
<application>make</application> instructions that are present in
|
||||
each document's <filename>Makefile</filename>s, as well as an
|
||||
overview of the <filename>doc.project.mk</filename> includes.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Be able to customize the build process by using
|
||||
<application>make</application> variables and
|
||||
<application>make</application> targets.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<sect1>
|
||||
<title>The FreeBSD Documentation Build Toolset</title>
|
||||
|
||||
<para>Here are your tools. Use them every way you can.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The primary build tool you will need is
|
||||
<application>make</application>, but specifically
|
||||
<application>Berkeley Make</application>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Package building is handled by FreeBSD's
|
||||
<application>pkg_create</application>. If you are not using
|
||||
FreeBSD, you will either have to live without packages, or
|
||||
compile the source yourself.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><application>gzip</application> is needed to create
|
||||
compressed versions of the document.
|
||||
<application>bzip2</application> compression and
|
||||
<application>zip</application> archives are also supported.
|
||||
<application>tar</application> is supported, but package
|
||||
building demands it.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><application>install</application> is the default method
|
||||
to install the documentation. There are alternatives,
|
||||
however.</para
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<note>
|
||||
<para>It is unlikely you will not be able to find these last two, they
|
||||
are mentioned for completeness.</para>
|
||||
</note>
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Understanding Makefiles in the Documentation tree</title>
|
||||
|
||||
<para>There are three main types of <filename>Makefile</filename>s
|
||||
in the FreeBSD Documentation Project tree.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><link linkend="sub-make">Subdirectory
|
||||
<filename>Makefile</filename>s</link> simply pass
|
||||
commands to those directories below them.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><link linkend="doc-make">Documentation
|
||||
<filename>Makefile</filename>s</link> describe the
|
||||
document(s) that should be produced from this directory.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><link linkend="make-includes"><application>Make</application>
|
||||
includes</link> are the glue that perform the document production,
|
||||
and are usually of the form
|
||||
<filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para><application>Make</application> syntax is quickly revised as
|
||||
the we explore these types.</para>
|
||||
|
||||
<sect2 id="sub-make">
|
||||
<title>Subdirectory Makefiles</title>
|
||||
|
||||
<para>These directories usually take the form of:</para>
|
||||
|
||||
<programlisting>SUBDIR =articles
|
||||
SUBDIR+=books
|
||||
|
||||
COMPAT_SYMLINK = en
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/..
|
||||
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>
|
||||
|
||||
<para>In quick summary, the first four non-empty lines define the
|
||||
<application>make</application> variables,
|
||||
<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>,
|
||||
and <makevar>DOC_PREFIX</makevar>.</para>
|
||||
|
||||
<para>The first <makevar>SUBDIR</makevar> statement, as well as
|
||||
the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to
|
||||
assign a value to a variable, overriding any previous
|
||||
value.</para>
|
||||
|
||||
<para>The second <makevar>SUBDIR</makevar> statement shows how a
|
||||
value is appended to the current value of a variable. The
|
||||
<makevar>SUBDIR</makevar> variable is now <literal>articles
|
||||
books</literal>.</para>
|
||||
|
||||
<para>The <makevar>DOC_PREFIX</makevar> assignment shows how a
|
||||
value is assigned to the variable, but only if it is not already
|
||||
defined. This is useful if <makevar>DOC_PREFIX</makevar> is not
|
||||
where this <filename>Makefile</filename> thinks it is - the user
|
||||
can override this and provide the correct value.</para>
|
||||
|
||||
<para>Now what does it all mean? <makevar>SUBDIR</makevar>
|
||||
mentions which subdirectories below this one the build process
|
||||
should pass any work on to.</para>
|
||||
|
||||
<para><makevar>COMPAT_SYMLINK</makevar> is specific to
|
||||
compatibility symlinks (amazingly enough) for languages to their
|
||||
official encoding (<filename>doc/en</filename> would point to
|
||||
<filename>en_US.ISO-8859-1</filename>).</para>
|
||||
|
||||
<para><makevar>DOC_PREFIX</makevar> is the path to the root of the
|
||||
FreeBSD Document Project tree. This is not always that easy to
|
||||
find, and is also easily overridable, to allow for flexibility.
|
||||
<makevar>.CURDIR</makevar> is a <application>make</application>
|
||||
builtin variable with the path to the current directory.</para>
|
||||
|
||||
<para>The final line includes the FreeBSD Documentation Project's
|
||||
project-wide <application>make</application> system file
|
||||
<filename>doc.project.mk</filename> which is the glue which
|
||||
converts these variables into build instructions.</para>
|
||||
|
||||
</sect2>
|
||||
<sect2 id="doc-make">
|
||||
<title>Documentation Makefiles</title>
|
||||
|
||||
<para>These <filename>Makefile</filename>s set a bunch of
|
||||
<application>make</application> variables that describe how to
|
||||
build the documentation contained in that directory.</para>
|
||||
|
||||
<para>Here is an example:</para>
|
||||
|
||||
<programlisting>MAINTAINER=nik@FreeBSD.org
|
||||
|
||||
DOC?= book
|
||||
|
||||
FORMATS?= html-split html
|
||||
|
||||
INSTALL_COMPRESSED?= gz
|
||||
INSTALL_ONLY_COMPRESSED?=
|
||||
|
||||
# SGML content
|
||||
SRCS= book.sgml
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/../../..
|
||||
|
||||
.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>
|
||||
|
||||
<para>The <makevar>MAINTAINER</makevar> variable is a very
|
||||
important one. This variable provides the ability to claim
|
||||
ownership over a document in the FreeBSD Documentation
|
||||
Project, whereby you gain the responsibility for maintaining
|
||||
it.</para>
|
||||
|
||||
<para><makevar>DOC</makevar> is the name (sans the
|
||||
<filename>.sgml</filename> extension) of the main document
|
||||
created by this directory. <makevar>SRCS</makevar> lists all
|
||||
the individual files that make up the document. This should
|
||||
also include important files in which a change should result
|
||||
in a rebuild.</para>
|
||||
|
||||
<para><makevar>FORMATS</makevar> indicates the default formats
|
||||
that should be built for this document.
|
||||
<makevar>INSTALL_COMPRESSED</makevar> is the default list of
|
||||
compression techniques that should be used in the document
|
||||
build. <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by
|
||||
default, should be non-empty if only compressed documents are
|
||||
desired in the build.</para>
|
||||
|
||||
<note>
|
||||
<para>We covered optional variable assignments in the
|
||||
<link linkend="sub-make">previous section</link>.</para>
|
||||
</note>
|
||||
|
||||
<para>The <makevar>DOC_PREFIX</makevar> and include statements
|
||||
should be familiar already.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="make-includes">
|
||||
<title>FreeBSD Documentation Project make includes</title>
|
||||
|
||||
<para>This is best explained by inspection of the code. Here are
|
||||
the system include files:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><filename>doc.project.mk</filename> is the main project
|
||||
include file, which includes all the following include files, as
|
||||
necessary.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.subdir.mk</filename> handles traversing of
|
||||
the document tree during the build and install processes.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.install.mk</filename> provides variables
|
||||
that affect ownership and installation of documents.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><filename>doc.docbook.mk</filename> is included if
|
||||
<makevar>DOCFORMAT</makevar> is <literal>docbook</literal>
|
||||
and <makevar>DOC</makevar> is set.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<sect2>
|
||||
<title>doc.project.mk</title>
|
||||
|
||||
<para>By inspection:</para>
|
||||
|
||||
<programlisting>DOCFORMAT?= docbook
|
||||
MAINTAINER?= doc@FreeBSD.org
|
||||
|
||||
PREFIX?= /usr/local
|
||||
PRI_LANG?= en_US.ISO_8859-1
|
||||
|
||||
.if defined(DOC)
|
||||
.if ${DOCFORMAT} == "docbook"
|
||||
.include "doc.docbook.mk"
|
||||
.endif
|
||||
.endif
|
||||
|
||||
.include "doc.subdir.mk"
|
||||
.include "doc.install.mk"</programlisting>
|
||||
|
||||
<sect3>
|
||||
|
||||
<title>Variables</title>
|
||||
|
||||
<para><makevar>DOCFORMAT</makevar> and <makevar>MAINTAINER</makevar>
|
||||
are assigned default values, if these are not set by the
|
||||
document make file.</para>
|
||||
|
||||
<para><makevar>PREFIX</makevar> is the prefix under which the
|
||||
<link linkend="tools">documentation building tools</link> are
|
||||
installed. For normal package and port installation, this is
|
||||
<filename>/usr/local</filename>.</para>
|
||||
|
||||
<para><makevar>PRI_LANG</makevar> should be set to whatever
|
||||
language and encoding is natural amongst users these documents are
|
||||
being built for. US English is the default.</para>
|
||||
|
||||
<note>
|
||||
<para><makevar>PRI_LANG</makevar> in no way affects what documents
|
||||
can, or even will, be built. It's main use is creating links to
|
||||
commonly referenced documents into the FreeBSD documentation
|
||||
install root.</para>
|
||||
</note>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Conditionals</title>
|
||||
|
||||
<para>The <literal>.if defined(DOC)</literal> line is an example of
|
||||
a <application>make</application> conditional which, like in
|
||||
other programs, defines behaviour if some condition is true or
|
||||
if it is false. <literal>defined</literal> is a function which
|
||||
returns whether the variable given is defined or not.</para>
|
||||
|
||||
<para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next,
|
||||
tests whether the <makevar>DOCFORMAT</makevar> variable is
|
||||
<literal>"docbook"</literal>, and in this case, includes
|
||||
<filename>doc.docbook.mk</filename>.</para>
|
||||
|
||||
<para>The two <literal>.endif</literal>s close the two above
|
||||
conditionals, marking the end of their application.</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>doc.subdir.mk</title>
|
||||
|
||||
<para>This is too long to explain by inspection, you should be
|
||||
able to work it out with the knowledge gained from the previous
|
||||
chapters, and a little help given here.</para>
|
||||
|
||||
<sect3>
|
||||
<title>Variables</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><makevar>SUBDIR</makevar> is a list of subdirectories
|
||||
that the build process should go further down
|
||||
into.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><makevar>ROOT_SYMLINKS</makevar> is the name of
|
||||
directories that should be linked to the document
|
||||
install root from their actual locations, if the current
|
||||
language is the primary language (specified by
|
||||
<makevar>PRI_LANG</makevar>).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><makevar>COMPAT_SYMLINK</makevar> is described in the
|
||||
<link linkend="sub-make">Subdirectory Makefile</link>
|
||||
section.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Targets and macros</title>
|
||||
|
||||
<para>Dependencies are described by
|
||||
<literal><replaceable>target</replaceable>:
|
||||
<replaceable>dependency1 dependency2 ...</replaceable></literal>
|
||||
tuples, where to build <literal>target</literal>, you need to build
|
||||
the given dependencies first.</para>
|
||||
|
||||
<para>After that descriptive tuple, instructions on how to build
|
||||
the target may be given, if the conversion process between the
|
||||
target and it's dependencies are not previously defined, or if
|
||||
this particular conversion is not the same as the default
|
||||
conversion method.</para>
|
||||
|
||||
<para>A special dependency <literal>.USE</literal> defines
|
||||
the equivalent of a macro.</para>
|
||||
|
||||
<programlisting>_SUBDIRUSE: .USE
|
||||
.for entry in ${SUBDIR}
|
||||
@${ECHO} "===> ${DIRPRFX}${entry}"
|
||||
@(cd ${.CURDIR}/${entry} && \
|
||||
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
|
||||
.endfor</programlisting>
|
||||
|
||||
<para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now a
|
||||
macro which will execute the given commands when it is listed
|
||||
as a dependency.</para>
|
||||
|
||||
<para>What sets this macro apart from other targets? Basically,
|
||||
it is executed <emphasis>after</emphasis> the instructions
|
||||
given in the build procedure it is listed as a dependency to,
|
||||
and it doesn't adjust <makevar>.TARGET</makevar>, which is the
|
||||
variable which contains the name of the target currently
|
||||
being built.</para>
|
||||
|
||||
<programlisting>clean: _SUBDIRUSE
|
||||
rm -f ${CLEANFILES}</programlisting>
|
||||
|
||||
<para>In the above, <maketarget>clean</maketarget> will use the
|
||||
<maketarget>_SUBDIRUSE</maketarget> macro after it has
|
||||
executed the instruction
|
||||
<command>rm -f ${CLEANFILES}</command>. In effect, this causes
|
||||
<maketarget>clean</maketarget> to go further and further down
|
||||
the directory tree, deleting built files as it goes
|
||||
<emphasis>down</emphasis>, not on the way back up.</para>
|
||||
|
||||
<sect4>
|
||||
<title>Provided targets</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><maketarget>install</maketarget> and
|
||||
<maketarget>package</maketarget> both go down the
|
||||
directory tree calling the real versions of themselves
|
||||
in the subdirectories.
|
||||
(<maketarget>realinstall</maketarget> and
|
||||
<maketarget>realpackage</maketarget>
|
||||
respectively)</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><maketarget>clean</maketarget> removes files created
|
||||
by the build process (and goes down the directory tree
|
||||
too). <maketarget>cleandir</maketarget> does the same,
|
||||
and also removes the object directory, if any.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect4>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>More on conditionals</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>exists</literal> is another condition
|
||||
function which returns true if the given file exists.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>empty</literal> returns true if the given
|
||||
variable is empty.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>target</literal> returns true if the given
|
||||
target does not already exist.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect3>
|
||||
|
||||
<sect3>
|
||||
<title>Looping constructs in make (.for)</title>
|
||||
|
||||
<para><literal>.for</literal> provides a way to repeat a set of
|
||||
instructions for each space-seperated element in a variable.
|
||||
It does this by assigning a variable to contain the current
|
||||
element in the list being examined.</para>
|
||||
|
||||
<programlisting>_SUBDIRUSE: .USE
|
||||
.for entry in ${SUBDIR}
|
||||
@${ECHO} "===> ${DIRPRFX}${entry}"
|
||||
@(cd ${.CURDIR}/${entry} && \
|
||||
${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
|
||||
.endfor</programlisting>
|
||||
|
||||
<para>In the above, if <makevar>SUBDIR</makevar> is empty, no
|
||||
action is taken; if it has one or more elements, the
|
||||
instructions between <literal>.for</literal> and
|
||||
<literal>.endfor</literal> would repeat for every element,
|
||||
with <makevar>entry</makevar> being replaced with the value of
|
||||
the current element.</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
Local Variables:
|
||||
mode: sgml
|
||||
sgml-declaration: "../chapter.decl"
|
||||
sgml-indent-data: t
|
||||
sgml-omittag: nil
|
||||
sgml-always-quote-attributes: t
|
||||
sgml-parent-document: ("../book.sgml" "part" "chapter")
|
||||
End:
|
||||
-->
|
||||
|
||||
Loading…
Reference in a new issue