From a6a99aca657d46d5753cfa15cfa26e6a6aaff135 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Wed, 16 Apr 2025 15:39:26 +0100 Subject: [PATCH 01/17] docs: Split ContainerBuildPlugin documentation into multiple pages --- .spi.yml | 2 +- Package.swift | 8 +- .../ContainerImageBuilderPlugin.md | 0 .../Documentation.docc/Info.plist | 0 .../Empty.swift | 0 .../README.md | 0 .../Adding-the-plugin-to-your-project.md | 32 ++++++++ .../Documentation.docc/Info.plist | 28 +++++++ .../Platforms-and-requirements.md | 5 ++ .../Swift-Container-Plugin.md | 73 +++++++++++++++++++ .../Documentation.docc/authentication.md | 13 ++++ .../Documentation.docc/build.md | 42 +++++++++++ .../Documentation.docc/requirements.md | 41 +++++++++++ .../Documentation.docc/run.md | 20 +++++ Sources/swift-container-plugin/Empty.swift | 19 +++++ Sources/swift-container-plugin/README.md | 6 ++ 16 files changed, 284 insertions(+), 5 deletions(-) rename Sources/{ContainerImageBuilderPluginDocumentation => SwiftContainerPluginDocumentation}/Documentation.docc/ContainerImageBuilderPlugin.md (100%) rename Sources/{ContainerImageBuilderPluginDocumentation => SwiftContainerPluginDocumentation}/Documentation.docc/Info.plist (100%) rename Sources/{ContainerImageBuilderPluginDocumentation => SwiftContainerPluginDocumentation}/Empty.swift (100%) rename Sources/{ContainerImageBuilderPluginDocumentation => SwiftContainerPluginDocumentation}/README.md (100%) create mode 100644 Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/Info.plist create mode 100644 Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/authentication.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/build.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/requirements.md create mode 100644 Sources/swift-container-plugin/Documentation.docc/run.md create mode 100644 Sources/swift-container-plugin/Empty.swift create mode 100644 Sources/swift-container-plugin/README.md diff --git a/.spi.yml b/.spi.yml index 9e0e1e1..b2194b2 100644 --- a/.spi.yml +++ b/.spi.yml @@ -3,4 +3,4 @@ builder: configs: - documentation_targets: - containertool - - ContainerImageBuilderPlugin + - swift-container-plugin diff --git a/Package.swift b/Package.swift index e90006c..4527f73 100644 --- a/Package.swift +++ b/Package.swift @@ -27,7 +27,7 @@ let package = Package( .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0"..<"4.0.0"), .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"), .package(url: "https://github.com/apple/swift-http-types.git", from: "1.2.0"), - .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), + .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.0.0"), ], targets: [ .target( @@ -78,12 +78,12 @@ let package = Package( ), dependencies: [.target(name: "containertool")] ), - // Empty target that builds the DocC catalog at /ContainerImageBuilderPluginDocumentation/ContainerImageBuilder.docc. + // Empty target that builds the DocC catalog at /SwiftContainerPluginDocumentation/Documentation.docc. // The ContainerImageBuilder catalog includes high-level, user-facing documentation about using // the ContainerImageBuilder plugin from the command-line. .target( - name: "ContainerImageBuilderPlugin", - path: "Sources/ContainerImageBuilderPluginDocumentation", + name: "swift-container-plugin", + //path: "Sources/SwiftContainerPluginDocumentation", exclude: ["README.md"] ), .testTarget( diff --git a/Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md b/Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md similarity index 100% rename from Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md rename to Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md diff --git a/Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/Info.plist b/Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist similarity index 100% rename from Sources/ContainerImageBuilderPluginDocumentation/Documentation.docc/Info.plist rename to Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist diff --git a/Sources/ContainerImageBuilderPluginDocumentation/Empty.swift b/Sources/SwiftContainerPluginDocumentation/Empty.swift similarity index 100% rename from Sources/ContainerImageBuilderPluginDocumentation/Empty.swift rename to Sources/SwiftContainerPluginDocumentation/Empty.swift diff --git a/Sources/ContainerImageBuilderPluginDocumentation/README.md b/Sources/SwiftContainerPluginDocumentation/README.md similarity index 100% rename from Sources/ContainerImageBuilderPluginDocumentation/README.md rename to Sources/SwiftContainerPluginDocumentation/README.md diff --git a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md new file mode 100644 index 0000000..7277c15 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md @@ -0,0 +1,32 @@ +# Add the plugin to your project + +Make Swift Container Plugin available in your project + +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. + +## Install the plugin using the `swift package` CLI + +Recent versions of `swift package` suupport the `add-dependency` command: + +```shell +swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.5.0 +``` + +## Install the plugin by manually editing `Package.swift` + +If you cannot use the `swift package add-dependency` comand, append the following lines to your project's `Package.swift` file: + +```swift +package.dependencies += [ + .package(url: "https://github.com/apple/swift-container-plugin", from: "0.5.0"), +] +``` + +## Check that the plugin is available + +After installation, Swift Package Manager should show that the `ContainerImageBuilder` is now available: + +```shell +% swift package plugin --list +‘build-container-image’ (plugin ‘ContainerImageBuilder’ in package ‘swift-container-plugin) +``` \ No newline at end of file diff --git a/Sources/swift-container-plugin/Documentation.docc/Info.plist b/Sources/swift-container-plugin/Documentation.docc/Info.plist new file mode 100644 index 0000000..0fc40cf --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/Info.plist @@ -0,0 +1,28 @@ + + + + + + CDDefaultCodeListingLanguage + shell + CFBundleName + swift-container-plugin + CFBundleDisplayName + swift-container-plugin + CFBundleIdentifier + com.apple.ContainerPlugin + CFBundlePackageType + DOCS + CDDefaultModuleKind + Tool + + + diff --git a/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md b/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md new file mode 100644 index 0000000..ee84260 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md @@ -0,0 +1,5 @@ +# Installing dependencies + +* Swift Container Plugin runs on macOS and Linux and requires Swift 6.0 or later. +* 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. +* A container runtime is not required to build an image, but one must be available wherever the image is to be run. diff --git a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md new file mode 100644 index 0000000..cdd2a13 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md @@ -0,0 +1,73 @@ +# Swift Container Plugin + +@Metadata { + @TechnologyRoot() +} + +Build and publish container images using Swift Package Manager. + +## Overview + +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. + +Swift Container Plugin makes it easy to build container images for servers written in Swift, using Swift Package Manager. + +Find out more and see it in action: + +* [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/). +* [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/). + +## Usage + +Swift Container Plugin can package any executable product defined in `Package.swift` in a container image and publish it to a container registry. + +### Build and publish a container image + +After adding the plugin to your project, you can build and publish a container image in one step: + +``` +% swift package --swift-sdk x86_64-swift-linux-musl \ + build-container-image --repository registry.example.com/myservice +... +Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. +Stated reason: “This command publishes images to container registries over the network”. +Allow this plugin to allow all network connections on all ports? (yes/no) yes +... +Building for debugging... +Build of product 'containertool' complete! (4.95s) +... +Build of product 'hello-world' complete! (5.51s) +... +[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42 +[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4 +[ContainerImageBuilder] Built application layer +[ContainerImageBuilder] Uploading application layer +[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists +[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists +[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists +registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df +``` + +### Run the image + +You can deploy your service in the cloud, or use a standards-compliant container runtime such as `podman` to run it locally: + +``` +% podman run -p 8080:8080 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df +Trying to pull registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df... +... +2024-05-26T22:57:50+0000 info HummingBird : [HummingbirdCore] Server started and listening on 0.0.0.0:8080 +``` + +Take a look at the [Examples](Examples). + +## Topics + +### Essentials +- +- +- + +### Building and running +- +- \ No newline at end of file diff --git a/Sources/swift-container-plugin/Documentation.docc/authentication.md b/Sources/swift-container-plugin/Documentation.docc/authentication.md new file mode 100644 index 0000000..0b01093 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/authentication.md @@ -0,0 +1,13 @@ +# Set up your registry credentials + +Configure Swift Container Plugin to authenticate to your container registry + +## Overview + +Many registries require authentication in order to push images, or even pull them. The plugin can read your registry credentials from a `.netrc` file in your home directory. You can add a netrc record for each registry you need to use, and the plugin will choose the correct one: + +``` +machine registry.example.com + login myuser + password mypassword +``` \ No newline at end of file diff --git a/Sources/swift-container-plugin/Documentation.docc/build.md b/Sources/swift-container-plugin/Documentation.docc/build.md new file mode 100644 index 0000000..41ad29b --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/build.md @@ -0,0 +1,42 @@ +# Build and package your service + +## Overview + +`build-container-image` is a command plugin which takes care of building your service, packaging it in a container image and uploading it to a container registry, all in one command: + +```shell +% swift package --swift-sdk x86_64-swift-linux-musl \ + build-container-image --from swift:slim --repository registry.example.com/myservice +``` + +* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable. In this case we are using the Static Linux SDK, which was installed earlier, to build an statically-linked x86_64 Linux binary +* The `--from` argument specifies the base image on which our service will run. `swift:slim` is the default, but you can choose your own base image or use `scratch` if your service does not require a base image at all. +* The `--repository` argument specifies where the plugin will upload our finished image. + +The plugin needs permission to connect to the network to publish the image to the registry: + +``` +Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. +Stated reason: “This command publishes images to container registries over the network”. +Allow this plugin to allow all network connections on all ports? (yes/no) +``` + +Type `yes` to continue. + +``` +Building for debugging... +Build of product 'containertool' complete! (4.95s) +... +Build of product 'hello-world' complete! (5.51s) +... +[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42 +[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4 +[ContainerImageBuilder] Built application layer +[ContainerImageBuilder] Uploading application layer +[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists +[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists +[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists +registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df +``` + +When it finishes, the plugin prints a reference identifying the new image. Any standard container runtime can use the reference to pull and run your service. diff --git a/Sources/swift-container-plugin/Documentation.docc/requirements.md b/Sources/swift-container-plugin/Documentation.docc/requirements.md new file mode 100644 index 0000000..fb57db3 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/requirements.md @@ -0,0 +1,41 @@ +# Install a toolchain for cross-compilation (macOS) + +The open source Swift toolchain and a compatible Swift SDK make it possible to build Linux executables on macOS + +* Swift Container Plugin runs on macOS and Linux and requires Swift 6.0 or later. +* 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. +* The Swift Static Linux SDK requires the [open source Swift toolchain](https://www.swift.org/install/macos/) to be installed. +* A container runtime is not required to build an image, but you will need one wherever you want to run the image. + +## Install the open source Swift toolchain + +Follow the instructions at [https://www.swift.org/install/macos/](https://www.swift.org/install/macos/) to install the open source Swift toolchain. The easiest way to do this is to use the [Swiftly swift toolchain installer](https://www.swift.org/install/macos/swiftly/). + +## Install a Swift SDK for cross-compilation + +If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) to cross-compile your server executable for Linux. Either: + +* Install the [Static Linux SDK from swift.org](https://www.swift.org/documentation/articles/static-linux-getting-started.html) +* Use [Swift SDK Generator](https://github.com/apple/swift-sdk-generator) to build and install a custom SDK + +Let's install the Swift Static Linux SDK: +``` +% swift sdk install https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz --checksum 111c6f7d280a651208b8c74c0521dd99365d785c1976a6e23162f55f65379ac6 +Downloading a Swift SDK bundle archive from `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz`... + Downloading +100% [=============================================================] +Downloading swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz + +Swift SDK bundle archive successfully downloaded from `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz`. +Verifying if checksum of the downloaded archive is valid... +Downloaded archive has a valid checksum. +Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz` is assumed to be an archive, unpacking... +Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz` successfully installed as swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle. +``` + +Check that the new Swift SDK is now available: + +```shell +% swift sdk list +swift-6.1-RELEASE_static-linux-0.0.1 +``` diff --git a/Sources/swift-container-plugin/Documentation.docc/run.md b/Sources/swift-container-plugin/Documentation.docc/run.md new file mode 100644 index 0000000..f1bc463 --- /dev/null +++ b/Sources/swift-container-plugin/Documentation.docc/run.md @@ -0,0 +1,20 @@ +# Run your service + +## Overview + +Swift Container Plugin builds standards-compliant container images which can run in public or private cloud infrastructure, or locally on a desktop container runtime. + +The following command uses `podman` to run the service locally, making it available on port 8080: + +``` +% podman run -p 8080:8080 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df +Trying to pull registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df... +... +2024-05-26T22:57:50+0000 info HummingBird : [HummingbirdCore] Server started and listening on 0.0.0.0:8080 +``` + +When the service has started, we can access it with a web browser or `curl`: +``` +% curl localhost:8080 +Hello World, from Hummingbird on Ubuntu 24.04.2 LTS +``` \ No newline at end of file diff --git a/Sources/swift-container-plugin/Empty.swift b/Sources/swift-container-plugin/Empty.swift new file mode 100644 index 0000000..0ee2a58 --- /dev/null +++ b/Sources/swift-container-plugin/Empty.swift @@ -0,0 +1,19 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftContainerPlugin open source project +// +// Copyright (c) 2024 Apple Inc. and the SwiftContainerPlugin project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftContainerPlugin project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +// This is an empty source file used to make SwiftContainerPluginDocumentation a valid +// documentation build target. + +// SwiftContainerPluginDocumentation is an otherwise empty target that includes high-level, +// user-facing documentation about using the Swift Container Plugin from the command-line. diff --git a/Sources/swift-container-plugin/README.md b/Sources/swift-container-plugin/README.md new file mode 100644 index 0000000..42af32f --- /dev/null +++ b/Sources/swift-container-plugin/README.md @@ -0,0 +1,6 @@ +# ContainerImageBuilder Plugin Documentation + +`ContainerImageBuilderPluginDocumentation` is an otherwise empty target that includes high-level, +user-facing documentation about using the ContainerImageBuilder plugin from the command-line. + + From 5240d8487b63e74d3afca1732e95d3fb58b1bd29 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Wed, 16 Apr 2025 17:03:20 +0100 Subject: [PATCH 02/17] docs: Remove dangling files after restructure --- .../ContainerImageBuilderPlugin.md | 122 ------------------ .../Documentation.docc/Info.plist | 20 --- .../Empty.swift | 19 --- .../README.md | 12 -- 4 files changed, 173 deletions(-) delete mode 100644 Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md delete mode 100644 Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist delete mode 100644 Sources/SwiftContainerPluginDocumentation/Empty.swift delete mode 100644 Sources/SwiftContainerPluginDocumentation/README.md diff --git a/Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md b/Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md deleted file mode 100644 index 9ccd602..0000000 --- a/Sources/SwiftContainerPluginDocumentation/Documentation.docc/ContainerImageBuilderPlugin.md +++ /dev/null @@ -1,122 +0,0 @@ -# ``ContainerImageBuilderPlugin`` - -Publish container images from Swift Package Manager. - -@Metadata { - @DisplayName("ContainerImageBuilder Plugin") -} - -## Overview - -> 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. - -The ContainerImageBuilder plugin is a Swift Package Manager command plugin which can publish a container image for any executable target defined in `Package.swift`. - -* `containertool` is a tool which packs any executable into a container image. -* `ContainerImageBuilder` is a Swift Package Manager command plugin which uses `containertool` to build a container image for any executable target in a single command. - -The plugin requires Swift 6.0 and runs on macOS and Linux. -The plugin does not require a container runtime to be installed locally in order to build an image. - -Try one of the [Examples](../../../Examples) - -### Install a Swift SDK for cross-compilation on macOS - -If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) to cross-compile your server executable for Linux. Either: - -* Install the [Static Linux SDK from swift.org](https://www.swift.org/documentation/articles/static-linux-getting-started.html) -* Use [Swift SDK Generator](https://github.com/apple/swift-sdk-generator) to build and install a custom SDK - -Check that the SDK is available. In this case we have installed the Swift Static Linux SDK: - -```shell -% swift sdk list -swift-6.0.1-RELEASE_static-linux-0.0.1 -``` - -> Note: To use the Static Linux SDK on macOS, you must [install the open source Swift toolchain from swift.org](https://www.swift.org/documentation/articles/static-linux-getting-started.html#installing-the-sdk) - -### Add the plugin to your project - -Swift Container Plugin is distributed as a Swift Package Manager package. Use the `swift package` command to add it to your project: - -```shell -swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.4.0 -``` - -Alternatively, append the following lines to `Package.swift`: - -```swift -package.dependencies += [ - .package(url: "https://github.com/apple/swift-container-plugin", from: "0.4.0"), -] -``` - -Check that `ContainerImageBuilder` is now available in Swift Package Manager: - -```shell -% swift package plugin --list -‘build-container-image’ (plugin ‘ContainerImageBuilder’ in package ‘swift-container-plugin) -``` - -### Add your registry credentials to .netrc - -Many registries require authentication in order to push images, or even pull them. The plugin can read your registry credentials from a `.netrc` file in your home directory. You can add a netrc record for each registry you need to use: - -``` -machine registry.example.com - login myuser - password mypassword -``` - -### Build and package your service - -`build-container-image` takes care of building your service, packaging it in a container image and uploading it to a container registry, all in one command: - -```shell -% swift package --swift-sdk x86_64-swift-linux-musl \ - build-container-image --from swift:slim --repository registry.example.com/myservice -``` - -* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable. In this case we are using the Static Linux SDK which was installed earlier. -* The `--from` argument specifies the base image on which our service will run. `swift:slim` is the default. -* The `--repository` argument specifies where ContainerImageBuilder will upload our finished image. - -The plugin needs permission to connect to the network to publish the image to the registry: - -``` -Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. -Stated reason: “This command publishes images to container registries over the network”. -Allow this plugin to allow all network connections on all ports? (yes/no) -``` - -Type `yes` to continue. - -``` -Building for debugging... -Build of product 'containertool' complete! (4.95s) -... -Build of product 'hello-world' complete! (5.51s) -... -[ContainerImageBuilder] Found base image manifest: sha256:7bd643386c6e65cbf52f6e2c480b7a76bce8102b562d33ad2aff7c81b7169a42 -[ContainerImageBuilder] Found base image configuration: sha256:b904a448fde1f8088913d7ad5121c59645b422e6f94c13d922107f027fb7a5b4 -[ContainerImageBuilder] Built application layer -[ContainerImageBuilder] Uploading application layer -[ContainerImageBuilder] Layer sha256:dafa2b0c44d2cfb0be6721f079092ddf15dc8bc537fb07fe7c3264c15cb2e8e6: already exists -[ContainerImageBuilder] Layer sha256:2565d8e736345fc7ba44f9b3900c5c20eda761eee01e01841ac7b494f9db5cf6: already exists -[ContainerImageBuilder] Layer sha256:2c179bb2e4fe6a3b8445fbeb0ce5351cf24817cb0b068c75a219b12434c54a58: already exists -registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df -``` - -When it finishes, ContainerImageBuilder prints a reference identifying the new image. Any standard container runtime can use the reference to pull and run your service. - -### Run your service - -For example, you could use `podman` to run the service locally, making it available on port 8080: - -``` -% podman run -p 8080:8080 registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df -Trying to pull registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df... -... -2024-05-26T22:57:50+0000 info HummingBird : [HummingbirdCore] Server started and listening on 0.0.0.0:8080 -``` diff --git a/Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist b/Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist deleted file mode 100644 index 1798fc3..0000000 --- a/Sources/SwiftContainerPluginDocumentation/Documentation.docc/Info.plist +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - CDDefaultCodeListingLanguage - shell - CDDefaultModuleKind - Command Plugin - - - diff --git a/Sources/SwiftContainerPluginDocumentation/Empty.swift b/Sources/SwiftContainerPluginDocumentation/Empty.swift deleted file mode 100644 index 8d872ef..0000000 --- a/Sources/SwiftContainerPluginDocumentation/Empty.swift +++ /dev/null @@ -1,19 +0,0 @@ -//===----------------------------------------------------------------------===// -// -// This source file is part of the SwiftContainerPlugin open source project -// -// Copyright (c) 2024 Apple Inc. and the SwiftContainerPlugin project authors -// Licensed under Apache License v2.0 -// -// See LICENSE.txt for license information -// See CONTRIBUTORS.txt for the list of SwiftContainerPlugin project authors -// -// SPDX-License-Identifier: Apache-2.0 -// -//===----------------------------------------------------------------------===// - -// This is an empty source file used to make ContainerImageBuilderPluginDocumentation a valid -// documentation build target. - -// ContainerImageBuilderPluginDocumentation is an otherwise empty target that includes high-level, -// user-facing documentation about using the ContainerImageBuilder Plugin from the command-line. diff --git a/Sources/SwiftContainerPluginDocumentation/README.md b/Sources/SwiftContainerPluginDocumentation/README.md deleted file mode 100644 index 204a434..0000000 --- a/Sources/SwiftContainerPluginDocumentation/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# ContainerImageBuilder Plugin Documentation - -`ContainerImageBuilderPluginDocumentation` is an otherwise empty target that includes high-level, -user-facing documentation about using the ContainerImageBuilder plugin from the command-line. - -To preview the documentation, run the following command: - -```bash -swift package --disable-sandbox preview-documentation --target ContainerImageBuilderPlugin -``` - - From 8a91eb0fccbbe46d0f959ad51bced50543261dd6 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Wed, 16 Apr 2025 17:04:59 +0100 Subject: [PATCH 03/17] docs: Add the docc-generator preview command to README.md --- Sources/swift-container-plugin/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Sources/swift-container-plugin/README.md b/Sources/swift-container-plugin/README.md index 42af32f..1e9fa3a 100644 --- a/Sources/swift-container-plugin/README.md +++ b/Sources/swift-container-plugin/README.md @@ -3,4 +3,10 @@ `ContainerImageBuilderPluginDocumentation` is an otherwise empty target that includes high-level, user-facing documentation about using the ContainerImageBuilder plugin from the command-line. +To preview the documentation, run the following command: + +```bash +swift package --disable-sandbox preview-documentation --target swift-container-plugin +``` + From 48aaaebe78703e4c406ee85eb0d4df65121e3e05 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Wed, 16 Apr 2025 17:40:48 +0100 Subject: [PATCH 04/17] docs: Address CI docs checker warnings about heading levels --- .../Adding-the-plugin-to-your-project.md | 8 +++++--- .../Documentation.docc/Platforms-and-requirements.md | 5 ----- .../Documentation.docc/requirements.md | 6 ++++-- 3 files changed, 9 insertions(+), 10 deletions(-) delete mode 100644 Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md diff --git a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md index 7277c15..35625af 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md +++ b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md @@ -2,9 +2,11 @@ Make Swift Container Plugin available in your project +## Overview + 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. -## Install the plugin using the `swift package` CLI +### Install the plugin using the `swift package` CLI Recent versions of `swift package` suupport the `add-dependency` command: @@ -12,7 +14,7 @@ Recent versions of `swift package` suupport the `add-dependency` command: swift package add-dependency https://github.com/apple/swift-container-plugin --from 0.5.0 ``` -## Install the plugin by manually editing `Package.swift` +### Install the plugin by manually editing `Package.swift` If you cannot use the `swift package add-dependency` comand, append the following lines to your project's `Package.swift` file: @@ -22,7 +24,7 @@ package.dependencies += [ ] ``` -## Check that the plugin is available +### Check that the plugin is available After installation, Swift Package Manager should show that the `ContainerImageBuilder` is now available: diff --git a/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md b/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md deleted file mode 100644 index ee84260..0000000 --- a/Sources/swift-container-plugin/Documentation.docc/Platforms-and-requirements.md +++ /dev/null @@ -1,5 +0,0 @@ -# Installing dependencies - -* Swift Container Plugin runs on macOS and Linux and requires Swift 6.0 or later. -* 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. -* A container runtime is not required to build an image, but one must be available wherever the image is to be run. diff --git a/Sources/swift-container-plugin/Documentation.docc/requirements.md b/Sources/swift-container-plugin/Documentation.docc/requirements.md index fb57db3..3a7fcb3 100644 --- a/Sources/swift-container-plugin/Documentation.docc/requirements.md +++ b/Sources/swift-container-plugin/Documentation.docc/requirements.md @@ -2,16 +2,18 @@ The open source Swift toolchain and a compatible Swift SDK make it possible to build Linux executables on macOS +## Overview + * Swift Container Plugin runs on macOS and Linux and requires Swift 6.0 or later. * 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. * The Swift Static Linux SDK requires the [open source Swift toolchain](https://www.swift.org/install/macos/) to be installed. * A container runtime is not required to build an image, but you will need one wherever you want to run the image. -## Install the open source Swift toolchain +### Install the open source Swift toolchain Follow the instructions at [https://www.swift.org/install/macos/](https://www.swift.org/install/macos/) to install the open source Swift toolchain. The easiest way to do this is to use the [Swiftly swift toolchain installer](https://www.swift.org/install/macos/swiftly/). -## Install a Swift SDK for cross-compilation +### Install a Swift SDK for cross-compilation If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) to cross-compile your server executable for Linux. Either: From bf67ac999226d6d334f96e77a2c963168f3da315 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 11:50:21 +0100 Subject: [PATCH 05/17] Apply suggestions from code review Co-authored-by: Joseph Heck --- .../Documentation.docc/Swift-Container-Plugin.md | 6 +++++- .../Documentation.docc/authentication.md | 8 ++++++-- .../swift-container-plugin/Documentation.docc/build.md | 9 +++++---- .../Documentation.docc/requirements.md | 8 ++++---- 4 files changed, 20 insertions(+), 11 deletions(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md index cdd2a13..a54102f 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md +++ b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md @@ -19,8 +19,12 @@ Find out more and see it in action: ## Usage -Swift Container Plugin can package any executable product defined in `Package.swift` in a container image and publish it to a container registry. +Use the Swift Container Plugin to package an executable product from your Swift package into a container image and publish it to a container registry. +To use the plugin: +- +- +- ### Build and publish a container image After adding the plugin to your project, you can build and publish a container image in one step: diff --git a/Sources/swift-container-plugin/Documentation.docc/authentication.md b/Sources/swift-container-plugin/Documentation.docc/authentication.md index 0b01093..5e1c55e 100644 --- a/Sources/swift-container-plugin/Documentation.docc/authentication.md +++ b/Sources/swift-container-plugin/Documentation.docc/authentication.md @@ -1,10 +1,14 @@ # Set up your registry credentials -Configure Swift Container Plugin to authenticate to your container registry +Configure the plugin to authenticate to your container registry. ## Overview -Many registries require authentication in order to push images, or even pull them. The plugin can read your registry credentials from a `.netrc` file in your home directory. You can add a netrc record for each registry you need to use, and the plugin will choose the correct one: +Many container registries require authentication in order to push images, or even pull them. +The plugin reads your registry credentials from a `.netrc` file in your home directory. +Add a record into the `.netrc` file for each registry you use, the plugin uses the authentication by the registry you choose. + +The following example shows placeholder values for the registry `registry.example.com`: ``` machine registry.example.com diff --git a/Sources/swift-container-plugin/Documentation.docc/build.md b/Sources/swift-container-plugin/Documentation.docc/build.md index 41ad29b..ba00af9 100644 --- a/Sources/swift-container-plugin/Documentation.docc/build.md +++ b/Sources/swift-container-plugin/Documentation.docc/build.md @@ -2,18 +2,18 @@ ## Overview -`build-container-image` is a command plugin which takes care of building your service, packaging it in a container image and uploading it to a container registry, all in one command: +The plugin exposes the command `build-container-image` which you invoke to build your service, package it in a container image and upload it to a container registry, in a single command: ```shell % swift package --swift-sdk x86_64-swift-linux-musl \ build-container-image --from swift:slim --repository registry.example.com/myservice ``` -* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable. In this case we are using the Static Linux SDK, which was installed earlier, to build an statically-linked x86_64 Linux binary +* The `--swift-sdk` argument specifies the Swift SDK with which to build the executable. In this case we are using the Static Linux SDK, installed earlier, to build an statically-linked x86_64 Linux binary. * The `--from` argument specifies the base image on which our service will run. `swift:slim` is the default, but you can choose your own base image or use `scratch` if your service does not require a base image at all. * The `--repository` argument specifies where the plugin will upload our finished image. -The plugin needs permission to connect to the network to publish the image to the registry: +> Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry. ``` Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. @@ -39,4 +39,5 @@ Build of product 'hello-world' complete! (5.51s) registry.example.com/myservice@sha256:a3f75d0932d052dd9d448a1c9040b16f9f2c2ed9190317147dee95a218faf1df ``` -When it finishes, the plugin prints a reference identifying the new image. Any standard container runtime can use the reference to pull and run your service. +When the plugin finishes, it prints a reference identifying the new image. +Any standard container runtime can use the reference to pull and run your service. diff --git a/Sources/swift-container-plugin/Documentation.docc/requirements.md b/Sources/swift-container-plugin/Documentation.docc/requirements.md index 3a7fcb3..a776768 100644 --- a/Sources/swift-container-plugin/Documentation.docc/requirements.md +++ b/Sources/swift-container-plugin/Documentation.docc/requirements.md @@ -1,6 +1,6 @@ -# Install a toolchain for cross-compilation (macOS) +# Install a toolchain for cross-compilation -The open source Swift toolchain and a compatible Swift SDK make it possible to build Linux executables on macOS +Install an open source Swift toolchain and a compatible Swift SDK to build Linux executables on macOS. ## Overview @@ -20,7 +20,7 @@ If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/ * Install the [Static Linux SDK from swift.org](https://www.swift.org/documentation/articles/static-linux-getting-started.html) * Use [Swift SDK Generator](https://github.com/apple/swift-sdk-generator) to build and install a custom SDK -Let's install the Swift Static Linux SDK: +The following example illustrates installing the Swift Static Linux SDK: ``` % swift sdk install https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz --checksum 111c6f7d280a651208b8c74c0521dd99365d785c1976a6e23162f55f65379ac6 Downloading a Swift SDK bundle archive from `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz`... @@ -35,7 +35,7 @@ Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swi Swift SDK bundle at `https://download.swift.org/swift-6.1-release/static-sdk/swift-6.1-RELEASE/swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle.tar.gz` successfully installed as swift-6.1-RELEASE_static-linux-0.0.1.artifactbundle. ``` -Check that the new Swift SDK is now available: +After the installation is complete, check that the SDK is available: ```shell % swift sdk list From 20ebe14c55e262eafaafa61c62c6cd9cd57cee56 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:42:18 +0100 Subject: [PATCH 06/17] Link the main page example to the HelloWorldHummingbird project Co-authored-by: Joseph Heck --- .../Documentation.docc/Swift-Container-Plugin.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md index a54102f..a5cde75 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md +++ b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md @@ -27,7 +27,8 @@ To use the plugin: - ### Build and publish a container image -After adding the plugin to your project, you can build and publish a container image in one step: +After adding the plugin to your project, you can build and publish a container image in one step. +Here is how to build the [HelloWorld example](https://github.com/apple/swift-container-plugin/tree/main/Examples/HelloWorldHummingbird) as a static binary for Linux running the `x86_64` architecture: ``` % swift package --swift-sdk x86_64-swift-linux-musl \ From d891a52d876f7e32f97c9094be1d33ce2c8577ba Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:43:09 +0100 Subject: [PATCH 07/17] Re-word the explanation of the --repository argument Co-authored-by: Joseph Heck --- Sources/swift-container-plugin/Documentation.docc/build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/build.md b/Sources/swift-container-plugin/Documentation.docc/build.md index ba00af9..6bb7512 100644 --- a/Sources/swift-container-plugin/Documentation.docc/build.md +++ b/Sources/swift-container-plugin/Documentation.docc/build.md @@ -11,7 +11,7 @@ The plugin exposes the command `build-container-image` which you invoke to build * The `--swift-sdk` argument specifies the Swift SDK with which to build the executable. In this case we are using the Static Linux SDK, installed earlier, to build an statically-linked x86_64 Linux binary. * The `--from` argument specifies the base image on which our service will run. `swift:slim` is the default, but you can choose your own base image or use `scratch` if your service does not require a base image at all. -* The `--repository` argument specifies where the plugin will upload our finished image. +* The `--repository` argument specifies the repository to which the plugin will upload the finished image. > Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry. From 8ee74f28fa15ed78d7b09690ed5ec8c504295ab9 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:44:11 +0100 Subject: [PATCH 08/17] Add an abstract to the "Run your service" page Co-authored-by: Joseph Heck --- Sources/swift-container-plugin/Documentation.docc/run.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Sources/swift-container-plugin/Documentation.docc/run.md b/Sources/swift-container-plugin/Documentation.docc/run.md index f1bc463..640e424 100644 --- a/Sources/swift-container-plugin/Documentation.docc/run.md +++ b/Sources/swift-container-plugin/Documentation.docc/run.md @@ -1,5 +1,6 @@ # Run your service +Run the container you built on cloud infrastructure or locally on a desktop container runtime. ## Overview Swift Container Plugin builds standards-compliant container images which can run in public or private cloud infrastructure, or locally on a desktop container runtime. From b6c1b4010be55f519c6d106b784fc3116433f325 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Wed, 16 Apr 2025 17:43:59 +0100 Subject: [PATCH 09/17] docs: Remove commented-out path for swift-container-plugin docs target --- Package.swift | 1 - 1 file changed, 1 deletion(-) diff --git a/Package.swift b/Package.swift index 4527f73..c08d0da 100644 --- a/Package.swift +++ b/Package.swift @@ -83,7 +83,6 @@ let package = Package( // the ContainerImageBuilder plugin from the command-line. .target( name: "swift-container-plugin", - //path: "Sources/SwiftContainerPluginDocumentation", exclude: ["README.md"] ), .testTarget( From 00d85f25e884035ceb50e94bb4f471bcfe49a2e9 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:54:08 +0100 Subject: [PATCH 10/17] docs: Add abstract for image build page --- .../Documentation.docc/Adding-the-plugin-to-your-project.md | 2 +- Sources/swift-container-plugin/Documentation.docc/build.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md index 35625af..a887c1c 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md +++ b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md @@ -1,6 +1,6 @@ # Add the plugin to your project -Make Swift Container Plugin available in your project +Make Swift Container Plugin available in your project. ## Overview diff --git a/Sources/swift-container-plugin/Documentation.docc/build.md b/Sources/swift-container-plugin/Documentation.docc/build.md index 6bb7512..98e5de7 100644 --- a/Sources/swift-container-plugin/Documentation.docc/build.md +++ b/Sources/swift-container-plugin/Documentation.docc/build.md @@ -1,5 +1,7 @@ # Build and package your service +Build a container image and upload it to a registry. + ## Overview The plugin exposes the command `build-container-image` which you invoke to build your service, package it in a container image and upload it to a container registry, in a single command: From af35361ad47e4f0c27672bc3172a5d07e9a31245 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:56:45 +0100 Subject: [PATCH 11/17] docs: Add flag to show notes and usage hints when previewing documentation --- Sources/swift-container-plugin/Empty.swift | 4 ++++ Sources/swift-container-plugin/README.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/Sources/swift-container-plugin/Empty.swift b/Sources/swift-container-plugin/Empty.swift index 0ee2a58..d071bc6 100644 --- a/Sources/swift-container-plugin/Empty.swift +++ b/Sources/swift-container-plugin/Empty.swift @@ -17,3 +17,7 @@ // SwiftContainerPluginDocumentation is an otherwise empty target that includes high-level, // user-facing documentation about using the Swift Container Plugin from the command-line. + +// To preview the documentation, run the following command: +// +// swift package --disable-sandbox preview-documentation --target swift-container-plugin --analyze diff --git a/Sources/swift-container-plugin/README.md b/Sources/swift-container-plugin/README.md index 1e9fa3a..399422c 100644 --- a/Sources/swift-container-plugin/README.md +++ b/Sources/swift-container-plugin/README.md @@ -6,7 +6,7 @@ user-facing documentation about using the ContainerImageBuilder plugin from the To preview the documentation, run the following command: ```bash -swift package --disable-sandbox preview-documentation --target swift-container-plugin +swift package --disable-sandbox preview-documentation --target swift-container-plugin --analyze ``` From 17654372e869f3bf9e10d8dd84bd2657ec9e96b3 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 12:57:19 +0100 Subject: [PATCH 12/17] docs: Use correct indentation level for section headings --- .../swift-container-plugin/Documentation.docc/requirements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/requirements.md b/Sources/swift-container-plugin/Documentation.docc/requirements.md index a776768..71e4291 100644 --- a/Sources/swift-container-plugin/Documentation.docc/requirements.md +++ b/Sources/swift-container-plugin/Documentation.docc/requirements.md @@ -9,11 +9,11 @@ Install an open source Swift toolchain and a compatible Swift SDK to build Linux * The Swift Static Linux SDK requires the [open source Swift toolchain](https://www.swift.org/install/macos/) to be installed. * A container runtime is not required to build an image, but you will need one wherever you want to run the image. -### Install the open source Swift toolchain +### Install an open source Swift toolchain Follow the instructions at [https://www.swift.org/install/macos/](https://www.swift.org/install/macos/) to install the open source Swift toolchain. The easiest way to do this is to use the [Swiftly swift toolchain installer](https://www.swift.org/install/macos/swiftly/). -### Install a Swift SDK for cross-compilation +### Install a Swift SDK for cross-compilation which matches the open source toolchain If you are running on macOS, you can use a [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md) to cross-compile your server executable for Linux. Either: From be4400188fc3b43aec4e946e447f42e96920511a Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 13:14:35 +0100 Subject: [PATCH 13/17] docs: Update ServerSide.Swift 2024 links --- README.md | 2 +- .../Documentation.docc/Swift-Container-Plugin.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1605ff9..5c42bb8 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Swift Container Plugin makes it easy to build container images for servers writt Find out more and see it in action: * [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/). -* [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/). +* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/2024/speakers/euan-harris/). ## Usage diff --git a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md index a5cde75..8d99468 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md +++ b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md @@ -15,7 +15,7 @@ Swift Container Plugin makes it easy to build container images for servers writt Find out more and see it in action: * [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/). -* [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/). +* [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/2024/speakers/euan-harris/). ## Usage @@ -75,4 +75,4 @@ Take a look at the [Examples](Examples). ### Building and running - -- \ No newline at end of file +- From 7ac78a89be3a2554ebab2a061920fbf847213727 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 13:16:48 +0100 Subject: [PATCH 14/17] docs: Fix heading indentation in top level page --- .../Documentation.docc/Swift-Container-Plugin.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md index 8d99468..a7bc6a7 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md +++ b/Sources/swift-container-plugin/Documentation.docc/Swift-Container-Plugin.md @@ -17,7 +17,7 @@ Find out more and see it in action: * [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/). * [Swift to the cloud in a single step](https://www.youtube.com/watch?v=9AaINsCfZzw) at [ServerSide.Swift 2024](https://www.serversideswift.info/2024/speakers/euan-harris/). -## Usage +### Usage Use the Swift Container Plugin to package an executable product from your Swift package into a container image and publish it to a container registry. @@ -25,6 +25,7 @@ To use the plugin: - - - + ### Build and publish a container image After adding the plugin to your project, you can build and publish a container image in one step. From 2127832af5b080b2206b89a05c37921dafb4f56a Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 13:21:10 +0100 Subject: [PATCH 15/17] docs: Move whole network permission section into a note --- .../Documentation.docc/build.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Sources/swift-container-plugin/Documentation.docc/build.md b/Sources/swift-container-plugin/Documentation.docc/build.md index 98e5de7..3714c8e 100644 --- a/Sources/swift-container-plugin/Documentation.docc/build.md +++ b/Sources/swift-container-plugin/Documentation.docc/build.md @@ -16,14 +16,14 @@ The plugin exposes the command `build-container-image` which you invoke to build * The `--repository` argument specifies the repository to which the plugin will upload the finished image. > Note: on macOS, the plugin needs permission to connect to the network to publish the image to the registry. - -``` -Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. -Stated reason: “This command publishes images to container registries over the network”. -Allow this plugin to allow all network connections on all ports? (yes/no) -``` - -Type `yes` to continue. +> +> ``` +> Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports. +> Stated reason: “This command publishes images to container registries over the network”. +> Allow this plugin to allow all network connections on all ports? (yes/no) +> ``` +> +> Type `yes` to continue. ``` Building for debugging... From 6d19d2a4237b3de0864e6f79d797a5601fd631b8 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 13:27:42 +0100 Subject: [PATCH 16/17] docs: Add missing containertool arguments --- Sources/containertool/Documentation.docc/containertool.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Sources/containertool/Documentation.docc/containertool.md b/Sources/containertool/Documentation.docc/containertool.md index e0d80b3..b6a39f0 100644 --- a/Sources/containertool/Documentation.docc/containertool.md +++ b/Sources/containertool/Documentation.docc/containertool.md @@ -8,7 +8,7 @@ Wrap a binary in a container image and publish it. > Note: A container image is the standard way to package cloud software. Once you have wrapped your server in a container image, you can deploy it on any public or private cloud service based on [Kubernetes](https://kubernetes.io), or run it locally using a desktop container runtime. -## Usage +### Usage `containertool` can be run directly but its main role is to be a helper tool used by the `ContainerImageBuilder` command plugin. See the plugin documentation for examples of how to use it in this way. @@ -23,6 +23,7 @@ ARGUMENTS: OPTIONS: --repository Repository path + --resources Resource bundle directory --username Username --password Password -v, --verbose Verbose output @@ -33,5 +34,10 @@ OPTIONS: --from Base image reference --os Operating system (default: linux) --tag Tag for this manifest + --enable-netrc/--disable-netrc + Load credentials from a netrc file (default: + --enable-netrc) + --netrc-file + Specify the netrc file path -h, --help Show help information. ``` From ddb815f76cbe38725710e4088f89588bedbd7af7 Mon Sep 17 00:00:00 2001 From: Euan Harris Date: Thu, 17 Apr 2025 17:30:10 +0100 Subject: [PATCH 17/17] docs: Add note about duplicate dependencies --- .../Documentation.docc/Adding-the-plugin-to-your-project.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md index a887c1c..b58fc33 100644 --- a/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md +++ b/Sources/swift-container-plugin/Documentation.docc/Adding-the-plugin-to-your-project.md @@ -8,6 +8,9 @@ Swift Container Plugin is distributed as a Swift Package Manager package. To ### Install the plugin using the `swift package` CLI +> Adding the same dependency to your project more than once will prevent it from building. +> If this happens, delete the duplicate dependency lines from `Package.swift` and rebuild. + Recent versions of `swift package` suupport the `add-dependency` command: ```shell