使用帮助系统注册命令行参数: Boost-Build

Question

我们使用升压-建造构建我们的软件。为了帮助实现这一点，我们编写了一个规则和操作库。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有一个帮助模块，但我看不出有任何方法可以在帮助系统中注册参数。

是否有方法注册命令行标志，包括简短的文档，帮助系统将拾取？

Answer 1

在回答我自己的问题时，我添加了我正在询问的特性：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 ;
}

Answer 2

没有办法在B2帮助系统中“注册”单个选项。一般来说，这并不是帮助系统的工作方式。帮助系统只记录B2模块(即类)和项目(即jamfile)。当您执行"b2 --帮助“时，您看到的是项目帮助信息和模块信息的集合。所有数据都是从解析框文件中提取的。

对于模块，您可以向类和参数添加注释，并将它们格式化为输出。例如，查看一下"container.jam“源代码。在文件上的第二个注释是模块帮助文档，“类节点”之前的注释是类帮助文档，“规则集”之前的注释是方法帮助文档，注释是“值”之后的注释？争论是有帮助的医生。

对于项目，项目的jamfile中的第二个注释作为帮助文档。例如，Boost 贾姆鲁特有一个关于使用信息的大型帮助文档注释。如果您：

cd <boost-root>
b2 --help

如果您对某个项目jamfiles (注意:它假设第一个注释是版权通知，因此跳过它并使用第二个注释块作为帮助文档)和cd到该项目目录并执行b2 --help，那么应该会看到它被打印出来。

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