|
| 1 | +# Swift Package Manager: Quick Start |
| 2 | +Swift Package Manager (SwiftPM) is a tool for building, testing and managing Swift project dependencies. |
| 3 | +In order to use it you will need Swift 3.0 or greater. |
| 4 | +SwiftPM is also included in Xcode 8.0 and above. |
| 5 | +For usage getting started: [https://swift.org/getting-started/#using-the-package-manager](https://swift.org/getting-started/#using-the-package-manager) |
| 6 | +For overview and examples: [https://swift.org/package-manager](https://swift.org/package-manager/) |
| 7 | + |
| 8 | +## Code Contributions |
| 9 | +Everyone is welcome to contribute to SwiftPM, submitting fixes, enhancement etc. |
| 10 | +Find out how previous coding decisions for SwiftPM evolution have been made: https://github.com/apple/swift-package-manager/blob/main/Documentation/Internals/PackageManagerCommunityProposal.md |
| 11 | + |
| 12 | +### Requirements |
| 13 | +You have multiple ways to setup your development environment, here we will focus on 2: |
| 14 | +A) *[Using Xcode](#using-xcode)* or B) [Using *the standalone Swift toolchain*](#using-standalone). |
| 15 | + |
| 16 | +<a id="using-xcode">*A) _Use Xcode to setup what you need_*.</a> |
| 17 | +Xcode is only available for macOS. |
| 18 | + |
| 19 | +1. Install Xcode 12 - [https://developer.apple.com/xcode](https://developer.apple.com/xcode/) |
| 20 | +2. Make sure you have at least SwiftPM 5.3: |
| 21 | +``` |
| 22 | +$> swift package --version |
| 23 | +Swift Package Manager - Swift 5.3.0 |
| 24 | +``` |
| 25 | +3. Make sure you have at least Swift 5.3: |
| 26 | +``` |
| 27 | +$> swift --version |
| 28 | +Apple Swift version 5.3 |
| 29 | +``` |
| 30 | +If you were able to do and verify the steps above, go to [**Getting Started**](#getting-started) |
| 31 | + |
| 32 | +<a id="using-standalone">*B) _Use standalone Swift toolchain</a>: 2a) [On macOS](#on-macos) or 2b) [On Linux](#on-linux)_*. |
| 33 | + |
| 34 | +Procedure valid for macOS and Linux. |
| 35 | + |
| 36 | +1. Pull the Swift repository: |
| 37 | +``` |
| 38 | +git clone https://github.com/apple/swift.git |
| 39 | +``` |
| 40 | +- 2 a. <a id="on-macos">On macOS</a> |
| 41 | +``` |
| 42 | +PATH/TO/REPO/swift/utils/build-script --preset=buildbot_swiftpm_macos_platform,tools=RA,stdlib=RA |
| 43 | +``` |
| 44 | +- 2b. <a id="on-linux">On Linux</a> |
| 45 | +``` |
| 46 | +PATH/TO/REPO/swift/utils/build-script --preset=buildbot_swiftpm_linux_platform,tools=RA,stdlib=RA |
| 47 | +``` |
| 48 | + |
| 49 | +### <a name="getting-started">Getting Started</a> |
| 50 | +1. Pull the SwiftPM repository: |
| 51 | +``` |
| 52 | +git clone https://github.com/apple/swift-package-manager.git |
| 53 | +``` |
| 54 | +2. Run your first build: |
| 55 | +``` |
| 56 | +$> cd swift-package-manager |
| 57 | +$> swift build |
| 58 | +``` |
| 59 | +If the build process ends with exit code 0, the build is successful (we have an Enhancement Radar to implement a message for successful build and a short output on where the generated binaries are: rdar://69970428). |
| 60 | +After a successful build (currently), you should see something like this: |
| 61 | +``` |
| 62 | +[476/476] Linking swift-package |
| 63 | +``` |
| 64 | +A `.build/` folder will be generated and it should have inside a similar structure (including build binaries): |
| 65 | +``` |
| 66 | +artifacts/ |
| 67 | +checkouts/ |
| 68 | +debug/ |
| 69 | +repositories |
| 70 | +x86_64-apple-macosx |
| 71 | +debug.yaml |
| 72 | +manifest.db |
| 73 | +workspace-state.json |
| 74 | +``` |
| 75 | +Binaries (in the example above) are in `x86_64-apple-macosx/` |
| 76 | +If you need to build the generated binaries, run `swift-build` in inside `.build/`: |
| 77 | +``` |
| 78 | +./.build/x86_64-apple-macosx/debug/swift-build |
| 79 | +``` |
| 80 | + |
| 81 | +### Code Editor |
| 82 | +If you are contributing using macOS, the best option is to use Xcode to build and run test SwiftPM. |
| 83 | + |
| 84 | +### Troubleshooting |
| 85 | +* If during `swift build` you encounter these outputs: |
| 86 | +``` |
| 87 | +/../swift-package-manager/Sources/SPMTestSupport/misc.swift:93:35: warning: parameter 'file' with default argument '#file' passed to parameter 'file', whose default argument is '#filePath' |
| 88 | + XCTFail("\(error)", file: file, line: line) |
| 89 | + ^ |
| 90 | +/../swift-package-manager/Sources/SPMTestSupport/misc.swift:37:26: note: did you mean for parameter 'file' to default to '#filePath'? |
| 91 | + file: StaticString = #file, |
| 92 | + ^~~~~ |
| 93 | + #filePath |
| 94 | +/../swift-package-manager/Sources/SPMTestSupport/misc.swift:93:35: note: add parentheses to silence this warning |
| 95 | + XCTFail("\(error)", file: file, line: line) |
| 96 | + ^ |
| 97 | + ( ) |
| 98 | +``` |
| 99 | +Do not worry, since those are known warnings that will be addressed at some point. |
| 100 | +Warnings differ depending on the platform and they can be seen from time to time due the amount of contributions. |
| 101 | +Our goal is to constantly monitor warnings and work on fix them (even if they are not affecting a successful implementation). |
| 102 | +* If during `swift build` you encounter this error: |
| 103 | +``` |
| 104 | +/../apple-repos/swift-package-manager/.build/checkouts/swift-driver/Sources/SwiftDriver/Explicit Module Builds/InterModuleDependencyGraph.swift:102:3: error: unknown attribute '_spi' |
| 105 | + @_spi(Testing) public var isFramework: Bool |
| 106 | + ^ |
| 107 | +``` |
| 108 | +Make sure you are using SwiftPM 5.3 |
| 109 | +``` |
| 110 | +$> swift package --version |
| 111 | +Swift Package Manager - Swift 5.3.0 |
| 112 | +``` |
| 113 | + |
| 114 | +### Find your way to contribute |
| 115 | +Report a bug guide: https://github.com/apple/swift-package-manager/blob/main/Documentation/Resources.md#reporting-a-good-swiftpm-bug. |
| 116 | +JIRA Bug Tracker (a place where you can open bugs, enhancements to start to contribute): [https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22](https://bugs.swift.org/browse/SR-13640?jql=component%20%3D%20%22Package%20Manager%22). |
| 117 | + |
| 118 | +### Commits / PRs |
| 119 | +1. Fork: https://github.com/apple/swift-package-manager |
| 120 | +2. Clone a working copy of your fork |
| 121 | +3. Create a new branch |
| 122 | +4. Make your code changes |
| 123 | +5. Commit (include the Radar link or JIRA issue id in the commit message if possible and a description your changes) |
| 124 | +6. Push the commit / branch to your fork |
| 125 | +7. Make a PR from your fork / branch to `apple: main` |
| 126 | +8. Leave a new comment to trigger smoke tests: `[@swift-ci](https://github.com/swift-ci) please smoke test` |
| 127 | +9. Reviewers are going to be automatically added to your PR |
| 128 | +10. Merge pull request when you received approval from the reviewers (one or more) |
| 129 | + |
| 130 | +### Community and Support |
| 131 | +If you want to connect with the Swift community you can: |
| 132 | +* Use Swift Forums: [https://forums.swift.org](https://forums.swift.org/) |
| 133 | +* Contact the CODEOWNERS: https://github.com/apple/swift-package-manager/blob/main/CODEOWNERS |
| 134 | + |
| 135 | + |
| 136 | +### Additional Links |
| 137 | +* Official Apple GitHub |
| 138 | +[https://github.com/apple](https://github.com/apple) |
| 139 | +* Swift Package Manager GitHub |
| 140 | +[https://github.com/apple/swift-package-manager](https://github.com/apple/swift-package-manager) |
| 141 | +* Setup Development |
| 142 | +[https://github.com/apple/swift-package-manager/blob/main/Documentation/Development.md](https://github.com/apple/swift-package-manager/blob/main/Documentation/Development.md) |
| 143 | +* `Swift.org` Contributing page |
| 144 | +[https://swift.org/contributing/](https://swift.org/contributing/) |
| 145 | +* License |
| 146 | +[https://swift.org/LICENSE.txt](https://swift.org/LICENSE.txt) |
| 147 | +* Code of Conduct |
| 148 | +[https://swift.org/community/#code-of-conduct](https://swift.org/community/#code-of-conduct) |
0 commit comments