Package Manager command line option clean-up


(Anders Bertelrud) #1

Hello all,

Now that the `package` subcommand has been implemented (see https://github.com/apple/swift-evolution/blob/master/proposals/0085-package-manager-command-name.md), some of the options have ended up with awkward syntax. For example, the old `--init` option took an optional package type parameter, and after the command renaming, the syntax has become somewhat awkward: `package init=library`.

In order to clean this up, we have added some flags for the newly introduced subcommands, and I wanted to run them by the list to get any feedback before making the change.

The command line interface vended by the new `package` subcommand introduced by SE-0085 is shown in its help text:

OVERVIEW: Perform operations on Swift packages

USAGE: swift package [command] [options]

COMMANDS:
  init [--type <type>] Initialize a new package (executable|library)
  fetch Fetch package dependencies
  update Update package dependencies
  generate-xcodeproj [--output <path>] Generates an Xcode project
  show-dependencies [--format <format>] Print dependency graph (text|dot|json)
  dump-package [--output <path>] Print Package.swift as JSON

OPTIONS:
  --chdir <path> Change working directory before any command [-C]
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift build` to build packages, and `swift test` to test packages

The changes are to introduce new flags for the parameters that were previously passed to the subcommand names themselves. The last three flags listed (-Xcc, -Xlinker, and -Xswiftc) are unchanged to maintain compatibility with the swift compiler — this will likely be revisited at a later time.

As described in SE-0085, the `build` subcommand stays. It how has this interface:

OVERVIEW: Build sources into binary products

USAGE: swift build [mode] [options]

MODES:
  --configuration <value> Build with configuration (debug|release)
  --clean [<mode>] Delete artifacts (build|dist)

OPTIONS:
  --chdir <path> Change working directory before any other operation [-C]
  --build-path <path> Specify build directory
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift package` to perform other functions on packages

Finally, the `test` subcommand remains largely unmodified, with this interface:

OVERVIEW: Build and run tests

USAGE: swift test [specifier] [options]

SPECIFIER:
  -s TestModule.TestCase Run a test case subclass
  -s TestModule.TestCase/test1 Run a specific test method

OPTIONS:
  --chdir Change working directory before any other operation [-C]
  --build-path <path> Specify build directory

NOTE: Use `swift package` to perform other functions on packages

Questions / comments / concerns?

Anders


(Daniel Dunbar) #2

SGTM, I definitely prefer using the more modern (?) style "--foo <bar>" arguments and agree about the other cleanups.

- Daniel

···

On May 25, 2016, at 4:13 PM, Anders Bertelrud via swift-build-dev <swift-build-dev@swift.org> wrote:

Hello all,

Now that the `package` subcommand has been implemented (see https://github.com/apple/swift-evolution/blob/master/proposals/0085-package-manager-command-name.md), some of the options have ended up with awkward syntax. For example, the old `--init` option took an optional package type parameter, and after the command renaming, the syntax has become somewhat awkward: `package init=library`.

In order to clean this up, we have added some flags for the newly introduced subcommands, and I wanted to run them by the list to get any feedback before making the change.

The command line interface vended by the new `package` subcommand introduced by SE-0085 is shown in its help text:

OVERVIEW: Perform operations on Swift packages

USAGE: swift package [command] [options]

COMMANDS:
  init [--type <type>] Initialize a new package (executable|library)
  fetch Fetch package dependencies
  update Update package dependencies
  generate-xcodeproj [--output <path>] Generates an Xcode project
  show-dependencies [--format <format>] Print dependency graph (text|dot|json)
  dump-package [--output <path>] Print Package.swift as JSON

OPTIONS:
  --chdir <path> Change working directory before any command [-C]
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift build` to build packages, and `swift test` to test packages

The changes are to introduce new flags for the parameters that were previously passed to the subcommand names themselves. The last three flags listed (-Xcc, -Xlinker, and -Xswiftc) are unchanged to maintain compatibility with the swift compiler — this will likely be revisited at a later time.

As described in SE-0085, the `build` subcommand stays. It how has this interface:

OVERVIEW: Build sources into binary products

USAGE: swift build [mode] [options]

MODES:
  --configuration <value> Build with configuration (debug|release)
  --clean [<mode>] Delete artifacts (build|dist)

OPTIONS:
  --chdir <path> Change working directory before any other operation [-C]
  --build-path <path> Specify build directory
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift package` to perform other functions on packages

Finally, the `test` subcommand remains largely unmodified, with this interface:

OVERVIEW: Build and run tests

USAGE: swift test [specifier] [options]

SPECIFIER:
  -s TestModule.TestCase Run a test case subclass
  -s TestModule.TestCase/test1 Run a specific test method

OPTIONS:
  --chdir Change working directory before any other operation [-C]
  --build-path <path> Specify build directory

NOTE: Use `swift package` to perform other functions on packages

Questions / comments / concerns?

Anders

_______________________________________________
swift-build-dev mailing list
swift-build-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-build-dev


(Rob Allen) #3

Looks nice and consistent to me. I like it.

It seems like `-vv` is not documented though or has it been removed?

Also, it seems slightly strange that there's not a long-form name for test's `-s` option.

Regards,

Rob...

···

On 26 May 2016, at 00:13, Anders Bertelrud via swift-build-dev <swift-build-dev@swift.org> wrote:

Hello all,

Now that the `package` subcommand has been implemented (see https://github.com/apple/swift-evolution/blob/master/proposals/0085-package-manager-command-name.md), some of the options have ended up with awkward syntax. For example, the old `--init` option took an optional package type parameter, and after the command renaming, the syntax has become somewhat awkward: `package init=library`.

In order to clean this up, we have added some flags for the newly introduced subcommands, and I wanted to run them by the list to get any feedback before making the change.

The command line interface vended by the new `package` subcommand introduced by SE-0085 is shown in its help text:

OVERVIEW: Perform operations on Swift packages

USAGE: swift package [command] [options]

COMMANDS:
  init [--type <type>] Initialize a new package (executable|library)
  fetch Fetch package dependencies
  update Update package dependencies
  generate-xcodeproj [--output <path>] Generates an Xcode project
  show-dependencies [--format <format>] Print dependency graph (text|dot|json)
  dump-package [--output <path>] Print Package.swift as JSON

OPTIONS:
  --chdir <path> Change working directory before any command [-C]
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift build` to build packages, and `swift test` to test packages

The changes are to introduce new flags for the parameters that were previously passed to the subcommand names themselves. The last three flags listed (-Xcc, -Xlinker, and -Xswiftc) are unchanged to maintain compatibility with the swift compiler — this will likely be revisited at a later time.

As described in SE-0085, the `build` subcommand stays. It how has this interface:

OVERVIEW: Build sources into binary products

USAGE: swift build [mode] [options]

MODES:
  --configuration <value> Build with configuration (debug|release)
  --clean [<mode>] Delete artifacts (build|dist)

OPTIONS:
  --chdir <path> Change working directory before any other operation [-C]
  --build-path <path> Specify build directory
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift package` to perform other functions on packages

Finally, the `test` subcommand remains largely unmodified, with this interface:

OVERVIEW: Build and run tests

USAGE: swift test [specifier] [options]

SPECIFIER:
  -s TestModule.TestCase Run a test case subclass
  -s TestModule.TestCase/test1 Run a specific test method

OPTIONS:
  --chdir Change working directory before any other operation [-C]
  --build-path <path> Specify build directory

NOTE: Use `swift package` to perform other functions on packages

Questions / comments / concerns?

Anders

_______________________________________________
swift-build-dev mailing list
swift-build-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-build-dev

--
Development thoughts at http://akrabat.com
Daily Jotter for Mac OS X at http://dailyjotter.com


(Anders Bertelrud) #4

Looks nice and consistent to me. I like it.

Great!

It seems like `-vv` is not documented though or has it been removed?

It’s been removed, since:

a) it is non-standard, and
b) it can be easily achieved using -v -v

I didn’t change the behavior that each occurrence of -v increments the verbosity level.

Also, it seems slightly strange that there's not a long-form name for test's `-s` option.

That’s a good point. “specifier” would be the obvious suggestion for a long-form name. Does that sound good to you?

Thanks!

Anders

Regards,

Rob...

Hello all,

Now that the `package` subcommand has been implemented (see https://github.com/apple/swift-evolution/blob/master/proposals/0085-package-manager-command-name.md), some of the options have ended up with awkward syntax. For example, the old `--init` option took an optional package type parameter, and after the command renaming, the syntax has become somewhat awkward: `package init=library`.

In order to clean this up, we have added some flags for the newly introduced subcommands, and I wanted to run them by the list to get any feedback before making the change.

The command line interface vended by the new `package` subcommand introduced by SE-0085 is shown in its help text:

OVERVIEW: Perform operations on Swift packages

USAGE: swift package [command] [options]

COMMANDS:
  init [--type <type>] Initialize a new package (executable|library)
  fetch Fetch package dependencies
  update Update package dependencies
  generate-xcodeproj [--output <path>] Generates an Xcode project

  show-dependencies [--format <format>] Print dependency graph (text|dot|json)

···

On 2016-05-26, at 00.43, Rob Allen <rob@akrabat.com> wrote:

On 26 May 2016, at 00:13, Anders Bertelrud via swift-build-dev <swift-build-dev@swift.org <mailto:swift-build-dev@swift.org>> wrote:
  dump-package [--output <path>] Print Package.swift as JSON

OPTIONS:
  --chdir <path> Change working directory before any command [-C]
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift build` to build packages, and `swift test` to test packages

The changes are to introduce new flags for the parameters that were previously passed to the subcommand names themselves. The last three flags listed (-Xcc, -Xlinker, and -Xswiftc) are unchanged to maintain compatibility with the swift compiler — this will likely be revisited at a later time.

As described in SE-0085, the `build` subcommand stays. It how has this interface:

OVERVIEW: Build sources into binary products

USAGE: swift build [mode] [options]

MODES:
  --configuration <value> Build with configuration (debug|release)
  --clean [<mode>] Delete artifacts (build|dist)

OPTIONS:
  --chdir <path> Change working directory before any other operation [-C]
  --build-path <path> Specify build directory
  --color <mode> Specify color mode (auto|always|never)
  --verbose Increase verbosity of informational output [-v]
  -Xcc <flag> Pass flag through to all C compiler instantiations
  -Xlinker <flag> Pass flag through to all linker instantiations
  -Xswiftc <flag> Pass flag through to all Swift compiler instantiations

NOTE: Use `swift package` to perform other functions on packages

Finally, the `test` subcommand remains largely unmodified, with this interface:

OVERVIEW: Build and run tests

USAGE: swift test [specifier] [options]

SPECIFIER:
  -s TestModule.TestCase Run a test case subclass
  -s TestModule.TestCase/test1 Run a specific test method

OPTIONS:
  --chdir Change working directory before any other operation [-C]
  --build-path <path> Specify build directory

NOTE: Use `swift package` to perform other functions on packages

Questions / comments / concerns?

Anders

_______________________________________________
swift-build-dev mailing list
swift-build-dev@swift.org <mailto:swift-build-dev@swift.org>
https://lists.swift.org/mailman/listinfo/swift-build-dev

--
Development thoughts at http://akrabat.com <http://akrabat.com/>
Daily Jotter for Mac OS X at http://dailyjotter.com <http://dailyjotter.com/>


(Rob Allen) #5

Looks nice and consistent to me. I like it.

Great!

It seems like `-vv` is not documented though or has it been removed?

It’s been removed, since:

a) it is non-standard, and
b) it can be easily achieved using -v -v

I didn’t change the behavior that each occurrence of -v increments the verbosity level.

Works for me.

Also, it seems slightly strange that there's not a long-form name for test's `-s` option.

That’s a good point. “specifier” would be the obvious suggestion for a long-form name. Does that sound good to you?

Personally, I'm not a fan of the word "specifier to mean a single test class/method, and would have picked --case/-c or --test/-t given the choice.

However, given that the recently chosen short form is -s and the title of that section is "SPECIFIER", then --specifier is nicely consistent.

Regards,

Rob...

···

On 26 May 2016, at 18:44, Anders Bertelrud <anders@apple.com> wrote:
On 2016-05-26, at 00.43, Rob Allen <rob@akrabat.com <mailto:rob@akrabat.com>> wrote:


(Daniel Dunbar) #6

Looks nice and consistent to me. I like it.

Great!

It seems like `-vv` is not documented though or has it been removed?

It’s been removed, since:

a) it is non-standard, and
b) it can be easily achieved using -v -v

I didn’t change the behavior that each occurrence of -v increments the verbosity level.

Works for me.

Also, it seems slightly strange that there's not a long-form name for test's `-s` option.

That’s a good point. “specifier” would be the obvious suggestion for a long-form name. Does that sound good to you?

Personally, I'm not a fan of the word "specifier to mean a single test class/method, and would have picked --case/-c or --test/-t given the choice.

However, given that the recently chosen short form is -s and the title of that section is "SPECIFIER", then --specifier is nicely consistent.

+1 for specifier, for now.

We have some work in flight to allow moving to a more flexible syntax for this, eventually (but we need XCTest discovery to land first).

- Daniel

···

On May 26, 2016, at 11:04 AM, Rob Allen via swift-build-dev <swift-build-dev@swift.org> wrote:

On 26 May 2016, at 18:44, Anders Bertelrud <anders@apple.com <mailto:anders@apple.com>> wrote:
On 2016-05-26, at 00.43, Rob Allen <rob@akrabat.com <mailto:rob@akrabat.com>> wrote:

Regards,

Rob...

_______________________________________________
swift-build-dev mailing list
swift-build-dev@swift.org <mailto:swift-build-dev@swift.org>
https://lists.swift.org/mailman/listinfo/swift-build-dev