2

我们正在使用Boost-Build来构建我们的软件。为了帮助实现这一点，我们编写了一个规则和操作库。Boost-Build 允许传入命令行参数，并将传递任何以 . 为前缀的参数--。目前，为了获取参数并检查标志，我们正在执行以下操作：

import modules ;

local args = [ modules.peek : ARGV ] ;
# or like this
if "--my-flag" in [ modules.peek : ARGV ]

哪个可以获取和检查值。但是，使用 Boost-Build 和我们的 jam 库的开发人员并不知道这些标志是可用的，并且希望在运行时看到这些标志的一些帮助bjam -h或bjam --help. 我看到 BB 有一个帮助模块，但我没有看到任何方法可以在帮助系统中注册参数。

有没有办法注册命令行标志，并附有简短的文档，帮助系统会选择？

4

2 回答 2

2

在回答我自己的问题时，我添加了我所询问的功能：https ://github.com/boostorg/build/pull/23

它使用现有的选项插件系统。每当您想创建新的命令行选项时，请在options目录中创建一个新模块。在该新模块中，创建一个包含值或为空的变量。在变量上方创建注释。注释用作命令行文档，值（如果给出）用于描述该变量的默认值。

在新模块中创建process规则并在系统中注册您的选项。这允许导入option模块并从单一来源获取值。这要求每个变量名称都以模块名称为前缀。

创建一个名为.option-description. 它的值是节分隔符，它的注释是节的描述。

例如：

# within options/cool.jam

# These are the options for the Cool option plugin
.option-description = Cool Options

# This enables option1
.option.--cool-option1 ?= ;

# This enables something cool
.option.--cool-default-option ?= "my default value" ;

rule process (
    command # The option.
    : values * # The values, starting after the "=".
    )
{
    option.set $(command) : $(values) ;
}

bjam使用该标志运行时--help-options，它将输出options目录中遵循上述模式的所有模块。它将具有类似于以下的输出：

Boost.Build Usage:

  b2 [ options... ] targets...

  * -a; Build all targets, even if they are current.
  * -fx; Read 'x' as the Jamfile for building instead of searching for the
    Boost.Build system.
  * -jx; Run up to 'x' commands concurrently.
  * -n; Do not execute build commands. Instead print out the commands as they
    would be executed if building.
  * -ox; Output the used build commands to file 'x'.
  * -q; Quit as soon as a build failure is encountered. Without this option
    Boost.Jam will continue building as many targets as it can.
  * -sx=y; Sets a Jam variable 'x' to the value 'y', overriding any value that
    variable would have from the environment.
  * -tx; Rebuild the target 'x', even if it is up-to-date.
  * -v; Display the version of b2.
  * --x; Any option not explicitly handled by Boost.Build remains available to
    build scripts using the 'ARGV' variable.
  * --abbreviate-paths; Use abbreviated paths for targets.
  * --hash; Shorten target paths by using an MD5 hash.
  * -dn; Enables output of diagnostic messages. The debug level 'n' and all
    below it are enabled by this option.
  * -d+n; Enables output of diagnostic messages. Only the output for debug
    level 'n' is enabled.

Debug Levels:

  Each debug level shows a different set of information. Usually with higher
  levels producing more verbose information. The following levels are supported:

  * 0; Turn off all diagnostic output. Only errors are reported.
  * 1; Show the actions taken for building targets, as they are executed.
  * 2; Show quiet actions and display all action text, as they are executed.
  * 3; Show dependency analysis, and target/source timestamps/paths.
  * 4; Show arguments of shell invocations.
  * 5; Show rule invocations and variable expansions.
  * 6; Show directory/header file/archive scans, and attempts at binding to
    targets.
  * 7; Show variable settings.
  * 8; Show variable fetches, variable expansions, and evaluation of 'if'
    expressions.
  * 9; Show variable manipulation, scanner tokens, and memory usage.
  * 10; Show execution times for rules.
  * 11; Show parsing progress of Jamfiles.
  * 12; Show graph for target dependencies.
  * 13; Show changes in target status (fate).

Cool Options:
    These are the options for the Cool option plugin

    * --cool-option1: This enables option1. Default is disabled.
    * --cool-default-option: This enables something cool. "my default value".

稍后在您自己的 Jam 代码中，您可以通过执行以下操作从注册的选项中获取值：

import option ;

option1 = option.get '--cool-option1' ;
if $(option1) {
    # do_something ;
}
于 2014-09-09T21:52:42.150 回答
1

无法使用 B2 帮助系统“注册”单个选项。通常这不是帮助系统的工作方式。帮助系统仅记录 B2 模块（即类）和项目（即 jamfile）。执行“b2 --help”时看到的是项目帮助信息和模块信息的集合。所有数据都是从解析 jamfile 中提取的。

对于模块，您向类和参数添加注释，它们会被格式化以供输出。例如，看看“ container.jam ”源。其中文件的第二条注释是模块帮助文档，“类节点”之前的注释是类帮助文档，“规则集”之前的注释是方法帮助文档，“值？”之后的注释 参数是帮助文档。

对于项目，项目的 jamfile 中的第二条注释被视为帮助文档。例如，Boost Jamroot有一个用于使用信息的大型帮助文档注释。如果您：

cd <boost-root>
b2 --help

如果您对其中一个项目 jamfile 发表了这样的评论（注意：它假定第一个评论是版权声明，因此跳过它并使用帮助文档的第二个评论块），然后 cd 到该项目目录，b2 --help您应该看到它打印出来了。

您想要哪种类型的帮助文档当然取决于您的项目和您的意图。

于 2014-07-18T19:52:24.070 回答