Add titles to global option groups for better help screens #8282

natecook1000 · 2025-02-06T15:44:07Z

2/10/25: Updated example output to match changes.

Adds titles to the option groups that comprise the GlobalOptions struct, for better help screen formatting.

Motivation:

The current help screen includes a long list of flags and options, with no categorization, making it hard for users to understand what kinds of options are available.

Modifications:

This change adds titles to all the @OptionGroup declarations inside the global options struct, which results in each group being labeled in the help screens for swift package, swift run, etc.

Result:

The new, categorized screen for swift run is below.

Note

These are just initial guesses at what the appropriate names should be – reviewers, please discuss/revise what's here!

OVERVIEW: Build and run an executable product

SEE ALSO: swift build, swift package, swift test

USAGE: swift run [<options>] [<executable>] [<arguments> ...]

ARGUMENTS:
  <executable>            The executable to run
  <arguments>             The arguments to pass to the executable

PATHS & LOCATIONS:
  --package-path <package-path>
                          Specify the package path to operate on (default
                          current directory). This changes the working
                          directory before any other operation
  --cache-path <cache-path>
                          Specify the shared cache directory path
  --config-path <config-path>
                          Specify the shared configuration directory path
  --security-path <security-path>
                          Specify the shared security directory path
  --scratch-path <scratch-path>
                          Specify a custom scratch directory path (default
                          .build)
  --swift-sdks-path <swift-sdks-path>
                          Path to the directory containing installed Swift SDKs
  --toolset <toolset>     Specify a toolset JSON file to use when building for
                          the target platform. Use the option multiple times to
                          specify more than one toolset. Toolsets will be
                          merged in the order they're specified into a single
                          final toolset for the current build.
  --pkg-config-path <pkg-config-path>
                          Specify alternative path to search for pkg-config
                          `.pc` files. Use the option multiple times to
                          specify more than one path.

CACHING:
  --enable-dependency-cache/--disable-dependency-cache
                          Use a shared cache when fetching dependencies
                          (default: --enable-dependency-cache)
  --enable-build-manifest-caching/--disable-build-manifest-caching
                          (default: --enable-build-manifest-caching)
  --manifest-cache <manifest-cache>
                          Caching mode of Package.swift manifests (shared:
                          shared cache, local: package's build directory, none:
                          disabled) (default: shared)
  --enable-experimental-prebuilts/--disable-experimental-prebuilts
                          Whether to use prebuilt swift-syntax libraries for
                          macros (default: --disable-experimental-prebuilts)

LOGGING:
  -v, --verbose           Increase verbosity to include informational output
  --very-verbose, --vv    Increase verbosity to include debug output
  -q, --quiet             Decrease verbosity to only include error output.

SECURITY:
  --disable-sandbox       Disable using the sandbox when executing subprocesses
  --netrc                 Use netrc file even in cases where other credential
                          stores are preferred
  --enable-netrc/--disable-netrc
                          Load credentials from a netrc file (default:
                          --enable-netrc)
  --netrc-file <netrc-file>
                          Specify the netrc file path
  --enable-keychain/--disable-keychain
                          Search credentials in macOS keychain (default:
                          --enable-keychain)
  --resolver-fingerprint-checking <resolver-fingerprint-checking>
                          (default: strict)
  --resolver-signing-entity-checking <resolver-signing-entity-checking>
                          (default: warn)
  --enable-signature-validation/--disable-signature-validation
                          Validate signature of a signed package release
                          downloaded from registry (default:
                          --enable-signature-validation)

RESOLUTION:
  --enable-prefetching/--disable-prefetching
                          (default: --enable-prefetching)
  --force-resolved-versions, --disable-automatic-resolution, --only-use-versions-from-resolved-file
                          Only use versions from the Package.resolved file and
                          fail resolution if it is out-of-date
  --skip-update           Skip updating dependencies from their remote during a
                          resolution
  --disable-scm-to-registry-transformation
                          disable source control to registry transformation
                          (default: --disable-scm-to-registry-transformation)
  --use-registry-identity-for-scm
                          look up source control dependencies in the registry
                          and use their registry identity when possible to help
                          deduplicate across the two origins
  --replace-scm-with-registry
                          look up source control dependencies in the registry
                          and use the registry to retrieve them instead of
                          source control when possible
  --default-registry-url <default-registry-url>
                          Default registry URL to use, instead of the
                          registries.json configuration file

BUILD OPTIONS:
  -c, --configuration <configuration>
                          Build with configuration (values: debug, release)
  -Xcc <Xcc>              Pass flag through to all C compiler invocations
  -Xswiftc <Xswiftc>      Pass flag through to all Swift compiler invocations
  -Xlinker <Xlinker>      Pass flag through to all linker invocations
  -Xcxx <Xcxx>            Pass flag through to all C++ compiler invocations
  --triple <triple>
  --sdk <sdk>
  --toolchain <toolchain>
  --swift-sdk <swift-sdk> Filter for selecting a specific Swift SDK to build
                          with
  --sanitize <sanitize>   Turn on runtime checks for erroneous behavior,
                          possible values: address, thread, undefined, scudo
                          (values: address, thread, undefined, scudo)
  --auto-index-store/--enable-index-store/--disable-index-store
                          Enable or disable indexing-while-building feature
                          (default: --auto-index-store)
  --enable-parseable-module-interfaces
  -j, --jobs <jobs>       The number of jobs to spawn in parallel during the
                          build process
  --use-integrated-swift-driver
  --explicit-target-dependency-import-check <explicit-target-dependency-import-check>
                          A flag that indicates this build should check whether
                          targets only import their explicitly-declared
                          dependencies (values: none, warn, error; default:
                          none)
  --experimental-explicit-module-build
  --build-system <build-system>
                          (values: native, xcode; default: native)
  -debug-info-format <debug-info-format>
                          The Debug Information Format to use (values: dwarf,
                          codeview, none; default: dwarf)
 --enable-dead-strip/--disable-dead-strip
                          Disable/enable dead code stripping by the linker
                          (default: --enable-dead-strip)
  --disable-local-rpath   Disable adding $ORIGIN/@loader_path to the rpath by
                          default

OPTIONS:
  --repl                  Launch Swift REPL for the package
  --debugger              Launch the executable in a debugger session
  --run                   Launch the executable with the provided arguments
                          (default: --run)
  --skip-build            Skip building the executable product
  --build-tests           Build both source and test targets
  --traits <traits>       Enables the passed traits of the package. Multiple
                          traits can be specified by providing a space
                          separated list e.g. `--traits Trait1 Trait2`. When
                          enabling specific traits the defaults traits need to
                          explictily enabled as well by passing `defaults` to
                          this command.
  --enable-all-traits     Enables all traits of the package.
  --disable-default-traits
                          Disables all default traits of the package.
  --version               Show the version.
  -h, -help, --help       Show help information.

dschaefer2 · 2025-02-06T16:06:11Z

Awesome. Thanks Nate!

dschaefer2 · 2025-02-06T16:06:53Z

@swift-ci please test

rauhul · 2025-02-06T18:27:22Z

thank goodness!

Sources/CoreCommands/Options.swift

jakepetroules

This is great, thanks! I've been wanting to take advantage of this new swift-argument-parser functionality for a while.

Sources/CoreCommands/Options.swift

natecook1000 · 2025-02-10T22:27:08Z

I couldn't remember what ArgumentParser does when you use the same name for more than one option group, and, happily, it just combines them! So that section of the help output is amended to:

...
  --replace-scm-with-registry
                          look up source control dependencies in the registry and use the registry to retrieve them instead of source control
                          when possible
  --default-registry-url <default-registry-url>
                          Default registry URL to use, instead of the registries.json configuration file

BUILD OPTIONS:
  -c, --configuration <configuration>
                          Build with configuration (values: debug, release)
  -Xcc <Xcc>              Pass flag through to all C compiler invocations
  -Xswiftc <Xswiftc>      Pass flag through to all Swift compiler invocations
  -Xlinker <Xlinker>      Pass flag through to all linker invocations
  -Xcxx <Xcxx>            Pass flag through to all C++ compiler invocations
  --triple <triple>
  --sdk <sdk>
  --toolchain <toolchain>
  --swift-sdk <swift-sdk> Filter for selecting a specific Swift SDK to build with
  --sanitize <sanitize>   Turn on runtime checks for erroneous behavior, possible values: address, thread, undefined, scudo (values: address,
                          thread, undefined, scudo)
  --auto-index-store/--enable-index-store/--disable-index-store
                          Enable or disable indexing-while-building feature (default: --auto-index-store)
  --enable-parseable-module-interfaces
  -j, --jobs <jobs>       The number of jobs to spawn in parallel during the build process
  --use-integrated-swift-driver
  --explicit-target-dependency-import-check <explicit-target-dependency-import-check>
                          A flag that indicates this build should check whether targets only import their explicitly-declared dependencies
                          (values: none, warn, error; default: none)
  --experimental-explicit-module-build
  --build-system <build-system>
                          (values: native, xcode; default: native)
  -debug-info-format <debug-info-format>
                          The Debug Information Format to use (values: dwarf, codeview, none; default: dwarf)
  --enable-dead-strip/--disable-dead-strip
                          Disable/enable dead code stripping by the linker (default: --enable-dead-strip)
  --disable-local-rpath   Disable adding $ORIGIN/@loader_path to the rpath by default

OPTIONS:
  --repl                  Launch Swift REPL for the package
  --debugger              Launch the executable in a debugger session
...

MaxDesiatov · 2025-02-11T10:39:07Z

@swift-ci test

MaxDesiatov · 2025-02-11T10:52:49Z

@swift-ci test windows

dschaefer2 · 2025-02-11T15:58:33Z

Good to go. Thanks again Nate! The mess that is our help came up in a recent UX review. This will help a lot.

bkhouri · 2025-02-26T22:07:09Z

Sources/CoreCommands/Options.swift

    public var build: BuildOptions

-    @OptionGroup()
+    @OptionGroup(title: "Build Options")


Should this be "Linker Options"?

This has been previously discussed #8282 (comment)

…#8282) _2/10/25: Updated example output to match changes._ Adds titles to the option groups that comprise the `GlobalOptions` struct, for better help screen formatting. ### Motivation: The current help screen includes a long list of flags and options, with no categorization, making it hard for users to understand what kinds of options are available. ### Modifications: This change adds titles to all the `@OptionGroup` declarations inside the global options struct, which results in each group being labeled in the help screens for `swift package`, `swift run`, etc. ### Result: The new, categorized screen for `swift run` is below. > [!NOTE] > These are just initial guesses at what the appropriate names should be – reviewers, please discuss/revise what's here! ``` OVERVIEW: Build and run an executable product SEE ALSO: swift build, swift package, swift test USAGE: swift run [<options>] [<executable>] [<arguments> ...] ARGUMENTS: <executable> The executable to run <arguments> The arguments to pass to the executable PATHS & LOCATIONS: --package-path <package-path> Specify the package path to operate on (default current directory). This changes the working directory before any other operation --cache-path <cache-path> Specify the shared cache directory path --config-path <config-path> Specify the shared configuration directory path --security-path <security-path> Specify the shared security directory path --scratch-path <scratch-path> Specify a custom scratch directory path (default .build) --swift-sdks-path <swift-sdks-path> Path to the directory containing installed Swift SDKs --toolset <toolset> Specify a toolset JSON file to use when building for the target platform. Use the option multiple times to specify more than one toolset. Toolsets will be merged in the order they're specified into a single final toolset for the current build. --pkg-config-path <pkg-config-path> Specify alternative path to search for pkg-config `.pc` files. Use the option multiple times to specify more than one path. CACHING: --enable-dependency-cache/--disable-dependency-cache Use a shared cache when fetching dependencies (default: --enable-dependency-cache) --enable-build-manifest-caching/--disable-build-manifest-caching (default: --enable-build-manifest-caching) --manifest-cache <manifest-cache> Caching mode of Package.swift manifests (shared: shared cache, local: package's build directory, none: disabled) (default: shared) --enable-experimental-prebuilts/--disable-experimental-prebuilts Whether to use prebuilt swift-syntax libraries for macros (default: --disable-experimental-prebuilts) LOGGING: -v, --verbose Increase verbosity to include informational output --very-verbose, --vv Increase verbosity to include debug output -q, --quiet Decrease verbosity to only include error output. SECURITY: --disable-sandbox Disable using the sandbox when executing subprocesses --netrc Use netrc file even in cases where other credential stores are preferred --enable-netrc/--disable-netrc Load credentials from a netrc file (default: --enable-netrc) --netrc-file <netrc-file> Specify the netrc file path --enable-keychain/--disable-keychain Search credentials in macOS keychain (default: --enable-keychain) --resolver-fingerprint-checking <resolver-fingerprint-checking> (default: strict) --resolver-signing-entity-checking <resolver-signing-entity-checking> (default: warn) --enable-signature-validation/--disable-signature-validation Validate signature of a signed package release downloaded from registry (default: --enable-signature-validation) RESOLUTION: --enable-prefetching/--disable-prefetching (default: --enable-prefetching) --force-resolved-versions, --disable-automatic-resolution, --only-use-versions-from-resolved-file Only use versions from the Package.resolved file and fail resolution if it is out-of-date --skip-update Skip updating dependencies from their remote during a resolution --disable-scm-to-registry-transformation disable source control to registry transformation (default: --disable-scm-to-registry-transformation) --use-registry-identity-for-scm look up source control dependencies in the registry and use their registry identity when possible to help deduplicate across the two origins --replace-scm-with-registry look up source control dependencies in the registry and use the registry to retrieve them instead of source control when possible --default-registry-url <default-registry-url> Default registry URL to use, instead of the registries.json configuration file BUILD OPTIONS: -c, --configuration <configuration> Build with configuration (values: debug, release) -Xcc <Xcc> Pass flag through to all C compiler invocations -Xswiftc <Xswiftc> Pass flag through to all Swift compiler invocations -Xlinker <Xlinker> Pass flag through to all linker invocations -Xcxx <Xcxx> Pass flag through to all C++ compiler invocations --triple <triple> --sdk <sdk> --toolchain <toolchain> --swift-sdk <swift-sdk> Filter for selecting a specific Swift SDK to build with --sanitize <sanitize> Turn on runtime checks for erroneous behavior, possible values: address, thread, undefined, scudo (values: address, thread, undefined, scudo) --auto-index-store/--enable-index-store/--disable-index-store Enable or disable indexing-while-building feature (default: --auto-index-store) --enable-parseable-module-interfaces -j, --jobs <jobs> The number of jobs to spawn in parallel during the build process --use-integrated-swift-driver --explicit-target-dependency-import-check <explicit-target-dependency-import-check> A flag that indicates this build should check whether targets only import their explicitly-declared dependencies (values: none, warn, error; default: none) --experimental-explicit-module-build --build-system <build-system> (values: native, xcode; default: native) -debug-info-format <debug-info-format> The Debug Information Format to use (values: dwarf, codeview, none; default: dwarf) --enable-dead-strip/--disable-dead-strip Disable/enable dead code stripping by the linker (default: --enable-dead-strip) --disable-local-rpath Disable adding $ORIGIN/@loader_path to the rpath by default OPTIONS: --repl Launch Swift REPL for the package --debugger Launch the executable in a debugger session --run Launch the executable with the provided arguments (default: --run) --skip-build Skip building the executable product --build-tests Build both source and test targets --traits <traits> Enables the passed traits of the package. Multiple traits can be specified by providing a space separated list e.g. `--traits Trait1 Trait2`. When enabling specific traits the defaults traits need to explictily enabled as well by passing `defaults` to this command. --enable-all-traits Enables all traits of the package. --disable-default-traits Disables all default traits of the package. --version Show the version. -h, -help, --help Show help information. ```

Add titles to global option groups for better help screens

cac8e91

natecook1000 requested review from bnbarham, MaxDesiatov, jakepetroules, xedin, dschaefer2, shawnhyam, bripeticca, plemarquand, owenv and bkhouri as code owners February 6, 2025 15:44

MaxDesiatov approved these changes Feb 6, 2025

View reviewed changes

dschaefer2 approved these changes Feb 6, 2025

View reviewed changes

rauhul approved these changes Feb 6, 2025

View reviewed changes

MaxDesiatov requested changes Feb 6, 2025

View reviewed changes

Sources/CoreCommands/Options.swift Outdated Show resolved Hide resolved

jakepetroules requested changes Feb 7, 2025

View reviewed changes

Sources/CoreCommands/Options.swift Outdated Show resolved Hide resolved

Combine 2 groups into 'Build Options'

07f0ba7

MaxDesiatov approved these changes Feb 11, 2025

View reviewed changes

jakepetroules approved these changes Feb 11, 2025

View reviewed changes

dschaefer2 merged commit a86e9f9 into main Feb 11, 2025
5 checks passed

dschaefer2 deleted the nate/global-option-groups branch February 11, 2025 15:58

bkhouri reviewed Feb 26, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add titles to global option groups for better help screens #8282

Add titles to global option groups for better help screens #8282

Uh oh!

natecook1000 commented Feb 6, 2025 •

edited

Loading

Uh oh!

dschaefer2 commented Feb 6, 2025

Uh oh!

dschaefer2 commented Feb 6, 2025

Uh oh!

rauhul commented Feb 6, 2025

Uh oh!

Uh oh!

jakepetroules left a comment

Uh oh!

Uh oh!

natecook1000 commented Feb 10, 2025

Uh oh!

MaxDesiatov commented Feb 11, 2025

Uh oh!

MaxDesiatov commented Feb 11, 2025

Uh oh!

dschaefer2 commented Feb 11, 2025

Uh oh!

Uh oh!

bkhouri Feb 26, 2025

Uh oh!

MaxDesiatov Feb 26, 2025

Uh oh!

Uh oh!

Add titles to global option groups for better help screens #8282

Add titles to global option groups for better help screens #8282

Uh oh!

Conversation

natecook1000 commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation:

Modifications:

Result:

Uh oh!

dschaefer2 commented Feb 6, 2025

Uh oh!

dschaefer2 commented Feb 6, 2025

Uh oh!

rauhul commented Feb 6, 2025

Uh oh!

Uh oh!

jakepetroules left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

natecook1000 commented Feb 10, 2025

Uh oh!

MaxDesiatov commented Feb 11, 2025

Uh oh!

MaxDesiatov commented Feb 11, 2025

Uh oh!

dschaefer2 commented Feb 11, 2025

Uh oh!

Uh oh!

bkhouri Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

MaxDesiatov Feb 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

natecook1000 commented Feb 6, 2025 •

edited

Loading