Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
48 changes: 3 additions & 45 deletions Plugins/Documentation.docc/Proposals/0001-v2-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,14 @@ This document describes a proposal for the v2 plugins for `swift-aws-lambda-runt
Versions:

* v1 (2024-12-25): Initial version
* v2 (2025-03-13):
* v2 (2025-03-13):
- Include [comments from the community](https://forums.swift.org/t/lambda-plugins-for-v2/76859).
- [init] Add the templates for `main.swift`
- [build] Add the section **Cross-compiling options**
- [deploy] Add details about locating AWS Credentials.
- [deploy] Add `--input-path` parameter.
- [deploy] Add details how the function name is computed.
- [deploy] Add `--architecture` option and details how the default is computed.
* v3 (2026-02-17):
- [build] Add `--container-cli` option to support Apple's `container` CLI as an alternative to Docker (addresses [#644](https://github.com/awslabs/swift-aws-lambda-runtime/issues/644)).
- [build] Add the section **Container CLI options**

## Motivation

Expand Down Expand Up @@ -67,7 +64,7 @@ The plugin cannot be invoked without the required dependency on `swift-aws-lambd
swift package init --type executable --name MyLambda

# Step 2: Add the Swift AWS Lambda Runtime dependency
swift package add-dependency https://github.com/awslabs/swift-aws-lambda-runtime.git --branch main
swift package add-dependency https://github.com/swift-server/swift-aws-lambda-runtime.git --branch main
swift package add-target-dependency AWSLambdaRuntime MyLambda --package swift-aws-lambda-runtime

# Step 3: Call the lambda-init plugin
Expand Down Expand Up @@ -163,8 +160,7 @@ The plugin interface is based on the existing `archive` plugin, with the additio
```text
OVERVIEW: A SwiftPM plugin to build and package your Lambda function.

REQUIREMENTS: To use this plugin, Docker or Apple container must be installed and running
(when using docker or container cross-compilation methods).
REQUIREMENTS: To use this plugin, Docker must be installed and running.

USAGE: swift package archive
[--help] [--verbose]
Expand All @@ -176,7 +172,6 @@ USAGE: swift package archive
[--disable-docker-image-update]
[--no-strip]
[--cross-compile <value>]
[--container-cli <value>]
[--allow-network-connections docker]

OPTIONS:
Expand All @@ -197,9 +192,6 @@ OPTIONS:
--no-strip Do not strip the binary of debug symbols.
--cross-compile <value> Cross-compile the binary using the specified method.
(default: docker) Accepted values are: docker, swift-static-sdk, custom-sdk
--container-cli <value> Specify the container CLI to use for Docker-based builds.
(default: docker) Accepted values are: docker, container
This parameter is only used when --cross-compile is set to docker.
```

#### Cross compiling options
Expand All @@ -213,40 +205,6 @@ For an ideal developer experience, we would imagine the following sequence:
- if not installed or outdated, the plugin downloads a custom SDK from a safe source and installs it [questions : who should maintain such SDK binaries? Where to host them? We must have a kind of signature to ensure the SDK has not been modified. How to manage Swift version and align with the local toolchain?]
- the plugin build the archive using the custom sdk

#### Container CLI options

The plugin supports using different container CLIs to build Lambda packages. By default, it uses Docker, but it can also use Apple's `container` CLI on macOS, which provides native support for OCI (Open Container Initiative) images.

**Supported Container CLIs:**

- **Docker** (default): Uses the standard Docker CLI
- Pull images: `docker pull <image>`
- Run containers: `docker run --rm -v <volume> -w <workdir> <image> bash -cl "<cmd>"`

- **Apple container**: Uses Apple's native container CLI (available on macOS)
- Pull images: `container image pull <image>`
- Run containers: `container run --rm -v <volume> -w <workdir> <image> bash -cl "<cmd>"`

**Configuration:**

The container CLI can be specified via the command-line flag: `--container-cli docker` or `--container-cli container`. If not specified, the plugin defaults to `docker`.

**Example usage:**

```bash
# Use Docker (default)
swift package lambda-build

# Use Apple container
swift package lambda-build --container-cli container
```

**Requirements:**

- When using `docker`, Docker Desktop or Docker Engine must be installed and running
- When using `container`, Apple's container CLI must be installed and running
- The `--container-cli` option is only applicable when using Docker-based cross-compilation (`--cross-compile docker`)

### Deploy (lambda-deploy)

The `lambda-deploy` plugin will assist developers in deploying their Lambda function to AWS. It will handle the deployment process, including creating the IAM role, the Lambda function itself, and optionally configuring a Lambda function URL.
Expand Down
Loading