doxygen.jam

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

# Copyright 2003, 2004 Douglas Gregor
# Copyright 2003, 2004, 2005 Vladimir Prus
# Copyright 2006 Rene Rivera
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

# This module defines rules to handle generation of various outputs from source
# files documented with doxygen comments. The supported transformations are:
#
# * Source -> Doxygen XML -> BoostBook XML
# * Source -> Doxygen HTML
#
# The type of transformation is selected based on the target requested. For
# BoostBook XML, the default, specifying a target with an ".xml" suffix, or an
# empty suffix, will produce a <target>.xml and <target>.boostbook. For Doxygen
# HTML specifying a target with an ".html" suffix will produce a directory
# <target> with the Doxygen html files, and a <target>.html file redirecting to
# that directory.

import "class" : new ;
import targets ;
import feature ;
import property ;
import generators ;
import boostbook ;
import type ;
import path ;
import print ;
import regex ;
import stage ;
import project ;
import xsltproc ;
import make ;
import os ;
import toolset : flags ;
import alias ;
import common ;
import modules ;


# Use to specify extra configuration paramters. These get translated
# into a doxyfile which configures the building of the docs.
feature.feature doxygen:param : : free ;

# Specify the "<xsl:param>boost.doxygen.header.prefix" XSLT option.
feature.feature prefix : : free ;

# Specify the "<xsl:param>boost.doxygen.reftitle" XSLT option.
feature.feature reftitle : : free ;

# Which processor to use for various translations from Doxygen.
feature.feature doxygen.processor : xsltproc doxproc : propagated implicit ;

# To generate, or not, index sections.
feature.feature doxygen.doxproc.index : no yes : propagated incidental ;

# The ID for the resulting BoostBook reference section.
feature.feature doxygen.doxproc.id : : free ;

# The title for the resulting BoostBook reference section.
feature.feature doxygen.doxproc.title : : free ;

# Doxygen configuration input file.
type.register DOXYFILE : doxyfile ;

# Doxygen XML multi-file output.
type.register DOXYGEN_XML_MULTIFILE : xml-dir : XML ;

# Doxygen XML coallesed output.
type.register DOXYGEN_XML : doxygen : XML ;

# Doxygen HTML multifile directory.
type.register DOXYGEN_HTML_MULTIFILE : html-dir : HTML ;

# Redirection HTML file to HTML multifile directory.
type.register DOXYGEN_HTML : : HTML ;


# Initialize the Doxygen module. Parameters are:
#   name: the name of the 'doxygen' executable. If not specified, the name
#         'doxygen' will be used
#
rule init ( name ? )
{
    if ! $(.initialized)
    {
        .initialized = true ;

        if ! $(name)
        {
            local doxygen-path ;

            if [ os.name ] = NT
            {
                local ProgramFiles = [ modules.peek : ProgramFiles ] ;
                if $(ProgramFiles)
                {
                    ProgramFiles = "$(ProgramFiles:J= )" ;
                }
                else
                {
                    ProgramFiles = "C:\\Program Files" ;
                }

                doxygen-path =
                    [ GLOB
                        [ modules.peek : PATH ]
                        "$(ProgramFiles)\\doxygen\\bin"
                        : doxygen\.exe ] ;
            }
            else
            {
                doxygen-path =
                    [ GLOB
                        [ modules.peek : PATH ]
                        : doxygen ] ;
            }

            doxygen-path = $(doxygen-path[1]) ;

            if $(doxygen-path)
            {
                .doxygen = $(doxygen-path) ;
            }

            .doxygen ?= doxygen ;
        }
        else
        {
            .doxygen = $(name) ;
        }

        if --debug-configuration in [ modules.peek : ARGV ]
        {
            ECHO "notice:" using doxygen ":" $(.doxygen) ;
        }

        .doxproc = [ modules.binding $(__name__) ] ;
        .doxproc = $(.doxproc:D)/doxproc.py ;

        generators.register-composing doxygen.headers-to-doxyfile
            : H HPP CPP : DOXYFILE ;
        generators.register-standard doxygen.run
            : DOXYFILE : DOXYGEN_XML_MULTIFILE ;
        generators.register-standard doxygen.xml-dir-to-boostbook
            : DOXYGEN_XML_MULTIFILE : BOOSTBOOK : <doxygen.processor>doxproc ;
        generators.register-standard doxygen.xml-to-boostbook
            : DOXYGEN_XML : BOOSTBOOK : <doxygen.processor>xsltproc ;
        generators.register-standard doxygen.collect
            : DOXYGEN_XML_MULTIFILE : DOXYGEN_XML ;
        generators.register-standard doxygen.run
            : DOXYFILE : DOXYGEN_HTML_MULTIFILE ;
        generators.register-standard doxygen.html-redirect
            : DOXYGEN_HTML_MULTIFILE : DOXYGEN_HTML ;

        IMPORT $(__name__) : doxygen : : doxygen ;
    }
}


rule name ( )
{
    return $(.doxygen) ;
}


# Runs Doxygen on the given Doxygen configuration file (the source) to generate
# the Doxygen files. The output is dumped according to the settings in the
# Doxygen configuration file, not according to the target! Because of this, we
# essentially "touch" the target file, in effect making it look like we have
# really written something useful to it. Anyone that uses this action must deal
# with this behavior.
#
actions doxygen-action
{
    $(RM) "$(*.XML)" & "$(NAME:E=doxygen)" "$(>)" && echo "Stamped" > "$(<)"
}


# Runs the Python doxproc XML processor.
#
actions doxproc
{
    python "$(DOXPROC)" "--xmldir=$(>)" "--output=$(<)" "$(OPTIONS)" "--id=$(ID)" "--title=$(TITLE)"
}


# Generates a doxygen configuration file (doxyfile) given a set of C++ sources
# and a property list that may contain <doxygen:param> features.
#
rule headers-to-doxyfile ( target : sources * : properties * )
{
    local text "# Generated by Boost.Build version 2" ;

    local output-dir ;

    # Translate <doxygen:param> into command line flags.
    for local param in [ feature.get-values <doxygen:param> : $(properties) ]
    {
        local namevalue = [ regex.match ([^=]*)=(.*) : $(param) ] ;
        text += "$(namevalue[1]) = $(namevalue[2])" ;
        if $(namevalue[1]) = OUTPUT_DIRECTORY
        {
            output-dir = "$(namevalue[2])" ;
        }
    }

    if ! $(output-dir)
    {
        output-dir = [ on $(target) return $(LOCATE) ] ;
        text += "OUTPUT_DIRECTORY = \"$(output-dir)\"" ;
    }

    local headers = \"$(sources:G=)\" ;

    # Doxygen generates LaTex by default. So disable it unconditionally, or at
    # least until someone needs, and hence writes support for, LaTex output.
    text += "GENERATE_LATEX = NO" ;
    text += "INPUT = $(headers:J= )" ;
    print.output $(target) plain ;
    print.text $(text) : true ;
}


# Run Doxygen. See doxygen-action for a description of the strange properties of
# this rule.
#
rule run ( target : source : properties * )
{
    doxygen-action $(target) : $(source) ;
    NAME on $(target) = $(.doxygen) ;