From 89143e97237011ebf60ea2a503ed059a89c82ba6 Mon Sep 17 00:00:00 2001 From: Rene Rivera Date: Wed, 19 Apr 2006 20:13:54 +0000 Subject: [PATCH] Fix missing online help docs, and refactor to not use header scanning to speed up the parsing of Jamfiles for docs. [SVN r33746] --- src/build-system.jam | 3 -- src/build/project.jam | 2 +- src/kernel/bootstrap.jam | 26 ++++++--- src/options/help.jam | 61 ++++++++++++--------- src/util/doc.jam | 112 +++++++++++++++++++++++++++++---------- src/util/option.jam | 7 +-- 6 files changed, 141 insertions(+), 70 deletions(-) diff --git a/src/build-system.jam b/src/build-system.jam index 90a2a6895..5100dcd74 100755 --- a/src/build-system.jam +++ b/src/build-system.jam @@ -26,7 +26,6 @@ import "class" : new ; import builtin ; import make ; import os ; -import option ; import version ; @@ -141,8 +140,6 @@ if --version in [ modules.peek : ARGV ] } -option.process ; - # We always load project in "." so that 'use-project' directives has # any chance of been seen. Otherwise, we won't be able to refer to diff --git a/src/build/project.jam b/src/build/project.jam index 0a512e523..dd7fe3920 100644 --- a/src/build/project.jam +++ b/src/build/project.jam @@ -204,7 +204,7 @@ JAMFILE ?= [Bb]uild.jam [Jj]amfile.v2 [Jj]amfile [Jj]amfile.jam ; # causes this to search not the given directory but the ones above it up # to the directory given in it. # -local rule find-jamfile ( +rule find-jamfile ( dir # The directory(s) to look for a Jamfile. parent-root ? # Optional flag indicating to search for the parent Jamfile. : no-errors ? diff --git a/src/kernel/bootstrap.jam b/src/kernel/bootstrap.jam index 5d8736caf..67b681449 100755 --- a/src/kernel/bootstrap.jam +++ b/src/kernel/bootstrap.jam @@ -1,5 +1,5 @@ # (C) Copyright David Abrahams, 2001. -# (C) Copyright Rene Rivera, 2003. +# (C) Copyright Rene Rivera, 2003 2006. # # See accompanying license for terms and conditions of use. # @@ -112,11 +112,23 @@ IMPORT modules : import : : import ; # import modules ; -# Allow users to override the build system file from the -# command-line (mostly for testing) -local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ; -build-system ?= build-system ; +# Process option plugins first to alow them to prevent loading +# the rest of the build system. +# +import option ; +local dont-build = [ option.process ] ; -# Use last element in case of multiple command-line options -import $(build-system[-1]) ; +# Should we skip building, i.e. loding the build system, according +# to the options processed? +# +if ! $(dont-build) +{ + # Allow users to override the build system file from the + # command-line (mostly for testing) + local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ; + build-system ?= build-system ; + + # Use last element in case of multiple command-line options + import $(build-system[-1]) ; +} diff --git a/src/options/help.jam b/src/options/help.jam index 05d1fcb25..c087592ee 100755 --- a/src/options/help.jam +++ b/src/options/help.jam @@ -13,6 +13,7 @@ import sequence ; import set ; import project ; import print ; +import os ; # List of possible modules, but which really aren't. @@ -57,37 +58,36 @@ rule process ( local module-files = [ GLOB $(path-to-modules) : $(m)\\.jam ] ; modules-to-scan += $(module-files[1]) ; } - do-scan $(modules-to-scan[1--2]) ; - do-scan $(modules-to-scan[-1]) : print-help-all ; + do-scan $(modules-to-scan) : print-help-all ; did-help = true ; - + case --help-enable-* : local option = [ MATCH --help-enable-(.*) : $(command) ] ; option = $(option:L) ; set-option $(option) : enabled ; did-help = true ; - + case --help-disable-* : local option = [ MATCH --help-disable-(.*) : $(command) ] ; option = $(option:L) ; set-option $(option) ; did-help = true ; - + case --help-output : set-output $(values[1]) ; did-help = true ; - + case --help-output-file : set-output-file $(values[1]) ; did-help = true ; - + case --help-options : local doc-module-spec = [ split-symbol doc ] ; do-scan $(doc-module-spec[1]) : print-help-options ; did-help = true ; - + case --help-usage : print-help-usage ; did-help = true ; - + case --help : local spec = $(values[1]) ; if $(spec) @@ -114,25 +114,38 @@ rule process ( else { # First print documentation from the current Jamfile, if any. - if [ project.find "." : "." ] + local project-file = + [ project.find-jamfile . : no-error ] + [ project.find-jamfile . parent : no-error ] ; + for local p in $(project-file) { - local m = [ project.load "." ] ; - local help = [ modules.peek $(m) : project-help ] ; - if $(help) - { - print.text "Project-specific help" ; - print.text "" ; - print.text $(help) ; - } + do-scan $(p) : print-help-project $(p) ; } - print-help-top ; + # Next any user-config help. + local user-path = [ os.home-directories ] [ os.environ BOOST_BUILD_PATH ] ; + local user-config = [ GLOB $(user-path) : user-config.jam ] ; + if $(user-config) + { + do-scan $(user-config[1]) : print-help-config user $(user-config[1]) ; + } + + # Next any site-config help. + local site-config = [ GLOB $(user-path) : site-config.jam ] ; + if $(site-config) + { + do-scan $(site-config[1]) : print-help-config site $(site-config[1]) ; + } + + # Then the overall help. + print-help-top ; } did-help = true ; } if $(did-help) { UPDATE all ; + NOCARE all ; } return $(did-help) ; } @@ -153,11 +166,11 @@ local rule split-symbol ( local module-path = [ GLOB $(path-to-modules) : $(module-name)\\.jam ] ; if $(module-path) { - # The 'module-name' in fact refers to module. Return the full - # module path and a symbol within it. If 'symbol' passed to this - # rule is already module, 'symbol-name' will be empty. Otherwise, - # it's initialized on the previous loop iteration. - # In case there are several modules by this name, + # The 'module-name' in fact refers to module. Return the full + # module path and a symbol within it. If 'symbol' passed to this + # rule is already module, 'symbol-name' will be empty. Otherwise, + # it's initialized on the previous loop iteration. + # In case there are several modules by this name, # use the first one. result = $(module-path[1]) $(symbol-name) ; } diff --git a/src/util/doc.jam b/src/util/doc.jam index aedd38304..1c79c54df 100644 --- a/src/util/doc.jam +++ b/src/util/doc.jam @@ -570,6 +570,41 @@ local rule print-help-variables ( } } +# Generate documentation for a project. +# +local rule print-help-project ( + unused ? + : jamfile * # The project Jamfile. + ) +{ + if $(jamfile<$(jamfile)>.docs[1]) + { + # Print the docs. + print.section "Project-specific help" + Project has jamfile at $(jamfile) ; + + print.lines $(jamfile<$(jamfile)>.docs) "" ; + } +} + +# Generate documentation for a config file. +# +local rule print-help-config ( + unused ? + : type # The type of configuration file user or site. + config-file # The configuration Jamfile. + ) +{ + if $(jamfile<$(config-file)>.docs[1]) + { + # Print the docs. + print.section "Configuration help" + Configuration file at $(config-file) ; + + print.lines $(jamfile<$(config-file)>.docs) "" ; + } +} + local rule __test__ { } @@ -808,11 +843,11 @@ local rule scan-class ( rule scan-module ( target # The module file. : text * # The text in the file, one item per line. - : binding + : action * # Rule to call to output docs for the module. ) -{ +{ if $(.option.debug) { ECHO "HELP:" scanning module target '$(target)' ; } - local module-name = $(.module<$(target)>.name) ; + local module-name = $(target:B) ; local module-documented = ; local comment-block = ; local syntax-block = ; @@ -836,6 +871,12 @@ rule scan-module ( # mark as the copy for the module. set-module-copyright $(module-name) : $(comment-block) ; } + else if $(action[1]) in "print-help-project" "print-help-config" + && ! $(jamfile<$(target)>.docs[1]) + { + # special module docs for the project jamfile. + jamfile<$(target)>.docs = $(comment-block) ; + } else if ! $(module-documented) { # document the module. @@ -843,11 +884,9 @@ rule scan-module ( module-documented = true ; } } - for local action in $(.module<$(target)>.actions) + if $(action) { - local action-rule = [ $(action).front ] ; $(action).pop-front ; - local action-args = [ $(action).get ] ; - local ignored = [ $(action-rule) $(module-name) : $(action-args) ] ; + $(action[1]) $(module-name) : $(action[2-]) ; } } @@ -855,6 +894,38 @@ rule scan-module ( # header scanning phase. IMPORT $(__name__) : scan-module : : doc.scan-module ; +# Read in a file using the SHELL builtin and return the +# individual lines as would be done for header scanning. +# +local rule read-file ( + file # The file to read in. + ) +{ + if ! $(.file<$(file)>.lines) + { + local content ; + switch [ modules.peek : OS ] + { + case NT : + content = [ SHELL "TYPE \"$(file)\"" ] ; + + case * : + content = [ SHELL "cat \"$(file)\"" ] ; + } + local lines ; + local nl = " +" ; + local << = "([^$(nl)]*)[$(nl)](.*)" ; + local line+ = [ MATCH "$(<<)" : "$(content)" ] ; + while $(line+) + { + lines += $(line+[1]) ; + line+ = [ MATCH "$(<<)" : "$(line+[2])" ] ; + } + .file<$(file)>.lines = $(lines) ; + } + return $(.file<$(file)>.lines) ; +} # Add a scan action to perform to generate the help documentation. # The action rule is passed the name of the module as the first argument. @@ -866,38 +937,21 @@ local rule do-scan ( : action * # The action rule, plus the secondary arguments to pass to the action rule. ) { - local targets = ; - for local module-file in $(modules) - { - local module-name = $(module-file:B) ; - .module<$(module-file)>.name = $(module-name) ; - if $(action) - { - .module<$(module-file)>.actions += [ class.new vector $(action) ] ; - } - HDRSCAN on $(module-file) = "^(.*).$" ; - HDRRULE on $(module-file) = doc.scan-module ; - NOTFILE $(module-name).scan ; - ALWAYS $(module-name).scan ; - INCLUDES $(module-name).scan : $(module-file) ; - targets += $(module-name).scan ; - } - if $(help-output) = console - { - DEPENDS all : $(targets) ; - } if $(help-output) = text { print.output $(help-output-file).txt plain ; ALWAYS $(help-output-file).txt ; - DEPENDS $(help-output-file).txt : $(targets) ; DEPENDS all : $(help-output-file).txt ; } if $(help-output) = html { print.output $(help-output-file).html html ; ALWAYS $(help-output-file).html ; - DEPENDS $(help-output-file).html : $(targets) ; DEPENDS all : $(help-output-file).html ; } + for local module-file in $(modules[1--2]) + { + scan-module $(module-file) : [ read-file $(module-file) ] ; + } + scan-module $(modules[-1]) : [ read-file $(modules[-1]) ] : $(action) ; } diff --git a/src/util/option.jam b/src/util/option.jam index daa56b011..57944a8b6 100644 --- a/src/util/option.jam +++ b/src/util/option.jam @@ -88,11 +88,6 @@ rule process ( ) } } - if $(dont-build) - { - # Exit without printing "don't know how to build..." and "found 1 target" - # messages. - EXIT ; - } + return $(dont-build) ; }