New build system
Simon L. Nielsen
simon at nitro.dk
Tue May 27 15:36:53 UTC 2003
On 2003.05.27 17:34:39 +0200, Simon L. Nielsen wrote:
> To get an idea of what to implement/support and to actually have
> documentation for the build system, when completed, I have started a
> article about it. It can be found in text version attached or at
> http://simon.nitro.dk/freebsd/doc-buildsystem/article.html in HTML.
And of course I forgot to attach it :-) Should be here this time.
--
Simon L. Nielsen
-------------- next part --------------
Next generation FreeBSD documentation build system
Simon L. Nielsen
simon at nitro.dk
$FreeBSD: doc/en_US.ISO8859-1/articles/doc-buildsystem/article.sgml,v
1.1.1000.9 2003/05/27 14:57:09 simonln Exp $
Copyright (c) 2003 by The FreeBSD Documentation Project
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.
Important: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
PROJECT "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 THE FREEBSD
DOCUMENTATION PROJECT 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.
This document describes the authors proposal for FreeBSD Next Generation
documentation build system.
----------------------------------------------------------------------
----------------------------------------------------------------------
1 Introduction
This document tries to describe a new build system for the FreeBSD
documentation, i.e. the doc/ part of the FreeBSD CVS repository.
Next Generation is a bit overused, but the best I can come up with at this
time. Please feel free to suggest alternatives.
The updated working copy of this document is available at
http://simon.nitro.dk/freebsd/doc-buildsystem/article.html.
Please note that this document is in no way an official FreeBSD document
(yet anyway), and are solely based on the authors ideas on how a new
documentation build system could be.
Warning: This document is still work in progress! Do not consider this
document complete at all. Please send comments to <simon at nitro.dk> or
FreeBSD documentation project mailing list.
----------------------------------------------------------------------
2 Goals / requirements
The categorization is mainly of the order of which things will be
implemented/supported. All things in the must and should support lists
will most likely get implemented.
Note: When referring to building with OBJDIR what is actually meant is
building the documentation where the temporary files are stored in
/usr/obj instead of the source tree, by running make obj before
building.
Note: The ordering withing each list is more or less random.
The new doc build system must support
* Building then entire current documentation set.
* Output in HTML (single and split), TXT, PDF, PS, and RTF formats.
* Build both with and without OBJDIR.
* Only build the images which are shared between translations once when
building all translations.
* Don't copy images when building (OBJDIR mainly).
* The cleandir target should work with or without OBJDIR.
* Support for DSSSL and XSL style sheets.
* Good documentation of the build system including comments in the
makefiles.
* Support proper use of DESTDIR which does not conflict with the meaning
in the normal FreeBSD source tree.
* Consistent use of boolean variables.
* Support for multiple HTML to text converters and a simple way to
switch between them. Inspired by multiple threads about which
``converter'' to use on the FreeBSD documentation project mailing list
and e.g. PR docs/50211.
* Support compressing output with bzip2(1), gzip(1), compress(1) and
zip.
The new doc build system should support
* XML DocBook documents.
* XML DocBook build tools by converting SGML DocBook documents to XML
DocBook documents during build.
* Building on other operation systems than FreeBSD.
* Use as much of the normal FreeBSD build system as possible; that is
src/share/mk.
* Output in PDB (Palm Pilot Documentation).
* A simple way to ad pre/post process targets to each build stage. PR
docs/33589.
* Make folded books using psutils. PR docs/36432
* A simple documented way to negate all boolean variables.
* Being style.Makefile(5) compatible.
* Parallel builds using make -j X
The new doc build system might support
* HTML based documents (DOCFORMAT=html).
Note: Only en_US.ISO8859-1/articles/console-server uses the HTML
input format. It might be simpler to convert the article in question
to SGML DocBook, rather than supporting HTML articles.
* Support for path's with spaces. PR docs/35678.
Note: It is unlikely that this is possible to support with the way
make(1) works.
----------------------------------------------------------------------
3 Implementation notes/thoughts
To implement the actual installation of files bsd.files.mk can be used to
allow a more flexible handling. Some parts of the installation might still
need custom handling, since when using some output formats, e.g. the
html-split, it is not know before the build, which files are produced, and
therefor needs to be installed.
The language independent images can be handled by having them be created
by a separate makefile in doc/share/images/ and then installing symbolic
links in the build directory to the shared images. The shared images are
then build under doc/share/images/ by another make process by using SUBDIR
or similar functionality.
Note: It must be tested if all the build tools can actually handle
symbolic links...
Since shared images are now build in a sub make process dependencies does
not work. To know which image types to generate for each format there must
be a mapping ``table'' instead of the old dependencies.
The build/install can happen in several stages:
Build stages
1. Build document images.
a. Build general shared images.
b. Symlink general shared images.
c. Build per document shared images.
d. Symlink per document shared images.
e. Build per document per language specific images.
2. E.g. convert SGML to XML.
3. Build document (to HTML, TEX, PS and so on).
4. Install document and images.
5. Package document and images (e.g. tar(1) or zip).
----------------------------------------------------------------------
3.1 TODO
* Implement build of images.
* Implement build of shared images.
* Implement use of shared images in documents.
* Implement build of SGML DocBook with HTML output.
* Implement build of SGML DocBook with TEX/PS output.
* Make build system work with stub bsd.XXX.mk make include files.
* Complete this list with all the other tasks.
----------------------------------------------------------------------
3.2 Assumptions
This section contains some of the assumptions that the new build system
make. If you break any of thees the results are... ``undefined''.
* There can only be one level of image subdirectories, in IMAGES and
similar variables. E.g. foo/img.png is OK, but foo/bar/img.png will
break things.
Note: It actually may be trivial to support this anyway. Time will
show.
----------------------------------------------------------------------
4 General usage of the new build system
4.1 The document makefiles
Note: These are based on the current doc build system and may very well
be redefined during actually implementation, but where possible the old
variable names / meanings will be preserved.
Each document Makefile have several options which can/should be set.
MAINTAINER
The maintainer of the document. Defaults to <doc at freebsd.org> if
not set.
DOC
The name of the output file. Normally article or book.
DOC_PREFIX
The relative path to the root of the documentation source tree.
Should be conditionally defined with the ?= operator so the user
can override it if needed. Must be an relative path; that is may
not include .CURDIR.
SRCS
The sources used to generate the document.
HAS_INDEX
Set to indicate the document have an index which should be
handled.
FORMATS
The formats the resulting document should be generated in.
IMAGES
The per document list of images which are language dependent and
provided in the tree.
IMAGES_LIB
The general list of images which are provided in the tree.
IMAGES_EN
The per document list of images which are language independent and
provided in the tree.
SYMLINKS
TODO.
INSTALL_COMPRESSED
TODO.
INSTALL_ONLY_COMPRESSED
If set, only the compressed version of the document will be
installed.
CHAPTERS
Which chapters to build. Should be the chapter source files with
extension. The source files Only for books.
WITH_ARTICLE_TOC
Add a Table Of Contents to articles.
----------------------------------------------------------------------
4.2 User variables
Thees variables should in general not be force set in the document
Makefile, but the document Makefile may set defaults.
DESTDIR
This variable can be used to override the default tree under which
files gets installed. This is like the normal DESTDIR variable
which can be used used when installing FreeBSD.
Warning: This is different from the current meaning of DESTDIR
in the documentation build system, but since the current meaning
conflict with the meaning in the FreeBSD src/ tree it should be
changed.
----------------------------------------------------------------------
This, and other documents, can be downloaded from
ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
For questions about FreeBSD, read the documentation before contacting
<questions at FreeBSD.org>.
For questions about this documentation, e-mail <doc at FreeBSD.org>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030527/cdf8f3d9/attachment.sig>
More information about the freebsd-doc
mailing list