From e7df54cffaacb509211b040de573d86da2bfa48a Mon Sep 17 00:00:00 2001 From: tom doron Date: Thu, 4 Aug 2022 14:59:13 -0700 Subject: [PATCH 1/4] initial adoption of DocC based documentaiton motivation: use DocC for docs change: * add DocC catalog to NIO target, as the "landing page" * remove jazzy doc generation script * add Package.swift with tools-version 5.6 so that DocC can be used, and add a dependency on the DocC plugin * udpate soundness script --- Package@swift-5.6.swift | 146 ++++++++++++++++++++++++++ Sources/NIO/Docs.docc/index.md | 183 +++++++++++++++++++++++++++++++++ scripts/generate_docs.sh | 126 ----------------------- scripts/soundness.sh | 5 +- 4 files changed, 332 insertions(+), 128 deletions(-) create mode 100644 Package@swift-5.6.swift create mode 100644 Sources/NIO/Docs.docc/index.md delete mode 100755 scripts/generate_docs.sh diff --git a/Package@swift-5.6.swift b/Package@swift-5.6.swift new file mode 100644 index 0000000000..54480ad876 --- /dev/null +++ b/Package@swift-5.6.swift @@ -0,0 +1,146 @@ +// swift-tools-version:5.6 +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftNIO project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +import PackageDescription + +let swiftAtomics: PackageDescription.Target.Dependency = .product(name: "Atomics", package: "swift-atomics") + +var targets: [PackageDescription.Target] = [ + .target(name: "NIOCore", + dependencies: ["NIOConcurrencyHelpers", "CNIOLinux", "CNIOWindows"]), + .target(name: "_NIODataStructures"), + .target(name: "NIOEmbedded", + dependencies: ["NIOCore", + "NIOConcurrencyHelpers", + "_NIODataStructures", + swiftAtomics]), + .target(name: "NIOPosix", + dependencies: ["CNIOLinux", + "CNIODarwin", + "CNIOWindows", + "NIOConcurrencyHelpers", + "NIOCore", + "_NIODataStructures", + swiftAtomics]), + .target(name: "NIO", + dependencies: ["NIOCore", + "NIOEmbedded", + "NIOPosix"]), + .target(name: "_NIOConcurrency", + dependencies: ["NIO", "NIOCore"]), + .target(name: "_NIOBeta", + dependencies: ["NIOCore"]), + .target(name: "NIOFoundationCompat", dependencies: ["NIO", "NIOCore"]), + .target(name: "CNIOAtomics", dependencies: []), + .target(name: "CNIOSHA1", dependencies: []), + .target(name: "CNIOLinux", dependencies: []), + .target(name: "CNIODarwin", dependencies: [], cSettings: [.define("__APPLE_USE_RFC_3542")]), + .target(name: "CNIOWindows", dependencies: []), + .target(name: "NIOConcurrencyHelpers", + dependencies: ["CNIOAtomics"]), + .target(name: "NIOHTTP1", + dependencies: ["NIO", "NIOCore", "NIOConcurrencyHelpers", "CNIOHTTPParser"]), + .executableTarget(name: "NIOEchoServer", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOEchoClient", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOHTTP1Server", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOHTTP1Client", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .target(name: "CNIOHTTPParser"), + .target(name: "NIOTLS", dependencies: ["NIO", "NIOCore"]), + .executableTarget(name: "NIOChatServer", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOChatClient", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .target(name: "NIOWebSocket", + dependencies: ["NIO", "NIOCore", "NIOHTTP1", "CNIOSHA1"]), + .executableTarget(name: "NIOWebSocketServer", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOWebSocket"], + exclude: ["README.md"]), + .executableTarget(name: "NIOWebSocketClient", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOWebSocket"], + exclude: ["README.md"]), + .executableTarget(name: "NIOPerformanceTester", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", "NIOFoundationCompat", "NIOWebSocket"]), + .executableTarget(name: "NIOMulticastChat", + dependencies: ["NIOPosix", "NIOCore"]), + .executableTarget(name: "NIOUDPEchoServer", + dependencies: ["NIOPosix", "NIOCore"], + exclude: ["README.md"]), + .executableTarget(name: "NIOUDPEchoClient", + dependencies: ["NIOPosix", "NIOCore"], + exclude: ["README.md"]), + .target(name: "NIOTestUtils", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", swiftAtomics]), + .executableTarget(name: "NIOCrashTester", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", "NIOWebSocket", "NIOFoundationCompat"]), + .executableTarget(name: "NIOAsyncAwaitDemo", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1"]), + .testTarget(name: "NIOCoreTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOFoundationCompat"]), + .testTarget(name: "NIOBetaTests", + dependencies: ["_NIOBeta"]), + .testTarget(name: "NIOEmbeddedTests", + dependencies: ["NIOConcurrencyHelpers", "NIOCore", "NIOEmbedded"]), + .testTarget(name: "NIOPosixTests", + dependencies: ["NIOPosix", "NIOCore", "NIOFoundationCompat", "NIOTestUtils", "NIOConcurrencyHelpers", "NIOEmbedded"]), + .testTarget(name: "NIOConcurrencyHelpersTests", + dependencies: ["NIOConcurrencyHelpers", "NIOCore"]), + .testTarget(name: "NIODataStructuresTests", + dependencies: ["_NIODataStructures"]), + .testTarget(name: "NIOHTTP1Tests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOPosix", "NIOHTTP1", "NIOFoundationCompat", "NIOTestUtils"]), + .testTarget(name: "NIOTLSTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOTLS", "NIOFoundationCompat"]), + .testTarget(name: "NIOWebSocketTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOWebSocket"]), + .testTarget(name: "NIOTestUtilsTests", + dependencies: ["NIOTestUtils", "NIOCore", "NIOEmbedded", "NIOPosix"]), + .testTarget(name: "NIOFoundationCompatTests", + dependencies: ["NIOCore", "NIOFoundationCompat"]), + .testTarget(name: "NIOTests", + dependencies: ["NIO"]), +] + +let package = Package( + name: "swift-nio", + products: [ + .library(name: "NIOCore", targets: ["NIOCore"]), + .library(name: "NIO", targets: ["NIO"]), + .library(name: "NIOEmbedded", targets: ["NIOEmbedded"]), + .library(name: "NIOPosix", targets: ["NIOPosix"]), + .library(name: "_NIOConcurrency", targets: ["_NIOConcurrency"]), + .library(name: "_NIOBeta", targets: ["_NIOBeta"]), + .library(name: "NIOTLS", targets: ["NIOTLS"]), + .library(name: "NIOHTTP1", targets: ["NIOHTTP1"]), + .library(name: "NIOConcurrencyHelpers", targets: ["NIOConcurrencyHelpers"]), + .library(name: "NIOFoundationCompat", targets: ["NIOFoundationCompat"]), + .library(name: "NIOWebSocket", targets: ["NIOWebSocket"]), + .library(name: "NIOTestUtils", targets: ["NIOTestUtils"]), + ], + dependencies: [ + .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), + ], + targets: targets +) diff --git a/Sources/NIO/Docs.docc/index.md b/Sources/NIO/Docs.docc/index.md new file mode 100644 index 0000000000..d9fce32c4f --- /dev/null +++ b/Sources/NIO/Docs.docc/index.md @@ -0,0 +1,183 @@ +# ``NIO`` + +Event-driven, non-blocking, network application framework for high performance protocol servers & clients. + +## Overview + +SwiftNIO is a cross-platform asynchronous event-driven network application framework for rapid development of maintainable high performance protocol servers & clients. + +It's like Netty, but written for Swift. + +## Repository organization + +The SwiftNIO project is split across multiple repositories: + +Repo | Usage +--|-- +[swift-nio][repo-nio] | SwiftNIO core +[swift-nio-ssl][repo-nio-ssl] | TLS (SSL) support +[swift-nio-http2][repo-nio-http2] | HTTP/2 support +[swift-nio-extras][repo-nio-extras] | Useful additions around SwiftNIO +[swift-nio-transport-services][repo-nio-transport-services] | First-class support for macOS, iOS, tvOS, and watchOS +[swift-nio-ssh][repo-nio-ssh] | SSH support + +## Modules + +SwiftNIO has a number of products that provide different functionality. This package includes the following products: + +- ``NIO``. This is an umbrella module exporting [NIOCore][module-core], [NIOEmbedded][module-embedded] and [NIOPosix][module-posix]. +- [NIOCore][module-core]. This provides the core abstractions and types for using SwiftNIO (see ["Conceptual Overview"](#conceptual-overview) for more details). Most NIO extension projects that provide things like new [`EventLoop`s][el] and [`Channel`s][c] or new protocol implementations should only need to depend on [NIOCore][module-core]. +- [NIOPosix][module-posix]. This provides the primary [`EventLoopGroup`], [`EventLoop`][el], and [`Channel`s][c] for use on POSIX-based systems. This is our high performance core I/O layer. In general, this should only be imported by projects that plan to do some actual I/O, such as high-level protocol implementations or applications. +- [NIOEmbedded][module-embedded]. This provides [`EmbeddedChannel`][ec] and [`EmbeddedEventLoop`][eel], implementations of the [NIOCore][module-core] abstractions that provide fine-grained control over their execution. These are most often used for testing, but can also be used to drive protocol implementations in a way that is decoupled from networking altogether. +- [NIOConcurrencyHelpers][module-concurrency-helpers]. This provides a few low-level concurrency primitives that are used by NIO implementations, such as locks and atomics. +- [NIOFoundationCompat][module-foundation-compatibility]. This extends a number of NIO types for better interoperation with Foundation data types. If you are working with Foundation data types such as `Data`, you should import this. +- [NIOTLS][module-tls]. This provides a few common abstraction types for working with multiple TLS implementations. Note that this doesn't provide TLS itself: please investigate [swift-nio-ssl][repo-nio-ssl] and [swift-nio-transport-services][repo-nio-transport-services] for concrete implementations. +- [NIOHTTP1][module-http1]. This provides a low-level HTTP/1.1 protocol implementation. +- [NIOWebSocket][module-websocket]. This provides a low-level WebSocket protocol implementation. +- [NIOTestUtils][module-test-utilities]. This provides a number of helpers for testing projects that use SwiftNIO. + +## 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. + +To achieve its goals SwiftNIO extensively uses "non-blocking I/O": hence the name! Non-blocking I/O differs from the more common blocking I/O model because the application does not wait for data to be sent to or received from the network: instead, SwiftNIO asks for the kernel to notify it when I/O operations can be performed without waiting. + +SwiftNIO does not aim to provide high-level solutions like, for example, web frameworks do. Instead, SwiftNIO is focused on providing the low-level building blocks for these higher-level applications. When it comes to building a web application, most users will not want to use SwiftNIO directly: instead, they'll want to use one of the many great web frameworks available in the Swift ecosystem. Those web frameworks, however, may choose to use SwiftNIO under the covers to provide their networking support. + +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. + +### Basic Architecture + +The basic building blocks of SwiftNIO are the following 8 types of objects: + +- [`EventLoopGroup`][elg], a protocol, provided by [NIOCore][module-core]. +- [`EventLoop`][el], a protocol, provided by [NIOCore][module-core]. +- [`Channel`][c], a protocol, provided by [NIOCore][module-core]. +- [`ChannelHandler`][ch], a protocol, provided by [NIOCore][module-core]. +- `Bootstrap`, several related structures, provided by [NIOCore][module-core]. +- [`ByteBuffer`][bb], a struct, provided by [NIOCore][module-core]. +- [`EventLoopFuture`][elf], a generic class, provided by [NIOCore][module-core]. +- [`EventLoopPromise`][elp], a generic struct, provided by [NIOCore][module-core]. + +All SwiftNIO applications are ultimately constructed of these various components. + +#### EventLoops and EventLoopGroups + +The basic I/O primitive of SwiftNIO is the event loop. The event loop is an object that waits for events (usually I/O related events, such as "data received") to happen and then fires some kind of callback when they do. In almost all SwiftNIO applications there will be relatively few event loops: usually only one or two per CPU core the application wants to use. Generally speaking event loops run for the entire lifetime of your application, spinning in an endless loop dispatching events. + +Event loops are gathered together into event loop *groups*. These groups provide a mechanism to distribute work around the event loops. For example, when listening for inbound connections the listening socket will be registered on one event loop. However, we don't want all connections that are accepted on that listening socket to be registered with the same event loop, as that would potentially overload one event loop while leaving the others empty. For that reason, the event loop group provides the ability to spread load across multiple event loops. + +In SwiftNIO today there is one [`EventLoopGroup`][elg] implementation, and two [`EventLoop`][el] implementations. For production applications there is the [`MultiThreadedEventLoopGroup`][mtelg], an [`EventLoopGroup`][elg] that creates a number of threads (using the POSIX [`pthreads`][pthreads] library) and places one `SelectableEventLoop` on each one. The `SelectableEventLoop` is an event loop that uses a selector (either [`kqueue`][kqueue] or [`epoll`][epoll] depending on the target system) to manage I/O events from file descriptors and to dispatch work. These [`EventLoop`s][el] and [`EventLoopGroup`s][elg] are provided by the [NIOPosix][module-posix] module. Additionally, there is the [`EmbeddedEventLoop`][eel], which is a dummy event loop that is used primarily for testing purposes, provided by the [NIOEmbedded][module-embedded] module. + +[`EventLoop`][el]s have a number of important properties. Most vitally, they are the way all work gets done in SwiftNIO applications. In order to ensure thread-safety, any work that wants to be done on almost any of the other objects in SwiftNIO must be dispatched via an [`EventLoop`][el]. [`EventLoop`][el] objects own almost all the other objects in a SwiftNIO application, and understanding their execution model is critical for building high-performance SwiftNIO applications. + +#### Channels, Channel Handlers, Channel Pipelines, and Channel Contexts + +While [`EventLoop`][el]s are critical to the way SwiftNIO works, most users will not interact with them substantially beyond asking them to create [`EventLoopPromise`][elp]s and to schedule work. The parts of a SwiftNIO application most users will spend the most time interacting with are [`Channel`][c]s and [`ChannelHandler`][ch]s. + +Almost every file descriptor that a user interacts with in a SwiftNIO program is associated with a single [`Channel`][c]. The [`Channel`][c] owns this file descriptor, and is responsible for managing its lifetime. It is also responsible for processing inbound and outbound events on that file descriptor: whenever the event loop has an event that corresponds to a file descriptor, it will notify the [`Channel`][c] that owns that file descriptor. + +[`Channel`][c]s by themselves, however, are not useful. After all, it is a rare application that doesn't want to do anything with the data it sends or receives on a socket! So the other important part of the [`Channel`][c] is the [`ChannelPipeline`][cp]. + +A [`ChannelPipeline`][cp] is a sequence of objects, called [`ChannelHandler`][ch]s, that process events on a [`Channel`][c]. The [`ChannelHandler`][ch]s process these events one after another, in order, mutating and transforming events as they go. This can be thought of as a data processing pipeline; hence the name [`ChannelPipeline`][cp]. + +All [`ChannelHandler`][ch]s are either Inbound or Outbound handlers, or both. Inbound handlers process "inbound" events: events like reading data from a socket, reading socket close, or other kinds of events initiated by remote peers. Outbound handlers process "outbound" events, such as writes, connection attempts, and local socket closes. + +Each handler processes the events in order. For example, read events are passed from the front of the pipeline to the back, one handler at a time, while write events are passed from the back of the pipeline to the front. Each handler may, at any time, generate either inbound or outbound events that will be sent to the next handler in whichever direction is appropriate. This allows handlers to split up reads, coalesce writes, delay connection attempts, and generally perform arbitrary transformations of events. + +In general, [`ChannelHandler`][ch]s are designed to be highly re-usable components. This means they tend to be designed to be as small as possible, performing one specific data transformation. This allows handlers to be composed together in novel and flexible ways, which helps with code reuse and encapsulation. + +[`ChannelHandler`][ch]s are able to keep track of where they are in a [`ChannelPipeline`][cp] by using a [`ChannelHandlerContext`][chc]. These objects contain references to the previous and next channel handler in the pipeline, ensuring that it is always possible for a [`ChannelHandler`][ch] to emit events while it remains in a pipeline. + +SwiftNIO ships with many [`ChannelHandler`][ch]s built in that provide useful functionality, such as HTTP parsing. In addition, high-performance applications will want to provide as much of their logic as possible in [`ChannelHandler`][ch]s, as it helps avoid problems with context switching. + +Additionally, SwiftNIO ships with a few [`Channel`][c] implementations. In particular, it ships with `ServerSocketChannel`, a [`Channel`][c] for sockets that accept inbound connections; `SocketChannel`, a [`Channel`][c] for TCP connections; and `DatagramChannel`, a [`Channel`][c] for UDP sockets. All of these are provided by the [NIOPosix][module-posix] module. It also provides[`EmbeddedChannel`][ec], a [`Channel`][c] primarily used for testing, provided by the [NIOEmbedded][module-embedded] module. + +##### A Note on Blocking + +One of the important notes about [`ChannelPipeline`][cp]s is that they are thread-safe. This is very important for writing SwiftNIO applications, as it allows you to write much simpler [`ChannelHandler`][ch]s in the knowledge that they will not require synchronization. + +However, this is achieved by dispatching all code on the [`ChannelPipeline`][cp] on the same thread as the [`EventLoop`][el]. This means that, as a general rule, [`ChannelHandler`][ch]s **must not** call blocking code without dispatching it to a background thread. If a [`ChannelHandler`][ch] blocks for any reason, all [`Channel`][c]s attached to the parent [`EventLoop`][el] will be unable to progress until the blocking call completes. + +This is a common concern while writing SwiftNIO applications. If it is useful to write code in a blocking style, it is highly recommended that you dispatch work to a different thread when you're done with it in your pipeline. + +#### Bootstrap + +While it is possible to configure and register [`Channel`][c]s with [`EventLoop`][el]s directly, it is generally more useful to have a higher-level abstraction to handle this work. + +For this reason, SwiftNIO ships a number of `Bootstrap` objects whose purpose is to streamline the creation of channels. Some `Bootstrap` objects also provide other functionality, such as support for Happy Eyeballs for making TCP connection attempts. + +Currently SwiftNIO ships with three `Bootstrap` objects in the [NIOPosix][module-posix] module: [`ServerBootstrap`](./NIOPosix/Classes/ServerBootstrap.html), for bootstrapping listening channels; [`ClientBootstrap`](./NIOPosix/Classes/ClientBootstrap.html), for bootstrapping client TCP channels; and [`DatagramBootstrap`](./NIOPosix/Classes/DatagramBootstrap.html) for bootstrapping UDP channels. + +#### ByteBuffer + +The majority of the work in a SwiftNIO application involves shuffling buffers of bytes around. At the very least, data is sent and received to and from the network in the form of buffers of bytes. For this reason it's very important to have a high-performance data structure that is optimized for the kind of work SwiftNIO applications perform. + +For this reason, SwiftNIO provides [`ByteBuffer`][bb], a fast copy-on-write byte buffer that forms a key building block of most SwiftNIO applications. This type is provided by the [NIOCore][module-core] module. + +[`ByteBuffer`][bb] provides a number of useful features, and in addition provides a number of hooks to use it in an "unsafe" mode. This turns off bounds checking for improved performance, at the cost of potentially opening your application up to memory correctness problems. + +In general, it is highly recommended that you use the [`ByteBuffer`][bb] in its safe mode at all times. + +For more details on the API of [`ByteBuffer`][bb], please see our API documentation, linked below. + +#### Promises and Futures + +One major difference between writing concurrent code and writing synchronous code is that not all actions will complete immediately. For example, when you write data on a channel, it is possible that the event loop will not be able to immediately flush that write out to the network. For this reason, SwiftNIO provides [`EventLoopPromise`][elp] and [`EventLoopFuture`][elf] to manage operations that complete *asynchronously*. These types are provided by the [NIOCore][module-core] module. + +An [`EventLoopFuture`][elf] is essentially a container for the return value of a function that will be populated *at some time in the future*. Each [`EventLoopFuture`][elf] has a corresponding [`EventLoopPromise`][elp], which is the object that the result will be put into. When the promise is succeeded, the future will be fulfilled. + +If you had to poll the future to detect when it completed that would be quite inefficient, so [`EventLoopFuture`][elf] is designed to have managed callbacks. Essentially, you can hang callbacks off the future that will be executed when a result is available. The [`EventLoopFuture`][elf] will even carefully arrange the scheduling to ensure that these callbacks always execute on the event loop that initially created the promise, which helps ensure that you don't need too much synchronization around [`EventLoopFuture`][elf] callbacks. + +Another important topic for consideration is the difference between how the promise passed to `close` works as opposed to `closeFuture` on a [`Channel`][c]. For example, the promise passed into `close` will succeed after the [`Channel`][c] is closed down but before the [`ChannelPipeline`][cp] is completely cleared out. This will allow you to take action on the [`ChannelPipeline`][cp] before it is completely cleared out, if needed. If it is desired to wait for the [`Channel`][c] to close down and the [`ChannelPipeline`][cp] to be cleared out without any further action, then the better option would be to wait for the `closeFuture` to succeed. + +There are several functions for applying callbacks to [`EventLoopFuture`][elf], depending on how and when you want them to execute. Details of these functions is left to the API documentation. + +### Design Philosophy + +SwiftNIO is designed to be a powerful tool for building networked applications and frameworks, but it is not intended to be the perfect solution for all levels of abstraction. SwiftNIO is tightly focused on providing the basic I/O primitives and protocol implementations at low levels of abstraction, leaving more expressive but slower abstractions to the wider community to build. The intention is that SwiftNIO will be a building block for server-side applications, not necessarily the framework those applications will use directly. + +Applications that need extremely high performance from their networking stack may choose to use SwiftNIO directly in order to reduce the overhead of their abstractions. These applications should be able to maintain extremely high performance with relatively little maintenance cost. SwiftNIO also focuses on providing useful abstractions for this use-case, such that extremely high performance network servers can be built directly. + +The core SwiftNIO repository will contain a few extremely important protocol implementations, such as HTTP, directly in tree. However, we believe that most protocol implementations should be decoupled from the release cycle of the underlying networking stack, as the release cadence is likely to be very different (either much faster or much slower). For this reason, we actively encourage the community to develop and maintain their protocol implementations out-of-tree. Indeed, some first-party SwiftNIO protocol implementations, including our TLS and HTTP/2 bindings, are developed out-of-tree! + + + + +[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 +[repo-nio-ssh]: https://github.com/apple/swift-nio-ssh + +[module-core]: ./NIOCore +[module-posix]: ./NIOPosix +[module-embedded]: ./NIOEmbedded +[module-concurrency-helpers]: ./NIOConcurrencyHelpers +[module-embedded]: ./NIOEmbedded +[module-foundation-compatibility]: ./NIOFoundationCompat +[module-http1]: ./NIOHTTP1 +[module-tls]: ./NIOTLS +[module-websocket]: ./NIOWebSocket +[module-test-utilities]: ./NIOTestUtils + +[ch]: ./NIOCore/Protocols/ChannelHandler.html +[c]: ./NIOCore/Protocols/Channel.html +[chc]: ./NIOCore/Classes/ChannelHandlerContext.html +[ec]: ./NIOCore/Classes/EmbeddedChannel.html +[el]: ./NIOCore/Protocols/EventLoop.html +[eel]: ./NIOCore/Classes/EmbeddedEventLoop.html +[elg]: ./NIOCore/Protocols/EventLoopGroup.html +[bb]: ./NIOCore/Structs/ByteBuffer.html +[elf]: ./NIOCore/Classes/EventLoopFuture.html +[elp]: ./NIOCore/Structs/EventLoopPromise.html +[cp]: ./NIOCore/Classes/ChannelPipeline.html +[mtelg]: ./NIOPosix/Classes/MultiThreadedEventLoopGroup.html +[pthreads]: https://en.wikipedia.org/wiki/POSIX_Threads +[kqueue]: https://en.wikipedia.org/wiki/Kqueue +[epoll]: https://en.wikipedia.org/wiki/Epoll + + diff --git a/scripts/generate_docs.sh b/scripts/generate_docs.sh deleted file mode 100755 index 97eb25b89f..0000000000 --- a/scripts/generate_docs.sh +++ /dev/null @@ -1,126 +0,0 @@ -#!/bin/bash -##===----------------------------------------------------------------------===## -## -## This source file is part of the SwiftNIO open source project -## -## Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors -## Licensed under Apache License v2.0 -## -## See LICENSE.txt for license information -## See CONTRIBUTORS.txt for the list of SwiftNIO project authors -## -## SPDX-License-Identifier: Apache-2.0 -## -##===----------------------------------------------------------------------===## - -set -ex - -my_path="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" -root_path="$my_path/.." -version=$(git describe --abbrev=0 --tags || echo "0.0.0") -modules=( NIOCore NIOEmbedded NIOPosix NIOHTTP1 NIOFoundationCompat NIOWebSocket NIOConcurrencyHelpers NIOTLS NIOTestUtils ) - -if [[ "$(uname -s)" == "Linux" ]]; then - # build code if required - if [[ ! -d "$root_path/.build/x86_64-unknown-linux" ]]; then - swift build - fi - # setup source-kitten if required - mkdir -p "$root_path/.build/sourcekitten" - source_kitten_source_path="$root_path/.build/sourcekitten/source" - if [[ ! -d "$source_kitten_source_path" ]]; then - git clone https://github.com/jpsim/SourceKitten.git "$source_kitten_source_path" - fi - source_kitten_path="$source_kitten_source_path/.build/debug" - if [[ ! -d "$source_kitten_path" ]]; then - rm -rf "$source_kitten_source_path/.swift-version" - cd "$source_kitten_source_path" && swift build && cd "$root_path" - fi - # generate - for module in "${modules[@]}"; do - if [[ ! -f "$root_path/.build/sourcekitten/$module.json" ]]; then - "$source_kitten_path/sourcekitten" doc --spm --module-name $module > "$root_path/.build/sourcekitten/$module.json" - fi - done -fi - -[[ -d docs/$version ]] || mkdir -p docs/$version -[[ -d swift-nio.xcodeproj ]] || swift package generate-xcodeproj - -# run jazzy -if ! command -v jazzy > /dev/null; then - gem install jazzy --no-ri --no-rdoc -fi - -jazzy_dir="$root_path/.build/jazzy" -rm -rf "$jazzy_dir" -mkdir -p "$jazzy_dir" - -module_switcher="$jazzy_dir/README.md" -jazzy_args=(--clean - --author 'SwiftNIO Team' - --readme "$module_switcher" - --author_url https://github.com/apple/swift-nio - --github_url https://github.com/apple/swift-nio - --theme fullwidth - --github-file-prefix https://github.com/apple/swift-nio/tree/$version - --xcodebuild-arguments -scheme,swift-nio-Package) -cat > "$module_switcher" <<"EOF" -# SwiftNIO Docs - -SwiftNIO contains multiple modules: - -EOF - -for module in "${modules[@]}"; do - echo " - [$module](../$module/index.html)" >> "$module_switcher" -done - -cat >> "$module_switcher" <<"EOF" - ---- - -For the API documentation of the other repositories in the SwiftNIO family check: - -- [`swift-nio` API docs](https://apple.github.io/swift-nio/docs/current/NIOCore/index.html) -- [`swift-nio-ssl` API docs](https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/index.html) -- [`swift-nio-http2` API docs](https://apple.github.io/swift-nio-http2/docs/current/NIOHTTP2/index.html) -- [`swift-nio-extras` API docs](https://apple.github.io/swift-nio-extras/docs/current/NIOExtras/index.html) - -EOF - -for module in "${modules[@]}"; do - args=("${jazzy_args[@]}" --output "$jazzy_dir/docs/$version/$module" --docset-path "$jazzy_dir/docset/$version/$module" - --module "$module" --module-version $version - --root-url "https://apple.github.io/swift-nio/docs/$version/$module/") - if [[ -f "$root_path/.build/sourcekitten/$module.json" ]]; then - args+=(--sourcekitten-sourcefile "$root_path/.build/sourcekitten/$module.json") - fi - jazzy "${args[@]}" -done - -# push to github pages -if [[ $PUSH == true ]]; then - BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD) - GIT_AUTHOR=$(git --no-pager show -s --format='%an <%ae>' HEAD) - git fetch origin +gh-pages:gh-pages - git checkout gh-pages - rm -rf "docs/$version" - rm -rf "docs/current" - cp -r "$jazzy_dir/docs/$version" docs/ - cp -r "docs/$version" docs/current - git add --all docs - echo '' > index.html - git add index.html - touch .nojekyll - git add .nojekyll - changes=$(git diff-index --name-only HEAD) - if [[ -n "$changes" ]]; then - echo -e "changes detected\n$changes" - git commit --author="$GIT_AUTHOR" -m "publish $version docs" - git push origin gh-pages - else - echo "no changes detected" - fi - git checkout -f $BRANCH_NAME -fi diff --git a/scripts/soundness.sh b/scripts/soundness.sh index ceea1b153c..47af9bdbf3 100755 --- a/scripts/soundness.sh +++ b/scripts/soundness.sh @@ -52,17 +52,18 @@ if git grep --color=never -i "${unacceptable_terms[@]}" -- . ":(exclude)CODE_OF_ fi printf "\033[0;32mokay.\033[0m\n" -printf "=> Checking license headers... " +printf "=> Checking license headers\n" tmp=$(mktemp /tmp/.swift-nio-soundness_XXXXXX) for language in swift-or-c bash dtrace python; do + printf " * $language... " declare -a matching_files declare -a exceptions expections=( ) matching_files=( -name '*' ) case "$language" in swift-or-c) - exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h) + exceptions=( -name c_nio_http_parser.c -o -name c_nio_http_parser.h -o -name cpp_magic.h -o -name Package.swift -o -name Package@*.swift -o -name CNIOSHA1.h -o -name c_nio_sha1.c -o -name ifaddrs-android.c -o -name ifaddrs-android.h) matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' ) cat > "$tmp" <<"EOF" //===----------------------------------------------------------------------===// From 1f5c8ca4cb3e8f623a3110346c0f87dc3e7f3f38 Mon Sep 17 00:00:00 2001 From: tom doron Date: Fri, 5 Aug 2022 10:39:15 -0700 Subject: [PATCH 2/4] * add packge.swift files for older vrsions * adjust waning-as-error and enable-test-discovery to the different permutations --- Package.swift | 3 +- ...swift-5.6.swift => Package@swift-5.4.swift | 7 +- Package@swift-5.5.swift | 147 ++++++++++++++++++ docker/docker-compose.1804.54.yaml | 2 + docker/docker-compose.2004.55.yaml | 2 + docker/docker-compose.2004.56.yaml | 2 + docker/docker-compose.2004.57.yaml | 2 + docker/docker-compose.2004.main.yaml | 2 + docker/docker-compose.yaml | 4 +- 9 files changed, 165 insertions(+), 6 deletions(-) rename Package@swift-5.6.swift => Package@swift-5.4.swift (96%) create mode 100644 Package@swift-5.5.swift diff --git a/Package.swift b/Package.swift index e5b209a644..3a3e0c8ec6 100644 --- a/Package.swift +++ b/Package.swift @@ -1,4 +1,4 @@ -// swift-tools-version:5.4 +// swift-tools-version:5.6 //===----------------------------------------------------------------------===// // // This source file is part of the SwiftNIO open source project @@ -142,6 +142,7 @@ let package = Package( dependencies: [ .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"), .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.2"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), ], targets: targets ) diff --git a/Package@swift-5.6.swift b/Package@swift-5.4.swift similarity index 96% rename from Package@swift-5.6.swift rename to Package@swift-5.4.swift index 54480ad876..e5b209a644 100644 --- a/Package@swift-5.6.swift +++ b/Package@swift-5.4.swift @@ -1,4 +1,4 @@ -// swift-tools-version:5.6 +// swift-tools-version:5.4 //===----------------------------------------------------------------------===// // // This source file is part of the SwiftNIO open source project @@ -16,10 +16,11 @@ import PackageDescription let swiftAtomics: PackageDescription.Target.Dependency = .product(name: "Atomics", package: "swift-atomics") +let swiftCollections: PackageDescription.Target.Dependency = .product(name: "DequeModule", package: "swift-collections") var targets: [PackageDescription.Target] = [ .target(name: "NIOCore", - dependencies: ["NIOConcurrencyHelpers", "CNIOLinux", "CNIOWindows"]), + dependencies: ["NIOConcurrencyHelpers", "CNIOLinux", "CNIOWindows", swiftCollections]), .target(name: "_NIODataStructures"), .target(name: "NIOEmbedded", dependencies: ["NIOCore", @@ -140,7 +141,7 @@ let package = Package( ], dependencies: [ .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"), - .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), + .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.2"), ], targets: targets ) diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift new file mode 100644 index 0000000000..6de337362b --- /dev/null +++ b/Package@swift-5.5.swift @@ -0,0 +1,147 @@ +// swift-tools-version:5.5 +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2017-2021 Apple Inc. and the SwiftNIO project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftNIO project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +import PackageDescription + +let swiftAtomics: PackageDescription.Target.Dependency = .product(name: "Atomics", package: "swift-atomics") +let swiftCollections: PackageDescription.Target.Dependency = .product(name: "DequeModule", package: "swift-collections") + +var targets: [PackageDescription.Target] = [ + .target(name: "NIOCore", + dependencies: ["NIOConcurrencyHelpers", "CNIOLinux", "CNIOWindows", swiftCollections]), + .target(name: "_NIODataStructures"), + .target(name: "NIOEmbedded", + dependencies: ["NIOCore", + "NIOConcurrencyHelpers", + "_NIODataStructures", + swiftAtomics]), + .target(name: "NIOPosix", + dependencies: ["CNIOLinux", + "CNIODarwin", + "CNIOWindows", + "NIOConcurrencyHelpers", + "NIOCore", + "_NIODataStructures", + swiftAtomics]), + .target(name: "NIO", + dependencies: ["NIOCore", + "NIOEmbedded", + "NIOPosix"]), + .target(name: "_NIOConcurrency", + dependencies: ["NIO", "NIOCore"]), + .target(name: "_NIOBeta", + dependencies: ["NIOCore"]), + .target(name: "NIOFoundationCompat", dependencies: ["NIO", "NIOCore"]), + .target(name: "CNIOAtomics", dependencies: []), + .target(name: "CNIOSHA1", dependencies: []), + .target(name: "CNIOLinux", dependencies: []), + .target(name: "CNIODarwin", dependencies: [], cSettings: [.define("__APPLE_USE_RFC_3542")]), + .target(name: "CNIOWindows", dependencies: []), + .target(name: "NIOConcurrencyHelpers", + dependencies: ["CNIOAtomics"]), + .target(name: "NIOHTTP1", + dependencies: ["NIO", "NIOCore", "NIOConcurrencyHelpers", "CNIOHTTPParser"]), + .executableTarget(name: "NIOEchoServer", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOEchoClient", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOHTTP1Server", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOHTTP1Client", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .target(name: "CNIOHTTPParser"), + .target(name: "NIOTLS", dependencies: ["NIO", "NIOCore"]), + .executableTarget(name: "NIOChatServer", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .executableTarget(name: "NIOChatClient", + dependencies: ["NIOPosix", "NIOCore", "NIOConcurrencyHelpers"], + exclude: ["README.md"]), + .target(name: "NIOWebSocket", + dependencies: ["NIO", "NIOCore", "NIOHTTP1", "CNIOSHA1"]), + .executableTarget(name: "NIOWebSocketServer", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOWebSocket"], + exclude: ["README.md"]), + .executableTarget(name: "NIOWebSocketClient", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1", "NIOWebSocket"], + exclude: ["README.md"]), + .executableTarget(name: "NIOPerformanceTester", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", "NIOFoundationCompat", "NIOWebSocket"]), + .executableTarget(name: "NIOMulticastChat", + dependencies: ["NIOPosix", "NIOCore"]), + .executableTarget(name: "NIOUDPEchoServer", + dependencies: ["NIOPosix", "NIOCore"], + exclude: ["README.md"]), + .executableTarget(name: "NIOUDPEchoClient", + dependencies: ["NIOPosix", "NIOCore"], + exclude: ["README.md"]), + .target(name: "NIOTestUtils", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", swiftAtomics]), + .executableTarget(name: "NIOCrashTester", + dependencies: ["NIOPosix", "NIOCore", "NIOEmbedded", "NIOHTTP1", "NIOWebSocket", "NIOFoundationCompat"]), + .executableTarget(name: "NIOAsyncAwaitDemo", + dependencies: ["NIOPosix", "NIOCore", "NIOHTTP1"]), + .testTarget(name: "NIOCoreTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOFoundationCompat"]), + .testTarget(name: "NIOBetaTests", + dependencies: ["_NIOBeta"]), + .testTarget(name: "NIOEmbeddedTests", + dependencies: ["NIOConcurrencyHelpers", "NIOCore", "NIOEmbedded"]), + .testTarget(name: "NIOPosixTests", + dependencies: ["NIOPosix", "NIOCore", "NIOFoundationCompat", "NIOTestUtils", "NIOConcurrencyHelpers", "NIOEmbedded"]), + .testTarget(name: "NIOConcurrencyHelpersTests", + dependencies: ["NIOConcurrencyHelpers", "NIOCore"]), + .testTarget(name: "NIODataStructuresTests", + dependencies: ["_NIODataStructures"]), + .testTarget(name: "NIOHTTP1Tests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOPosix", "NIOHTTP1", "NIOFoundationCompat", "NIOTestUtils"]), + .testTarget(name: "NIOTLSTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOTLS", "NIOFoundationCompat"]), + .testTarget(name: "NIOWebSocketTests", + dependencies: ["NIOCore", "NIOEmbedded", "NIOWebSocket"]), + .testTarget(name: "NIOTestUtilsTests", + dependencies: ["NIOTestUtils", "NIOCore", "NIOEmbedded", "NIOPosix"]), + .testTarget(name: "NIOFoundationCompatTests", + dependencies: ["NIOCore", "NIOFoundationCompat"]), + .testTarget(name: "NIOTests", + dependencies: ["NIO"]), +] + +let package = Package( + name: "swift-nio", + products: [ + .library(name: "NIOCore", targets: ["NIOCore"]), + .library(name: "NIO", targets: ["NIO"]), + .library(name: "NIOEmbedded", targets: ["NIOEmbedded"]), + .library(name: "NIOPosix", targets: ["NIOPosix"]), + .library(name: "_NIOConcurrency", targets: ["_NIOConcurrency"]), + .library(name: "_NIOBeta", targets: ["_NIOBeta"]), + .library(name: "NIOTLS", targets: ["NIOTLS"]), + .library(name: "NIOHTTP1", targets: ["NIOHTTP1"]), + .library(name: "NIOConcurrencyHelpers", targets: ["NIOConcurrencyHelpers"]), + .library(name: "NIOFoundationCompat", targets: ["NIOFoundationCompat"]), + .library(name: "NIOWebSocket", targets: ["NIOWebSocket"]), + .library(name: "NIOTestUtils", targets: ["NIOTestUtils"]), + ], + dependencies: [ + .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"), + .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.2"), + ], + targets: targets +) diff --git a/docker/docker-compose.1804.54.yaml b/docker/docker-compose.1804.54.yaml index c2739f09bf..7a5dee40cc 100644 --- a/docker/docker-compose.1804.54.yaml +++ b/docker/docker-compose.1804.54.yaml @@ -59,6 +59,8 @@ services: - MAX_ALLOCS_ALLOWED_scheduling_10000_executions=98 - MAX_ALLOCS_ALLOWED_udp_1000_reqs_1_conn=12200 - MAX_ALLOCS_ALLOWED_udp_1_reqs_1000_conn=168050 + # - FORCE_TEST_DISCOVERY=--enable-test-discovery + - WARN_AS_ERROR_ARG=-Xswiftc -warnings-as-errors # - SANITIZER_ARG=--sanitize=thread # TSan broken still performance-test: diff --git a/docker/docker-compose.2004.55.yaml b/docker/docker-compose.2004.55.yaml index 2c6214aa77..6bfb3fc277 100644 --- a/docker/docker-compose.2004.55.yaml +++ b/docker/docker-compose.2004.55.yaml @@ -59,6 +59,8 @@ services: - MAX_ALLOCS_ALLOWED_scheduling_10000_executions=98 - MAX_ALLOCS_ALLOWED_udp_1000_reqs_1_conn=12200 - MAX_ALLOCS_ALLOWED_udp_1_reqs_1000_conn=168050 + - FORCE_TEST_DISCOVERY=--enable-test-discovery + # - WARN_AS_ERROR_ARG=-Xswiftc -warnings-as-errors # - SANITIZER_ARG=--sanitize=thread # TSan broken still performance-test: diff --git a/docker/docker-compose.2004.56.yaml b/docker/docker-compose.2004.56.yaml index f9f08ab99d..7d794939f1 100644 --- a/docker/docker-compose.2004.56.yaml +++ b/docker/docker-compose.2004.56.yaml @@ -59,6 +59,8 @@ services: - MAX_ALLOCS_ALLOWED_scheduling_10000_executions=97 - MAX_ALLOCS_ALLOWED_udp_1000_reqs_1_conn=12200 - MAX_ALLOCS_ALLOWED_udp_1_reqs_1000_conn=166050 + - FORCE_TEST_DISCOVERY=--enable-test-discovery + - WARN_AS_ERROR_ARG=-Xswiftc -warnings-as-errors # - SANITIZER_ARG=--sanitize=thread # TSan broken still performance-test: diff --git a/docker/docker-compose.2004.57.yaml b/docker/docker-compose.2004.57.yaml index 4da8d28e83..4c1d738292 100644 --- a/docker/docker-compose.2004.57.yaml +++ b/docker/docker-compose.2004.57.yaml @@ -58,6 +58,8 @@ services: - MAX_ALLOCS_ALLOWED_scheduling_10000_executions=97 - MAX_ALLOCS_ALLOWED_udp_1000_reqs_1_conn=12200 - MAX_ALLOCS_ALLOWED_udp_1_reqs_1000_conn=166050 + - FORCE_TEST_DISCOVERY=--enable-test-discovery + - WARN_AS_ERROR_ARG=-Xswiftc -warnings-as-errors # - SANITIZER_ARG=--sanitize=thread # TSan broken still performance-test: diff --git a/docker/docker-compose.2004.main.yaml b/docker/docker-compose.2004.main.yaml index a632f7f252..f9e50b3f9b 100644 --- a/docker/docker-compose.2004.main.yaml +++ b/docker/docker-compose.2004.main.yaml @@ -58,6 +58,8 @@ services: - MAX_ALLOCS_ALLOWED_scheduling_10000_executions=97 - MAX_ALLOCS_ALLOWED_udp_1000_reqs_1_conn=12200 - MAX_ALLOCS_ALLOWED_udp_1_reqs_1000_conn=166050 + - FORCE_TEST_DISCOVERY=--enable-test-discovery + - WARN_AS_ERROR_ARG=-Xswiftc -warnings-as-errors # - SANITIZER_ARG=--sanitize=thread # TSan broken still performance-test: diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index 6a45a0345e..b251ed7075 100644 --- a/docker/docker-compose.yaml +++ b/docker/docker-compose.yaml @@ -28,7 +28,7 @@ services: unit-tests: <<: *common - command: /bin/bash -xcl "swift $${SWIFT_TEST_VERB-test} -Xswiftc -warnings-as-errors" + command: /bin/bash -xcl "swift $${SWIFT_TEST_VERB-test} $${FORCE_TEST_DISCOVERY-} $${WARN_AS_ERROR_ARG-}" integration-tests: <<: *common @@ -36,7 +36,7 @@ services: test: <<: *common - command: /bin/bash -xcl "swift $${SWIFT_TEST_VERB-test} -Xswiftc -warnings-as-errors $${SANITIZER_ARG-} && ./scripts/integration_tests.sh $${INTEGRATION_TESTS_ARG-}" + command: /bin/bash -xcl "swift $${SWIFT_TEST_VERB-test} $${FORCE_TEST_DISCOVERY-} $${WARN_AS_ERROR_ARG-} $${SANITIZER_ARG-} && ./scripts/integration_tests.sh $${INTEGRATION_TESTS_ARG-}" performance-test: <<: *common From c97bc3e1c07a73860f101bd602adf5194d14c876 Mon Sep 17 00:00:00 2001 From: tom doron Date: Fri, 5 Aug 2022 10:41:46 -0700 Subject: [PATCH 3/4] fixup --- Sources/NIO/Docs.docc/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/NIO/Docs.docc/index.md b/Sources/NIO/Docs.docc/index.md index d9fce32c4f..2e865170a7 100644 --- a/Sources/NIO/Docs.docc/index.md +++ b/Sources/NIO/Docs.docc/index.md @@ -44,7 +44,7 @@ To achieve its goals SwiftNIO extensively uses "non-blocking I/O": hence the nam SwiftNIO does not aim to provide high-level solutions like, for example, web frameworks do. Instead, SwiftNIO is focused on providing the low-level building blocks for these higher-level applications. When it comes to building a web application, most users will not want to use SwiftNIO directly: instead, they'll want to use one of the many great web frameworks available in the Swift ecosystem. Those web frameworks, however, may choose to use SwiftNIO under the covers to provide their networking support. -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. +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 document. ### Basic Architecture From 139102651719b3bed27c2045377ccd1c58f65458 Mon Sep 17 00:00:00 2001 From: tom doron Date: Fri, 5 Aug 2022 17:11:09 -0700 Subject: [PATCH 4/4] remove jazzy --- docker/Dockerfile | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index ad384fc586..dd62c17f8e 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -16,11 +16,8 @@ ENV LANGUAGE en_US.UTF-8 RUN apt-get update && apt-get install -y wget RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools curl jq # used by integration tests -# ruby and jazzy for docs generation +# ruby RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev build-essential -# jazzy no longer works on xenial as ruby is too old. -RUN if [ "${ubuntu_version}" = "focal" ] ; then echo "gem: --no-document" > ~/.gemrc ; fi -RUN if [ "${ubuntu_version}" = "focal" ] ; then gem install jazzy ; fi # tools RUN mkdir -p $HOME/.tools