-
Notifications
You must be signed in to change notification settings - Fork 78
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Delete duplicate content, add new sections. * Add module description * Add block quote for runtime module link * Remove codgen module info --------- Co-authored-by: Sichan Yoo <[email protected]>
- Loading branch information
Showing
1 changed file
with
35 additions
and
145 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,158 +1,48 @@ | ||
| # AWS SDK for Swift | ||
|
|
||
| The **AWS SDK for Swift** is a pure Swift SDK for accessing any & all AWS services. | ||
|
|
||
| ## License | ||
|
|
||
| This library is licensed under the Apache 2.0 License. | ||
| # <img alt="aws_logo.png" src="https://avatars.githubusercontent.com/u/3299148?s=200&v=4" width="28"> AWS SDK for Swift | ||
|
|
||
| [![License][apache-badge]][apache-url] | ||
|
|
||
| [apache-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg | ||
| [apache-url]: LICENSE | ||
|
|
||
| ## Requirements | ||
| ## Getting Started | ||
|
|
||
| - [SDK Product Page](https://aws.amazon.com/sdk-for-swift/) | ||
| - [Developer Guide](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/home.html) | ||
| - [API Reference](https://sdk.amazonaws.com/swift/api/awssdkforswift/latest/documentation/awssdkforswift) | ||
| - [Code Examples Repo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) | ||
|
|
||
| To get started using the SDK, follow the setup instructions at [Set up the AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/setting-up.html), then check out our step-by-step tutorial at [Get started with the AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/getting-started.html). | ||
|
|
||
| ## Feedback | ||
|
|
||
| The AWS SDK for Swift supports the following: | ||
| - Swift 5.9 or higher | ||
| - iOS & iPadOS 13.0 or higher | ||
| - macOS 10.15 or higher | ||
| - Ubuntu Linux 16.04 LTS or higher | ||
| - Amazon Linux 2 or higher | ||
| If you'd like to provide feedback, report a bug, request a feature, or would like to bring | ||
| attention to an issue in general, please do so by submitting a GitHub issue to the repo [here](https://github.com/awslabs/aws-sdk-swift/issues/new/choose). | ||
|
|
||
| Other environments (watchOS, tvOS, Windows, or others) may work but have not been verified. | ||
| This is the preferred mechanism for user feedback as it allows anyone with similar issue or suggestion to engage in conversation as well. | ||
|
|
||
| These supported versions may change in the future. | ||
| ## Contributing | ||
|
|
||
| ## Provide Credentials | ||
| If you are interested in contributing to AWS SDK for Swift, see [CONTRIBUTING](CONTRIBUTING.md) for more information. | ||
|
|
||
| ## Development | ||
|
|
||
| ### Runtime Modules (under `Sources/Core/`) | ||
|
|
||
| * `AWSClientRuntime` - concrete types, protocols, enums, etc. that provide most AWS specific runtime functionalities for the SDK. | ||
| Has several other runtime modules as its dependencies. | ||
| * `AWSSDKChecksums` - implementation for handling checksum in AWS requests | ||
| * `AWSSDKCommon` - concrete types used by other runtime modules | ||
| * `AWSSDKEventStreamsAuth` - concrete types for signing AWS event stream message | ||
| * `AWSSDKHTTPAuth` - concrete types for AWS SigV4 signer, and types related to auth flow | ||
| * `AWSSDKIdentity` - concrete types for AWS credentials and identity resolvers | ||
|
|
||
| > 📖 For more information on runtime modules, see [the AWS Runtime Module Documentation in API reference](https://sdk.amazonaws.com/swift/api/awssdkforswift/latest/documentation/awssdkforswift#AWS-Runtime-Module-Documentation) | ||
| ## License | ||
|
|
||
| For virtually all AWS operations, you must provide AWS security credentials for the SDK to use. | ||
| This library is licensed under the Apache 2.0 License. | ||
|
|
||
| You can accomplish this for local development by installing and configuring the | ||
| [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) | ||
| on your development machine. The AWS SDK for Swift will share the AWS CLI's credentials (written at | ||
| `~/.aws/credentials`) when executing on your development machine. | ||
| ## Security | ||
|
|
||
| See your AWS account administrator to obtain your credentials if you do not already have them. | ||
|
|
||
| ## Test the AWS SDK for Swift with your credentials | ||
|
|
||
| Here, we'll be creating a simple Swift package to show you how the SDK is used, and verify that the SDK can use your | ||
| credentials to access a live AWS service. | ||
|
|
||
| You can perform this on either Mac or Linux on any supported OS version, but must have a supported version of either | ||
| Xcode (for Mac) or the Swift toolchain (for Linux) installed. | ||
|
|
||
| Be sure you've set up AWS credentials on your development machine, per the section above. | ||
|
|
||
| 1. On your command line, create a new, executable Swift package: | ||
| ``` | ||
| $ mkdir AWSCredentialTester | ||
| $ cd AWSCredentialTester | ||
| $ swift package init --type executable | ||
| ``` | ||
|
|
||
| 2. Edit your new package's `Package.swift` file to read: | ||
| ``` | ||
| // swift-tools-version: 5.9 | ||
| import PackageDescription | ||
| let package = Package( | ||
| name: "AWSCredentialTester", | ||
| platforms: [.macOS(.v10_15), .iOS(.v13)], | ||
| dependencies: [ | ||
| .package(url: "https://github.com/awslabs/aws-sdk-swift.git", from: "0.16.0") | ||
| ], | ||
| targets: [ | ||
| .executableTarget( | ||
| name: "AWSCredentialTester", | ||
| dependencies: [ | ||
| .product(name: "AWSSTS", package: "aws-sdk-swift") | ||
| ], | ||
| path: "Sources" | ||
| ) | ||
| ] | ||
| ) | ||
| ``` | ||
|
|
||
| 3. Edit your project's `Sources/main.swift` file to read: | ||
| ``` | ||
| import AWSSTS | ||
| let client = try STSClient(region: "us-east-1") | ||
| let input = GetCallerIdentityInput() | ||
| let output = try await client.getCallerIdentity(input: input) | ||
| let userID = output.userId ?? "not known" | ||
| print("Caller's AWS user ID is \(userID)") | ||
| ``` | ||
|
|
||
| 4. Execute your Swift package from the command line: | ||
| ``` | ||
| $ swift run | ||
| ``` | ||
| Your package will resolve dependencies, compile, and run. | ||
|
|
||
| In the terminal output, you will see (after a number of log statements): | ||
| ``` | ||
| Caller's AWS user ID is <an alphanumeric string> | ||
| ``` | ||
| (this user ID should match your AWS Access Key ID for your AWS credentials.) | ||
|
|
||
| If you’ve made it this far... congratulations! 🎉 | ||
|
|
||
| ## Integrating Into an Existing Xcode Project or Package | ||
|
|
||
| Now that you've tested the SDK and your credentials in a simple project, here are steps to quickly get the AWS SDK for | ||
| Swift installed into either your existing Xcode project or Swift package. | ||
|
|
||
| ### Installing the AWS SDK for Swift into your Xcode Project | ||
|
|
||
| 1. Open your project in the Xcode IDE. From the drop down menu, select File > Add Packages... | ||
|
|
||
| 2. In the field labeled "Search or Enter Package URL", enter "https://github.com/awslabs/aws-sdk-swift". Set the | ||
| dependency rule and project as needed, then click "Add Package". The package will download and install to your Xcode | ||
| project. | ||
|
|
||
| 3. In the "Choose Package Products for aws-sdk-swift" popup window, check the box next to the specific AWS services you | ||
| want to access, and set the Xcode target next to each service. Click "Add Package". | ||
|
|
||
| ### Installing the AWS SDK for Swift into your Swift Package | ||
|
|
||
| 1. In your package's `Package.swift`, add AWS SDK for Swift as a package dependency: | ||
| ``` | ||
| let package = Package( | ||
| name: "MyPackage", | ||
| dependencies: [ | ||
| + .package(url: "https://github.com/awslabs/aws-sdk-swift", from: "0.16.0") | ||
| ], | ||
| ``` | ||
|
|
||
| 2. Add the specific AWS services you plan to use into the `dependencies` of one of the targets in your package's | ||
| `Package.swift`. To finish this example, you will need to add at least `AWS Secure Token Service (STS)` : | ||
| ``` | ||
| targets: [ | ||
| .target( | ||
| name: "MyTarget", | ||
| dependencies: [ | ||
| + .product(name: "AWSS3", package: "aws-sdk-swift"), | ||
| + .product(name: "AWSSTS", package: "aws-sdk-swift"), | ||
| + .product(name: "AWSTranscribe", package: "aws-sdk-swift") | ||
| ] | ||
| ) | ||
| ] | ||
| ``` | ||
| See the AWS SDK for Swift's [`Package.swift`](Package.swift) file for the names of all available AWS services. | ||
|
|
||
| *What’s next?* | ||
| Try some other AWS services. Help us better understand what you think the most critical features are next. Give us | ||
| feedback on your experience. etc... | ||
|
|
||
| *Run into a bug?* | ||
| Please file a Github issue on this project. We try to respond within a business day. | ||
|
|
||
| ## API Reference documentation | ||
| We recommend that you use the documentation generation capabilities within Xcode (Option+Click on a symbol); if you run | ||
| across an API that is not documented, please file an issue in this project. | ||
|
|
||
| Generated online documentation will be provided soon. | ||
| Please refer to our [security policy](https://github.com/awslabs/aws-sdk-swift/security/policy). |