ceph/src/boost/tools/build/src/tools/doxygen.jam

   1 # Copyright 2003, 2004 Douglas Gregor
   2 # Copyright 2003, 2004, 2005 Vladimir Prus
   3 # Copyright 2006 Rene Rivera
   4 # Distributed under the Boost Software License, Version 1.0.
   5 # (See accompanying file LICENSE_1_0.txt or copy at
   6 # http://www.boost.org/LICENSE_1_0.txt)
   7
   8 # This module defines rules to handle generation of various outputs from source
   9 # files documented with doxygen comments. The supported transformations are:
  10 #
  11 # * Source -> Doxygen XML -> BoostBook XML
  12 # * Source -> Doxygen HTML
  13 #
  14 # The type of transformation is selected based on the target requested. For
  15 # BoostBook XML, the default, specifying a target with an ".xml" suffix, or an
  16 # empty suffix, will produce a <target>.xml and <target>.boostbook. For Doxygen
  17 # HTML specifying a target with an ".html" suffix will produce a directory
  18 # <target> with the Doxygen html files, and a <target>.html file redirecting to
  19 # that directory.
  20
  21 import alias ;
  22 import boostbook ;
  23 import "class" : new ;
  24 import common ;
  25 import feature ;
  26 import make ;
  27 import modules ;
  28 import generators ;
  29 import os ;
  30 import path ;
  31 import print ;
  32 import project ;
  33 import property ;
  34 import stage ;
  35 import targets ;
  36 import toolset ;
  37 import type ;
  38 import utility ;
  39 import xsltproc ;
  40 import virtual-target ;
  41
  42
  43 # Use to specify extra configuration paramters. These get translated into a
  44 # doxyfile which configures the building of the docs.
  45 feature.feature doxygen:param : : free ;
  46
  47 # Specify the "<xsl:param>boost.doxygen.header.prefix" XSLT option.
  48 feature.feature prefix : : free ;
  49
  50 # Specify the "<xsl:param>boost.doxygen.reftitle" XSLT option.
  51 feature.feature reftitle : : free ;
  52
  53 # Which processor to use for various translations from Doxygen.
  54 feature.feature doxygen.processor : xsltproc doxproc : propagated implicit ;
  55
  56 # To generate, or not, index sections.
  57 feature.feature doxygen.doxproc.index : no yes : propagated incidental ;
  58
  59 # The ID for the resulting BoostBook reference section.
  60 feature.feature doxygen.doxproc.id : : free ;
  61
  62 # The title for the resulting BoostBook reference section.
  63 feature.feature doxygen.doxproc.title : : free ;
  64
  65 # Location for images when generating XML
  66 feature.feature doxygen:xml-imagedir : : free ;
  67
  68 # Indicates whether the entire directory should be deleted
  69 feature.feature doxygen.rmdir : off on : optional incidental ;
  70
  71 # Doxygen configuration input file.
  72 type.register DOXYFILE : doxyfile ;
  73
  74 # Doxygen XML multi-file output.
  75 type.register DOXYGEN_XML_MULTIFILE : xml-dir : XML ;
  76
  77 # Doxygen XML coallesed output.
  78 type.register DOXYGEN_XML : doxygen : XML ;
  79
  80 # Doxygen HTML multifile directory.
  81 type.register DOXYGEN_HTML_MULTIFILE : html-dir : HTML ;
  82
  83 # Redirection HTML file to HTML multifile directory.
  84 type.register DOXYGEN_HTML : : HTML ;
  85
  86 type.register DOXYGEN_XML_IMAGES : doxygen-xml-images ;
  87
  88
  89 # Initialize the Doxygen module. Parameters are:
  90 #   name: the name of the 'doxygen' executable. If not specified, the name
  91 #         'doxygen' will be used
  92 #
  93 rule init ( name ? )
  94 {
  95     if ! $(.initialized)
  96     {
  97         .initialized = true ;
  98
  99         .doxproc = [ modules.binding $(__name__) ] ;
 100         .doxproc = $(.doxproc:D)/doxproc.py ;
 101
 102         generators.register-composing doxygen.headers-to-doxyfile
 103             : H HPP CPP MARKDOWN : DOXYFILE ;
 104         generators.register-standard doxygen.run
 105             : DOXYFILE : DOXYGEN_XML_MULTIFILE ;
 106         generators.register-standard doxygen.xml-dir-to-boostbook
 107             : DOXYGEN_XML_MULTIFILE : BOOSTBOOK : <doxygen.processor>doxproc ;
 108         generators.register-standard doxygen.xml-to-boostbook
 109             : DOXYGEN_XML : BOOSTBOOK : <doxygen.processor>xsltproc ;
 110         generators.register-standard doxygen.collect
 111             : DOXYGEN_XML_MULTIFILE : DOXYGEN_XML ;
 112         generators.register-standard doxygen.run
 113             : DOXYFILE : DOXYGEN_HTML_MULTIFILE ;
 114         generators.register-standard doxygen.html-redirect
 115             : DOXYGEN_HTML_MULTIFILE : DOXYGEN_HTML ;
 116         generators.register-standard doxygen.copy-latex-pngs
 117             : DOXYGEN_HTML : DOXYGEN_XML_IMAGES ;
 118
 119         IMPORT $(__name__) : doxygen : : doxygen ;
 120     }
 121
 122     if $(name)
 123     {
 124         modify-config ;
 125         .doxygen = $(name) ;
 126         check-doxygen ;
 127     }
 128
 129     if ! $(.doxygen)
 130     {
 131         check-doxygen ;
 132     }
 133 }
 134
 135
 136 local rule freeze-config ( )
 137 {
 138     if ! $(.initialized)
 139     {
 140         import errors ;
 141         errors.user-error doxygen must be initialized before it can be used. ;
 142     }
 143     if ! $(.config-frozen)
 144     {
 145         .config-frozen = true ;
 146         if [ .is-cygwin ]
 147         {
 148             .is-cygwin = true ;
 149         }
 150     }
 151 }
 152
 153
 154 local rule modify-config ( )
 155 {
 156     if $(.config-frozen)
 157     {
 158         import errors ;
 159         errors.user-error "Cannot change doxygen after it has been used." ;
 160     }
 161 }
 162
 163
 164 local rule check-doxygen ( )
 165 {
 166     if --debug-configuration in [ modules.peek : ARGV ]
 167     {
 168         ECHO "notice:" using doxygen ":" $(.doxygen) ;
 169     }
 170     local extra-paths ;
 171     if [ os.name ] = NT
 172     {
 173         local ProgramFiles = [ modules.peek : ProgramFiles ] ;
 174         if $(ProgramFiles)
 175         {
 176             extra-paths = "$(ProgramFiles:J= )" ;
 177         }
 178         else
 179         {
 180             extra-paths = "C:\\Program Files" ;
 181         }
 182     }
 183     .doxygen = [ common.get-invocation-command doxygen : doxygen : $(.doxygen) :
 184         $(extra-paths) ] ;
 185 }
 186
 187
 188 rule name ( )
 189 {
 190     freeze-config ;
 191     return $(.doxygen) ;
 192 }
 193
 194
 195 local rule .is-cygwin ( )
 196 {
 197     if [ os.on-windows ]
 198     {
 199         local file = [ path.make [ modules.binding $(__name__) ] ] ;
 200         local dir = [ path.native [ path.join [ path.parent $(file) ] doxygen ]
 201             ] ;
 202         local command = cd \"$(dir)\" "&&" \"$(.doxygen)\"
 203             windows-paths-check.doxyfile 2>&1 ;
 204         command = $(command:J=" ") ;
 205         result = [ SHELL $(command) ] ;
 206         if [ MATCH "(Parsing file /)" : $(result) ]
 207         {
 208             return true ;
 209         }
 210     }
 211 }
 212
 213
 214 # Runs Doxygen on the given Doxygen configuration file (the source) to generate
 215 # the Doxygen files. The output is dumped according to the settings in the
 216 # Doxygen configuration file, not according to the target! Because of this, we
 217 # essentially "touch" the target file, in effect making it look like we have
 218 # really written something useful to it. Anyone that uses this action must deal
 219 # with this behavior.
 220 #
 221 actions doxygen-action
 222 {
 223     $(RM) "$(*.XML)" & "$(NAME:E=doxygen)" "$(>)" && echo "Stamped" > "$(<)"
 224 }
 225
 226
 227 # Runs the Python doxproc XML processor.
 228 #
 229 actions doxproc
 230 {
 231     python "$(DOXPROC)" "--xmldir=$(>)" "--output=$(<)" "$(OPTIONS)" "--id=$(ID)" "--title=$(TITLE)"
 232 }
 233
 234
 235 rule translate-path ( path )
 236 {
 237     freeze-config ;
 238     if [ os.on-windows ]
 239     {
 240         if [ os.name ] = CYGWIN
 241         {
 242             if $(.is-cygwin)
 243             {
 244                 return $(path) ;
 245             }
 246             else
 247             {
 248                 return $(path:W) ;
 249             }
 250         }
 251         else
 252         {
 253             if $(.is-cygwin)
 254             {
 255                 match = [ MATCH ^(.):(.*) : $(path) ] ;
 256                 if $(match)
 257                 {
 258                     return /cygdrive/$(match[1])$(match[2]:T) ;
 259                 }
 260                 else
 261                 {
 262                     return $(path:T) ;
 263                 }
 264             }
 265             else
 266             {
 267                 return $(path) ;
 268             }
 269         }
 270     }
 271     else
 272     {
 273         return $(path) ;
 274     }
 275 }
 276
 277
 278 # Generates a doxygen configuration file (doxyfile) given a set of C++ sources
 279 # and a property list that may contain <doxygen:param> features.
 280 #
 281 rule headers-to-doxyfile ( target : sources * : properties * )
 282 {
 283     local text = "# Generated by Boost.Build version 2" ;
 284
 285     local output-dir ;
 286
 287     # Translate <doxygen:param> into command line flags.
 288     for local param in [ feature.get-values <doxygen:param> : $(properties) ]
 289     {
 290         local namevalue = [ MATCH ([^=]*)=(.*) : $(param) ] ;
 291         if $(namevalue[1]) = OUTPUT_DIRECTORY
 292         {
 293             output-dir = [ translate-path [ utility.unquote $(namevalue[2]) ] ]
 294                 ;
 295             text += "OUTPUT_DIRECTORY = \"$(output-dir)\"" ;
 296         }
 297         else
 298         {
 299             text += "$(namevalue[1]) = $(namevalue[2])" ;
 300         }
 301     }
 302
 303     if ! $(output-dir)
 304     {
 305         output-dir = [ translate-path [ on $(target) return $(LOCATE) ] ] ;
 306         text += "OUTPUT_DIRECTORY = \"$(output-dir)\"" ;
 307     }
 308
 309     local headers ;
 310     for local header in $(sources:G=)
 311     {
 312         header = [ translate-path $(header) ] ;
 313         headers += \"$(header)\" ;
 314     }
 315
 316     # Doxygen generates LaTex by default. So disable it unconditionally, or at
 317     # least until someone needs, and hence writes support for, LaTex output.
 318     text += "GENERATE_LATEX = NO" ;
 319     text += "INPUT = $(headers:J= )" ;
 320     print.output $(target) plain ;
 321     print.text $(text) : true ;
 322 }
 323
 324
 325 # Run Doxygen. See doxygen-action for a description of the strange properties of
 326 # this rule.
 327 #
 328 rule run ( target : source : properties * )
 329 {
 330     freeze-config ;
 331     if <doxygen.rmdir>on in $(properties)
 332     {
 333         local output-dir = [ path.make [ MATCH
 334             <doxygen:param>OUTPUT_DIRECTORY=\"?([^\"]*) : $(properties) ] ] ;
 335         local html-dir = [ path.make [ MATCH <doxygen:param>HTML_OUTPUT=(.*) :
 336             $(properties) ] ] ;
 337         if $(output-dir) && $(html-dir) &&
 338             [ path.glob $(output-dir) : $(html-dir) ]
 339         {
 340             HTMLDIR on $(target) = [ path.native [ path.join $(output-dir)
 341                 $(html-dir) ] ] ;
 342             rm-htmldir $(target) ;
 343         }
 344     }
 345     doxygen-action $(target) : $(source) ;
 346     NAME on $(target) = $(.doxygen) ;
 347     RM on $(target) = [ modules.peek common : RM ] ;
 348     *.XML on $(target) = [ path.native [ path.join [ path.make [ on $(target)
 349         return $(LOCATE) ] ] $(target:B:S=) *.xml ] ] ;
 350 }
 351
 352
 353 if [ os.name ] = NT
 354 {
 355     RMDIR = rmdir /s /q ;
 356 }
 357 else
 358 {
 359     RMDIR = rm -rf ;
 360 }
 361
 362 actions quietly rm-htmldir
 363 {
 364     $(RMDIR) $(HTMLDIR)
 365 }
 366
 367
 368 # The rules below require BoostBook stylesheets, so we need some code to check
 369 # that the boostbook module has actualy been initialized.
 370 #
 371 rule check-boostbook ( )
 372 {
 373     if ! [ modules.peek boostbook : .initialized ]
 374     {
 375         import errors ;
 376         errors.user-error
 377             : The boostbook module is not initialized you have attempted to use
 378             : the 'doxygen' toolset, which requires BoostBook, but never
 379             : initialized BoostBook.
 380             : Hint: add 'using boostbook ;' to your user-config.jam. ;
 381     }
 382 }
 383
 384
 385 # Collect the set of Doxygen XML files into a single XML source file that can be
 386 # handled by an XSLT processor. The source is completely ignored (see
 387 # doxygen-action), because this action picks up the Doxygen XML index file xml/
 388 # index.xml. This is because we can not teach Doxygen to act like a NORMAL
 389 # program and take a "-o output.xml" argument (grrrr). The target of the
 390 # collection will be a single Doxygen XML file.
 391 #
 392 rule collect ( target : source : properties * )
 393 {
 394     check-boostbook ;
 395     local collect-xsl-dir
 396         = [ path.native [ path.join [ boostbook.xsl-dir ] doxygen collect ] ] ;
 397     local source-path
 398         = [ path.make [ on $(source) return $(LOCATE) ] ] ;
 399     local collect-path
 400         = [ path.root [ path.join $(source-path) $(source:B) ] [ path.pwd ] ] ;
 401     local native-path
 402         = [ path.native $(collect-path) ] ;
 403     local real-source
 404         = [ path.native [ path.join $(collect-path) index.xml ] ] ;
 405     xsltproc.xslt $(target) : $(real-source) $(collect-xsl-dir:S=.xsl)
 406         : <xsl:param>doxygen.xml.path=$(native-path) ;
 407 }
 408
 409
 410 # Translate Doxygen XML into BoostBook.
 411 #
 412 rule xml-to-boostbook ( target : source : properties * )
 413 {
 414     check-boostbook ;
 415     local xsl-dir = [ boostbook.xsl-dir ] ;
 416     local d2b-xsl = [ path.native [ path.join [ boostbook.xsl-dir ] doxygen
 417         doxygen2boostbook.xsl ] ] ;
 418
 419     local xslt-properties = $(properties) ;
 420     for local prefix in [ feature.get-values <prefix> : $(properties) ]
 421     {
 422         xslt-properties += "<xsl:param>boost.doxygen.header.prefix=$(prefix)" ;
 423     }
 424     for local title in [ feature.get-values <reftitle> : $(properties) ]
 425     {
 426         xslt-properties += "<xsl:param>boost.doxygen.reftitle=$(title)" ;
 427     }
 428
 429     xsltproc.xslt $(target) : $(source) $(d2b-xsl) : $(xslt-properties) ;
 430 }
 431
 432
 433 toolset.flags doxygen.xml-dir-to-boostbook OPTIONS <doxygen.doxproc.index>yes :
 434     --enable-index ;
 435 toolset.flags doxygen.xml-dir-to-boostbook ID <doxygen.doxproc.id> ;
 436 toolset.flags doxygen.xml-dir-to-boostbook TITLE <doxygen.doxproc.title> ;
 437
 438
 439 rule xml-dir-to-boostbook ( target : source : properties * )
 440 {
 441     DOXPROC on $(target) = $(.doxproc) ;
 442     LOCATE on $(source:S=) = [ on $(source) return $(LOCATE) ] ;
 443     doxygen.doxproc $(target) : $(source:S=) ;
 444 }
 445
 446
 447 # Generate the HTML redirect to HTML dir index.html file.
 448 #
 449 rule html-redirect ( target : source : properties * )
 450 {
 451     local uri = "$(target:B)/index.html" ;
 452     print.output $(target) plain ;
 453     print.text
 454 "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\"
 455     \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">
 456 <html xmlns=\"http://www.w3.org/1999/xhtml\">
 457 <head>
 458   <meta http-equiv=\"refresh\" content=\"0; URL=$(uri)\" />
 459
 460   <title></title>
 461 </head>
 462
 463 <body>
 464   Automatic redirection failed, please go to <a href=
 465   \"$(uri)\">$(uri)</a>.
 466 </body>
 467 </html>
 468 "
 469         : true ;
 470 }
 471
 472 rule copy-latex-pngs ( target : source : requirements * )
 473 {
 474     local directory = [ path.native [ feature.get-values <doxygen:xml-imagedir>
 475         : $(requirements) ] ] ;
 476     local location = [ on $(target) return $(LOCATE) ] ;
 477
 478     local pdf-location = [ path.native [ path.join [ path.make $(location) ]
 479         [ path.make $(directory) ] ] ] ;
 480     local html-location = [ path.native [ path.join . html [ path.make
 481         $(directory) ] ] ] ;
 482
 483     common.MkDir $(pdf-location) ;
 484     common.MkDir $(html-location) ;
 485
 486     DEPENDS $(target) : $(pdf-location) $(html-location) ;
 487
 488     if [ os.name ] = NT
 489     {
 490         CP on $(target) = copy /y ;
 491         FROM on $(target) = \\*.png ;
 492         TOHTML on $(target) = .\\html\\$(directory) ;
 493         TOPDF on $(target) = \\$(directory) ;
 494     }
 495     else
 496     {
 497         CP on $(target) = cp ;
 498         FROM on $(target) = /*.png ;
 499         TOHTML on $(target) = ./html/$(directory) ;
 500         TOPDF on $(target) = $(target:D)/$(directory) ;
 501     }
 502 }
 503
 504 actions copy-latex-pngs
 505 {
 506     $(CP) $(>:S=)$(FROM) $(TOHTML)
 507     $(CP) $(>:S=)$(FROM) $(<:D)$(TOPDF)
 508     echo "Stamped" > "$(<)"
 509 }
 510
 511
 512 # Building latex images for doxygen XML depends on latex, dvips, and gs being in
 513 # your PATH. This is true for most Unix installs, but not on Win32, where you
 514 # will need to install MkTex and Ghostscript and add these tools to your path.
 515
 516 actions check-latex
 517 {
 518     latex -version >$(<)
 519 }
 520
 521 actions check-dvips
 522 {
 523     dvips -version >$(<)
 524 }
 525
 526 if [ os.name ] = "NT"
 527 {
 528     actions check-gs
 529     {
 530         gswin32c -version >$(<)
 531     }
 532 }
 533 else
 534 {
 535     actions check-gs
 536     {
 537         gs -version >$(<)
 538     }
 539 }
 540
 541
 542 local rule check-tools-targets ( project )
 543 {
 544     if ! $(.check-tools-targets)
 545     {
 546         # Find the root project.
 547         #
 548         # This is a best effort attempt to avoid using different locations for
 549         # storing *.check files depending on which project imported the doxygen
 550         # toolset first. The files are stored in a location related to the
 551         # project's root project. Note that this location may change depending
 552         # on the folder the build was run from in case the build uses multiple
 553         # related projects with their own Jamroot separate modules.
 554         local project-module = [ $(project).project-module ] ;
 555         local root-module = [ project.get-jamroot-module $(project-module) ] ;
 556         if ! $(root-module)
 557         {
 558             import errors ;
 559             if [ project.is-config-module $(project-module) ]
 560             {
 561                 errors.user-error doxygen targets can not be declared in Boost
 562                     Build's configuration modules. ;
 563             }
 564             else
 565             {
 566                 errors.user-error doxygen targets can not be declared in
 567                     standalone projects. : use a Jamfile/Jamroot project
 568                     instead. ;
 569             }
 570         }
 571         local root-project = [ project.target $(root-module) ] ;
 572
 573         local targets =
 574             [ new file-target latex.check : : $(root-project) : [ new action :
 575                 doxygen.check-latex ] ]
 576             [ new file-target dvips.check : : $(root-project) : [ new action :
 577                 doxygen.check-dvips ] ]
 578             [ new file-target gs.check : : $(root-project) : [ new action :
 579                 doxygen.check-gs ] ] ;
 580
 581         for local target in $(targets)
 582         {
 583             .check-tools-targets += [ virtual-target.register $(target) ] ;
 584         }
 585     }
 586     return $(.check-tools-targets) ;
 587 }
 588
 589
 590 project.initialize $(__name__) ;
 591 project doxygen ;
 592
 593 class doxygen-check-tools-target-class : basic-target
 594 {
 595     rule construct ( name : sources * : property-set )
 596     {
 597         IMPORT doxygen : check-tools-targets : $(__name__) :
 598             doxygen.check-tools-targets ;
 599         return [ property-set.empty ] [ doxygen.check-tools-targets [ project ]
 600             ] ;
 601     }
 602 }
 603
 604
 605 # Declares a metatarget for collecting version information on different external
 606 # tools used in this module.
 607 #
 608 rule check-tools ( target )
 609 {
 610     freeze-config ;
 611     targets.create-metatarget doxygen-check-tools-target-class :
 612         [ project.current ] : $(target) ;
 613 }
 614
 615
 616 # User-level rule to generate HTML files or BoostBook XML from a set of headers
 617 # via Doxygen.
 618 #
 619 rule doxygen ( target : sources + : requirements * : default-build * :
 620     usage-requirements * )
 621 {
 622     requirements += <format>none ;
 623     freeze-config ;
 624     local project = [ project.current ] ;
 625
 626     if $(target:S) = .html
 627     {
 628         # Build an HTML directory from the sources.
 629         local html-location = [ feature.get-values <location> : $(requirements)
 630             ] ;
 631         local output-dir ;
 632         if [ $(project).get build-dir ]
 633         {
 634             # Explicitly specified build dir. Add html at the end.
 635             output-dir = [ path.join [ $(project).build-dir ]
 636                 $(html-location:E=html) ] ;
 637         }
 638         else
 639         {
 640             # Trim 'bin' from implicit build dir, for no other reason than
 641             # backward compatibility.
 642             output-dir = [ path.join [ path.parent [ $(project).build-dir ] ]
 643                 $(html-location:E=html) ] ;
 644         }
 645         output-dir = [ path.root $(output-dir) [ path.pwd ] ] ;
 646         local output-dir-native = [ path.native $(output-dir) ] ;
 647         requirements = [ property.change $(requirements) : <location> ] ;
 648
 649         # The doxygen configuration file.
 650         targets.create-typed-target DOXYFILE : $(project) : $(target:S=.tag)
 651             : $(sources)
 652             : $(requirements)
 653                 <doxygen:param>GENERATE_HTML=YES
 654                 <doxygen:param>GENERATE_XML=NO
 655                 <doxygen:param>"OUTPUT_DIRECTORY=\"$(output-dir-native)\""
 656                 <doxygen:param>HTML_OUTPUT=$(target:B)
 657             : $(default-build) ;
 658         $(project).mark-target-as-explicit $(target:S=.tag) ;
 659
 660         # The html directory to generate by running doxygen.
 661         targets.create-typed-target DOXYGEN_HTML_MULTIFILE : $(project)
 662             : $(target:S=.dir)  # Name.
 663             : $(target:S=.tag)  # Sources.
 664             : $(requirements)
 665                 <doxygen:param>"OUTPUT_DIRECTORY=\"$(output-dir-native)\""
 666                 <doxygen:param>HTML_OUTPUT=$(target:B)
 667             : $(default-build) ;
 668         $(project).mark-target-as-explicit $(target:S=.dir) ;
 669
 670         # The redirect html file into the generated html.
 671         targets.create-typed-target DOXYGEN_HTML : $(project) : $(target)
 672             : $(target:S=.dir)  # Sources.
 673             : $(requirements) <location>$(output-dir)
 674             : $(default-build) ;
 675     }
 676     else
 677     {
 678         # Build a BoostBook XML file from the sources.
 679         local location-xml = [ feature.get-values <location> : $(requirements) ]
 680             ;
 681         requirements = [ property.change $(requirements) : <location> ] ;
 682         local target-xml = $(target:B=$(target:B)-xml) ;
 683
 684         # Check whether we need to build images.
 685         local images-location = [ feature.get-values <doxygen:xml-imagedir> :
 686             $(requirements) ] ;
 687         if $(images-location)
 688         {
 689             # Prepare a metatarget for collecting used external tool version
 690             # information. We use only one such metatarget as they always
 691             # produce the same files and we do not want to deal with multiple
 692             # metatargets having matching names, causing 'ambiguous variants'
 693             # errors.
 694             if ! $(.check-tools)
 695             {
 696                 # FIXME: Since we have the check-tools target object reference,
 697                 # see how we can use that instead of having to construct a valid
 698                 # target reference string for use in <dependency> property
 699                 # values.
 700                 local project-id = --doxygen.check-tools-project-- ;
 701                 local target-id = --doxygen.check-tools-- ;
 702                 local pm = [ $(project).project-module ] ;
 703                 project.register-id $(project-id) : $(pm) ;
 704                 check-tools $(target-id) ;
 705                 .check-tools = /$(project-id)//$(target-id) ;
 706             }
 707
 708             doxygen $(target).doxygen-xml-images.html : $(sources) :
 709                 $(requirements)
 710                 <doxygen.rmdir>on
 711                 <doxygen:param>QUIET=YES
 712                 <doxygen:param>WARNINGS=NO
 713                 <doxygen:param>WARN_IF_UNDOCUMENTED=NO
 714                 <dependency>$(.check-tools) ;
 715             $(project).mark-target-as-explicit $(target).doxygen-xml-images.html
 716                 ;
 717
 718             targets.create-typed-target DOXYGEN_XML_IMAGES : $(project)
 719                 : $(target).doxygen-xml-images  # Name.
 720                 : $(target).doxygen-xml-images.html  # Sources.
 721                 : $(requirements)
 722                 : $(default-build) ;
 723             $(project).mark-target-as-explicit $(target).doxygen-xml-images ;
 724
 725             if ! [ MATCH (/)$ : $(images-location) ]
 726             {
 727                 images-location = $(images-location)/ ;
 728             }
 729
 730             requirements +=
 731                 <dependency>$(target).doxygen-xml-images
 732                 <xsl:param>boost.doxygen.formuladir=$(images-location) ;
 733         }
 734
 735         # The doxygen configuration file.
 736         targets.create-typed-target DOXYFILE : $(project) : $(target-xml:S=.tag)
 737             : $(sources)
 738             : $(requirements)
 739                 <doxygen:param>GENERATE_HTML=NO
 740                 <doxygen:param>GENERATE_XML=YES
 741                 <doxygen:param>XML_OUTPUT=$(target-xml)
 742             : $(default-build) ;
 743         $(project).mark-target-as-explicit $(target-xml:S=.tag) ;
 744
 745         # The Doxygen XML directory for the processed source files.
 746         targets.create-typed-target DOXYGEN_XML_MULTIFILE : $(project)
 747             : $(target-xml:S=.dir)  # Name.
 748             : $(target-xml:S=.tag)  # Sources.
 749             : $(requirements)
 750             : $(default-build) ;
 751         $(project).mark-target-as-explicit $(target-xml:S=.dir) ;
 752
 753         # The resulting BoostBook file is generated by the processor tool. The
 754         # tool can be either the xsltproc plus accompanying XSL scripts. Or it
 755         # can be the python doxproc.py script.
 756         targets.create-typed-target BOOSTBOOK : $(project) : $(target-xml)
 757             : $(target-xml:S=.dir)  # Sources.
 758             : $(requirements)
 759             : $(default-build) ;
 760         $(project).mark-target-as-explicit $(target-xml) ;
 761
 762         stage $(target:S=.xml)  # Name.
 763             : $(target-xml)  # Sources.
 764             : $(requirements)
 765                 <location>$(location-xml:E=.)
 766                 <name>$(target:S=.xml)
 767             : $(default-build) ;
 768         $(project).mark-target-as-explicit $(target:S=.xml) ;
 769
 770         # TODO: See why this alias target is used here instead of simply naming
 771         # the previous stage target $(target) and having it specify the alias
 772         # target's usage requirements directly.
 773         alias $(target) : : $(requirements) : $(default-build) :
 774             $(usage-requirements) <dependency>$(target:S=.xml) ;
 775     }
 776 }