Skip to content

Commit 8ee24aa

Browse files
0xTim0xTim
authored
Content improvement guide updates (#373)
1 parent eb921bc commit 8ee24aa

File tree

2 files changed

+73
-122
lines changed

2 files changed

+73
-122
lines changed

‎getting-started/cli-swiftpm/index.md

Lines changed: 47 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -23,48 +23,24 @@ This will generate a new directory called MyCLI with the following files:
2323
~~~no-highlight
2424
.
2525
├── Package.swift
26-
├── README.md
27-
├── Sources
28-
│   └── MyCLI
29-
│   └── MyCLI.swift
30-
└── Tests
31-
└── MyCLITests
32-
└── MyCLITests.swift
26+
└── Sources
27+
   └── main.swift
3328
~~~
3429

3530
`Package.swift` is the manifest file for Swift. It’s where you keep metadata for your project, as well as dependencies.
3631

37-
`Sources/MyCLI/MyCLI.swift` is the application entry point and where we’ll write our application code.
38-
`Test/MyCLITests/MyCLITests.swift` is where we can write tests for our application.
32+
`Sources/main.swift` is the application entry point and where we’ll write our application code.
3933

40-
In fact, SwiftPM generated a "Hello, world!" project for us, including some unit tests!
34+
In fact, SwiftPM generated a "Hello, world!" project for us!
4135

42-
We can run the tests by running `swift test` in our terminal.
43-
44-
~~~bash
45-
$ swift test
46-
Building for debugging...
47-
[6/6] Linking MyCLIPackageTests
48-
Build complete! (16.53s)
49-
Test Suite 'All tests' started at 2023-01-12 13:38:22.393
50-
Test Suite 'MyCLIPackageTests.xctest' started at 2023-01-12 13:38:22.394
51-
Test Suite 'MyCLITests' started at 2023-01-12 13:38:22.394
52-
Test Case '-[MyCLITests.MyCLITests testExample]' started.
53-
Test Case '-[MyCLITests.MyCLITests testExample]' passed (0.003 seconds).
54-
Test Suite 'MyCLITests' passed at 2023-01-12 13:38:22.397.
55-
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.003) seconds
56-
Test Suite 'MyCLIPackageTests.xctest' passed at 2023-01-12 13:38:22.398.
57-
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.004) seconds
58-
Test Suite 'All tests' passed at 2023-01-12 13:38:22.398.
59-
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.005) seconds
60-
~~~
61-
62-
We can also run the program by running `swift run` in our terminal.
36+
We can run the program by running `swift run` in our terminal.
6337

6438
~~~bash
6539
$ swift run MyCLI
40+
Building for debugging...
6641
[3/3] Linking MyCLI
67-
Hello, World!
42+
Build complete! (0.68s)
43+
Hello, world!
6844
~~~
6945

7046
## Adding dependencies
@@ -78,30 +54,26 @@ You can find more interesting libraries on [Swift Package Index](https://swiftpa
7854
To do so, we extend our `Package.swift` file with the following information:
7955

8056
~~~swift
81-
// swift-tools-version: 5.7
57+
// swift-tools-version: 5.8
58+
// The swift-tools-version declares the minimum version of Swift required to build this package.
8259

8360
import PackageDescription
8461

8562
let package = Package(
86-
name: "MyCLI",
87-
products: [
88-
.executable(name: "MyCLI", targets: ["MyCLI"])
89-
],
90-
dependencies: [
91-
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
92-
],
93-
targets: [
94-
.executableTarget(
95-
name: "MyCLI",
96-
dependencies: [
97-
.product(name: "Figlet", package: "example-package-figlet"),
98-
]
99-
),
100-
.testTarget(
101-
name: "MyCLITests",
102-
dependencies: ["MyCLI"]
103-
),
104-
]
63+
name: "MyCLI",
64+
dependencies: [
65+
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
66+
],
67+
targets: [
68+
// Targets are the basic building blocks of a package, defining a module or a test suite.
69+
// Targets can depend on other targets in this package and products from dependencies.
70+
.executableTarget(
71+
name: "MyCLI",
72+
dependencies: [
73+
.product(name: "Figlet", package: "example-package-figlet"),
74+
],
75+
path: "Sources"),
76+
]
10577
)
10678
~~~
10779

@@ -110,20 +82,12 @@ Running `swift build` will instruct SwiftPM to download the new dependencies and
11082
Running this command also created a new file for us, `Package.resolved`.
11183
This file is a snapshot of the exact versions of the dependencies we are using locally.
11284

113-
To use this dependency, we can open `MyCLI.swift`, remove everything that’s in there (it’s just an example), and add this line to it:
114-
115-
~~~swift
116-
import Figlet
117-
~~~
118-
119-
This line means that we can now use the `Figlet` module that the `example-package-figlet` package exports.
120-
12185
## A small application
12286

123-
Now let’s write a small application with our new dependency. In our `MyCLI.swift`, add the following code:
87+
Start by removing `main.swift`. We’ll replace it with a new file called `MyCLI.swift`. Add the following code to it:
12488

12589
~~~swift
126-
import Figlet // from the previous step
90+
import Figlet
12791

12892
@main
12993
struct FigletTool {
@@ -133,15 +97,9 @@ struct FigletTool {
13397
}
13498
~~~
13599

136-
Now lets remove the default unit test since we changes the tools' code.
137-
Replace the example content of `MyCLITests.swift` with the following code:
100+
This provides a new entrypoint to the app which could be asynchronous if required. You can either have a `main.swift` file or a `@main` entrypoint, but not both.
138101

139-
~~~swift
140-
@testable import MyCLI
141-
import XCTest
142-
143-
final class MyCLITests: XCTestCase {}
144-
~~~
102+
With `import Figlet` we can now use the `Figlet` module that the `example-package-figlet` package exports.
145103

146104
Once we save that, we can run our application with `swift run`
147105
Assuming everything went well, you should see your application print this to the screen:
@@ -164,40 +122,36 @@ To add this capability to our application, we add a dependency on [swift-argumen
164122
To do so, we extend our `Package.swift` file with the following information:
165123

166124
~~~swift
167-
// swift-tools-version: 5.7
125+
// swift-tools-version: 5.8
126+
// The swift-tools-version declares the minimum version of Swift required to build this package.
168127

169128
import PackageDescription
170129

171130
let package = Package(
172-
name: "swift-swift",
173-
dependencies: [
174-
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
175-
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
176-
],
177-
products: [
178-
.executable(name: "MyCLI", targets: ["MyCLI"])
179-
],
180-
targets: [
181-
.executableTarget(
182-
name: "MyCLI",
183-
dependencies: [
184-
.product(name: "Figlet", package: "example-package-figlet"),
185-
.product(name: "ArgumentParser", package: "swift-argument-parser"),
186-
]
187-
),
188-
.testTarget(
189-
name: "MyCLITests",
190-
dependencies: ["MyCLI"]
191-
),
192-
]
131+
name: "MyCLI",
132+
dependencies: [
133+
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
134+
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
135+
],
136+
targets: [
137+
// Targets are the basic building blocks of a package, defining a module or a test suite.
138+
// Targets can depend on other targets in this package and products from dependencies.
139+
.executableTarget(
140+
name: "MyCLI",
141+
dependencies: [
142+
.product(name: "Figlet", package: "example-package-figlet"),
143+
.product(name: "ArgumentParser", package: "swift-argument-parser"),
144+
],
145+
path: "Sources"),
146+
]
193147
)
194148
~~~
195149

196150
We can now import the argument parsing module provided by `swift-argument-parser` and use it in our application:
197151

198152
~~~swift
199-
import ArgumentParser
200153
import Figlet
154+
import ArgumentParser
201155

202156
@main
203157
struct FigletTool: ParsableCommand {

‎getting-started/library-swiftpm/index.md

Lines changed: 26 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ This will generate a new directory called _MyLibrary_ with the following files:
2323
~~~no-highlight
2424
.
2525
├── Package.swift
26-
├── README.md
2726
├── Sources
2827
│   └── MyLibrary
2928
│   └── MyLibrary.swift
@@ -43,19 +42,19 @@ We can run the tests by running `swift test` in our terminal.
4342
~~~bash
4443
$ swift test
4544
Building for debugging...
46-
[4/4] Compiling MyLibraryTests MyLibraryTests.swift
47-
Build complete! (1.30s)
48-
Test Suite 'All tests' started at 2023-01-12 12:05:56.127
49-
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-01-12 12:05:56.128
50-
Test Suite 'MyLibraryTests' started at 2023-01-12 12:05:56.128
45+
[5/5] Linking MyLibraryPackageTests
46+
Build complete! (7.91s)
47+
Test Suite 'All tests' started at 2023-08-29 18:59:31.328
48+
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-08-29 18:59:31.329
49+
Test Suite 'MyLibraryTests' started at 2023-08-29 18:59:31.329
5150
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' started.
52-
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' passed (0.005 seconds).
53-
Test Suite 'MyLibraryTests' passed at 2023-01-12 12:05:56.133.
54-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
55-
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-01-12 12:05:56.133.
56-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
57-
Test Suite 'All tests' passed at 2023-01-12 12:05:56.133.
58-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.007) seconds
51+
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' passed (0.001 seconds).
52+
Test Suite 'MyLibraryTests' passed at 2023-08-29 18:59:31.330.
53+
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.001) seconds
54+
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-08-29 18:59:31.330.
55+
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.001) seconds
56+
Test Suite 'All tests' passed at 2023-08-29 18:59:31.330.
57+
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.002) seconds
5958
~~~
6059

6160
## A small library
@@ -100,26 +99,24 @@ final class MyLibraryTests: XCTestCase {
10099
}
101100
~~~
102101

103-
Once we save that, we can run our application with `swift run`.
104-
Assuming everything went well, we can run the tests successfully again:
102+
Once we save that, we can run the tests again:
105103

106104
~~~no-highlight
107105
❯ swift test
108106
Building for debugging...
109-
[3/3] Linking swift-libraryPackageTests
110-
Build complete! (0.84s)
111-
Test Suite 'All tests' started at 2023-01-03 16:22:45.070
112-
Test Suite 'swift-libraryPackageTests.xctest' started at 2023-01-03 16:22:45.071
113-
Test Suite 'swift_libraryTests' started at 2023-01-03 16:22:45.071
114-
Test Case '-[swift_libraryTests.swift_libraryTests testEmail]' started.
115-
Test Case '-[swift_libraryTests.swift_libraryTests testEmail]' passed (0.005 seconds).
116-
Test Suite 'swift_libraryTests' passed at 2023-01-03 16:22:45.076.
117-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
118-
Test Suite 'swift-libraryPackageTests.xctest' passed at 2023-01-03 16:22:45.076.
119-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
120-
Test Suite 'All tests' passed at 2023-01-03 16:22:45.076.
121-
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.007) seconds
122-
~~~
107+
[5/5] Linking MyLibraryPackageTests
108+
Build complete! (3.09s)
109+
Test Suite 'All tests' started at 2023-08-29 19:01:08.640
110+
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-08-29 19:01:08.641
111+
Test Suite 'MyLibraryTests' started at 2023-08-29 19:01:08.641
112+
Test Case '-[MyLibraryTests.MyLibraryTests testEmail]' started.
113+
Test Case '-[MyLibraryTests.MyLibraryTests testEmail]' passed (0.002 seconds).
114+
Test Suite 'MyLibraryTests' passed at 2023-08-29 19:01:08.643.
115+
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.002) seconds
116+
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-08-29 19:01:08.643.
117+
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.002) seconds
118+
Test Suite 'All tests' passed at 2023-08-29 19:01:08.643.
119+
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.003) seconds
123120
124121
---
125122

0 commit comments

Comments
 (0)