From b8368b6e09b7993896c42a6199103a73ecc1dbf9 Mon Sep 17 00:00:00 2001 From: Johannes Weiss Date: Tue, 26 Mar 2019 09:11:28 +0000 Subject: [PATCH] update the documentation for NIO 2 release (#927) Motivation: A bunch of things change with the release of NIO 2. We should update the documentation to reflect that. Modifications: - update readme - update migration guide Result: up to date docs. --- README.md | 69 ++++++++++++++++++---------- docs/migration-guide-NIO1-to-NIO2.md | 17 +------ 2 files changed, 45 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 9e3d8869..9af091ce 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,45 @@ for rapid development of maintainable high performance protocol servers & client It's like [Netty](https://netty.io), but written for Swift. +### Repository organization + +The SwiftNIO project is split across multiple repositories + +Repository | Swift 5 | Swift 4 +--- | --- | --- +[https://github.com/apple/swift-nio][repo-nio]
SwiftNIO core | `from: "2.0.0"` | `from: "1.0.0"` +[https://github.com/apple/swift-nio-ssl][repo-nio-ssl]
TLS (SSL) support | `from: "2.0.0"` | `from: "1.0.0"` +[https://github.com/apple/swift-nio-http2][repo-nio-http2]
HTTP/2 support | `from: "1.0.0"` | `from: "0.1.0"` +[https://github.com/apple/swift-nio-extras][repo-nio-extras]
useful additions around SwiftNIO | `from: "1.0.0"` | `from: "0.1.0"` +[https://github.com/apple/swift-nio-transport-services][repo-nio-transport-services]
first-class support for macOS, iOS, and tvOS | `from: "1.0.0"` | `from: "0.1.0"` + +### Supported Platforms + +SwiftNIO aims to support all of the platforms where Swift is supported. Currently, it is developed and tested on macOS and Linux, and is known to support the following operating system versions: + +* Ubuntu 14.04+ +* macOS 10.12+; (macOS 10.14+, iOS 12+, or tvOS 12+ with [swift-nio-transport-services][repo-nio-transport-services]) + +### Swift versions + +#### SwiftNIO 1 + +The latest released SwiftNIO 1 version supports Swift 4.0, 4.1, 4.2, and 5.0. + +#### SwiftNIO 2 + +The latest released SwiftNIO 2 version supports Swift 5.0. If you have a SwiftNIO 1 application or library that you would like to migrate to SwiftNIO 2, please check out the [migration guide](docs/migration-guide-NIO1-to-NIO2.md) we prepared for you. + +### Compatibility + +SwiftNIO follows [SemVer 2.0.0](https://semver.org/#semantic-versioning-200) with a separate document declaring [SwiftNIO's Public API](docs/public-api.md). + +What this means for you is that you should depend on SwiftNIO with a version range that covers everything from the minimum SwiftNIO version you require up to the next major version. +In SwiftPM that can be easily done specifying for example `from: "2.0.0"` meaning that you support SwiftNIO in every version starting from 2.0.0 up to (excluding) 3.0.0. +SemVer and SwiftNIO's Public API guarantees should result in a working program without having to worry about testing every single version for compatibility. + + + ## Conceptual Overview SwiftNIO is fundamentally a low-level tool for building high-performance networking applications in Swift. It particularly targets those use-cases where using a "thread-per-connection" model of concurrency is inefficient or untenable. This is a common limitation when building servers that use a large number of relatively low-utilization connections, such as HTTP servers. @@ -15,31 +54,6 @@ SwiftNIO does not aim to provide high-level solutions like, for example, web fra The following sections will describe the low-level tools that SwiftNIO provides, and provide a quick overview of how to work with them. If you feel comfortable with these concepts, then you can skip right ahead to the other sections of this README. -### Supported Platforms - -SwiftNIO aims to support all of the platforms where Swift is supported. Currently, it is developed and tested on macOS and Linux, and is known to support the following operating system versions: - -* Ubuntu 14.04+ -* macOS 10.12+ - -#### Swift versions - -#### SwiftNIO 1 (the stable, released version) - -The latest released SwiftNIO 1 version supports Swift 4.0, 4.1, 4.2, and 5.0. - -#### SwiftNIO 2 (the in development version) - -SwiftNIO 2 will support Swift 5.0. - -### Compatibility - -SwiftNIO follows [SemVer 2.0.0](https://semver.org/#semantic-versioning-200) with a separate document declaring [SwiftNIO's Public API](docs/public-api.md). - -What this means for you is that you should depend on SwiftNIO with a version range that covers everything from the minimum SwiftNIO version you require up to the next major version. -In SwiftPM that can be easily done specifying for example `from: "2.0.0"` meaning that you support SwiftNIO in every version starting from 2.0.0 up to (excluding) 3.0.0. -SemVer and SwiftNIO's Public API guarantees should result in a working program without having to worry about testing every single version for compatibility. - ### Basic Architecture The basic building blocks of SwiftNIO are the following 8 types of objects: @@ -275,3 +289,8 @@ dnf install swift-lang zlib-devel /usr/bin/nc /usr/bin/lsof /usr/bin/shasum [pthreads]: https://en.wikipedia.org/wiki/POSIX_Threads [kqueue]: https://en.wikipedia.org/wiki/Kqueue [epoll]: https://en.wikipedia.org/wiki/Epoll +[repo-nio]: https://github.com/apple/swift-nio +[repo-nio-extras]: https://github.com/apple/swift-nio-extras +[repo-nio-http2]: https://github.com/apple/swift-nio-http2 +[repo-nio-ssl]: https://github.com/apple/swift-nio-ssl +[repo-nio-transport-services]: https://github.com/apple/swift-nio-transport-services diff --git a/docs/migration-guide-NIO1-to-NIO2.md b/docs/migration-guide-NIO1-to-NIO2.md index ad651826..7546c98e 100644 --- a/docs/migration-guide-NIO1-to-NIO2.md +++ b/docs/migration-guide-NIO1-to-NIO2.md @@ -12,22 +12,7 @@ For macOS, download Xcode 10, beta 3 or better and you're good to go. On Linux, ## Step 2: Update your NIO dependencies -Update the NIO packages you use to include the following. - ---- -**NOTE** - -At this moment, NIO 2 is still in development so if you want to depend on the NIO 2 family packages before we tagged any versions. At this moment, the correct dependencies are: - -The already [converged](https://forums.swift.org/t/swiftnio-2-repository-convergence-plan/21387) repositories: - -- `swift-nio`: `.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0-convergence.1")` -- `swift-nio-extras`: `.package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.0.0-convergence.1")` -- `swift-nio-ssl`: `.package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.0.0-convergence.1")` -- `swift-nio-http2`: `.package(url: "https://github.com/apple/swift-nio-http2.git", from: "1.0.0-convergence.1")` -- `swift-nio-transport-services`: `.package(url: "https://github.com/apple/swift-nio-transport-services.git", from: "1.0.0-convergence.1")` - ---- +Update the NIO packages you use to include the following versions. - `swift-nio`: `.package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0")` - `swift-nio-ssl`: `.package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.0.0")`