dotnet / dotnet/command-line-api

Support grouping options in help

Open
#2,216 4 comments 1 reaction 0 assignees View on GitHub
Dominant language
C#
Stars
3.7k
Forks
428
PR merge metrics
No merged PRs in 30d

Description

Currently the options output for my program looks like this:

```
Description:
Build an Unreal Engine project or plugin.

Usage:
uet build [options]

Options:
-e, --engine The engine to use for the build. []
-p, --path The directory path that contains a .uproject file, a .uplugin file, or a BuildConfig.json file. If this parameter isn't provided, defaults to the current working directory. [default: C:\Work\internal
(BuildConfig.json)]
-d, --distribution The distribution to build if targeting a BuildConfig.json file. []
--shipping If set, builds for Shipping instead of Development. Only valid when not using a BuildConfig.json file to build.
-x, --executor The executor to use. [default: local]
--executor-output-file If the executor runs the build externally (e.g. a build server), this is the path to the emitted file that should be passed as the job or build description into the build server.
--windows-shared-storage-path If the build is running across multiple machines (depending on the executor), this is the network share for Windows machines to access.
--windows-sdks-path If set, UET will automatically manage and install platform SDKs, and store them in the provided path on Windows machines. This should be a local path; the SDKs will be installed on each machine as they're
needed.
--mac-shared-storage-path If the build is running across multiple machines (depending on the executor), this is the local path on macOS pre-mounted to the network share.
--mac-sdks-path If set, UET will automatically manage and install platform SDKs, and store them in the provided path on macOS machines. This should be a local path; the SDKs will be installed on each machine as they're
needed.
--test If set, executes the tests after building.
--deploy If set, executes the deployment after building (and testing if --test is set).
--strict-includes If set, disables unity and PCH builds. This forces all files to have the correct #include directives, at the cost of increased build time.
-?, -h, --help Show help and usage information
```

I would like to be able to customize the help output by assigning options and arguments to "groups", so that I can get help output like this instead:

```
Description:
Build an Unreal Engine project or plugin.

Usage:
uet build [options]

Options:
-e, --engine The engine to use for the build. []
-p, --path The directory path that contains a .uproject file, a .uplugin file, or a BuildConfig.json file. If this parameter isn't provided, defaults to the current working directory. [default: C:\Work\internal
(BuildConfig.json)]
--test If set, executes the tests after building.
--deploy If set, executes the deployment after building (and testing if --test is set).
--strict-includes If set, disables unity and PCH builds. This forces all files to have the correct #include directives, at the cost of increased build time.
-?, -h, --help Show help and usage information.

Options when targeting a BuildConfig.json file:
-d, --distribution The distribution to build if targeting a BuildConfig.json file. []

Options when targeting a .uplugin or .uproject file:
--shipping If set, builds for Shipping instead of Development

Options when building on CI/CD:
-x, --executor The executor to use. [default: local]
--executor-output-file If the executor runs the build externally (e.g. a build server), this is the path to the emitted file that should be passed as the job or build description into the build server.
--windows-shared-storage-path If the build is running across multiple machines (depending on the executor), this is the network share for Windows machines to access.
--windows-sdks-path If set, UET will automatically manage and install platform SDKs, and store them in the provided path on Windows machines. This should be a local path; the SDKs will be installed on each machine as they're
needed.
--mac-shared-storage-path If the build is running across multiple machines (depending on the executor), this is the local path on macOS pre-mounted to the network share.
--mac-sdks-path If set, UET will automatically manage and install platform SDKs, and store them in the provided path on macOS machines. This should be a local path; the SDKs will be installed on each machine as they're
needed.
```

I tried to customize the options output through HelpBuilder, but ran into the problem mentioned in #2215 where it uses a bunch of internals that are not accessible:

![image](https://github.com/dotnet/command-line-api/assets/504826/7895e80d-1b00-4220-967f-b144faf24e48)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.