Skip to content

Make Configuration introspectable - #268

Open
broken-circle wants to merge 2 commits into
swiftlang:mainfrom
broken-circle:introspectable-configuration-206
Open

Make Configuration introspectable#268
broken-circle wants to merge 2 commits into
swiftlang:mainfrom
broken-circle:introspectable-configuration-206

Conversation

@broken-circle

@broken-circle broken-circle commented May 18, 2026

Copy link
Copy Markdown
Member

Closes #206.

This PR adds public introspection of Arguments, Executable, and Environment so callers generating subprocess configurations can unit-test them without spawning a subprocess. The current storage of these types is opaque, leaving callers with only string-based descriptions to parse.

  • Arguments conforms to RandomAccessCollection<Arguments.Value>, where Value is a public mirror of the internal StringOrRawBytes. A Value enum was chosen over lossy UTF-8 decoding so callers constructing arguments from [UInt8] on POSIX can verify the exact bytes.

  • Arguments.executablePathOverride is exposed as a separate public property rather than folded into iteration. Folding would make argv[0] ambiguous between an override and a regular first argument, and would prevent callers from distinguishing the two cases in tests. The internal stored property is renamed to _executablePathOverride to free the name for the public accessor.

  • Executable and Environment expose their contents through new Representation mirror enums rather than exposing their internal storage types directly, decoupling the public introspection surface from internal storage. Environment.Key.path is promoted from package to public so callers can use it as a canonical reference to the PATH key.

The Swift tools version is bumped to 6.2.3 to support @nonexhaustive (SE-0487).

@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch from eabae88 to bbd9ecb Compare May 18, 2026 20:05
@jakepetroules

Copy link
Copy Markdown
Contributor

The capability is nice, but I'm a little concerned about the use of enums in public API -- usually that's discouraged. I'm not sure what other good options there are, though.

@allevato

Copy link
Copy Markdown
Member

Making it a @nonexhaustive enum would avoid the issues that tended to cause problems with evolution for enum-based APIs, I think?

@broken-circle

broken-circle commented May 18, 2026

Copy link
Copy Markdown
Member Author

Nice, I was just wondering if something like @nonexhaustive existed. Reading SE-0487, it seems appropriate here.

We could annotate Arguments.Value and Executable.Representation with @frozen, since their cases are exhaustive. Environment.Representation can be @nonexhaustive.

@iCharlesHu

Copy link
Copy Markdown
Contributor

@broken-circle thanks for the PR! Let's do this post 1.0 (it was originally scheduled for post 1.0)

@iCharlesHu iCharlesHu added this to the Post 1.0 - Feature Release milestone May 20, 2026
@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch 2 times, most recently from 231d282 to 32c1b2e Compare May 30, 2026 16:34
@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch from 32c1b2e to f7734e8 Compare August 6, 2026 19:57
@broken-circle
broken-circle marked this pull request as ready for review August 6, 2026 19:58
@broken-circle

Copy link
Copy Markdown
Member Author

This is ready for review now that we're post-1.0.

Earlier I thought Package.swift was fine as-is, but the tools version needed bumping to 6.2.3, since that's when @nonexhaustive was implemented. The CMake build doesn't declare a Swift floor; should we add a CMAKE_Swift_COMPILER_VERSION guard?

If the version bump isn't acceptable, we can make Environment.Representation @frozen instead, although this enum's set of members isn't necessarily closed. For example, there's currently no way to inherit the parent environment and override a value with raw bytes, and filling that gap would need a new case, and therefore a new major version.

@broken-circle broken-circle added the enhancement New feature or request label Aug 6, 2026
@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch 2 times, most recently from 894d75b to c44f40f Compare August 6, 2026 21:31
@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch from c44f40f to ae1e3f9 Compare August 10, 2026 20:44
`@nonexhaustive` (SE-0487) was implemented in Swift 6.2.3.
@broken-circle
broken-circle force-pushed the introspectable-configuration-206 branch from ae1e3f9 to d22b745 Compare August 14, 2026 22:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API Change enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Make Configuration, Arguments, and Environment more open for testing purposes

4 participants