tools/build/v2/options/help.jam

   1 # Copyright 2003 Dave Abrahams
   2 # Copyright 2003, 2006 Rene Rivera
   3 # Copyright 2003, 2006 Vladimir Prus
   4 # Distributed under the Boost Software License, Version 1.0.
   5 # (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
   6
   7 # This module is the plug-in handler for the --help and --help-.*
   8 # command-line options
   9 import modules ;
  10 import assert ;
  11 import doc : do-scan set-option set-output set-output-file print-help-usage print-help-top ;
  12 import sequence ;
  13 import set ;
  14 import project ;
  15 import print ;
  16 import os ;
  17 import version ;
  18 import path ;
  19
  20 # List of possible modules, but which really aren't.
  21 #
  22 .not-modules =
  23     boost-build bootstrap site-config test user-config
  24     -tools allyourbase boost-base features python stlport testing unit-tests ;
  25
  26 # The help system options are parsed here and handed off to the doc
  27 # module to translate into documentation requests and actions. The
  28 # understood options are:
  29 #
  30 #    --help-disable-<option>
  31 #    --help-doc-options
  32 #    --help-enable-<option>
  33 #    --help-internal
  34 #    --help-options
  35 #    --help-usage
  36 #    --help-output <type>
  37 #    --help-output-file <file>
  38 #    --help [<module-or-class>]
  39 #
  40 rule process (
  41     command # The option.
  42     : values * # The values, starting after the "=".
  43     )
  44 {
  45     assert.result --help : MATCH ^(--help).* : $(command) ;
  46     local did-help = ;
  47     switch $(command)
  48     {
  49         case --help-internal :
  50         local path-to-modules = [ modules.peek : BOOST_BUILD_PATH ] ;
  51         path-to-modules ?= . ;
  52         local possible-modules = [ GLOB $(path-to-modules) : *\\.jam ] ;
  53         local not-modules = [ GLOB $(path-to-modules) : *$(.not-modules)\\.jam ] ;
  54         local modules-to-list =
  55             [ sequence.insertion-sort
  56                 [ set.difference $(possible-modules:D=:S=) : $(not-modules:D=:S=) ] ] ;
  57         local modules-to-scan ;
  58         for local m in $(modules-to-list)
  59         {
  60             local module-files = [ GLOB $(path-to-modules) : $(m)\\.jam ] ;
  61             modules-to-scan += $(module-files[1]) ;
  62         }
  63         do-scan $(modules-to-scan) : print-help-all ;
  64         did-help = true ;
  65
  66         case --help-enable-* :
  67         local option = [ MATCH --help-enable-(.*) : $(command) ] ; option = $(option:L) ;
  68         set-option $(option) : enabled ;
  69         did-help = true ;
  70
  71         case --help-disable-* :
  72         local option = [ MATCH --help-disable-(.*) : $(command) ] ; option = $(option:L) ;
  73         set-option $(option) ;
  74         did-help = true ;
  75
  76         case --help-output :
  77         set-output $(values[1]) ;
  78         did-help = true ;
  79
  80         case --help-output-file :
  81         set-output-file $(values[1]) ;
  82         did-help = true ;
  83
  84         case --help-doc-options :
  85         local doc-module-spec = [ split-symbol doc ] ;
  86         do-scan $(doc-module-spec[1]) : print-help-options ;
  87         did-help = true ;
  88
  89         case --help-options :
  90         print-help-usage ;
  91         did-help = true ;
  92
  93         case --help :
  94         local spec = $(values[1]) ;
  95         if $(spec)
  96         {
  97             local spec-parts = [ split-symbol $(spec) ] ;
  98             if $(spec-parts)
  99             {
 100                 if $(spec-parts[2])
 101                 {
 102                     do-scan $(spec-parts[1]) : print-help-classes $(spec-parts[2]) ;
 103                     do-scan $(spec-parts[1]) : print-help-rules $(spec-parts[2]) ;
 104                     do-scan $(spec-parts[1]) : print-help-variables $(spec-parts[2]) ;
 105                 }
 106                 else
 107                 {
 108                     do-scan $(spec-parts[1]) : print-help-module ;
 109                 }
 110             }
 111             else
 112             {
 113                 EXIT "Unrecognized help option '"$(command)" "$(spec)"'." ;
 114             }
 115         }
 116         else
 117         {
 118             version.print ;
 119             ECHO ;
 120             # First print documentation from the current Jamfile, if any.
 121             # FIXME: Generally, this duplication of project.jam logic is bad.
 122             local names = [ modules.peek project : JAMROOT ]
 123               [ modules.peek project : JAMFILE ] ;
 124             local project-file = [ path.glob . : $(names) ] ;
 125             if ! $(project-file)
 126             {
 127                 project-file = [ path.glob-in-parents . : $(names) ] ;
 128             }
 129
 130             for local p in $(project-file)
 131             {
 132                 do-scan $(p) : print-help-project $(p) ;
 133             }
 134
 135             # Next any user-config help.
 136             local user-path = [ os.home-directories ] [ os.environ BOOST_BUILD_PATH ] ;
 137             local user-config = [ GLOB $(user-path) : user-config.jam ] ;
 138             if $(user-config)
 139             {
 140                 do-scan $(user-config[1]) : print-help-config user $(user-config[1]) ;
 141             }
 142
 143             # Next any site-config help.
 144             local site-config = [ GLOB $(user-path) : site-config.jam ] ;
 145             if $(site-config)
 146             {
 147                 do-scan $(site-config[1]) : print-help-config site $(site-config[1]) ;
 148             }
 149
 150             # Then the overall help.
 151             print-help-top ;
 152         }
 153         did-help = true ;
 154     }
 155     if $(did-help)
 156     {
 157         UPDATE all ;
 158         NOCARE all ;
 159     }
 160     return $(did-help) ;
 161 }
 162
 163 # Split a reference to a symbol into module and symbol parts.
 164 #
 165 local rule split-symbol (
 166     symbol # The symbol to split.
 167     )
 168 {
 169     local path-to-modules = [ modules.peek : BOOST_BUILD_PATH ] ;
 170     path-to-modules ?= . ;
 171     local module-name = $(symbol) ;
 172     local symbol-name = ;
 173     local result = ;
 174     while ! $(result)
 175     {
 176         local module-path = [ GLOB $(path-to-modules) : $(module-name)\\.jam ] ;
 177         if $(module-path)
 178         {
 179             # The 'module-name' in fact refers to module. Return the full
 180             # module path and a symbol within it. If 'symbol' passed to this
 181             # rule is already module, 'symbol-name' will be empty. Otherwise,
 182             # it's initialized on the previous loop iteration.
 183             # In case there are several modules by this name,
 184             # use the first one.
 185             result = $(module-path[1]) $(symbol-name) ;
 186         }
 187         else
 188         {
 189             if ! $(module-name:S)
 190             {
 191                 result = - ;
 192             }
 193             else
 194             {
 195                 local next-symbol-part = [ MATCH ^.(.*) : $(module-name:S) ] ;
 196                 if $(symbol-name)
 197                 {
 198                     symbol-name = $(next-symbol-part).$(symbol-name) ;
 199                 }
 200                 else
 201                 {
 202                     symbol-name = $(next-symbol-part) ;
 203                 }
 204                 module-name = $(module-name:B) ;
 205             }
 206         }
 207     }
 208     if $(result) != -
 209     {
 210         return $(result) ;
 211     }
 212 }