Init template cleanup #6144

bitjammer · 2023-02-10T22:00:19Z

Improve the `swift package init` experience using the following criteria:

Simplify the templates to include only the minimum necessary to get started without making assumptions.
Use documentation links instead of arbitrary template content to teach people about Swift.
Improve the "front door" experience with the help usage.

Detailed list of changes:

Remove the system-module template.
Remove the manifest template
Add a tool template, an executable that uses ArgumentParser
Remove README generation.
Don't generate empty directories.
Don't emit empty dependencies array in manifests.
Update library template content:
- Remove struct definition, use a simple public function instead.
- Include documentation links for TSPL and the Standard Library.
- Include documentation links for XCTest in the generated test case.
Update executable template content
- Use simpler top-level code instead of an @main struct.
- Remove executable tests.
- Put sources directly in ./Sources.
Clean up and align type argument help text
Update Usage.md documentation

rdar://98999734

Example resulting file listing

./executable
./executable/.gitignore
./executable/Package.swift
./executable/Sources
./executable/Sources/executable.swift

./tool
./tool/.gitignore
./tool/Package.swift
./tool/Sources
./tool/Sources/tool.swift

./empty
./empty/Package.swift

./library
./library/Tests
./library/Tests/libraryTests
./library/Tests/libraryTests/libraryTests.swift
./library/.gitignore
./library/Package.swift
./library/Sources
./library/Sources/library
./library/Sources/library/library.swift

Resulting command line usage

OVERVIEW: Initialize a new package

USAGE: swift package init [--type <type>] [--name <name>]

OPTIONS:
  --type <type>           Package type: (default: library)
        library           - A package with a library.
        executable        - A package with an executable.
        tool              - A package with an executable that uses
                            Swift Argument Parser. Use this template if you
                            plan to have a rich set of command-line arguments.
        empty             - An empty package with a Package.swift manifest.
  --name <name>           Provide custom package name
  --version               Show the version.
  -h, -help, --help       Show help information.

bitjammer · 2023-02-10T22:03:48Z

@swift-ci Please test

bitjammer · 2023-02-10T22:04:05Z

@swift-ci Please smoke test

CHANGELOG.md

Improve the `swift package init` experience using the following criteria: - Simplify the templates to include only the minimum necessary to get started without making assumptions. - Use documentation links instead of arbitrary template content to teach people about Swift. - Improve the "front door" experience with the help usage. Detailed list of changes: - Remove the `system-module` template. - Remove the `manifest` template - it's emptier than `empty` and isn't providing a lot of value on its own. Make the `empty` template only generate a manifest instead. - Remove README generation. - Don't generate empty directories. - Don't emit empty dependencies array in manifests. - Update `library` template content: - Remove struct definition, use a simple public function instead. - Include documentation links for TSPL and the Standard Library. - Include documentation links for XCTest in the generated test case. - Update `executable` template content - Use simpler top-level code instead of an `@main` struct. - Remove executable tests. - Put sources directly in `./Sources`. - Clean up and align `type` argument help text - Update Usage.md documentation - Update CHANGELOG to reflect init template changes in swiftlang#6144 rdar://98999734

bitjammer · 2023-02-13T21:58:46Z

@swift-ci Please smoke test

Improve the `swift package init` experience using the following criteria: - Simplify the templates to include only the minimum necessary to get started without making assumptions. - Use documentation links instead of arbitrary template content to teach people about Swift. - Improve the "front door" experience with the help usage. Detailed list of changes: - Remove the `system-module` template. - Remove the `manifest` template - it's emptier than `empty` and isn't providing a lot of value on its own. Make the `empty` template only generate a manifest instead. - Remove README generation. - Don't generate empty directories. - Don't emit empty dependencies array in manifests. - Update `library` template content: - Remove struct definition, use a simple public function instead. - Include documentation links for TSPL and the Standard Library. - Include documentation links for XCTest in the generated test case. - Update `executable` template content - Use simpler top-level code instead of an `@main` struct. - Remove executable tests. - Put sources directly in `./Sources`. - Clean up and align `type` argument help text - Update Usage.md documentation - Update CHANGELOG to reflect init template changes in swiftlang#6144 rdar://98999734

bitjammer · 2023-02-13T23:40:17Z

@swift-ci Please smoke test

Improve the `swift package init` experience using the following criteria: - Simplify the templates to include only the minimum necessary to get started without making assumptions. - Use documentation links instead of template content to teach people about Swift. - Improve the "front door" experience with the help usage. Detailed list of changes: - Remove the `system-module` template. - Remove the `manifest` template - Add a new `tool` template, an executable that uses ArgumentParser a manifest instead. - Remove README generation. - Don't generate empty directories. - Don't emit empty dependencies array in manifests. - Update `library` template content: - Remove struct definition, use a simple public function instead. - Include documentation links for TSPL and the Standard Library. - Include documentation links for XCTest in the generated test case. - Update `executable` template content - Use simpler top-level code instead of an `@main` struct. - Remove executable tests. - Put sources directly in `./Sources`. - Clean up and align `type` argument help text - Update Usage.md documentation - Update CHANGELOG to reflect init template changes in swiftlang#6144 rdar://98999734

neonichu

Thanks, Ashley.

This is looking great, we should give the forum post a couple of days to see if any interesting feedback will be provided by the community, but otherwise good to merge.

bitjammer · 2023-02-16T23:42:21Z

@swift-ci Please smoke test

TimTr · 2023-02-20T16:06:46Z

Looks good - here is the forum thread since I didn't see it referenced here (may have just missed it): https://forums.swift.org/t/update-to-swift-package-init-templates/63145/8

tomerd · 2023-02-21T17:27:30Z

@bitjammer @TimTr is this ready to be merged? do you feel we collected enough feedback from the community?

TimTr · 2023-02-21T18:39:49Z

@tomerd and @bitjammer I think we're good to merge. Post is live for a week now.

Improve the `swift package init` experience using the following criteria: - Simplify the templates to include only the minimum necessary to get started without making assumptions. - Use documentation links instead of template content to teach people about Swift. - Improve the "front door" experience with the help usage. Detailed list of changes: - Remove the `system-module` template. - Remove the `manifest` template - Add a new `tool` template, an executable that uses ArgumentParser a manifest instead. - Remove README generation. - Don't generate empty directories. - Don't emit empty dependencies array in manifests. - Update `library` template content: - Remove struct definition, use a simple public function instead. - Include documentation links for TSPL and the Standard Library. - Include documentation links for XCTest in the generated test case. - Update `executable` template content - Use simpler top-level code instead of an `@main` struct. - Remove executable tests. - Put sources directly in `./Sources`. - Clean up and align `type` argument help text - Update Usage.md documentation - Update CHANGELOG to reflect init template changes in swiftlang#6144 rdar://98999734

glbrntt · 2023-03-06T14:26:12Z

Missed this when it was posted in the forums but I think some of the changes are a bit of a miss-step here. Responded in the forums (https://forums.swift.org/t/update-to-swift-package-init-templates/63145)

cc @FranzBusch

Motivation: SwiftPM has changed its default layout for packages in swiftlang/swift-package-manager#6144. This breaks our CI, which assumes the prior layout. We should work around this. Modifications: Enhance the code to tolerate both layouts. Result: Integration tests run on all platforms

After getting some feedback about the added `path` argument for executable packages generated with `swift package init` (swiftlang#6144), this change allows a target's sources to occupy the entire sources directory when there is only one target in the package. All package types can benefit from this. When there is more than one target in a package, the existing requirements for target sources still apply. This change should be compatible with existing layouts as well. If there is only a single target in a package, then sources can of course continue to exist in `./Sources/<target>`. Amend the `executable` template's generated manifest to not include the `path` argument anymore. rdar://106829666

After getting some feedback about the added `path` argument for executable packages generated with `swift package init` (swiftlang#6144), this change allows a target's sources to occupy the entire "predefined sources directory" (e.g. `Sources`, `Tests`, or `Plugins`) when there is only one target of a specific kind occupying one of those directories in the package. All package types can benefit from this. For example, if there is only one library target and one test target, one can put sources directly in `./Sources` and `./Tests`. Adding another library means that one has to put the sources for TargetA in `./Sources/TargetA` and the sources for TargetB in `./Sources/TargetB`, and so on. When there is more than one target of a type in a package, the existing requirements for target sources still apply. This change should be compatible with existing layouts as well. If there is only a single target in a package, then sources can of course continue to exist exclusively in `./Sources/<target>`, or `./Tests/<testTarget>`, etc. Amend the `executable` and `tool` template's generated manifest to not include the `path` argument anymore as it is no longer needed. With this change, the `library` template type can also put its sources and tests directly in the `./Sources` and `./Tests` directories respectively. All of the above only takes place when the tools version is set to 5.9 or higher in the manifest. rdar://106829666

…6294) After getting some feedback about the added `path` argument for executable packages generated with `swift package init` (#6144), this change allows a target's sources to occupy the entire "predefined sources directory" (e.g. `Sources`, `Tests`, or `Plugins`) when there is only one target of a specific kind occupying one of those directories in the package. All package types can benefit from this. For example, if there is only one library target and one test target, one can put sources directly in `./Sources` and `./Tests`. Adding another library means that one has to put the sources for TargetA in `./Sources/TargetA` and the sources for TargetB in `./Sources/TargetB`, and so on. When there is more than one target of a type in a package, the existing requirements for target sources still apply. This change should be compatible with existing layouts as well. If there is only a single target in a package, then sources can of course continue to exist exclusively in `./Sources/<target>`, or `./Tests/<testTarget>`, etc. Amend the `executable` and `tool` template's generated manifest to not include the `path` argument anymore as it is no longer needed. With this change, the `library` template type can also put its sources and tests directly in the `./Sources` and `./Tests` directories respectively. All of the above only takes place when the tools version is set to 5.9 or higher in the manifest. rdar://106829666

bitjammer requested review from abertelrud, neonichu, tomerd and elsh as code owners February 10, 2023 22:00

bitjammer requested a review from TimTr February 10, 2023 22:00

bitjammer added a commit to bitjammer/swift-package-manager that referenced this pull request Feb 10, 2023

Update CHANGELOG to reflect init template changes in swiftlang#6144

04ef2f3

neonichu reviewed Feb 10, 2023

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

tomerd assigned bitjammer Feb 10, 2023

bitjammer force-pushed the acgarland/rdar-98999734-update-init-templates branch from 04ef2f3 to b574df1 Compare February 11, 2023 01:07

bitjammer force-pushed the acgarland/rdar-98999734-update-init-templates branch from b574df1 to 079a811 Compare February 11, 2023 01:08

bitjammer force-pushed the acgarland/rdar-98999734-update-init-templates branch from 079a811 to cc0c708 Compare February 13, 2023 21:58

bitjammer force-pushed the acgarland/rdar-98999734-update-init-templates branch from cc0c708 to ff2ba73 Compare February 13, 2023 23:40

bitjammer force-pushed the acgarland/rdar-98999734-update-init-templates branch from ff2ba73 to 8748e9e Compare February 15, 2023 19:52

neonichu approved these changes Feb 15, 2023

View reviewed changes

bitjammer mentioned this pull request Feb 21, 2023

Update tests for new swiftpm templates swiftlang/swift-integration-tests#108

Merged

neonichu merged commit 893ccb4 into swiftlang:main Feb 21, 2023

bitjammer deleted the acgarland/rdar-98999734-update-init-templates branch February 22, 2023 19:32

bitjammer mentioned this pull request Feb 22, 2023

[5.8] Init template cleanup (#6144) #6173

Merged

tomerd pushed a commit that referenced this pull request Feb 23, 2023

Init template cleanup (#6144) (#6173)

d390f03

Lukasa mentioned this pull request Mar 13, 2023

Work around the SwiftPM layout change. apple/swift-nio#2389

Merged

bitjammer mentioned this pull request Mar 16, 2023

Allow sources anywhere in ./Sources when only one target is present #6294

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Init template cleanup #6144

Init template cleanup #6144

bitjammer commented Feb 10, 2023 •

edited

Loading

bitjammer commented Feb 10, 2023

bitjammer commented Feb 10, 2023

bitjammer commented Feb 13, 2023

bitjammer commented Feb 13, 2023

neonichu left a comment

bitjammer commented Feb 16, 2023

TimTr commented Feb 20, 2023

tomerd commented Feb 21, 2023

TimTr commented Feb 21, 2023

glbrntt commented Mar 6, 2023

Init template cleanup #6144

Init template cleanup #6144

Conversation

bitjammer commented Feb 10, 2023 • edited Loading

Improve the swift package init experience using the following criteria:

Detailed list of changes:

Example resulting file listing

Resulting command line usage

bitjammer commented Feb 10, 2023

bitjammer commented Feb 10, 2023

bitjammer commented Feb 13, 2023

bitjammer commented Feb 13, 2023

neonichu left a comment

Choose a reason for hiding this comment

bitjammer commented Feb 16, 2023

TimTr commented Feb 20, 2023

tomerd commented Feb 21, 2023

TimTr commented Feb 21, 2023

glbrntt commented Mar 6, 2023

bitjammer commented Feb 10, 2023 •

edited

Loading

Improve the `swift package init` experience using the following criteria: