Skip to content

Content improvement guide updates #373

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 29, 2023
Merged

Content improvement guide updates #373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dc6e45e
Update library guide for 5.8
0xTim Aug 29, 2023
6db765f
Update CLI guide for 5.8
0xTim Aug 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 47 additions & 93 deletions getting-started/cli-swiftpm/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,48 +23,24 @@ This will generate a new directory called MyCLI with the following files:
~~~no-highlight
.
├── Package.swift
├── README.md
├── Sources
│   └── MyCLI
│   └── MyCLI.swift
└── Tests
└── MyCLITests
└── MyCLITests.swift
└── Sources
   └── main.swift
~~~

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

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

In fact, SwiftPM generated a "Hello, world!" project for us, including some unit tests!
In fact, SwiftPM generated a "Hello, world!" project for us!

We can run the tests by running `swift test` in our terminal.

~~~bash
$ swift test
Building for debugging...
[6/6] Linking MyCLIPackageTests
Build complete! (16.53s)
Test Suite 'All tests' started at 2023-01-12 13:38:22.393
Test Suite 'MyCLIPackageTests.xctest' started at 2023-01-12 13:38:22.394
Test Suite 'MyCLITests' started at 2023-01-12 13:38:22.394
Test Case '-[MyCLITests.MyCLITests testExample]' started.
Test Case '-[MyCLITests.MyCLITests testExample]' passed (0.003 seconds).
Test Suite 'MyCLITests' passed at 2023-01-12 13:38:22.397.
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.003) seconds
Test Suite 'MyCLIPackageTests.xctest' passed at 2023-01-12 13:38:22.398.
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.004) seconds
Test Suite 'All tests' passed at 2023-01-12 13:38:22.398.
Executed 1 test, with 0 failures (0 unexpected) in 0.003 (0.005) seconds
~~~

We can also run the program by running `swift run` in our terminal.
We can run the program by running `swift run` in our terminal.

~~~bash
$ swift run MyCLI
Building for debugging...
[3/3] Linking MyCLI
Hello, World!
Build complete! (0.68s)
Hello, world!
~~~

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

~~~swift
// swift-tools-version: 5.7
// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
name: "MyCLI",
products: [
.executable(name: "MyCLI", targets: ["MyCLI"])
],
dependencies: [
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
],
targets: [
.executableTarget(
name: "MyCLI",
dependencies: [
.product(name: "Figlet", package: "example-package-figlet"),
]
),
.testTarget(
name: "MyCLITests",
dependencies: ["MyCLI"]
),
]
name: "MyCLI",
dependencies: [
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
],
targets: [
// Targets are the basic building blocks of a package, defining a module or a test suite.
// Targets can depend on other targets in this package and products from dependencies.
.executableTarget(
name: "MyCLI",
dependencies: [
.product(name: "Figlet", package: "example-package-figlet"),
],
path: "Sources"),
]
)
~~~

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

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:

~~~swift
import Figlet
~~~

This line means that we can now use the `Figlet` module that the `example-package-figlet` package exports.

## A small application

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

~~~swift
import Figlet // from the previous step
import Figlet

@main
struct FigletTool {
Expand All @@ -133,15 +97,9 @@ struct FigletTool {
}
~~~

Now lets remove the default unit test since we changes the tools' code.
Replace the example content of `MyCLITests.swift` with the following code:
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.

~~~swift
@testable import MyCLI
import XCTest

final class MyCLITests: XCTestCase {}
~~~
With `import Figlet` we can now use the `Figlet` module that the `example-package-figlet` package exports.

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

~~~swift
// swift-tools-version: 5.7
// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
name: "swift-swift",
dependencies: [
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
],
products: [
.executable(name: "MyCLI", targets: ["MyCLI"])
],
targets: [
.executableTarget(
name: "MyCLI",
dependencies: [
.product(name: "Figlet", package: "example-package-figlet"),
.product(name: "ArgumentParser", package: "swift-argument-parser"),
]
),
.testTarget(
name: "MyCLITests",
dependencies: ["MyCLI"]
),
]
name: "MyCLI",
dependencies: [
.package(url: "https://github.com/apple/example-package-figlet", branch: "main"),
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
],
targets: [
// Targets are the basic building blocks of a package, defining a module or a test suite.
// Targets can depend on other targets in this package and products from dependencies.
.executableTarget(
name: "MyCLI",
dependencies: [
.product(name: "Figlet", package: "example-package-figlet"),
.product(name: "ArgumentParser", package: "swift-argument-parser"),
],
path: "Sources"),
]
)
~~~

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

~~~swift
import ArgumentParser
import Figlet
import ArgumentParser

@main
struct FigletTool: ParsableCommand {
Expand Down
55 changes: 26 additions & 29 deletions getting-started/library-swiftpm/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ This will generate a new directory called _MyLibrary_ with the following files:
~~~no-highlight
.
├── Package.swift
├── README.md
├── Sources
│   └── MyLibrary
│   └── MyLibrary.swift
Expand All @@ -43,19 +42,19 @@ We can run the tests by running `swift test` in our terminal.
~~~bash
$ swift test
Building for debugging...
[4/4] Compiling MyLibraryTests MyLibraryTests.swift
Build complete! (1.30s)
Test Suite 'All tests' started at 2023-01-12 12:05:56.127
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-01-12 12:05:56.128
Test Suite 'MyLibraryTests' started at 2023-01-12 12:05:56.128
[5/5] Linking MyLibraryPackageTests
Build complete! (7.91s)
Test Suite 'All tests' started at 2023-08-29 18:59:31.328
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-08-29 18:59:31.329
Test Suite 'MyLibraryTests' started at 2023-08-29 18:59:31.329
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' started.
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' passed (0.005 seconds).
Test Suite 'MyLibraryTests' passed at 2023-01-12 12:05:56.133.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-01-12 12:05:56.133.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
Test Suite 'All tests' passed at 2023-01-12 12:05:56.133.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.007) seconds
Test Case '-[MyLibraryTests.MyLibraryTests testExample]' passed (0.001 seconds).
Test Suite 'MyLibraryTests' passed at 2023-08-29 18:59:31.330.
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.001) seconds
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-08-29 18:59:31.330.
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.001) seconds
Test Suite 'All tests' passed at 2023-08-29 18:59:31.330.
Executed 1 test, with 0 failures (0 unexpected) in 0.001 (0.002) seconds
~~~

## A small library
Expand Down Expand Up @@ -100,26 +99,24 @@ final class MyLibraryTests: XCTestCase {
}
~~~

Once we save that, we can run our application with `swift run`.
Assuming everything went well, we can run the tests successfully again:
Once we save that, we can run the tests again:

~~~no-highlight
❯ swift test
Building for debugging...
[3/3] Linking swift-libraryPackageTests
Build complete! (0.84s)
Test Suite 'All tests' started at 2023-01-03 16:22:45.070
Test Suite 'swift-libraryPackageTests.xctest' started at 2023-01-03 16:22:45.071
Test Suite 'swift_libraryTests' started at 2023-01-03 16:22:45.071
Test Case '-[swift_libraryTests.swift_libraryTests testEmail]' started.
Test Case '-[swift_libraryTests.swift_libraryTests testEmail]' passed (0.005 seconds).
Test Suite 'swift_libraryTests' passed at 2023-01-03 16:22:45.076.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
Test Suite 'swift-libraryPackageTests.xctest' passed at 2023-01-03 16:22:45.076.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.005) seconds
Test Suite 'All tests' passed at 2023-01-03 16:22:45.076.
Executed 1 test, with 0 failures (0 unexpected) in 0.005 (0.007) seconds
~~~
[5/5] Linking MyLibraryPackageTests
Build complete! (3.09s)
Test Suite 'All tests' started at 2023-08-29 19:01:08.640
Test Suite 'MyLibraryPackageTests.xctest' started at 2023-08-29 19:01:08.641
Test Suite 'MyLibraryTests' started at 2023-08-29 19:01:08.641
Test Case '-[MyLibraryTests.MyLibraryTests testEmail]' started.
Test Case '-[MyLibraryTests.MyLibraryTests testEmail]' passed (0.002 seconds).
Test Suite 'MyLibraryTests' passed at 2023-08-29 19:01:08.643.
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.002) seconds
Test Suite 'MyLibraryPackageTests.xctest' passed at 2023-08-29 19:01:08.643.
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.002) seconds
Test Suite 'All tests' passed at 2023-08-29 19:01:08.643.
Executed 1 test, with 0 failures (0 unexpected) in 0.002 (0.003) seconds

---

Expand Down