Skip to content

Commit a6a99ac

Browse files
euanheuanh
committed
docs: Split ContainerBuildPlugin documentation into multiple pages
1 parent 55be678 commit a6a99ac

File tree

16 files changed

+284
-5
lines changed

16 files changed

+284
-5
lines changed

‎.spi.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ builder:
33
configs:
44
- documentation_targets:
55
- containertool
6-
- ContainerImageBuilderPlugin
6+
- swift-container-plugin

‎Package.swift‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ let package = Package(
2727
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0"..<"4.0.0"),
2828
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
2929
.package(url: "https://github.com/apple/swift-http-types.git", from: "1.2.0"),
30-
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
30+
.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.0.0"),
3131
],
3232
targets: [
3333
.target(
@@ -78,12 +78,12 @@ let package = Package(
7878
),
7979
dependencies: [.target(name: "containertool")]
8080
),
81-
// Empty target that builds the DocC catalog at /ContainerImageBuilderPluginDocumentation/ContainerImageBuilder.docc.
81+
// Empty target that builds the DocC catalog at /SwiftContainerPluginDocumentation/Documentation.docc.
8282
// The ContainerImageBuilder catalog includes high-level, user-facing documentation about using
8383
// the ContainerImageBuilder plugin from the command-line.
8484
.target(
85-
name: "ContainerImageBuilderPlugin",
86-
path: "Sources/ContainerImageBuilderPluginDocumentation",
85+
name: "swift-container-plugin",
86+
//path: "Sources/SwiftContainerPluginDocumentation",
8787
exclude: ["README.md"]
8888
),
8989
.testTarget(

‎Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md‎ renamed to ‎Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md‎

File renamed without changes.

‎Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/Info.plist‎ renamed to ‎Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist‎

File renamed without changes.

‎Sources/ContainerImageBuilderPluginDocumentation/Empty.swift‎ renamed to ‎Sources/SwiftContainerPluginDocumentation/Empty.swift‎

File renamed without changes.

‎Sources/ContainerImageBuilderPluginDocumentation/README.md‎ renamed to ‎Sources/SwiftContainerPluginDocumentation/README.md‎

File renamed without changes.

‎Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Add the plugin to your project
2+
3+
Make Swift Container Plugin available in your project
4+
5+
Swift Container Plugin is distributed as a Swift Package Manager package. To make it available, you must add it as a dependency of your project.
6+
7+
## Install the plugin using the `swift package` CLI
8+
9+
Recent versions of `swift package` suupport the `add-dependency` command:
10+
11+
```shell
12+
swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.5.0
13+
```
14+
15+
## Install the plugin by manually editing `Package.swift`
16+
17+
If you cannot use the `swift package add-dependency` comand, append the following lines to your project's `Package.swift` file:
18+
19+
```swift
20+
package.dependencies += [
21+
.package(url: "https://github.com/apple/swift-container-plugin", from: "0.5.0"),
22+
]
23+
```
24+
25+
## Check that the plugin is available
26+
27+
After installation, Swift Package Manager should show that the `ContainerImageBuilder` is now available:
28+
29+
```shell
30+
% swift package plugin --list
31+
‘build-container-image’ (plugin ‘ContainerImageBuilder’ in package ‘swift-container-plugin)
32+
```

‎Sources/swift-container-plugin/Documentation.docc/Info.plist‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3+
<!--
4+
This source file is part of the Swift.org open source project
5+
6+
Copyright (c) 2024 Apple Inc. and the Swift project authors
7+
Licensed under Apache License v2.0 with Runtime Library Exception
8+
9+
See https://swift.org/LICENSE.txt for license information
10+
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
11+
-->
12+
<plist version="1.0">
13+
<dict>
14+
<key>CDDefaultCodeListingLanguage</key>
15+
<string>shell</string>
16+
<key>CFBundleName</key>
17+
<string>swift-container-plugin</string>
18+
<key>CFBundleDisplayName</key>
19+
<string>swift-container-plugin</string>
20+
<key>CFBundleIdentifier</key>
21+
<string>com.apple.ContainerPlugin</string>
22+
<key>CFBundlePackageType</key>
23+
<string>DOCS</string>
24+
<key>CDDefaultModuleKind</key>
25+
<string>Tool</string>
26+
</dict>
27+
</plist>
28+

‎Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Installing dependencies
2+
3+
* Swift Container Plugin runs on macOS and Linux and requires Swift 6.0 or later.
4+
* On macOS you must install a cross-compilation Swift SDK, such as the [Swift Static Linux SDK](https://www.swift.org/documentation/articles/static-linux-getting-started.html), in order to build executables which can run on Linux-based cloud infrastructure.
5+
* A container runtime is not required to build an image, but one must be available wherever the image is to be run.

‎Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Swift Container Plugin
2+
3+
@Metadata {
4+
@TechnologyRoot()
5+
}
6+
7+
Build and publish container images using Swift Package Manager.
8+
9+
## Overview
10+
11+
Container images are the standard way to package cloud software today. Once you have packaged your server in a container image, you can deploy it on any container-based public or private cloud service, or run it locally using a desktop container runtime.
12+
13+
Swift Container Plugin makes it easy to build container images for servers written in Swift, using Swift Package Manager.
14+
15+
Find out more and see it in action:
16+
17+
* [How to put Swift in a box](https://fosdem.org/2025/schedule/event/fosdem-2025-5116-how-to-put-swift-in-a-box-building-container-images-with-swift-container-plugin/) at [FOSDEM 2025](https://fosdem.org/2025/schedule/track/swift/).
18+
* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/speakers/euan-harris/).
19+
20+
## Usage
21+
22+
Swift Container Plugin can package any executable product defined in `Package.swift` in a container image and publish it to a container registry.
23+
24+
### Build and publish a container image
25+
26+
After adding the plugin to your project, you can build and publish a container image in one step:
27+
28+
```
29+
% swift package --swift-sdk x86_64-swift-linux-musl \
30+
build-container-image --repository registry.example.com/myservice
31+
...
32+
Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports.
33+
Stated reason: “This command publishes images to container registries over the network”.
34+
Allow this plugin to allow all network connections on all ports? (yes/no) yes
35+
...
36+
Building for debugging...
37+
Build of product 'containertool' complete! (4.95s)
38+
...
39+
Build of product 'hello-world' complete! (5.51s)
40+
...
41+
[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42
42+
[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4
43+
[ContainerImageBuilder] Built application layer
44+
[ContainerImageBuilder] Uploading application layer
45+
[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists
46+
[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists
47+
[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists
48+
registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
49+
```
50+
51+
### Run the image
52+
53+
You can deploy your service in the cloud, or use a standards-compliant container runtime such as `podman` to run it locally:
54+
55+
```
56+
% podman run -p 8080:8080 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df
57+
Trying to pull registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df...
58+
...
59+
2024-05-26T22:57:50+0000 info HummingBird : [HummingbirdCore] Server started and listening on 0.0.0.0:8080
60+
```
61+
62+
Take a look at the [Examples](Examples).
63+
64+
## Topics
65+
66+
### Essentials
67+
- <doc:requirements>
68+
- <doc:Adding-the-plugin-to-your-project>
69+
- <doc:authentication>
70+
71+
### Building and running
72+
- <doc:build>
73+
- <doc:run>

0 commit comments

Comments
 (0)