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