build/v2/tools/doxygen.jam

#  Copyright (C) 2003 Doug Gregor. Permission to copy, use, modify,
#  sell and distribute this software is granted provided this
#  copyright notice appears in all copies. This software is provided
#  "as is" without express or implied warranty, and with no claim as
#  to its suitability for any purpose.

#  This module defines rules to handle generation of BoostBook XML
#  from Doxygen XML output. 

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 ;

feature.feature doxygen:param : : free ;
feature.feature prefix : : free ;
feature.feature reftitle : : free ;

type.register DOXYFILE : doxyfile ; # Doxygen input file
type.register DOXYGEN_XML_MULTIFILE : : XML ; # Doxygen XML multi-file output
type.register DOXYGEN_XML : doxygen : XML ; # Doxygen XML output

# 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)
    {
      .doxygen = $(name) ; 
    }   
    
    generators.register-composing doxygen.headers-to-doxyfile : H HPP : DOXYFILE ; 
    generators.register-standard doxygen.run : DOXYFILE : DOXYGEN_XML_MULTIFILE ;
    generators.register-standard doxygen.xml-to-boostbook : DOXYGEN_XML : BOOSTBOOK ;
    generators.register-standard doxygen.collect : DOXYGEN_XML_MULTIFILE : DOXYGEN_XML ;
            
    IMPORT $(__name__) : doxygen : : doxygen ;
  }
}

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

# Runs Doxygen on the given Doxygen configuration file (the source) to
# generate Doxygen XML (in multiple 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've really written
# something useful to it. Anyone that uses this action must deal with
# this behavior.  
actions doxygen-action 
{
  "$(NAME:E=doxygen)" $(>) ;
  echo "Stamped" > "$(<)"
}

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

  # 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])" ;
  }
 
  local headers = "" ;
  for local source in $(sources:G=)
  {
    headers = "$(headers) $(source)" ;
  }

  text += "GENERATE_HTML = NO" ;
  text += "GENERATE_LATEX = NO" ;
  text += "GENERATE_XML = YES" ;
  text += "INPUT = $(headers) " ;
  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) ;
}

# The rules below require Boost.Book stylesheets, so we need
# some code to check that the boostbook module is actaully
# initialized.
rule check-boostbook ( )
{
    if ! [ modules.peek boostbook : .initialized ]
    {
        ECHO "error: the boostbook module is not initialized" ;
        ECHO "error: you've attempted to use the 'doxygen' toolset, " ;
        ECHO "error: which requires Boost.Book," ;
        ECHO "error: but never initialized Boost.Book." ;
        EXIT "error: Hint: add 'using boostbook ;' to your user-config.jam" ;
    }      
}


# Collect the set of Doxygen XML files into a single XML source file
# that can be handled by an XSLT processor. The source is completely
# ignored (see doxygen-action), because this action picks up the
# Doxygen XML index file xml/index.xml. This is because we can't teach
# Doxygen to act like a NORMAL program and take a "-o output.xml"
# argument (grrrr). The target of the collection will be a single
# Doxygen XML file.
rule collect ( target : source : properties * )
{
  check-boostbook ;
  local collect-xsl-dir = [ path.native 
                        [ path.join [ boostbook.xsl-dir ] doxygen collect ] 
                          ] ;
  local collect-path = [ path.join [ path.pwd ] xml ] ;
  local real-source = [ path.native xml/index.xml ] ;
  NOTFILE $(real-source) ;
  xsltproc.xslt $(target) : $(real-source) $(collect-xsl-dir:S=.xsl) 
                 : <xsl:param>doxygen.xml.path=$(collect-path)
                 ;
}

# Translate Doxygen XML into BoostBook
rule xml-to-boostbook ( target : source : properties * )
{
  check-boostbook ;
  local xsl-dir = [ boostbook.xsl-dir ] ;
  local d2b-xsl = [ path.native 
                  [ path.join [ boostbook.xsl-dir ] doxygen 
                    doxygen2boostbook.xsl ] ] ;

  local xslt-properties = $(properties) ;
  for local prefix in [ feature.get-values <prefix> : $(properties) ]
  {
    xslt-properties += "<xsl:param>boost.doxygen.header.prefix=$(prefix)" ;
  }
  for local title in [ feature.get-values <reftitle> : $(properties) ]
  {
    xslt-properties += "<xsl:param>boost.doxygen.reftitle=\"$(title)\"" ;
  }

  xsltproc.xslt $(target) : $(source) $(d2b-xsl) : $(xslt-properties) ;
}

# User-level rule to generate BoostBook XML from a set of headers via Doxygen. 
rule doxygen ( target-name : sources * : requirements * : default-build * )
{
  local project = [ project.current ] ;

  local doxyfile = [ 
    new typed-target $(target-name) : $(project) : BOOSTBOOK
        : [ targets.main-target-sources $(sources) : $(target-name) ] 
        : [ targets.main-target-requirements $(requirements) : $(project) ] 
        : [ targets.main-target-default-build $(default-build) : $(project) ]
    ] ;

  targets.main-target-alternative $(doxyfile) ;

  targets.main-target-alternative
    [ new install-target-class $(target-name:S=.xml) : $(project) 
      : [ $(doxyfile).name ]
      : [ targets.main-target-requirements $(requirements) <location>. : $(project) ] 
      : [ targets.main-target-default-build $(default-build) : $(project) ] 
    ] ;
}