# LLVM命令行选项的处理

There are two libraries for processing command line options in LLVM.

## llvm/Support/ComandLine.h

See https://llvm.org/docs/CommandLine.html for documentation.

Global variables (mostly llvm::cl::opt<type>, some llvm::cl::list<type>) are most common to represent command-line options. The llvm::cl::opt constructor registers this command line option in a global registry. The program calls llvm::cl::ParseCommandLineOptions(argc, argv, ...) in main to parse the command line options. opt supports various integer types, bool, std::string, etc. Defining some specialization can support support custom class/enum types.

Beside functionality options, there are many internal command line options in LLVM.

• Having an option to select different code paths. Usually introduced when one feature is under development and is considered experimental.
• The functionality has been stable for a period of time, and the default value has been changed to true. In some cases, users who find a regression can set the option to false as a workaround.
• Provide more input to a pass for testing.

The llvm::cl library is easy to use. Adding a new option only requires adding a variable to a source file. The library provides some icing on the cake, e.g. recommending options with similar spellings in case of an incorrect spelling. But the customizability is poor. For example:

• A llvm::cl::opt<bool> option accepts various input methods such as -v 0 -v=0 -v false -v=false -v=False
• It is inconvenient to support both --long and --no-long at the same time. Occasionally, the workaround is to set a variable for --no-long. If you want to deal with two options override each other, you must determine the relative position of the two options in the command line

User-oriented external tools often have such customization requirements. The style of GNU getopt_long is --long. -long and --long can be mixed in llvm/Support/ComandLine.h, and mandatory -- is not supported for a long time.

LLVM binary utilities (llvm-nm, llvm-objdump, llvm-readelf, etc.) in order to replace GNU binutils, Need to provide grouped short options in the style of POSIX shell utilities (-ab means -a -b). This feature is not supported for a long time, which troubles users who want to migrate to LLVM binary utilities.

In addition, llvm::cl::opt is a singleton, and local variables can also be defined to dynamically increase options, but this usage is rare (llvm-readobj and llvm-cov). There is also a very peculiar usage. The legacy pass manager in the opt tool automatically obtains the pass name list and registers a large number of global options.

To prevent errors, llvm::cl::opt does not support defining the same option multiple times. If you link both shared object and archive LLVM libraries at the same time, a classic error will be triggered:

If you want to set the value of the llvm::cl::opt variable in Clang, you can use -mllvm -option=value. Use ld.lld/LLVMgold.so Full/Thin LTO to set these option values, use -plugin-opt=-option=value (ld.lld can also use -mllvm).

## llvm/Option/OptTable.h

This was originally developed for Clang. It was later moved to llvm and adopted by many components such as llvm-objcopy, lld, and most binutils counterparts (llvm-symbolizer, llvm-objdump, etc). OptTable uses a domain-specific language (TableGen) to describe command line options and generate a parser. The parsed options are organized into an object, and each option is represented by an integer. It is easy to check whether a pair of boolean options with variable default values (--demangle --no-demangle) are in effect: Args.hasFlag(OPT_demangle, OPT_no_demangle, !IsAddr2Line).

Here is an example TableGen file:

In the C++ source file, one writes:

Note that GCC's command line options do not support grouped short options, so Clang does not require it. Some binutils counterparts need the support, and I added grouped short options (D83639) in July 2020.

Anecdote: LLD uses this library to parse command-line options. GNU ld actually supports grouped short options, for example, ld.bfd -vvv means -v -v -v. I suggested that GNU ld actually supports many -long style options, and supporting grouped short options can cause confusion.

binutils 2.36 is expected to deprecate grouped short options :)

To expand, many users of getopt_long use a switch and a large number of cases to process command line options, and it is easy to create various position dependent behaviors. For large build systems, sometimes it is not clear where the compiler/linker options are added, and some position dependent behaviors are quite annoying.

# 中文版

LLVM中命令行选项的处理有两个库。

## llvm/Support/ComandLine.h

LLVM中有很多开发者使用的命令行选项，除了功能选项外，还有：

• 对某一pass有较大改动，in-tree开发时为了防止衰退，设置一个预设为false的enable变量
• 一段时间功能稳定，把预设值改为true。在某些场合下发现衰退的用户可以使用false作为workaround
• 给一个pass提供更多输入，用于测试

• 一个cl::opt<bool>选项接受-v 0 -v=0 -v false -v=false -v=False等多种输入方式
• 不便同时支持--long--no-long。偶尔有需求时的workaround是给--no-long也设置一个变量。假如要处理两个选项互相override，就要判断两个选项在命令行中的相对位置

LLVM binary utilities (llvm-nm、llvm-objdump、llvm-readelf等)为了替代GNU binutils， 需要提供POSIX shell utilities风格的grouped short options (-ab表示-a -b)。 很长一段时间这个功能不被支持，困扰了想要迁移到LLVM binary utilities的用户。

## llvm/Option/OptTable.h

binutils 2.36有望deprecate grouped short options:)