mirror of
https://github.com/Dimillian/IceCubesApp.git
synced 2024-09-23 20:20:01 +00:00
2729 lines
330 KiB
XML
2729 lines
330 KiB
XML
|
<?xml version="1.0" encoding="utf-8"?>
|
|||
|
|
<feed xmlns="http://www.w3.org/2005/Atom">
|
|||
|
|
<title type="text" xml:lang="en">Swift.org</title>
|
|||
|
|
<link type="application/atom+xml" href="https://swift.org/atom.xml" rel="self"/>
|
|||
|
|
<link type="text/html" href="" rel="alternate"/>
|
|||
|
|
<updated>2024-03-02T07:00:07-04:00</updated>
|
|||
|
|
<id>tag:swift.org,2015-12-03:Swift</id>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift joins Google Summer of Code 2024</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-google-summer-of-code-2024/"/>
|
|||
|
|
<updated>2024-02-23T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-google-summer-of-code-2024/</id>
|
|||
|
|
<content type="html"><p>We’re happy to announce that Swift will once again be joining <a href="https://summerofcode.withgoogle.com">Google Summer of Code 2024</a>!</p>
|
|||
|
|
|
|||
|
|
<p>Summer of Code is an annual program, organized by Google, which provides hands-on experience for newcomers contributing
|
|||
|
|
to open source projects. Participants usually are students, but do not have to be.</p>
|
|||
|
|
|
|||
|
|
<p>Swift has been participating in Summer of Code since 2018, and every year we’ve had successful projects,
|
|||
|
|
helping the Swift project among various aspects including the compiler, runtime, and general package and tooling ecosystem.
|
|||
|
|
If you’re curious, here are the two most recent project summaries for <a href="https://www.swift.org/blog/swift-summer-of-code-2022-summary/">2022</a> and <a href="https://www.swift.org/blog/summer-of-code-2023-summary/">2023</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Many GSoC participants become part of the Swift community and keep contributing even as the program ends.
|
|||
|
|
This is the most exciting part for us: helping you become a part of the Swift community!</p>
|
|||
|
|
|
|||
|
|
<p>If you are <a href="https://summerofcode.withgoogle.com/get-started">eligible</a>, and would like to contribute to Swift during
|
|||
|
|
this year’s GSoC, these are the steps to take:</p>
|
|||
|
|
|
|||
|
|
<ol>
|
|||
|
|
<li>Check out the existing <a href="https://www.swift.org/gsoc2024/">project ideas page</a>.</li>
|
|||
|
|
<li>If a project excites you, <a href="https://forums.swift.org/c/development/gsoc/98">proceed to the GSoC category on the Swift forums</a> to discuss the project.</li>
|
|||
|
|
<li>Once you are confident in your understanding of the project and how to approach it, <a href="https://google.github.io/gsocguides/student/writing-a-proposal">write an official proposal</a> and submit it to the <a href="https://summerofcode.withgoogle.com">GSoC website</a>.</li>
|
|||
|
|
</ol>
|
|||
|
|
|
|||
|
|
<p>You can also come up with your own project ideas. To do so, you’ll need to start a discussion thread <a href="https://forums.swift.org/c/development/gsoc/98">on the forums</a> and pitch the idea similar to how the existing
|
|||
|
|
ideas are listed on the ideas page. Proposing new ideas is exciting, but more difficult as you’ll have to ensure the project gets a mentor willing to take it on.</p>
|
|||
|
|
|
|||
|
|
<p>The forums are also a great resource of past GSoC discussions and projects. You can also read the <a href="https://google.github.io/gsocguides/student/index">GSoC Contributor Guide</a> to get a good grasp of what participating in the program entails.</p>
|
|||
|
|
|
|||
|
|
<p>Official proposal applications need to be sent through the Summer of Code website.
|
|||
|
|
Applications start on March 18, 2024, and end on April 2, 2024 at 18:00 UTC.</p>
|
|||
|
|
|
|||
|
|
<p>We look forward to working with you all again this year!</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>On-device ML research with MLX and Swift</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/mlx-swift/"/>
|
|||
|
|
<updated>2024-02-20T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/mlx-swift/</id>
|
|||
|
|
<content type="html"><p>The Swift programming language has a lot of potential to be used for machine learning research because it combines the ease of use and high-level syntax of a language like Python with the speed of a compiled language like C++.</p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/ml-explore/mlx">MLX</a> is an array framework for machine learning research on Apple silicon. MLX is intended for research and not for production deployment of models in apps.</p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/ml-explore/mlx-swift/">MLX Swift</a> expands MLX to the Swift language, making experimentation on Apple silicon easier for ML researchers.</p>
|
|||
|
|
|
|||
|
|
<p>As part of this release we are including:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>A comprehensive Swift API for MLX core</li>
|
|||
|
|
<li>Higher level neural network and optimizers packages</li>
|
|||
|
|
<li>An example of text generation with Mistral 7B</li>
|
|||
|
|
<li>An example of MNIST training</li>
|
|||
|
|
<li>A C API to MLX which acts as the bridge between Swift and the C++ core</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>We are releasing all of the above under a permissive <a href="https://github.com/ml-explore/mlx-swift/blob/main/LICENSE">MIT license</a>.</p>
|
|||
|
|
|
|||
|
|
<p>This is a big step to enable ML researchers to experiment using Swift.</p>
|
|||
|
|
|
|||
|
|
<h3 id="motivation">Motivation</h3>
|
|||
|
|
|
|||
|
|
<p>MLX has several important features for machine learning research that few if any existing Swift libraries support. These include:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Native support for hardware acceleration. MLX can run compute intensive operations on the CPU or GPU.</li>
|
|||
|
|
<li>Automatic differentiation for training neural networks and the gradient-based machine learning models</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>For more information on MLX see the <a href="https://ml-explore.github.io/mlx">documentation</a>.</p>
|
|||
|
|
|
|||
|
|
<p>The Swift programming language is fast, easy-to-use, and works well on Apple silicon. With MLX Swift, you now have a researcher-friendly machine learning framework with the ability to easily experiment on different platforms and devices.</p>
|
|||
|
|
|
|||
|
|
<h3 id="a-quick-tour">A Quick Tour</h3>
|
|||
|
|
|
|||
|
|
<p>Getting <a href="https://ml-explore.github.io/mlx-swift">set up</a> with MLX Swift is quick and easy with Xcode or SwiftPM.</p>
|
|||
|
|
|
|||
|
|
<p>In MLX Swift, building and performing operations with N-dimensional arrays is simple. In the following example, all of the operations will be run on the default device, which is the GPU unless otherwise specified.</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">MLX</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">MLXRandom</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">r</span> <span class="o">=</span> <span class="kt">MLXRandom</span><span class="o">.</span><span class="nf">normal</span><span class="p">([</span><span class="mi">2</span><span class="p">])</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">r</span><span class="p">)</span>
|
|||
|
|
<span class="c1">// array([-0.125875, 0.264235], dtype=float32)</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">a</span> <span class="o">=</span> <span class="kt">MLXArray</span><span class="p">(</span><span class="mi">0</span> <span class="o">..&lt;</span> <span class="mi">6</span><span class="p">,</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">])</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
|||
|
|
<span class="c1">// array([[0, 1],</span>
|
|||
|
|
<span class="c1">// [2, 3],</span>
|
|||
|
|
<span class="c1">// [4, 5]], dtype=int32)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// last element of 0th row</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">])</span>
|
|||
|
|
<span class="c1">// array(1, dtype=int32)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// slice of the first two rows </span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="mi">0</span> <span class="o">..&lt;</span> <span class="mi">2</span><span class="p">])</span>
|
|||
|
|
<span class="c1">// array([[0, 1],</span>
|
|||
|
|
<span class="c1">// [2, 3]], dtype=int32)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// add with broadcast</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">b</span> <span class="o">=</span> <span class="n">a</span> <span class="o">+</span> <span class="n">r</span>
|
|||
|
|
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">b</span><span class="p">)</span>
|
|||
|
|
<span class="c1">// array([[-0.510713, 1.04633],</span>
|
|||
|
|
<span class="c1">// [1.48929, 3.04633],</span>
|
|||
|
|
<span class="c1">// [3.48929, 5.04633]], dtype=float32)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>You can also use function transformations in MLX Swift. Function transformations in MLX are useful for training models with automatic differentiation as well as optimizing compute graphs for speed or memory use. Below is an example which computes the gradient of a function.</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="nf">fn</span><span class="p">(</span><span class="n">_</span> <span class="nv">x</span><span class="p">:</span> <span class="kt">MLXArray</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">MLXArray</span> <span class="p">{</span>
|
|||
|
|
<span class="n">x</span><span class="o">.</span><span class="nf">square</span><span class="p">()</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">gradFn</span> <span class="o">=</span> <span class="nf">grad</span><span class="p">(</span><span class="n">fn</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">x</span> <span class="o">=</span> <span class="kt">MLXArray</span><span class="p">(</span><span class="mf">1.5</span><span class="p">)</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">dfdx</span> <span class="o">=</span> <span class="nf">gradFn</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// prints 2 * 1.5 = 3</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">dfdx</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>The documentation contains a few more complete <a href="https://ml-explore.github.io/mlx-swift/MLX/documentation/mlx/examples">examples</a> to help you get started with MLX Swift:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Text generation with an LLM: A complete LLM text generation example with Mistral 7B. The example will generate text using any Mistral or Llama-style model including pre-quantized MLX models, many of which are available on <a href="https://huggingface.co/models?library=mlx&amp;sort=trending">Hugging Face</a>.</li>
|
|||
|
|
<li>Training an MLP on MNIST: The example trains a simple multi-layer perceptron to classify MNIST digits using the MLX Swift neural network and optimizers packages.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="further-resources">Further Resources</h3>
|
|||
|
|
|
|||
|
|
<p>Here are a few more resources to get started with MLX Swift:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://ml-explore.github.io/mlx-swift">Swift documentation and examples</a></li>
|
|||
|
|
<li><a href="https://github.com/ml-explore/mlx-swift">GitHub repository</a></li>
|
|||
|
|
<li>We encourage you to file an <a href="https://github.com/ml-explore/mlx-swift/issues">issue</a> if you encounter any problems or have suggestions for improvements.</li>
|
|||
|
|
<li>We welcome contributions. If you are interested in contributing to MLX Swift, check out our <a href="https://github.com/ml-explore/mlx-swift/blob/main/CONTRIBUTING.md">contribution guidelines</a>.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift Summer of Code 2023 Summary</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/summer-of-code-2023-summary/"/>
|
|||
|
|
<updated>2024-02-13T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/summer-of-code-2023-summary/</id>
|
|||
|
|
<content type="html"><p>The Swift project regularly participates in <a href="https://summerofcode.withgoogle.com">Google Summer of Code</a> in order to help people new to the open source ecosystem dip their toes in contributing to Swift and its growing ecosystem.</p>
|
|||
|
|
|
|||
|
|
<p>During the 2023 edition of the program, we ran three projects, all of which completed their assigned projects successfully.</p>
|
|||
|
|
|
|||
|
|
<p>The projects in this edition were:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Swift Memcache Library</li>
|
|||
|
|
<li>Incremental Parsing in SwiftParser</li>
|
|||
|
|
<li>Key Path Inference and Diagnostic Improvements</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>We’d like to extend our sincere thanks to the participants and mentors who poured their time and passion into these projects, and use this post to highlight their work to the wider community. Below, each project is described in a small summary.</p>
|
|||
|
|
|
|||
|
|
<p>Let’s take a look at each project, in the words of the mentees and mentors themselves:</p>
|
|||
|
|
|
|||
|
|
<h3 id="swift-memcache">Swift Memcache</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Mentee: <a href="https://github.com/dkz2">Delkhaz Ibrahimi</a></li>
|
|||
|
|
<li>Mentor: <a href="https://github.com/FranzBusch">Franz Busch</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>The goal of the project was to develop a native <a href="https://memcached.org">Memcached</a> connection abstraction for the Swift on Server ecosystem. This connection was implemented using <code class="language-plaintext highlighter-rouge">SwiftNIO,</code> offers native Swift Concurrency APIs and integrates well with the rest of the server ecosystem. The benefit of using Swift Concurrency for building such client is that it can make use of <a href="https://developer.apple.com/videos/play/wwdc2023/10170/">structured concurrency</a> which brings cancellation, executor awareness, and simple integration with <a href="https://github.com/apple/swift-distributed-tracing">distributed tracing</a> in the future.</p>
|
|||
|
|
|
|||
|
|
<p>The focus during the project was implementing the Memcache <a href="https://github.com/memcached/memcached/wiki/MetaCommands">meta command protocol</a> and offering basic <code class="language-plaintext highlighter-rouge">get</code> and <code class="language-plaintext highlighter-rouge">set</code> functionalities.</p>
|
|||
|
|
|
|||
|
|
<p>Below is a short example how the new <code class="language-plaintext highlighter-rouge">MemcacheConnection</code> type can be used to <code class="language-plaintext highlighter-rouge">set</code> and <code class="language-plaintext highlighter-rouge">get</code> a value for a given key:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Instantiate a new MemcacheConnection with host, port, and event loop group</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">memcacheConnection</span> <span class="o">=</span> <span class="kt">MemcacheConnection</span><span class="p">(</span><span class="nv">host</span><span class="p">:</span> <span class="s">"127.0.0.1"</span><span class="p">,</span> <span class="nv">port</span><span class="p">:</span> <span class="mi">11211</span><span class="p">,</span> <span class="nv">eventLoopGroup</span><span class="p">:</span> <span class="o">.</span><span class="n">singleton</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Initialize the service group</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">serviceGroup</span> <span class="o">=</span> <span class="kt">ServiceGroup</span><span class="p">(</span><span class="nv">services</span><span class="p">:</span> <span class="p">[</span><span class="n">memcacheConnection</span><span class="p">],</span> <span class="nv">logger</span><span class="p">:</span> <span class="n">logger</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="k">try</span> <span class="k">await</span> <span class="nf">withThrowingTaskGroup</span><span class="p">(</span><span class="nv">of</span><span class="p">:</span> <span class="kt">Void</span><span class="o">.</span><span class="k">self</span><span class="p">)</span> <span class="p">{</span> <span class="n">group</span> <span class="k">in</span>
|
|||
|
|
<span class="n">group</span><span class="o">.</span><span class="n">addTask</span> <span class="p">{</span> <span class="k">try</span> <span class="k">await</span> <span class="n">serviceGroup</span><span class="o">.</span><span class="nf">run</span><span class="p">()</span> <span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Set a value for a key.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">setValue</span> <span class="o">=</span> <span class="s">"bar"</span>
|
|||
|
|
<span class="k">try</span> <span class="k">await</span> <span class="n">memcacheConnection</span><span class="o">.</span><span class="nf">set</span><span class="p">(</span><span class="s">"foo"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="n">setValue</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Get the value for a key.</span>
|
|||
|
|
<span class="c1">// Specify the expected type for the value returned from Memcache.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">getValue</span> <span class="o">=</span> <span class="k">try</span> <span class="k">await</span> <span class="n">memcacheConnection</span><span class="o">.</span><span class="nf">get</span><span class="p">(</span><span class="s">"foo"</span><span class="p">,</span> <span class="nv">as</span><span class="p">:</span> <span class="kt">String</span><span class="o">.</span><span class="k">self</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>After finishing the foundational work to implement the <code class="language-plaintext highlighter-rouge">get</code> and <code class="language-plaintext highlighter-rouge">set</code> commands, support for <code class="language-plaintext highlighter-rouge">delete</code>, <code class="language-plaintext highlighter-rouge">append</code>, <code class="language-plaintext highlighter-rouge">prepend</code>, <code class="language-plaintext highlighter-rouge">increment</code> and <code class="language-plaintext highlighter-rouge">decrement</code> was added. Lastly, support for checking and updating the time-to-live for keys was added.</p>
|
|||
|
|
|
|||
|
|
<p>The new <code class="language-plaintext highlighter-rouge">MemcacheConnection</code> type lays the ground work to implement a higher-level <code class="language-plaintext highlighter-rouge">MemcacheClient</code> that offers additional functionality such as connection pooling, retries, key distribution across nodes and more. However, implementing such a client was out of scope for this year’s GSoC project.</p>
|
|||
|
|
|
|||
|
|
<p>If you’d like to learn more about this project and Delkhaz’s experience, see <a href="https://forums.swift.org/t/gsoc-2023-swift-memcache-gsoc-project-kickoff/64932">this thread</a> on the Swift forums.</p>
|
|||
|
|
|
|||
|
|
<h3 id="implement-incremental-re-parsing-in-swiftparser">Implement Incremental Re-Parsing in SwiftParser</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Mentee: <a href="https://github.com/StevenWong12">Ziyang Huang</a></li>
|
|||
|
|
<li>Mentor: <a href="https://github.com/ahoppen">Alex Hoppen</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>This project aimed to improve the performance of the <a href="https://github.com/apple/swift-syntax/tree/main/Sources/SwiftParser">SwiftParser</a> for scenarios like editor syntax highlighting, where minor edits are applied to the file. By adding incremental parsing and re-using parts of the syntax tree that remain unchanged, large performance improvements can be made.</p>
|
|||
|
|
|
|||
|
|
<p>The most challenging part of this project was to make sure we parse the source files correctly. Considering the code snippet below:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">foo</span><span class="p">()</span> <span class="p">{}</span>
|
|||
|
|
<span class="nv">someLabel</span><span class="p">:</span> <span class="k">switch</span> <span class="n">x</span> <span class="p">{</span>
|
|||
|
|
<span class="k">default</span><span class="p">:</span> <span class="k">break</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>This source is parsed as a <code class="language-plaintext highlighter-rouge">FunctionCallExprSyntax</code> and a <code class="language-plaintext highlighter-rouge">LabeledStmtSyntax</code>. When we remove the “<code class="language-plaintext highlighter-rouge">switch x</code>” part of this code, a naïve implementation could reuse <code class="language-plaintext highlighter-rouge">foo() {}</code> as a function call since the edit didn’t touch it. But this is not correct since the <code class="language-plaintext highlighter-rouge">someLabel</code> block now became a labeled trailing closure of <code class="language-plaintext highlighter-rouge">foo() {}</code>.</p>
|
|||
|
|
|
|||
|
|
<p>To solve this problem, we collect some additional information for every syntax node during the initial parse to mark the potentially affected range for each node. That information is used to correctly re-parse the <code class="language-plaintext highlighter-rouge">foo()</code> function call and include <code class="language-plaintext highlighter-rouge">someLabel</code> as a labeled trailing closure in the call.</p>
|
|||
|
|
|
|||
|
|
<p>The implementation speeds up parsing by about <strong>10x</strong> when we parse source incrementally while <strong>only incurring a 2~3% of performance loss</strong> during normal parsing.</p>
|
|||
|
|
|
|||
|
|
<p>If you’d like to read more about this project and Ziyang’s experience in his own words, head over to <a href="https://forums.swift.org/t/gsoc-2023-my-gsoc-experience/67340">his GSoC experience post</a> on the Swift forums.</p>
|
|||
|
|
|
|||
|
|
<h3 id="key-path-inference-and-diagnostic-improvements">Key Path Inference and Diagnostic Improvements</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Mentee: <a href="https://github.com/amritpan">Amritpan Kaur</a></li>
|
|||
|
|
<li>Mentor: <a href="https://github.com/xedin?tab=repositories">Pavel Yaskevich</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>This project was focused on performance and diagnostic improvements to type-checking of key path literal expressions as well as improvements to new features such as keypaths-as-functions introduced to the language by <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0249-key-path-literal-function-expressions.md">SE-0249</a>.</p>
|
|||
|
|
|
|||
|
|
<p>During compilation, the key path expression root and value were type-checked sequentially to resolve a key path type from this context. However, the design of the type-checker’s evaluation of key path component types, their relationships to each other, and key path capabilities results in hard to understand compiler errors and even failures to type-check some valid Swift code.</p>
|
|||
|
|
|
|||
|
|
<p>Some of the problems with this approach can be illustrated by the following code example:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">struct</span> <span class="kt">User</span> <span class="p">{</span>
|
|||
|
|
<span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">Name</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="kd">struct</span> <span class="kt">Name</span> <span class="p">{</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">firstName</span><span class="p">:</span> <span class="kt">String</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">func</span> <span class="nf">test</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span> <span class="kt">WritableKeyPath</span><span class="o">&lt;</span><span class="kt">User</span><span class="p">,</span> <span class="kt">String</span><span class="o">&gt;</span><span class="p">)</span> <span class="p">{}</span>
|
|||
|
|
|
|||
|
|
<span class="nf">test</span><span class="p">(\</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">firstName</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>The compiler produces the following error:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">error</span><span class="p">:</span> <span class="n">key</span> <span class="n">path</span> <span class="n">value</span> <span class="n">type</span> <span class="err">'</span><span class="kt">WritableKeyPath</span><span class="o">&lt;</span><span class="kt">User</span><span class="p">,</span> <span class="kt">String</span><span class="o">&gt;</span><span class="err">'</span> <span class="n">cannot</span> <span class="n">be</span> <span class="n">converted</span> <span class="n">to</span> <span class="n">contextual</span> <span class="n">type</span> <span class="err">'</span><span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">User</span><span class="p">,</span> <span class="kt">String</span><span class="o">&gt;</span><span class="err">'</span>
|
|||
|
|
<span class="nf">test</span><span class="p">(\</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">firstName</span><span class="p">)</span>
|
|||
|
|
<span class="o">^</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>There are multiple issues with this error diagnostic: contextual type is actually <code class="language-plaintext highlighter-rouge">WritableKeyPath</code> and key path should be inferred as read-only, the source information is lost and the compiler is unenable to point out a problem with an argument to a call to the function <code class="language-plaintext highlighter-rouge">test</code>.</p>
|
|||
|
|
|
|||
|
|
<p>To address these and other issues, we explored a different design for key path literal expression type-checking: infer the root type of the key path first and propagate that information to the components and infer capability based on the components before setting the type for the key path expression. This made it a lot easier to diagnose contextual type failures and support previously failing conversions. This approach improves the performance as well because the literal is resolved only if the context expects a key path and root type is either provided by the developer explicitly or is able to be inferred from the context.</p>
|
|||
|
|
|
|||
|
|
<p>With the new approach implemented the compiler now produces the following diagnostic:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">error</span><span class="p">:</span> <span class="n">cannot</span> <span class="n">convert</span> <span class="n">value</span> <span class="n">of</span> <span class="n">type</span> <span class="err">'</span><span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">User</span><span class="p">,</span> <span class="kt">String</span><span class="o">&gt;</span><span class="err">'</span> <span class="n">to</span> <span class="n">expected</span> <span class="n">argument</span> <span class="n">type</span> <span class="err">'</span><span class="kt">WritableKeyPath</span><span class="o">&lt;</span><span class="kt">User</span><span class="p">,</span> <span class="kt">String</span><span class="o">&gt;</span><span class="err">'</span>
|
|||
|
|
<span class="nf">test</span><span class="p">(\</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">firstName</span><span class="p">)</span>
|
|||
|
|
<span class="o">^</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>If you’d like to learn more about the details of this project, we recommend having a look at this excellent and <a href="https://forums.swift.org/t/key-path-inference-and-diagnostic-improvements-an-update/69632">very detailed writeup written by Amritpan</a> on the forums.</p>
|
|||
|
|
|
|||
|
|
<h2 id="mentee-impressions">Mentee Impressions</h2>
|
|||
|
|
|
|||
|
|
<p>It’s great to see what projects our GSoC participants accomplished this year! Even better though is seeing participants enjoy their time working with the Swift project, as a big part of Summer of Code is giving mentees (and mentors) a space to grow and learn about open source development.</p>
|
|||
|
|
|
|||
|
|
<p>Here are a few impressions of the mentees about their experience:</p>
|
|||
|
|
|
|||
|
|
<p><strong>Delkhaz (Swift Memcache):</strong></p>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>As we wrap up this technical update, it’s a bittersweet moment for me to share that my formal journey as a Google Summer of Code student has reached its conclusion, but what an incredible journey it’s been. This transformative experience has enriched my understanding of open source development and honed my skills as a developer. I want to extend a heartfelt thank you to everyone who has been a part of this adventure with me.</p>
|
|||
|
|
|
|||
|
|
<p>While this chapter may be closing, I’m thrilled to announce that I will remain actively involved in the project. I’m particularly excited about contributing toward taking this project to its v1 or production stage. So, this isn’t a goodbye; it’s just the beginning of a new chapter. Looking forward to staying in touch and continuing this journey with all of you.</p>
|
|||
|
|
|
|||
|
|
<p>Special thanks are in order for my mentor Franz, for his exceptional mentorship during my time in the program. His wisdom and insights in our weekly sessions have been nothing short of transformative for me as a developer. Whether it was navigating the complexities of open-source contributions or striving for the highest standards in our API development, Franz’s guidance has been indispensable. I’ve gained a multifaceted understanding of software development thanks to his continued support. I couldn’t have asked for a more impactful mentorship experience, and for that, I am deeply grateful.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<p><strong>Ziyang (Implement Incremental Re-Parsing in SwiftParser):</strong></p>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>After measurement, our implementation speed up parsing about 10 times when we parse source incrementally while only bring 2~3% of performance loss to normal parsing. 🎉 🎉</p>
|
|||
|
|
|
|||
|
|
<p>I also bring this feature to sourcekit-lsp and swift-stress-tester, it is really exciting to see my work can be actually put into use.</p>
|
|||
|
|
|
|||
|
|
<p>Special thanks to my mentor Alex for the quick response, detailed reviews and inspiring ideas.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<p><strong>Amritpan (Key Path inference and diagnostic improvements):</strong></p>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>I enjoyed working on this project this year, primarily because it was a challenge that allowed me to deepen my understanding of the solver implementation, utilize improvements I made last year to the debug output, and make more impactful changes to the compiler codebase.</p>
|
|||
|
|
|
|||
|
|
<p>Refactoring the debug output last year helped me understand how the various pieces of information that the type checker collected were then evaluated to assign types from context. Taking a look at key path expression type checking failures revealed some of the fallibilities of the constraint system and solver and how various design decision choices could solve certain issues while causing others.</p>
|
|||
|
|
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<p>We hope this writeup inspires you to either apply to work with us or become a mentor on the Swift project in a future!</p>
|
|||
|
|
|
|||
|
|
<p>We are always looking for ideas, mentors, and general input about how we can make Swift’s ecosystem more inclusive and easier to participate in. If you have some ideas, would like to become a mentor in future editions, or if you’re just curious about other project ideas that were floated during previous editions, visit the <a href="https://forums.swift.org/c/development/gsoc/98">dedicated GSoC category</a> on the Swift forums. You can also check out <a href="https://www.swift.org/blog/swift-summer-of-code-2022-summary/">last year’s GSoC summary blog post</a>, where we highlighted last year’s projects.</p>
|
|||
|
|
|
|||
|
|
<p>If you’re interested in participating as a mentee, keep an eye on the official <a href="https://summerofcode.withgoogle.com/">GSoC schedule</a> and on the Swift forum’s <a href="https://forums.swift.org/c/development/gsoc/98">GSoC category</a>.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift OpenAPI Generator 1.0 Released</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-openapi-generator-1.0/"/>
|
|||
|
|
<updated>2024-01-31T08:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-openapi-generator-1.0/</id>
|
|||
|
|
<content type="html"><p>We’re happy to announce the stable 1.0 release of <a href="https://github.com/apple/swift-openapi-generator">Swift OpenAPI Generator</a>!</p>
|
|||
|
|
|
|||
|
|
<p><a href="https://openapis.org">OpenAPI</a> is an open standard for describing the behavior of HTTP services with a rich ecosystem of tooling. One thing OpenAPI is particularly known for is tooling to generate <em>interactive</em> documentation. But the core motivation of OpenAPI is <em>code-generation</em>, which allows adopters to use an API-first approach to server development and, because many existing services document their API in this format, allows client developers to generate type-safe, idiomatic code to call these APIs.</p>
|
|||
|
|
|
|||
|
|
<!--read more-->
|
|||
|
|
|
|||
|
|
<p>Many real-world APIs have hundreds of operations, each with rich request and response types, header fields, parameters, and more. Writing and maintaining this code for every operation can be repetitive, verbose, and error-prone.</p>
|
|||
|
|
|
|||
|
|
<p>Swift OpenAPI Generator is a Swift package plugin that generates the code required to make API calls and implement API servers. The code is automatically generated at build-time, so it’s always in sync with the OpenAPI document and doesn’t need to be committed to your source repository.</p>
|
|||
|
|
|
|||
|
|
<p>Since the initial <a href="https://www.swift.org/blog/introducing-swift-openapi-generator">release</a> six months ago, the project received over 250 pull requests, from more than 20 contributors, and has gained several new features and a simpler API.</p>
|
|||
|
|
|
|||
|
|
<h2 id="feature-highlights">Feature Highlights</h2>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Works with OpenAPI Specification versions 3.0 and 3.1.</li>
|
|||
|
|
<li>Streaming request and response bodies, backed by AsyncSequence, enabling use cases such as JSON event streams, and large payloads without buffering.</li>
|
|||
|
|
<li>Support for common content types, including JSON, multipart, URL-encoded form, base64, plain text, and raw bytes; all represented as value types with type-safe properties.</li>
|
|||
|
|
<li>Flexible client, server, and middleware abstractions, decoupling the generated code from the HTTP client library and web framework.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="a-quick-look">A Quick Look</h2>
|
|||
|
|
|
|||
|
|
<p>Consider a fictitious HTTP server that provides a single API endpoint to return a personalized greeting:</p>
|
|||
|
|
|
|||
|
|
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">% curl 'https://example.com/api/greet?name=Jane'
|
|||
|
|
{
|
|||
|
|
"message": "Hello, Jane"
|
|||
|
|
}
|
|||
|
|
</span></code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>This service can be described using the following OpenAPI document:</p>
|
|||
|
|
|
|||
|
|
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">openapi</span><span class="pi">:</span> <span class="s1">'</span><span class="s">3.1.0'</span>
|
|||
|
|
<span class="na">info</span><span class="pi">:</span>
|
|||
|
|
<span class="na">title</span><span class="pi">:</span> <span class="s">GreetingService</span>
|
|||
|
|
<span class="na">version</span><span class="pi">:</span> <span class="s">1.0.0</span>
|
|||
|
|
<span class="na">servers</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="na">url</span><span class="pi">:</span> <span class="s">https://example.com/api</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">Example service deployment.</span>
|
|||
|
|
<span class="na">paths</span><span class="pi">:</span>
|
|||
|
|
<span class="na">/greet</span><span class="pi">:</span>
|
|||
|
|
<span class="na">get</span><span class="pi">:</span>
|
|||
|
|
<span class="na">operationId</span><span class="pi">:</span> <span class="s">getGreeting</span>
|
|||
|
|
<span class="na">parameters</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">name</span>
|
|||
|
|
<span class="na">required</span><span class="pi">:</span> <span class="kc">false</span>
|
|||
|
|
<span class="na">in</span><span class="pi">:</span> <span class="s">query</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">The name used in the returned greeting.</span>
|
|||
|
|
<span class="na">schema</span><span class="pi">:</span>
|
|||
|
|
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
|
|||
|
|
<span class="na">responses</span><span class="pi">:</span>
|
|||
|
|
<span class="s1">'</span><span class="s">200'</span><span class="err">:</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">A success response with a greeting.</span>
|
|||
|
|
<span class="na">content</span><span class="pi">:</span>
|
|||
|
|
<span class="na">application/json</span><span class="pi">:</span>
|
|||
|
|
<span class="na">schema</span><span class="pi">:</span>
|
|||
|
|
<span class="na">$ref</span><span class="pi">:</span> <span class="s1">'</span><span class="s">#/components/schemas/Greeting'</span>
|
|||
|
|
<span class="na">components</span><span class="pi">:</span>
|
|||
|
|
<span class="na">schemas</span><span class="pi">:</span>
|
|||
|
|
<span class="na">Greeting</span><span class="pi">:</span>
|
|||
|
|
<span class="na">type</span><span class="pi">:</span> <span class="s">object</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">A value with the greeting contents.</span>
|
|||
|
|
<span class="na">properties</span><span class="pi">:</span>
|
|||
|
|
<span class="na">message</span><span class="pi">:</span>
|
|||
|
|
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">The string representation of the greeting.</span>
|
|||
|
|
<span class="na">required</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="s">message</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Swift OpenAPI Generator can be configured to generate:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Code to make type-safe requests to an API server with any HTTP client library.</li>
|
|||
|
|
<li>Code to bootstrap an HTTP server with any web framework using business logic that is decoupled from the network requests.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="generated-client-api">Generated Client API</h3>
|
|||
|
|
|
|||
|
|
<p>The generated code provides a type, named <code class="language-plaintext highlighter-rouge">Client</code>, which provides a method for each operation defined in the OpenAPI document and can be used with any HTTP library that provides an integration package for Swift OpenAPI Generator.</p>
|
|||
|
|
|
|||
|
|
<p>The plugin produces the generated code at build time in a location determined by the build system. To use the generated code in your project, simply create a <code class="language-plaintext highlighter-rouge">Client</code> by providing the server URL and HTTP transport you’d like to use.</p>
|
|||
|
|
|
|||
|
|
<p>The following example creates a Greeting Service client that uses URLSession to make the underlying HTTP requests.</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">OpenAPIURLSession</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">Foundation</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">client</span> <span class="o">=</span> <span class="kt">Client</span><span class="p">(</span>
|
|||
|
|
<span class="nv">serverURL</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"http://localhost:8080/api"</span><span class="p">)</span><span class="o">!</span><span class="p">,</span>
|
|||
|
|
<span class="nv">transport</span><span class="p">:</span> <span class="kt">URLSessionTransport</span><span class="p">()</span>
|
|||
|
|
<span class="p">)</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">response</span> <span class="o">=</span> <span class="k">try</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="nf">getGreeting</span><span class="p">()</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="k">try</span> <span class="n">response</span><span class="o">.</span><span class="n">ok</span><span class="o">.</span><span class="n">body</span><span class="o">.</span><span class="n">json</span><span class="o">.</span><span class="n">message</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="generated-server-api-stubs">Generated Server API Stubs</h3>
|
|||
|
|
|
|||
|
|
<p>The generated code provides a Swift protocol, named <code class="language-plaintext highlighter-rouge">APIProtocol</code>, which defines a method requirement for each operation defined in the OpenAPI document, and is designed to work with any web framework that provides an integration package for Swift OpenAPI Generator.</p>
|
|||
|
|
|
|||
|
|
<p>To implement an API server, define a type that conforms to <code class="language-plaintext highlighter-rouge">APIProtocol</code>, providing just the business logic for each operation.</p>
|
|||
|
|
|
|||
|
|
<p>To start the API server, use the generated <code class="language-plaintext highlighter-rouge">registerHandlers</code> function to configure the HTTP server to route the HTTP requests to your handler.</p>
|
|||
|
|
|
|||
|
|
<p>The following example implements the Greeting Service API in a type named <code class="language-plaintext highlighter-rouge">Handler</code> and configures a Vapor web server to serve the HTTP requests.</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">OpenAPIRuntime</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">OpenAPIVapor</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">Vapor</span>
|
|||
|
|
|
|||
|
|
<span class="kd">struct</span> <span class="kt">Handler</span><span class="p">:</span> <span class="kt">APIProtocol</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">func</span> <span class="nf">getGreeting</span><span class="p">(</span><span class="n">_</span> <span class="nv">input</span><span class="p">:</span> <span class="kt">Operations</span><span class="o">.</span><span class="n">getGreeting</span><span class="o">.</span><span class="kt">Input</span><span class="p">)</span> <span class="k">async</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">Operations</span><span class="o">.</span><span class="n">getGreeting</span><span class="o">.</span><span class="kt">Output</span> <span class="p">{</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">name</span> <span class="o">=</span> <span class="n">input</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">name</span> <span class="p">??</span> <span class="s">"Stranger"</span>
|
|||
|
|
<span class="k">return</span> <span class="o">.</span><span class="nf">ok</span><span class="p">(</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">body</span><span class="p">:</span> <span class="o">.</span><span class="nf">json</span><span class="p">(</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">message</span><span class="p">:</span> <span class="s">"Hello, </span><span class="se">\(</span><span class="n">name</span><span class="se">)</span><span class="s">!"</span><span class="p">))))</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">@main</span> <span class="kd">struct</span> <span class="kt">Server</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">static</span> <span class="kd">func</span> <span class="nf">main</span><span class="p">()</span> <span class="k">async</span> <span class="k">throws</span> <span class="p">{</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">app</span> <span class="o">=</span> <span class="kt">Vapor</span><span class="o">.</span><span class="kt">Application</span><span class="p">()</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">transport</span> <span class="o">=</span> <span class="kt">VaporTransport</span><span class="p">(</span><span class="nv">routesBuilder</span><span class="p">:</span> <span class="n">app</span><span class="p">)</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">handler</span> <span class="o">=</span> <span class="kt">Handler</span><span class="p">()</span>
|
|||
|
|
<span class="k">try</span> <span class="n">handler</span><span class="o">.</span><span class="nf">registerHandlers</span><span class="p">(</span><span class="nv">on</span><span class="p">:</span> <span class="n">transport</span><span class="p">,</span> <span class="nv">serverURL</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"/api"</span><span class="p">)</span><span class="o">!</span><span class="p">)</span>
|
|||
|
|
<span class="k">try</span> <span class="k">await</span> <span class="n">app</span><span class="o">.</span><span class="nf">execute</span><span class="p">()</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="package-ecosystem">Package Ecosystem</h3>
|
|||
|
|
|
|||
|
|
<p>The Swift OpenAPI Generator project is split across multiple repositories to enable extensibility and minimize dependencies in your project.</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://github.com/apple/swift-openapi-generator">apple/swift-openapi-generator</a>: Swift package plugin and CLI.</li>
|
|||
|
|
<li><a href="https://github.com/apple/swift-openapi-runtime">apple/swift-openapi-runtime</a>: Runtime library used by the generated code.</li>
|
|||
|
|
<li><a href="https://github.com/apple/swift-openapi-urlsession">apple/swift-openapi-urlsession</a>: Client transport using URLSession.</li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-async-http-client">swift-server/swift-openapi-async-http-client</a>: Client transport using AsyncHTTPClient.</li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-vapor">swift-server/swift-openapi-vapor</a>: Server transport using Vapor web framework.</li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-hummingbird">swift-server/swift-openapi-hummingbird</a>: Server transport using Hummingbird web framework.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="next-steps">Next Steps</h2>
|
|||
|
|
|
|||
|
|
<p>To get started, check out the <a href="https://swiftpackageindex.com/apple/swift-openapi-generator/documentation">documentation</a>, which contains <a href="https://swiftpackageindex.com/apple/swift-openapi-generator/tutorials/swift-openapi-generator">step-by-step tutorials</a>.</p>
|
|||
|
|
|
|||
|
|
<p>You can also experiment with <a href="https://github.com/apple/swift-openapi-generator/blob/1.2.0/Examples/README.md">example projects</a> that use Swift OpenAPI Generator and integrate with other packages in the ecosystem.</p>
|
|||
|
|
|
|||
|
|
<p>Or if you prefer to watch a video, check out <a href="https://developer.apple.com/wwdc23/10171">Meet Swift OpenAPI Generator</a> from WWDC23.</p>
|
|||
|
|
|
|||
|
|
<p>To ask a question, request a feature, or report a bug, <a href="https://github.com/apple/swift-openapi-generator/issues/new/choose">reach out to us on Github</a> 👋.</p>
|
|||
|
|
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>On-Crash Backtraces in Swift</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-5.9-backtraces/"/>
|
|||
|
|
<updated>2023-11-08T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-5.9-backtraces/</id>
|
|||
|
|
<content type="html"><p>The new Swift 5.9 release contains a number of helpful, new features for debugging code, including an out-of-process, interactive
|
|||
|
|
crash handler to inspect crashes in real time, the ability to trigger
|
|||
|
|
the debugger for just-in-time debugging, along with concurrency-aware
|
|||
|
|
backtracing to make it easier to understand control flow in a program
|
|||
|
|
that uses structured concurrency.</p>
|
|||
|
|
|
|||
|
|
<h3 id="out-of-process-crash-handling">Out-of-Process Crash Handling</h3>
|
|||
|
|
|
|||
|
|
<p>Prior to Swift 5.9, all you would get when your program fails is a message
|
|||
|
|
from the parent process (often the shell) telling you that the child
|
|||
|
|
process crashed:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight">
|
|||
|
|
<pre class="terminal" style="color:var(--color-term-normal); background:var(--color-term-background)">
|
|||
|
|
<span class="shell">$ </span><span class="cmd">./crash</span>
|
|||
|
|
I&#39;m going to crash now
|
|||
|
|
zsh: segmentation fault ./crash
|
|||
|
|
</pre>
|
|||
|
|
</div></div>
|
|||
|
|
|
|||
|
|
<p>On Apple platforms or on Windows, you could look at the crash logs
|
|||
|
|
captured by the operating system’s built-in crash reporter, but on
|
|||
|
|
Linux that’s typically all you had to go on.</p>
|
|||
|
|
|
|||
|
|
<p>Now, instead of the opaque message above, the result looks something like this:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight">
|
|||
|
|
<pre class="terminal" style="color:var(--color-term-normal); background:var(--color-term-background)">
|
|||
|
|
<span class="shell">$ </span><span class="cmd">./crash</span>
|
|||
|
|
I&#39;m going to crash now
|
|||
|
|
|
|||
|
|
💣 <span style="color:var(--color-term-bright-red)">Program crashed: Bad pointer dereference at 0x0000000000000004</span>
|
|||
|
|
|
|||
|
|
Thread 0 crashed:
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">0</span> <span style="color:var(--color-term-bright-cyan)">reallyCrashMe()</span><span style="color:var(--color-term-white)"> + 404</span> in <span style="color:var(--color-term-bright-magenta)">crash</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crash.swift:4:15</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 2</span>│ print(&quot;I&#39;m going to crash now&quot;)
|
|||
|
|
<span style="color:var(--color-term-gray)"> 3</span>│ let ptr = UnsafeMutablePointer&lt;Int&gt;(bitPattern: 4)!
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 4<span style="color: var(--color-term-bright-white)">│ ptr.pointee = 42</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 5</span>│ }
|
|||
|
|
<span style="color:var(--color-term-gray)"> 6</span>│
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">1</span> <span style="color:var(--color-term-bright-cyan)">crashMe()</span><span style="color:var(--color-term-white)"> + 12</span> in <span style="color:var(--color-term-bright-magenta)">crash</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crash.swift:8:3</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 6</span>│
|
|||
|
|
<span style="color:var(--color-term-gray)"> 7</span>│ func crashMe() {
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 8<span style="color: var(--color-term-bright-white)">│ reallyCrashMe()</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 9</span>│ }
|
|||
|
|
<span style="color:var(--color-term-gray)"> 10</span>│
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">2</span> <span style="color:var(--color-term-bright-cyan)">main</span><span style="color:var(--color-term-white)"> + 12</span> in <span style="color:var(--color-term-bright-magenta)">crash</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crash.swift:11:1</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 9</span>│ }
|
|||
|
|
<span style="color:var(--color-term-gray)"> 10</span>│
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 11<span style="color: var(--color-term-bright-white)">│ crashMe()</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 12</span>│
|
|||
|
|
|
|||
|
|
Press space to interact, D to debug, or any other key to quit (30s)
|
|||
|
|
|
|||
|
|
</pre>
|
|||
|
|
</div></div>
|
|||
|
|
|
|||
|
|
<p>Or if you run the same program within a pipeline (not attached to
|
|||
|
|
a terminal), you’ll see a report like this:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>*** Program crashed: Bad pointer dereference at 0x0000000000000004 ***
|
|||
|
|
|
|||
|
|
Thread 0 crashed:
|
|||
|
|
|
|||
|
|
0 0x00000001045a3df0 reallyCrashMe() + 404 in crash at /Users/alastair/Source/crashDotSwift/crash.swift:4:15
|
|||
|
|
1 [ra] 0x00000001045a3ea4 crashMe() + 12 in crash at /Users/alastair/Source/crashDotSwift/crash.swift:8:3
|
|||
|
|
2 [ra] 0x00000001045a3c50 main + 12 in crash at /Users/alastair/Source/crashDotSwift/crash.swift:11:1
|
|||
|
|
3 [ra] [system] 0x000000018705d058 start + 2224 in dyld
|
|||
|
|
|
|||
|
|
|
|||
|
|
Registers:
|
|||
|
|
|
|||
|
|
x0 0x0000000000000001 1
|
|||
|
|
x1 0x0000000000000000 0
|
|||
|
|
x2 0x0000000000000000 0
|
|||
|
|
x3 0x000060000016c1c0 c0 c1 28 fd 79 96 00 00 fb 07 00 00 00 00 00 00 ÀÁ(ýy···û·······
|
|||
|
|
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
x26 0x0000000000000000 0
|
|||
|
|
x27 0x0000000000000000 0
|
|||
|
|
x28 0x0000000000000000 0
|
|||
|
|
fp 0x000000016b85f310 20 f3 85 6b 01 00 00 00 a4 3e 5a 04 01 00 00 00 ó·k····¤&gt;Z·····
|
|||
|
|
lr 0x72268001045a3d44 8225402511295135044
|
|||
|
|
sp 0x000000016b85f280 a0 f2 85 6b 01 00 00 00 00 00 00 00 00 00 00 00 ò·k············
|
|||
|
|
pc 0x00000001045a3df0 28 01 00 f9 fd 7b 49 a9 ff 83 02 91 c0 03 5f d6 (··ùý{I©ÿ···À·_Ö
|
|||
|
|
|
|||
|
|
|
|||
|
|
Images (42 omitted):
|
|||
|
|
|
|||
|
|
0x00000001045a0000–0x00000001045a4000 6776aba03ad432b68bc57220ac4e6ef8 crash /Users/alastair/Source/crashDotSwift/crash
|
|||
|
|
0x0000000187057000–0x00000001870ea874 ee3f4181cec538c2b8a84d310be33491 dyld /usr/lib/dyld
|
|||
|
|
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>This new feature greatly improves the on-crash debugging experience on Linux, where it is on by default. It is useful on macOS as well, but must be manually
|
|||
|
|
enabled. It is not presently supported on Windows.</p>
|
|||
|
|
|
|||
|
|
<h3 id="interactive-backtraces">Interactive Backtraces</h3>
|
|||
|
|
|
|||
|
|
<p>You might be wondering about the message on the last line of the
|
|||
|
|
in-terminal backtrace above, where it says:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Press space to interact, D to debug, or any other key to quit (30s)
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Often when developing a program at the terminal, you might find that
|
|||
|
|
the program crashes, but you aren’t able to reproduce the problem.
|
|||
|
|
Without a suitable crash log, that can be very frustrating — you know
|
|||
|
|
your program has a bug, but you don’t know what it was or how to
|
|||
|
|
reproduce it.</p>
|
|||
|
|
|
|||
|
|
<p>The idea behind this feature is that it leaves the program suspended
|
|||
|
|
(by default for 30 seconds, but this is configurable) and provides you
|
|||
|
|
with the opportunity to either attach a debugger, or perform some
|
|||
|
|
additional inspection of the crashed process.</p>
|
|||
|
|
|
|||
|
|
<p>If you tap the spacebar when this prompt appears, you will be
|
|||
|
|
presented with a simple command prompt that allows you to change the
|
|||
|
|
backtracer settings, generate a new backtrace, list loaded images,
|
|||
|
|
display register and memory contents, and get a listing of all of the
|
|||
|
|
threads in the process. Typing <code class="language-plaintext highlighter-rouge">help</code> at the prompt will bring up a
|
|||
|
|
list of available commands:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight">
|
|||
|
|
<pre class="terminal" style="color:var(--color-term-normal); background:var(--color-term-background)">
|
|||
|
|
<span style="color:var(--color-term-gray)">&gt;&gt;&gt; </span>help
|
|||
|
|
Available commands:
|
|||
|
|
|
|||
|
|
backtrace Display a backtrace.
|
|||
|
|
bt Synonym for backtrace.
|
|||
|
|
debug Attach the debugger.
|
|||
|
|
exit Exit interaction, allowing program to crash normally.
|
|||
|
|
help Display help.
|
|||
|
|
images List images loaded by the program.
|
|||
|
|
mem Synonym for memory.
|
|||
|
|
memory Inspect memory.
|
|||
|
|
process Show information about the process.
|
|||
|
|
quit Synonym for exit.
|
|||
|
|
reg Synonym for registers.
|
|||
|
|
registers Display the registers.
|
|||
|
|
set Set or show options.
|
|||
|
|
thread Show or set the current thread.
|
|||
|
|
threads Synonym for process.
|
|||
|
|
</pre>
|
|||
|
|
</div></div>
|
|||
|
|
|
|||
|
|
<p>If you use the <code class="language-plaintext highlighter-rouge">debug</code> command or press <code class="language-plaintext highlighter-rouge">D</code> at the prompt, the
|
|||
|
|
backtracer will help you to attach a debugger to your program.
|
|||
|
|
Exactly what happens here is platform-dependent.</p>
|
|||
|
|
|
|||
|
|
<p>If you press any other key, or if the 30 second timer runs down, the
|
|||
|
|
program will be allowed to crash normally.</p>
|
|||
|
|
|
|||
|
|
<p>By default, the interactive feature will trigger if your program’s
|
|||
|
|
standard input and output are both attached to a terminal. In many
|
|||
|
|
cases, this means you’ll get the right behavior automatically if
|
|||
|
|
you’re running in a CI system or as part of an automated script,
|
|||
|
|
as those tend to run with the program’s output redirected to a
|
|||
|
|
pipe or a file.</p>
|
|||
|
|
|
|||
|
|
<p>In situations where you do not want this feature enabled, you can
|
|||
|
|
explicitly disable it by setting the environment variable
|
|||
|
|
<code class="language-plaintext highlighter-rouge">SWIFT_BACKTRACE</code> to <code class="language-plaintext highlighter-rouge">interactive=no</code>. You can also disable the color
|
|||
|
|
output with <code class="language-plaintext highlighter-rouge">color=no</code>, as well as combine multiple options like <code class="language-plaintext highlighter-rouge">interactive=no,color=no</code>.</p>
|
|||
|
|
|
|||
|
|
<h3 id="structured-concurrency-support">Structured Concurrency Support</h3>
|
|||
|
|
|
|||
|
|
<p>The backtracer is concurrency-aware and will correctly step back
|
|||
|
|
through asynchronous frames. For example, given the program:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="nf">level</span><span class="p">(</span><span class="nv">n</span><span class="p">:</span> <span class="kt">Int</span><span class="p">)</span> <span class="k">async</span> <span class="p">{</span>
|
|||
|
|
<span class="k">if</span> <span class="n">n</span> <span class="o">&lt;</span> <span class="mi">5</span> <span class="p">{</span>
|
|||
|
|
<span class="k">await</span> <span class="nf">level</span><span class="p">(</span><span class="nv">n</span><span class="p">:</span> <span class="n">n</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">ptr</span> <span class="o">=</span> <span class="kt">UnsafeMutablePointer</span><span class="o">&lt;</span><span class="kt">Int</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">bitPattern</span><span class="p">:</span> <span class="mi">4</span><span class="p">)</span><span class="o">!</span>
|
|||
|
|
<span class="n">ptr</span><span class="o">.</span><span class="n">pointee</span> <span class="o">=</span> <span class="mi">42</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">@main</span>
|
|||
|
|
<span class="kd">struct</span> <span class="kt">CrashAsync</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">static</span> <span class="kd">func</span> <span class="nf">main</span><span class="p">()</span> <span class="k">async</span> <span class="p">{</span>
|
|||
|
|
<span class="k">await</span> <span class="nf">level</span><span class="p">(</span><span class="nv">n</span><span class="p">:</span> <span class="mi">1</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>the backtrace will look like:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight">
|
|||
|
|
<pre class="terminal" style="color:var(--color-term-normal); background:var(--color-term-background)">
|
|||
|
|
<span class="shell">$ </span><span class="cmd">./crashAsync</span>
|
|||
|
|
|
|||
|
|
💣 <span style="color:var(--color-term-bright-red)">Program crashed: Bad pointer dereference at 0x0000000000000004</span>
|
|||
|
|
|
|||
|
|
Thread 1 crashed:
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">0</span> <span style="color:var(--color-term-bright-cyan)">level(n:)</span><span style="color:var(--color-term-white)"> + 308</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:6:17</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 4</span>│ } else {
|
|||
|
|
<span style="color:var(--color-term-gray)"> 5</span>│ let ptr = UnsafeMutablePointer&lt;Int&gt;(bitPattern: 4)!
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 6<span style="color:var(--color-term-bright-white)">│ ptr.pointee = 42</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 7</span>│ }
|
|||
|
|
<span style="color:var(--color-term-gray)"> 8</span>│ }
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">1</span> <span style="color:var(--color-term-bright-cyan)">level(n:)</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:3</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 1</span>│ func level(n: Int) async {
|
|||
|
|
<span style="color:var(--color-term-gray)"> 2</span>│ if n &lt; 5 {
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 3<span style="color:var(--color-term-bright-white)">│ await level(n: n + 1)</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 4</span>│ } else {
|
|||
|
|
<span style="color:var(--color-term-gray)"> 5</span>│ let ptr = UnsafeMutablePointer&lt;Int&gt;(bitPattern: 4)!
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)">2</span> <span style="color:var(--color-term-bright-cyan)">level(n:)</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:3</span>
|
|||
|
|
<span style="color:var(--color-term-gray)">3</span> <span style="color:var(--color-term-bright-cyan)">level(n:)</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:3</span>
|
|||
|
|
<span style="color:var(--color-term-gray)">4</span> <span style="color:var(--color-term-bright-cyan)">level(n:)</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:3</span>
|
|||
|
|
<span style="color:var(--color-term-gray)">5</span> <span style="color:var(--color-term-bright-cyan)">static CrashAsync.main()</span> in <span style="color:var(--color-term-bright-magenta)">crashAsync</span> at <span style="color:var(--color-term-yellow)">/Users/alastair/Source/crashDotSwift/crashAsync.swift:13</span>
|
|||
|
|
|
|||
|
|
<span style="color:var(--color-term-gray)"> 11</span>│ struct CrashAsync {
|
|||
|
|
<span style="color:var(--color-term-gray)"> 12</span>│ static func main() async {
|
|||
|
|
<span style="background:var(--color-term-highlight-background)"><span style="color:var(--color-term-bright-white)"><span style="color:var(--color-term-gray)"> 13<span style="color:var(--color-term-bright-white)">│ await level(n: 1)</span></span></span> </span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> </span>│ <span style="color:var(--color-term-bright-red)">▲</span>
|
|||
|
|
<span style="color:var(--color-term-gray)"> 14</span>│ }
|
|||
|
|
<span style="color:var(--color-term-gray)"> 15</span>│ }
|
|||
|
|
|
|||
|
|
Press space to interact, D to debug, or any other key to quit (30s)
|
|||
|
|
|
|||
|
|
</pre>
|
|||
|
|
</div></div>
|
|||
|
|
|
|||
|
|
<p>On Apple platforms, this feature has no special requirements, but for
|
|||
|
|
other platforms the backtracer needs to be able to look up symbols
|
|||
|
|
to determine whether or not a given frame is asynchronous. If the
|
|||
|
|
necessary symbols are not available, the backtrace will follow the
|
|||
|
|
normal program stack rather than the async activation chain. This
|
|||
|
|
will usually result in it showing frames from the concurrency runtime,
|
|||
|
|
which are unlikely to be helpful when debugging most types of problem.</p>
|
|||
|
|
|
|||
|
|
<h3 id="improving-readability">Improving Readability</h3>
|
|||
|
|
|
|||
|
|
<p>The new backtracer also has a number of options to improve readability.</p>
|
|||
|
|
|
|||
|
|
<p>You can configure the maximum number of frames that the backtracer
|
|||
|
|
will generate (the default is 64), but since you might also want to
|
|||
|
|
see frames at the top of the stack, the backtracer also has a setting
|
|||
|
|
for the number of frames to capture there (by default 16). This is
|
|||
|
|
particularly handy if your program crashes due to excessive recursion,
|
|||
|
|
as you’ll usually see both the recursion and the cause of it, without
|
|||
|
|
being overwhelmed by thousands and thousands of frames.</p>
|
|||
|
|
|
|||
|
|
<p>The backtracer also skips over system frames and Swift thunks by
|
|||
|
|
default. These are usually not relevant except to compiler or runtime
|
|||
|
|
engineers, and generally result in more confusing output for most
|
|||
|
|
developers.</p>
|
|||
|
|
|
|||
|
|
<p>Additionally, the backtracer will automatically demangle both Swift
|
|||
|
|
and C++ mangled names.</p>
|
|||
|
|
|
|||
|
|
<h3 id="summary">Summary</h3>
|
|||
|
|
|
|||
|
|
<p>The new on-crash debugging options in Swift 5.9 help you
|
|||
|
|
debug your programs when they misbehave. The backtracer has a
|
|||
|
|
number of helpful features including:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Out-of-process crash handling</li>
|
|||
|
|
<li>Smart, in-line display of program source, where available</li>
|
|||
|
|
<li>The option to pause and inspect your crashed program, or even
|
|||
|
|
trigger the debugger for just-in-time debugging</li>
|
|||
|
|
<li>Support for Swift Concurrency</li>
|
|||
|
|
<li>Support for C++ name mangling in addition to Swift</li>
|
|||
|
|
<li>Colorized output for readability</li>
|
|||
|
|
<li>Expanded configuration options (<a href="https://github.com/apple/swift/blob/main/docs/Backtracing.rst">see
|
|||
|
|
documentation</a>).</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>The new feature is enabled by default on Linux and can be enabled for macOS (<a href="https://github.com/apple/swift/blob/main/docs/Backtracing.rst">see
|
|||
|
|
documentation</a>).
|
|||
|
|
There is no Windows support at present.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Introducing Packages on Swift.org</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/packages-page/"/>
|
|||
|
|
<updated>2023-11-01T06:30:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/packages-page/</id>
|
|||
|
|
<content type="html"><p>Today, Swift.org gains a useful, new <a href="/packages">top-level Packages page</a>.</p>
|
|||
|
|
|
|||
|
|
<p>The page provides a streamlined entry to exploring the Swift package ecosystem. It has common categories like <a href="/packages/server.html">server</a>, <a href="/packages/networking.html">networking</a>, <a href="/packages/testing.html">testing</a>, and <a href="/packages/logging.html">logging</a>, as well as categories of interest like <a href="/packages/macros.html">packages containing macros</a>. When you select a category, it provides a sample of some widely-used packages for that category, with information to help you explore further. It’s a great way to get a sense of the variety of packages available for Swift.</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/packages-page-blog/package-categories.png" alt="A screenshot of the packages page, showing four individual package cards in a grid" style="border: 1px solid #ddd;" />
|
|||
|
|
<em>The package lists give you relevant information at a glance.</em></p>
|
|||
|
|
|
|||
|
|
<p>The package lists are powered by the <a href="https://swiftpackageindex.com/">Swift Package Index</a>, thanks to the <a href="/blog/swift-package-index-developer-spotlight/">sponsorship and support of Apple</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="community-showcase">Community Showcase</h2>
|
|||
|
|
|
|||
|
|
<p>In addition to finding common categories of packages, you can also browse new and interesting work from across the Swift package ecosystem with the <a href="/packages/showcase.html">Community Showcase</a>.</p>
|
|||
|
|
|
|||
|
|
<p>The Community Showcase contains a rotating selection of packages being discussed by the Swift community. Anyone can nominate a package in <a href="https://forums.swift.org/t/nominations-for-the-packages-community-showcase-on-swift-org/68168">this forum thread</a>, and nominations will be reviewed monthly by the <a href="/website-workgroup/">Swift Website Workgroup</a>.</p>
|
|||
|
|
|
|||
|
|
<p>The new <a href="/packages">Packages page</a> is an exciting step in growing a valuable and thriving package ecosystem for the benefit of all Swift developers.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift Everywhere: Using Interoperability to Build on Windows</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-everywhere-windows-interop/"/>
|
|||
|
|
<updated>2023-10-13T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-everywhere-windows-interop/</id>
|
|||
|
|
<content type="html"><p><em>This post was originally published at <a href="https://speakinginswift.substack.com/p/interoperability-swifts-super-power">Speaking in Swift by The Browser Company</a> under the title “Interoperability: Swift’s Super Power”.</em></p>
|
|||
|
|
|
|||
|
|
<hr />
|
|||
|
|
|
|||
|
|
<p>Swift’s deliberate design choices over the years has resulted in a language that showcases how flexibility and compatibility does not need to come at the cost of usability. One of these design choices was Swift’s focus on native interoperability with other languages. The flexibility that this enables makes it a joy to build rich, native experiences in Swift across a variety of environments.</p>
|
|||
|
|
|
|||
|
|
<p>Traditionally when two languages need to interoperate, the function calls at the boundary between the two languages, also known as the Foreign Function Interface (FFI), will go through C using a library like libffi. This approach has some drawbacks such as incurred runtime performance costs and possibly extra boilerplate code. Instead, Swift embeds a copy of clang, the C and C++ compiler, which is able to directly translate between the languages avoiding penalties in code size and runtime performance. This level of interoperability composes wonderfully with existing systems and enables building complex software atop existing C libraries.</p>
|
|||
|
|
|
|||
|
|
<h2 id="the-windows-api">The Windows API</h2>
|
|||
|
|
|
|||
|
|
<p>When building native rich, native applications, one important use-case of interoperability is the ability to invoke platform-specific APIs. The Windows API surface reflects its extensive history; the requirement to maintain backwards compatibility has resulted in the accretion of APIs of different shapes. As such, a significant portion of the API is old and low-level enough to be defined in C.</p>
|
|||
|
|
|
|||
|
|
<p>Since Swift uses clang rather than libffi to access C functions and data types, the Swift compiler uses a feature of clang known as (header) modules. Clang modules bundle a set of declarations together, identifying which declarations belong to a particular library, what other modules it may depend on, and what language the declarations are for. This is done by introducing an auxiliary file named <code class="language-plaintext highlighter-rouge">module.modulemap</code> which contains the definition of the module.</p>
|
|||
|
|
|
|||
|
|
<p>As such, to access the Windows APIs, we must modularize the Windows SDK into one or more clang modules. Fortunately this is not just a theoretical idea. The Swift toolchain contains a module definition for the Windows SDK in the form of the <code class="language-plaintext highlighter-rouge">WinSDK</code> clang module. To further refine these definitions, a Swift module overlays the clang definitions to provide more Swift friendly definitions in some cases. This exposes the C API surface area of the Windows SDK, and although does not contain all the more modern APIs, enables us to build a variety of command line and GUI apps on Windows.</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/windows-interoperability-blog/swift-win32-gui-app.webp" alt="A screenshot of a GUI application written using Swift/Win32, showing various standard controls" style="max-width: 100%; height: auto; width: unset; margin: auto auto; display: block;" />
|
|||
|
|
<em>A GUI application using Swift/Win32, which provides a layer of Swift syntactic conveniences for older, C-based Windows UI APIs.</em></p>
|
|||
|
|
|
|||
|
|
<p>Modern APIs aren’t exposed using just C, however, and there are large portions of the Windows SDK which are exposed as C++. Realising there is a vast software ecosystem of C++ code that Swift developers may want access to, Swift 5.9 has introduced support for extending its language level interoperability to C++. Although virtual methods and copyable types are not yet available, as Swift’s C++ interoperability matures, the native platform API surface available to Swift will also grow to include the majority of the C++ APIs in the Windows SDK.</p>
|
|||
|
|
|
|||
|
|
<p>This C++ Interop enables a new set of libraries, beyond just the platform APIs, to become available to Swift. This allows Swift code to also take advantage of a variety of high-performance, cross-platform libraries written over decades by the C++ community. Firebase, for example, is a commonly used cloud computing service and is used in many modern products, including The Browser Company’s browser, Arc. Although there is a Swift SDK for Firebase, it is limited to the Apple platforms and is based on Objective-C. However, there is also a cross-platform C++ SDK available. Now with C++ Interop, it is possible to expose this C++ SDK to Swift clients. Such a bridge is being built up with <a href="https://github.com/compnerd/swift-firebase">swift-firebase</a>. Taking advantage of these C++ libraries cross-platform Swift software that would be difficult to build otherwise.</p>
|
|||
|
|
|
|||
|
|
<h2 id="component-object-model-com">Component Object Model (COM)</h2>
|
|||
|
|
|
|||
|
|
<p>While libraries are one mechanism for sharing code, they are not the only approach. Another style of code sharing is possible via inter-process communication (IPC), which allows two separate applications to communicate with each other and expose functionality to each other. One implementation of this technique that is prevalent on Windows is known as COM (Component Object Model).</p>
|
|||
|
|
|
|||
|
|
<p>Microsoft explored this idea at a higher level in 1990, evolving DDE (Dynamic Data Exchange) into “Object Linking and Embedding” or OLE. The approach was to enable sharing of custom document handlers which could be embedded into new applications without having to rewrite parsers and renders for the formats. To share the implementation of applications across processes, an application could implement well-defined interfaces (e.g. <code class="language-plaintext highlighter-rouge">IOleObject</code>) that could be consumed by other processes. Eventually, OLE would evolve into what would become to be known as the Component Object Model, or COM.</p>
|
|||
|
|
|
|||
|
|
<p>COM’s design was flexible and powerful, and resulted in it being adopted as a common design pattern across a multitude of environments. CoreFoundation adopted it for its plugin model. CFLite, and various forks thereof, brought an implementation of COM to Linux. XPCOM (Cross-Platform Component Object Model) is similar to COM and would gain popularity through Mozilla’s extensive usage, as would Open Office’s UNO technology. The model even found its way into driver development with the IOKit framework using a COM based model for kernel drivers.</p>
|
|||
|
|
|
|||
|
|
<p>At COM’s core is the idea of defining interfaces (which is normally done in the Interface Definition Language or IDL) that expose functionality to either through a library in the same address space or another process through IPC. Interfaces are identified by globally unique Interface IDs, and all inherit from a base interface called <code class="language-plaintext highlighter-rouge">IUnknown</code>. <code class="language-plaintext highlighter-rouge">IUnknown</code> exposes the two fundamental operations of COM:</p>
|
|||
|
|
|
|||
|
|
<ol>
|
|||
|
|
<li>object lifetime management</li>
|
|||
|
|
<li>access to the object’s functionality</li>
|
|||
|
|
</ol>
|
|||
|
|
|
|||
|
|
<p>Similar to Swift, object lifetime management is implemented through reference counting, exposed in COM via the <code class="language-plaintext highlighter-rouge">AddRef</code> and <code class="language-plaintext highlighter-rouge">Release</code> methods. Access to the object’s functionality is implemented via the <code class="language-plaintext highlighter-rouge">QueryInterface</code> method, allowing consumers to dynamically request for the object’s functionality. Because consumers dynamically query for a specific COM interface, we cannot statically identify the operations at build time. But the cost is limited to a couple of pointer indirections, similar to C++’s virtual methods, which gives COM a negligible performance overhead.</p>
|
|||
|
|
|
|||
|
|
<h2 id="com-support-in-swift-with-c-interop">COM Support in Swift with C Interop</h2>
|
|||
|
|
|
|||
|
|
<p>COM provides not only an interface for working with software dynamically but is also an Application Binary Interface, or ABI, which means it defines how parameters are passed and function calls are arranged. If we want to communicate with COM interfaces from Swift, we need to ensure that we conform to these ABI requirements. Given that the lingua franca for FFI is C, the ABI for COM can be expressed in C. So, as a first step, what does <code class="language-plaintext highlighter-rouge">IUnknown</code> look like in C?</p>
|
|||
|
|
|
|||
|
|
<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">typedef</span> <span class="k">struct</span> <span class="n">IUnknownVtbl</span> <span class="p">{</span>
|
|||
|
|
<span class="n">ULONG</span> <span class="p">(</span><span class="n">STDMETHODCALLTYPE</span> <span class="o">*</span><span class="n">AddRef</span><span class="p">)(</span><span class="n">IUnknown</span> <span class="o">*</span><span class="n">pUnk</span><span class="p">);</span>
|
|||
|
|
<span class="n">ULONG</span> <span class="p">(</span><span class="n">STDMETHODCALLTYPE</span> <span class="o">*</span><span class="n">Release</span><span class="p">)(</span><span class="n">IUnknown</span> <span class="o">*</span><span class="n">pUnk</span><span class="p">);</span>
|
|||
|
|
<span class="n">HRESULT</span> <span class="p">(</span><span class="n">STDMETHODCALLTYPE</span> <span class="o">*</span><span class="n">QueryInterface</span><span class="p">)(</span><span class="n">IUnknown</span> <span class="o">*</span><span class="n">pUnk</span><span class="p">,</span> <span class="n">REFIID</span> <span class="n">riid</span><span class="p">,</span> <span class="kt">void</span> <span class="o">**</span><span class="n">ppvObject</span><span class="p">);</span>
|
|||
|
|
<span class="p">}</span> <span class="n">IUnknownVtbl</span><span class="p">;</span>
|
|||
|
|
|
|||
|
|
<span class="k">struct</span> <span class="n">IUnknown</span> <span class="p">{</span>
|
|||
|
|
<span class="k">const</span> <span class="k">struct</span> <span class="n">IUnknownVtbl</span> <span class="o">*</span><span class="n">lpVtbl</span><span class="p">;</span>
|
|||
|
|
<span class="p">}</span> <span class="n">IUnknown</span><span class="p">;</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>If we were to describe this in Swift, we would expect this to be a protocol with a few constraints:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// typealias IID = WinSDK._GUID</span>
|
|||
|
|
|
|||
|
|
<span class="kd">public</span> <span class="kd">typealias</span> <span class="kt">REFIID</span> <span class="o">=</span> <span class="kt">UnsafePointer</span><span class="o">&lt;</span><span class="kt">IID</span><span class="o">&gt;</span>
|
|||
|
|
|
|||
|
|
<span class="kd">public</span> <span class="kd">protocol</span> <span class="kt">IUnknown</span><span class="p">:</span> <span class="kd">class</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">class</span> <span class="k">var</span> <span class="nv">IID</span><span class="p">:</span> <span class="kt">IID</span> <span class="p">{</span> <span class="k">get</span> <span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">func</span> <span class="kt">AddRef</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">ULONG</span>
|
|||
|
|
<span class="kd">func</span> <span class="kt">Release</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">ULONG</span>
|
|||
|
|
<span class="kd">func</span> <span class="kt">QueryInterface</span><span class="p">(</span><span class="n">_</span> <span class="nv">riid</span><span class="p">:</span> <span class="kt">REFIID</span><span class="p">,</span> <span class="n">_</span> <span class="nv">ppvObject</span><span class="p">:</span> <span class="kt">UnsafeMutablePointer</span><span class="o">&lt;</span><span class="kt">UnsafeMutableRawPointer</span><span class="p">?</span><span class="o">&gt;</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">HRESULT</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">extension</span> <span class="kt">IUnknown</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">func</span> <span class="kt">QueryInterface</span><span class="o">&lt;</span><span class="kt">Interface</span><span class="p">:</span> <span class="kt">IUnknown</span><span class="o">&gt;</span><span class="p">()</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">Interface</span><span class="p">?</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">: class</code> on the protocol declaration adds a class-constraint on the protocol, indicating that any conforming type must be a class in Swift. The astute reader would spot the semantic parallels between <code class="language-plaintext highlighter-rouge">IUnknown</code> and class-constrained types in Swift. <code class="language-plaintext highlighter-rouge">class</code> types in Swift employ reference counting through ARC, and COM does the same through MRC (manual reference counting), which explains the <code class="language-plaintext highlighter-rouge">AddRef</code> and <code class="language-plaintext highlighter-rouge">Release</code> methods. That leaves the <code class="language-plaintext highlighter-rouge">QueryInterface</code> method which is responsible for dynamically querying the COM Interface, which maps to Swift’s casting operation. As it is not possible to provide a custom cast operation for a type in Swift, the <code class="language-plaintext highlighter-rouge">QueryInterface()</code> method is a funny spelling for the as keyword. This shows that, conceptually, <code class="language-plaintext highlighter-rouge">IUnknown</code> is just another way to say “I have a class type in Swift that is implemented somewhere else”!</p>
|
|||
|
|
|
|||
|
|
<p>Since COM concepts bridge so neatly to Swift, we can now build a bridge between COM and Swift. The associated code is available at <a href="https://github.com/compnerd/swift-com">Swift/COM</a> and demonstrates the viability of interfacing with COM interfaces. As an example, Windows provides 3D acceleration through the DirectX APIs, which are exposed as a set of C++ and COM interfaces. <a href="https://github.com/compnerd/DXSample">DXSample</a> uses the COM bridged interfaces to implement a 3D accelerated cube replete with shaders to demonstrate that this bridging is possible to accomplish and use in real world scenarios.</p>
|
|||
|
|
|
|||
|
|
<p>Interfaces provide a definition of how you interact with some foreign type, one that may even be implemented in a different language. When using an interface implemented by someone else, such as a DirectX type, we receive a raw pointer to <code class="language-plaintext highlighter-rouge">IUnknown</code>. The raw pointer representation of the COM interface is cumbersome to use. Wrapping the pointer to abstract the indirection makes COM more approachable.</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">open</span> <span class="kd">class</span> <span class="kt">ID3D12Object</span><span class="p">:</span> <span class="kt">IUnknown</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">public</span> <span class="k">override</span> <span class="kd">class</span> <span class="k">var</span> <span class="nv">IID</span><span class="p">:</span> <span class="kt">IID</span> <span class="p">{</span> <span class="kt">IID_ID3D12Object</span> <span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="kd">public</span> <span class="kd">func</span> <span class="kt">SetName</span><span class="p">(</span><span class="n">_</span> <span class="kt">Name</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="k">throws</span> <span class="p">{</span>
|
|||
|
|
<span class="n">_</span> <span class="o">=</span> <span class="k">try</span> <span class="nf">perform</span><span class="p">(</span><span class="nv">as</span><span class="p">:</span> <span class="kt">WinSDK</span><span class="o">.</span><span class="kt">ID3D12Object</span><span class="o">.</span><span class="k">self</span><span class="p">)</span> <span class="p">{</span> <span class="n">pThis</span> <span class="k">in</span>
|
|||
|
|
<span class="k">try</span> <span class="kt">CHECKED</span><span class="p">(</span><span class="n">pThis</span><span class="o">.</span><span class="n">pointee</span><span class="o">.</span><span class="n">lpVtbl</span><span class="o">.</span><span class="n">pointee</span><span class="o">.</span><span class="kt">SetName</span><span class="p">(</span><span class="n">pThis</span><span class="p">,</span> <span class="nv">$0</span><span class="p">))</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="err">…</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>It is also possible to implement a COM interface in Swift, providing a Swift implementation that can be called from C/C++ code even, although this support is nascent and will evolve with Swift’s C++ interoperability support. As COM has a strict ABI, once the object is constructed properly, it can easily be passed across the language boundary and, as such, a Swift type can easily be passed to any COM client.</p>
|
|||
|
|
|
|||
|
|
<h2 id="com-support-in-swift-with-c-interop-1">COM Support in Swift with C++ Interop</h2>
|
|||
|
|
|
|||
|
|
<p>The evolving C++ interop in Swift makes bridging COM to Swift simpler. The interface model in COM is very similar to classes in C++. A COM interface maps directly to a C++ class, and each function on a COM interface maps to a virtual method on the C++ type. For Windows APIs exposed as COM types, such as the DirectX APIs, the COM interfaces are primarily exposed as C++ classes with some optionality to get a C representation of the interface for bridging into other languages. As Swift’s C++ interoperability support improves, it will be possible to import COM interfaces as C++ classes which bridge naturally to Swift types. This reduces the boilerplate we saw above when bridging to COM through C. As of this writing, Swift’s C++ interop support for virtual method dispatch is under development and will soon be able to simplify COM access.</p>
|
|||
|
|
|
|||
|
|
<p>Swift’s work on C++ interoperability has helped our efforts to bridge Swift with COM in other ways as well, adding support for reference-counted foreign types in Swift with the <code class="language-plaintext highlighter-rouge">SWIFT_SHARED_REFERENCE</code> annotation. Because COM provides a reference counted interface, we can attribute COM interfaces with <code class="language-plaintext highlighter-rouge">SWIFT_SHARED_REFERENCE</code> to take advantage of ARC while importing types and get memory management for free, avoiding a class of memory safety issues.</p>
|
|||
|
|
|
|||
|
|
<h2 id="improving-swift-language-support-for-com">Improving Swift Language Support for COM</h2>
|
|||
|
|
|
|||
|
|
<p>Due to the current limitations with C++ interop, we must fallback to the common denominator for interop - C - when trying to bridge COM interfaces. When implementing wrapper types to work with COM interfaces, we notice that it requires a significant amount of boilerplate code. One of Swift’s goals is to have clear, expressive code and this certainly takes away from that. An idea that merits a proper evolution proposal is extending the Swift language to support COM better through annotations. Imagine being able to declare a type as being accessible to COM by simply annotating it with an attribute as the follows:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@COM</span><span class="p">(</span><span class="kt">IID</span><span class="p">:</span> <span class="kt">IID_ICustomInterface</span><span class="p">,</span> <span class="kt">CLSID</span><span class="p">:</span> <span class="kt">CLSID_CustomInterface</span><span class="p">)</span>
|
|||
|
|
<span class="kd">open</span> <span class="kd">class</span> <span class="kt">CCustomInterface</span><span class="p">:</span> <span class="kt">ICustomInterface</span> <span class="p">{</span>
|
|||
|
|
<span class="k">override</span> <span class="kd">open</span> <span class="kd">func</span> <span class="kt">QueryInterface</span><span class="o">&lt;</span><span class="kt">Interface</span><span class="p">:</span> <span class="kt">IUnknown</span><span class="o">&gt;</span><span class="p">()</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">Interface</span><span class="p">?</span> <span class="p">{</span>
|
|||
|
|
<span class="k">switch</span> <span class="n">riid</span><span class="o">.</span><span class="n">pointee</span> <span class="p">{</span>
|
|||
|
|
<span class="k">case</span> <span class="kt">IID_ICustomInterface</span><span class="p">,</span> <span class="kt">IID_IUnknown</span><span class="p">:</span>
|
|||
|
|
<span class="k">return</span> <span class="kt">Unmanaged</span><span class="o">&lt;</span><span class="k">Self</span><span class="o">&gt;.</span><span class="nf">passRetained</span><span class="p">(</span><span class="k">self</span><span class="p">)</span>
|
|||
|
|
<span class="k">default</span><span class="p">:</span>
|
|||
|
|
<span class="k">return</span> <span class="kc">nil</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="err">…</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Swift macros could help alleviate some of this boilerplate, but in order to truly bridge the Swift type into COM, the object layout needs to be considered. Because COM is an ABI, how the object is represented in memory must be identical to that dictated by COM. Controlling the object layout impacts ABI and is not something that would be possible with macros alone. One way we could implement this COM attribute at the language level would be to add a tear-off entry to the object that would conform to the ABI requirements for COM as part of the Swift object layout (with an opt-in) enabling more transparent bridging to the system without having to manually re-construct the vtable.</p>
|
|||
|
|
|
|||
|
|
<p>Swift’s ongoing distributed actors work also aligns well with COM. Distributed COM (DCOM) allows for network transparency with COM objects and enables building robust distributed systems. Distributed actors do not mandate the wire format, which means that we could even re-use the standard wire protocol for DCOM (DCE/RPC). This would allow for native Swift applications on Windows to easily scale from command line applications to large scale distributed systems.</p>
|
|||
|
|
|
|||
|
|
<h2 id="interoperability-on-windows">Interoperability on Windows</h2>
|
|||
|
|
|
|||
|
|
<p>Swift’s arsenal of interoperability tools makes it a potent language for building rich, native applications and libraries on existing platforms, and provides a great alternative to C and C++ with its improved memory safety and ergonomics. On Windows particularly, the interoperability features allow us to gain access to a very large set of the system’s API. Best of all, since COM is used outside of the Windows ecosystem, improvements to Swift’s integration with Windows system APIs, such as the native COM bridging described above, would also help other platforms! New features such as C++ Interoperability, macros, and distributed actors are opening up a whole new set of opportunities for applications to be written in a more portable fashion.</p>
|
|||
|
|
|
|||
|
|
<p>This foray into Windows and our exploration of Swift’s approach to interoperability has given us a good foundation on how Swift’s interoperability tools allow us to build cross-platform applications that can access platform APIs.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Debugging Improvements in Swift 5.9</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/whats-new-swift-debugging-5.9/"/>
|
|||
|
|
<updated>2023-09-28T07:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/whats-new-swift-debugging-5.9/</id>
|
|||
|
|
<content type="html"><p>Swift 5.9 introduced a number of new debugging features to the compiler and <a href="https://lldb.llvm.org/" title="LLDB project home page">LLDB</a> debugger.</p>
|
|||
|
|
|
|||
|
|
<p>Here are three changes that can help with your everyday debugging workflows.</p>
|
|||
|
|
|
|||
|
|
<h3 id="faster-variable-inspection-with-p-and-po">Faster variable inspection with <code class="language-plaintext highlighter-rouge">p</code> and <code class="language-plaintext highlighter-rouge">po</code></h3>
|
|||
|
|
|
|||
|
|
<p>LLDB provides the shorthand <code class="language-plaintext highlighter-rouge">p</code> command alias to inspect variables and <code class="language-plaintext highlighter-rouge">po</code> to call the debugDescription property of objects. Originally, these were aliases for the rather heavyweight <code class="language-plaintext highlighter-rouge">expression</code> and <code class="language-plaintext highlighter-rouge">expression -O</code> commands. In Swift 5.9, the <code class="language-plaintext highlighter-rouge">p</code> and <code class="language-plaintext highlighter-rouge">po</code> command aliases have been redefined to the new <a href="https://reviews.llvm.org/D138315" title="LLVM review"><code class="language-plaintext highlighter-rouge">dwim-print</code> command</a>.</p>
|
|||
|
|
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">dwim-print</code> command prints values using the most user-friendly implementation. “DWIM” is an acronym for “Do What I Mean”. Specifically, when printing variables, <code class="language-plaintext highlighter-rouge">dwim-print</code> will use the same implementation as <code class="language-plaintext highlighter-rouge">frame variable</code> or <code class="language-plaintext highlighter-rouge">v</code> instead of the more expensive expression evaluator.</p>
|
|||
|
|
|
|||
|
|
<p>In addition to being faster, using <code class="language-plaintext highlighter-rouge">p</code> <a href="https://reviews.llvm.org/D145609" title="LLVM review">no longer creates persistent result variables</a> like <code class="language-plaintext highlighter-rouge">$R0</code>, which are often unused in debugging sessions. Persistent result variables not only incur overhead but also retain any objects they contain, which can be an unexpected side effect for the program execution.</p>
|
|||
|
|
|
|||
|
|
<p>Users who want persistent results on occasion can use <code class="language-plaintext highlighter-rouge">expression</code> (or a unique prefix such as <code class="language-plaintext highlighter-rouge">expr</code>) directly instead of <code class="language-plaintext highlighter-rouge">p</code>. If you wish to enable persistent results every time, you can take advantage of LLDB’s handy alias feature and put the following into the <code class="language-plaintext highlighter-rouge">~/.lldbinit</code> file:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>command unalias p
|
|||
|
|
command alias p dwim-print --persistent-result on --
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">dwim-print</code> command also gives <code class="language-plaintext highlighter-rouge">po</code> new functionality. The <code class="language-plaintext highlighter-rouge">po</code> command can now print Swift objects <em>even when only given a raw address</em>. When running <code class="language-plaintext highlighter-rouge">po &lt;object-address&gt;</code>, LLDB’s embedded Swift compiler will automatically evaluate the expression <code class="language-plaintext highlighter-rouge">unsafeBitCast(&lt;object-address&gt;, to: AnyObject.self)</code> under the hood to produce the expected result.</p>
|
|||
|
|
|
|||
|
|
<p>Before Swift 5.9:</p>
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>(lldb) po 0x00006000025c43d0
|
|||
|
|
(Int) 105553155867600
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>With Swift 5.9:</p>
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>(lldb) po 0x00006000025c43d0
|
|||
|
|
&lt;MyApp.AppDelegate: 0x6000025c43d0&gt;
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="support-for-generic-type-parameters-in-expressions">Support for generic type parameters in expressions</h3>
|
|||
|
|
|
|||
|
|
<p>LLDB now supports referring to generic type parameters in expression evaluation. For example, given the following code:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="n">use</span><span class="o">&lt;</span><span class="kt">T</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">t</span><span class="p">:</span> <span class="kt">T</span><span class="p">)</span> <span class="p">{</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">t</span><span class="p">)</span> <span class="c1">// break here</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="nf">use</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
|
|||
|
|
<span class="nf">use</span><span class="p">(</span><span class="s">"Hello!"</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Running <code class="language-plaintext highlighter-rouge">po T.self</code>, when stopped in <code class="language-plaintext highlighter-rouge">use</code>, will print <code class="language-plaintext highlighter-rouge">Int</code> when coming in through the first call, and <code class="language-plaintext highlighter-rouge">String</code> in the second.</p>
|
|||
|
|
|
|||
|
|
<p>In addition to displaying the concrete type of the generic, you can use this to set conditions that look for concrete types. For example, if you add the condition <code class="language-plaintext highlighter-rouge">T.self == String.self</code> to the above breakpoint, <code class="language-plaintext highlighter-rouge">use</code> will only stop when the variable <code class="language-plaintext highlighter-rouge">t</code> is a <code class="language-plaintext highlighter-rouge">String</code>. (Note this last example only works on nightly builds of the Swift 5.9 toolchain.)</p>
|
|||
|
|
|
|||
|
|
<p>More details about the implementation of this feature can be found in the original <a href="https://github.com/apple/llvm-project/pull/5715">LLDB pull request</a>.</p>
|
|||
|
|
|
|||
|
|
<h3 id="fine-grained-scope-information">Fine-grained scope information</h3>
|
|||
|
|
|
|||
|
|
<p>The Swift compiler now emits more precise lexical scopes in debug information, allowing the debugger to better distinguish between different variables, like the many variables named <code class="language-plaintext highlighter-rouge">x</code> in the following example:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="nf">f</span><span class="p">(</span><span class="nv">x</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">?)</span> <span class="p">{</span>
|
|||
|
|
<span class="c1">// function parameter `x: AnyObject?`</span>
|
|||
|
|
<span class="k">guard</span> <span class="k">let</span> <span class="nv">x</span> <span class="k">else</span> <span class="p">{}</span>
|
|||
|
|
<span class="c1">// local variable `x: AnyObject`, which shadows the function argument `x`</span>
|
|||
|
|
<span class="o">...</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>In Swift 5.9, the compiler now uses more accurate <code class="language-plaintext highlighter-rouge">ASTScope</code> information to generate the lexical scope hierarchy in the debug information, which results in some behavior changes in the debugger.</p>
|
|||
|
|
|
|||
|
|
<p>In the example below, the local variable <code class="language-plaintext highlighter-rouge">a</code> is not yet in scope at the call site of <code class="language-plaintext highlighter-rouge">getInt()</code> and will only be available after it has been assigned. With the debug information produced by previous versions of the Swift compiler, the debugger might have displayed uninitialized memory as the contents of <code class="language-plaintext highlighter-rouge">a</code> at the call site of <code class="language-plaintext highlighter-rouge">getInt()</code>. In Swift 5.9, the variable <code class="language-plaintext highlighter-rouge">a</code> only becomes visible after it has been initialized:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> 1 func getInt() -&gt; Int { return 42 }
|
|||
|
|
2
|
|||
|
|
3 func f() {
|
|||
|
|
4 let a = getInt()
|
|||
|
|
^
|
|||
|
|
5 print(a)
|
|||
|
|
6 }
|
|||
|
|
|
|||
|
|
(lldb) p a
|
|||
|
|
error: &lt;EXPR&gt;:3:1: error: cannot find 'a' in scope
|
|||
|
|
|
|||
|
|
(lldb) n
|
|||
|
|
3 func f() {
|
|||
|
|
4 let a = getInt()
|
|||
|
|
5 print(a)
|
|||
|
|
^
|
|||
|
|
6 }
|
|||
|
|
|
|||
|
|
(lldb) p a
|
|||
|
|
42
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<!---
|
|||
|
|
In fact, the Swift language's scoping rules allow some astonishing things to be done with variable bindings:
|
|||
|
|
|
|||
|
|
```swift
|
|||
|
|
enum E<T> {
|
|||
|
|
case A(T)
|
|||
|
|
case B(T)
|
|||
|
|
case C(String)
|
|||
|
|
case D(T, T, T)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func f<T>(_ e: E<T>) -> String {
|
|||
|
|
switch e {
|
|||
|
|
case .A(let a), .B(let a): return "One variable \(a): T in scope"
|
|||
|
|
case .C(let a): return "One variable \(a): String in scope"
|
|||
|
|
case .D(let a, _, let c): return "One \(a): T and one \(c): T in scope"
|
|||
|
|
default: return "Only the function argument e is in scope"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
All of these can be correctly disambiguated by LLDB thanks to lexical scope debug information.
|
|||
|
|
--->
|
|||
|
|
|
|||
|
|
<p>For more details, see the <a href="https://github.com/apple/swift/pull/64941">pull request</a> that introduced this change.</p>
|
|||
|
|
|
|||
|
|
<h3 id="get-involved">Get involved</h3>
|
|||
|
|
|
|||
|
|
<p>If you want to learn more about Swift debugging and LLDB, provide feedback, or contribute to the tooling itself, join us in the <a href="https://forums.swift.org/c/development/lldb/13">LLDB section</a> of the Swift development forums.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift 5.9 Released</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-5.9-released/"/>
|
|||
|
|
<updated>2023-09-18T07:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-5.9-released/</id>
|
|||
|
|
<content type="html"><p>Swift 5.9 is now available! 🎉</p>
|
|||
|
|
|
|||
|
|
<p>This is a major new release that <strong>adds an expressive macro system to the language</strong> and introduces <strong>support for integrating Swift into C++ codebases</strong> through bidirectional interoperability.</p>
|
|||
|
|
|
|||
|
|
<p>It also introduces parameter packs, an improved expression evaluator while debugging, enhanced crash handling, Windows platform improvements, and more.</p>
|
|||
|
|
|
|||
|
|
<p>Read on for a deep dive into changes to the language, standard library, tooling, platform support, and next steps for getting started with Swift 5.9.</p>
|
|||
|
|
|
|||
|
|
<p>Thank you to everyone in the Swift community who made this release possible. Your Swift Forums discussions, bug reports, pull requests, educational content, and other contributions are always appreciated!</p>
|
|||
|
|
|
|||
|
|
<h2 id="language-and-standard-library">Language and Standard Library</h2>
|
|||
|
|
|
|||
|
|
<p>Swift’s fundamental goal is to encourage code that is clear and concise, while remaining safe and efficient.</p>
|
|||
|
|
|
|||
|
|
<p>This release adds three long-desired features that further that goal: a new macro system for more expressive libraries, parameter packs to make overloaded APIs natural to use, and new ownership features to offer more control over performance in low-level code.</p>
|
|||
|
|
|
|||
|
|
<h3 id="macros">Macros</h3>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/visions/macros.md">Macros</a> help developers reduce repetitive boilerplate and create more expressive libraries that can be distributed as a Swift package.</p>
|
|||
|
|
|
|||
|
|
<p>Using a macro is easy and natural. Macros can either be expanded with a function-like freestanding <code class="language-plaintext highlighter-rouge">#macroName</code> syntax:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">_</span><span class="p">:</span> <span class="kt">Font</span> <span class="o">=</span> <span class="k">#fontLiteral</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"SF Mono"</span><span class="p">,</span> <span class="nv">size</span><span class="p">:</span> <span class="mi">14</span><span class="p">,</span> <span class="nv">weight</span><span class="p">:</span> <span class="o">.</span><span class="n">regular</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>or attached to declarations with an <code class="language-plaintext highlighter-rouge">@MacroName</code> attribute:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Move storage from the stored properties into a dictionary,</span>
|
|||
|
|
<span class="c1">// turning the stored properties into computed properties.</span>
|
|||
|
|
<span class="kd">@DictionaryStorage</span>
|
|||
|
|
<span class="kd">struct</span> <span class="kt">Point</span> <span class="p">{</span>
|
|||
|
|
<span class="k">var</span> <span class="nv">x</span><span class="p">:</span> <span class="kt">Int</span> <span class="o">=</span> <span class="mi">1</span>
|
|||
|
|
<span class="k">var</span> <span class="nv">y</span><span class="p">:</span> <span class="kt">Int</span> <span class="o">=</span> <span class="mi">2</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>They work just like built-in language features but can’t be mistaken for normal code.</p>
|
|||
|
|
|
|||
|
|
<p>You write macros using a powerful and flexible approach: they are simply Swift functions that use the <a href="https://github.com/apple/swift-syntax">SwiftSyntax</a> library to generate code to be inserted into the source file.</p>
|
|||
|
|
|
|||
|
|
<p>Macros make it easy for your library’s users to adopt powerful capabilities that adapt to the code they’re used in, like <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0395-observability.md">the new <code class="language-plaintext highlighter-rouge">Observation</code> module</a>, which allows Swift classes to automatically notify other code when their properties change.</p>
|
|||
|
|
|
|||
|
|
<p>The Swift community has been hard at work creating tools and frameworks that build upon macros. For some examples, take a look at <a href="https://github.com/kishikawakatsumi/swift-power-assert">swift-power-assert</a>, <a href="https://github.com/Matejkob/swift-spyable">swift-spyable</a>, <a href="https://github.com/pointfreeco/swift-macro-testing">swift-macro-testing</a>, and <a href="https://github.com/SwiftyLab/MetaCodable">MetaCodable</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Swift 5.9 supports macros on macOS and Linux, with Windows support coming soon.</p>
|
|||
|
|
|
|||
|
|
<h3 id="parameter-packs">Parameter packs</h3>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0393-parameter-packs.md">Parameter packs</a> let you write generic types and functions which work over an arbitrary number of types.</p>
|
|||
|
|
|
|||
|
|
<p>For example, without parameter packs, if you wanted to write a function called <code class="language-plaintext highlighter-rouge">all</code> to check whether any number of <code class="language-plaintext highlighter-rouge">Optional</code> values are <code class="language-plaintext highlighter-rouge">nil</code>, you would need to write a separate overload for each argument length you wanted to support, creating an arbitrary upper limit:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="n">all</span><span class="o">&lt;</span><span class="kt">W1</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">optional</span><span class="p">:</span> <span class="kt">W1</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="kt">W1</span><span class="p">?</span>
|
|||
|
|
<span class="kd">func</span> <span class="n">all</span><span class="o">&lt;</span><span class="kt">W1</span><span class="p">,</span> <span class="kt">W2</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">optional1</span><span class="p">:</span> <span class="kt">W1</span><span class="p">?,</span> <span class="nv">optional2</span><span class="p">:</span> <span class="kt">W2</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">W1</span><span class="p">,</span> <span class="kt">W2</span><span class="p">)?</span>
|
|||
|
|
<span class="kd">func</span> <span class="n">all</span><span class="o">&lt;</span><span class="kt">W1</span><span class="p">,</span> <span class="kt">W2</span><span class="p">,</span> <span class="kt">W3</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">optional1</span><span class="p">:</span> <span class="kt">W1</span><span class="p">?,</span> <span class="nv">optional2</span><span class="p">:</span> <span class="kt">W2</span><span class="p">?,</span> <span class="nv">optional3</span><span class="p">:</span> <span class="kt">W3</span><span class="p">?)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">W1</span><span class="p">,</span> <span class="kt">W2</span><span class="p">,</span> <span class="kt">W3</span><span class="p">)?</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>With parameter packs, you can express this API as a single function that has no upper limit, allowing you to pass any number of arguments:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="n">all</span><span class="o">&lt;</span><span class="k">each</span> <span class="kt">Wrapped</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">optional</span><span class="p">:</span> <span class="nf">repeat</span> <span class="p">(</span><span class="k">each</span> <span class="kt">Wrapped</span><span class="p">)?)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="k">repeat</span> <span class="k">each</span> <span class="kt">Wrapped</span><span class="p">)?</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Calling an API that uses parameter packs is intuitive and requires no extra work:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="k">let</span> <span class="p">(</span><span class="nv">int</span><span class="p">,</span> <span class="nv">double</span><span class="p">,</span> <span class="nv">string</span><span class="p">,</span> <span class="nv">bool</span><span class="p">)</span> <span class="o">=</span> <span class="nf">all</span><span class="p">(</span><span class="n">optionalInt</span><span class="p">,</span> <span class="n">optionalDouble</span><span class="p">,</span> <span class="n">optionalString</span><span class="p">,</span> <span class="n">optionalBool</span><span class="p">)</span> <span class="p">{</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">int</span><span class="p">,</span> <span class="n">double</span><span class="p">,</span> <span class="n">string</span><span class="p">,</span> <span class="n">bool</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="k">else</span> <span class="p">{</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="s">"got a nil"</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="ownership">Ownership</h3>
|
|||
|
|
|
|||
|
|
<p>Ownership features can help developers fine-tune memory management behavior in performance-critical code.</p>
|
|||
|
|
|
|||
|
|
<p>The new <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0366-move-function.md"><code class="language-plaintext highlighter-rouge">consume</code> operator</a> tells Swift to deinitialize a variable and transfer its contents without copying it. The <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0377-parameter-ownership-modifiers.md"><code class="language-plaintext highlighter-rouge">consuming</code> and <code class="language-plaintext highlighter-rouge">borrowing</code> parameter modifiers</a> provide hints that Swift can use to eliminate unnecessary copying and reference-counting operations when passing a parameter. Finally, <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0390-noncopyable-structs-and-enums.md">noncopyable structs and enums</a> allow you to create types which, like a class, can’t be meaningfully copied when assigned, but like a struct or enum, do not need to be reference-counted because only one storage location can own the instance at a time.</p>
|
|||
|
|
|
|||
|
|
<p>These major features are the foundation for further evolution that puts more expressive power and performance control into your hands. We’re excited about what you can do with Swift 5.9, and we’re working toward a future with a larger suite of variadic generics and ownership features.</p>
|
|||
|
|
|
|||
|
|
<h3 id="additional-features">Additional Features</h3>
|
|||
|
|
|
|||
|
|
<p>Swift 5.9 also includes smaller, quality-of-life changes to the language, like the ability to use <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0380-if-switch-expressions.md"><code class="language-plaintext highlighter-rouge">if</code> and <code class="language-plaintext highlighter-rouge">switch</code> as expressions</a> for variable assignment and return values:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">statusBar</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="k">if</span> <span class="o">!</span><span class="n">hasConnection</span> <span class="p">{</span> <span class="s">"Disconnected"</span> <span class="p">}</span>
|
|||
|
|
<span class="k">else</span> <span class="k">if</span> <span class="k">let</span> <span class="nv">error</span> <span class="o">=</span> <span class="n">lastError</span> <span class="p">{</span> <span class="n">error</span><span class="o">.</span><span class="n">localizedDescription</span> <span class="p">}</span>
|
|||
|
|
<span class="k">else</span> <span class="p">{</span> <span class="s">"Ready"</span> <span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>A <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md">new <code class="language-plaintext highlighter-rouge">package</code> access level</a> lets other modules in the same package access APIs, but hides them from code outside the package. It’s great for splitting up large modules into several smaller ones without exposing internals to the package’s clients.</p>
|
|||
|
|
|
|||
|
|
<p>Developers using Swift Concurrency may appreciate the <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0381-task-group-discard-results.md">more convenient <code class="language-plaintext highlighter-rouge">DiscardingTaskGroup</code> types</a> for task groups that don’t generate results and the advanced <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0392-custom-actor-executors.md">custom actor executors</a> feature for controlling the exact environment that an actor is run in.</p>
|
|||
|
|
|
|||
|
|
<p>A full list of Swift 5.9 Evolution proposals can be found at the end of this post.</p>
|
|||
|
|
|
|||
|
|
<h2 id="developer-experience">Developer Experience</h2>
|
|||
|
|
|
|||
|
|
<h3 id="crash-handling">Crash Handling</h3>
|
|||
|
|
|
|||
|
|
<p>On Linux, the Swift runtime will now catch program crashes and Swift runtime errors and display a backtrace on the program’s output. The backtracer is out-of-process and includes support for <code class="language-plaintext highlighter-rouge">async</code> functions.</p>
|
|||
|
|
|
|||
|
|
<p>This feature is also available on macOS but is disabled by default. To enable it, set <code class="language-plaintext highlighter-rouge">SWIFT_BACKTRACE=enable=yes</code> and sign your program with the <code class="language-plaintext highlighter-rouge">com.apple.security.get-task-allow</code> entitlement.</p>
|
|||
|
|
|
|||
|
|
<h3 id="debugging">Debugging</h3>
|
|||
|
|
|
|||
|
|
<p>Swift 5.9 introduces new features to <a href="https://lldb.llvm.org/">LLDB</a> and the Swift compiler aimed at making Swift debugging faster and more reliable.</p>
|
|||
|
|
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">p</code> and <code class="language-plaintext highlighter-rouge">po</code> commands now print local variables and properties as fast as the <code class="language-plaintext highlighter-rouge">frame variable</code> or <code class="language-plaintext highlighter-rouge">v</code> commands by bypassing the Swift compiler when evaluating simple expressions.</p>
|
|||
|
|
|
|||
|
|
<p>Swift expressions can now refer to generic type parameters. This allows setting a conditional breakpoint in a generic function that only triggers when a type parameter is instantiated with a specific concrete type.</p>
|
|||
|
|
|
|||
|
|
<p>The debug info produced by the Swift compiler now more precisely scopes local variables, making it less likely to display variables backed by uninitialized memory in the debugger.</p>
|
|||
|
|
|
|||
|
|
<h2 id="ecosystem">Ecosystem</h2>
|
|||
|
|
|
|||
|
|
<h3 id="c-interoperability">C++ Interoperability</h3>
|
|||
|
|
|
|||
|
|
<p>Swift 5.9 supports bidirectional interoperability with C++ and Objective-C++ for certain kinds of APIs.</p>
|
|||
|
|
|
|||
|
|
<p>For example, if you have a C++ function like:</p>
|
|||
|
|
|
|||
|
|
<div class="language-cpp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Clang module 'PromptResponder'</span>
|
|||
|
|
<span class="cp">#pragma once
|
|||
|
|
#include</span> <span class="cpf">&lt;vector&gt;</span><span class="cp">
|
|||
|
|
</span>
|
|||
|
|
<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&gt;</span> <span class="n">generatePromptResponse</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">prompt</span><span class="p">);</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>you can call it directly from your Swift code:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">PromptResponder</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">codeLines</span> <span class="o">=</span> <span class="nf">generatePromptResponse</span><span class="p">(</span><span class="s">"Write Swift code that prints hello world"</span><span class="p">)</span>
|
|||
|
|
<span class="o">.</span><span class="nf">map</span><span class="p">(</span><span class="kt">String</span><span class="o">.</span><span class="kd">init</span><span class="p">)</span>
|
|||
|
|
<span class="o">.</span><span class="n">filter</span> <span class="p">{</span> <span class="o">!</span><span class="nv">$0</span><span class="o">.</span><span class="n">isEmpty</span> <span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="k">for</span> <span class="n">line</span> <span class="k">in</span> <span class="n">codeLines</span> <span class="p">{</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>C++ interoperability is actively evolving, with some aspects subject to change in future releases as the community gathers feedback from real world adoption in mixed Swift and C++ codebases.</p>
|
|||
|
|
|
|||
|
|
<p>For information on enabling C++ interoperability and the supported language subset, please refer to the <a href="/documentation/cxx-interop/">documentation</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Special thanks to the <a href="/cxx-interop-workgroup/">C++ Interoperability Workgroup</a> for their focus and dedication in supporting this feature.</p>
|
|||
|
|
|
|||
|
|
<h3 id="swift-package-manager">Swift Package Manager</h3>
|
|||
|
|
|
|||
|
|
<p>The <a href="https://github.com/apple/swift-package-manager">Swift Package Manager</a> has a number of improvements in Swift 5.9:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p>Packages can use the new <code class="language-plaintext highlighter-rouge">package</code> access modifier, allowing access of symbols in another target / module within the same package without making them public. SwiftPM automatically sets the new compiler configuration to ensure this feature works out-of-the-box for packages.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">CompilerPluginSupport</code> module enables defining macro targets. Macro targets allow authoring and distributing custom Swift macros as APIs in a library.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The new <code class="language-plaintext highlighter-rouge">.embedInCode</code> resource rule allows embedding the contents of a resource into an executable by generating a byte array.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">allowNetworkConnections(scope:reason:)</code> setting gives a command plugin permissions to access the network. Permissions can be scoped to Unix domain sockets as well as local or remote IP connections, with an option to limit by port. For non-interactive use cases, the <code class="language-plaintext highlighter-rouge">--allow-network-connections</code> command-line flag allows network connections for a particular scope.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>SwiftPM can now publish to a registry following the specification defined in <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0391-package-registry-publish.md">SE-0391</a>, as well as support signed packages, which may be required by a registry. Trust-on-first-use (TOFU) validation checks can now use signing identities in addition to fingerprints, and are enforced for source archives as well as package manifests.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>SwiftPM now supports cross compilation based on <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md#swift-sdk-bundles">the Swift SDK bundle format</a>. While the feature is still considered experimental, we invite users to try it out and provide feedback.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>See the <a href="https://github.com/apple/swift-package-manager/blob/main/CHANGELOG.md#swift-59">Swift Package Manager changelog</a> for the complete list of changes.</p>
|
|||
|
|
|
|||
|
|
<h3 id="swift-syntax">Swift Syntax</h3>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-syntax">swift-syntax</a> is an essential tool for parsing Swift code and helps power the new macro system. This year, swift-syntax received a number of improvements:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p>Syntax node names are more consistent and accurately reflect the Swift language.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>Error recovery in the new SwiftParser is greatly improved, leading to more precise error messages for incorrect or missing syntax.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>Incremental parsing is now supported, allowing editors and other tools to only reparse those parts of a syntax tree that have changed.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <a href="https://swiftpackageindex.com/apple/swift-syntax">documentation</a> of swift-syntax has been greatly expanded.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Over the last year, swift-syntax has been a huge success as an open source project. Since the release of Swift 5.8, more than 30 distinct contributors have worked on the package, accounting for more than 30% of the commits. In addition, the community tool <a href="https://swift-ast-explorer.com">swift-ast-explorer.com</a> is invaluable in exploring and understanding the SwiftSyntax tree. Thank you to everyone who contributed!</p>
|
|||
|
|
|
|||
|
|
<h3 id="server">Server</h3>
|
|||
|
|
|
|||
|
|
<p>Custom actor executors and other features from Swift 5.9 are making their way into the Swift on server ecosystem.</p>
|
|||
|
|
|
|||
|
|
<p>The server workgroup also recently published their <a href="/blog/sswg-update-2023/">annual update for 2023</a>, detailing plans to increase adoption of concurrency within key libraries, as well as other efforts.</p>
|
|||
|
|
|
|||
|
|
<h3 id="windows-platform">Windows Platform</h3>
|
|||
|
|
|
|||
|
|
<p>Windows support for Swift 5.9 greatly improves stability and the developer experience.</p>
|
|||
|
|
|
|||
|
|
<p>The Windows installer now supports installation both before and after Visual Studio installation, and no longer requires repair after a Visual Studio upgrade. Initial work has also begun to enable multiple, parallel toolchains installed side-by-side on Windows.</p>
|
|||
|
|
|
|||
|
|
<p>The Swift toolchain also added new flags (<code class="language-plaintext highlighter-rouge">-windows-sdk-root</code>, <code class="language-plaintext highlighter-rouge">-windows-sdk-version</code>, <code class="language-plaintext highlighter-rouge">-visualc-tools-root</code>, <code class="language-plaintext highlighter-rouge">-visualc-tools-version</code>) to help control the Windows SDK and Visual C++ tools that it builds against.</p>
|
|||
|
|
|
|||
|
|
<p>The Windows SDK (<code class="language-plaintext highlighter-rouge">WinSDK</code>) module saw improvements in coverage, enabling access to a wider set of system APIs. The Visual C++ (<code class="language-plaintext highlighter-rouge">vcruntime</code>) module was greatly restructured to support C++ interoperability.</p>
|
|||
|
|
|
|||
|
|
<p>Structured Concurrency is now significantly more stable on Windows, eliminating stack overflows and other execution failures for common patterns such as iterating over an <code class="language-plaintext highlighter-rouge">AsyncStream</code> with many elements.</p>
|
|||
|
|
|
|||
|
|
<p>Improvements to path handling in the LSP and SwiftPM makes both of these tools more robust on Windows. LLDB also saw initial work towards improving support for Windows, enabling fundamental debugging workflows in LLDB on Windows. While still a work in progress, this will significantly improve the developer experience on Windows.</p>
|
|||
|
|
|
|||
|
|
<p>Small improvements have also been made to reduce the size of the toolchain on Windows.</p>
|
|||
|
|
|
|||
|
|
<h2 id="next-steps">Next Steps</h2>
|
|||
|
|
|
|||
|
|
<h3 id="downloads">Downloads</h3>
|
|||
|
|
|
|||
|
|
<p>Official binaries are <a href="https://swift.org/download/">available for download</a> from <a href="http://swift.org/">Swift.org</a> for macOS, Windows, and Linux. The Swift 5.9 compiler is also included in <a href="https://apps.apple.com/app/xcode/id497799835">Xcode 15</a>.</p>
|
|||
|
|
|
|||
|
|
<h3 id="website">Website</h3>
|
|||
|
|
|
|||
|
|
<p>Swift.org has revamped certain key pages, including <a href="/">a richer home page</a> and clearer <a href="/install/">download and install instructions</a>.</p>
|
|||
|
|
|
|||
|
|
<p>If you’re new to Swift or looking to dive deeper, check out the updated <a href="/getting-started/">Getting Started guides</a>.</p>
|
|||
|
|
|
|||
|
|
<h3 id="language-guide">Language Guide</h3>
|
|||
|
|
|
|||
|
|
<p><a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/">The Swift Programming Language</a> book has been updated for Swift 5.9 and is now published with DocC.</p>
|
|||
|
|
|
|||
|
|
<p>This is the official Swift guide and a great entry point for learning Swift.</p>
|
|||
|
|
|
|||
|
|
<p>The Swift community also maintains a number of <a href="/documentation/tspl/#translations">translations</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="swift-evolution-appendix">Swift Evolution Appendix</h2>
|
|||
|
|
|
|||
|
|
<p>The following language, standard library, and Swift Package Manager proposals were accepted through the <a href="https://github.com/apple/swift-evolution">Swift Evolution</a> process and <a href="https://apple.github.io/swift-evolution/#?version=5.9">implemented in Swift 5.9</a>.</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>SE-0366: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0366-move-function.md"><code class="language-plaintext highlighter-rouge">consume</code> operator to end the lifetime of a variable binding</a></li>
|
|||
|
|
<li>SE-0374: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0374-clock-sleep-for.md">Add sleep(for:) to Clock</a></li>
|
|||
|
|
<li>SE-0377: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0377-parameter-ownership-modifiers.md"><code class="language-plaintext highlighter-rouge">borrowing</code> and <code class="language-plaintext highlighter-rouge">consuming</code> parameter ownership modifiers</a></li>
|
|||
|
|
<li>SE-0380: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0380-if-switch-expressions.md"><code class="language-plaintext highlighter-rouge">if</code> and <code class="language-plaintext highlighter-rouge">switch</code> expressions</a></li>
|
|||
|
|
<li>SE-0381: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0381-task-group-discard-results.md">DiscardingTaskGroups</a></li>
|
|||
|
|
<li>SE-0382: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0382-expression-macros.md">Expression Macros</a></li>
|
|||
|
|
<li>SE-0384: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0384-importing-forward-declared-objc-interfaces-and-protocols.md">Importing Forward Declared Objective-C Interfaces and Protocols</a></li>
|
|||
|
|
<li>SE-0386: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md">New access modifier: <code class="language-plaintext highlighter-rouge">package</code></a></li>
|
|||
|
|
<li>SE-0388: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0388-async-stream-factory.md">Convenience Async[Throwing]Stream.makeStream methods</a></li>
|
|||
|
|
<li>SE-0389: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md">Attached Macros</a></li>
|
|||
|
|
<li>SE-0390: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0390-noncopyable-structs-and-enums.md">Noncopyable structs and enums</a></li>
|
|||
|
|
<li>SE-0392: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0392-custom-actor-executors.md">Custom Actor Executors</a></li>
|
|||
|
|
<li>SE-0393: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0393-parameter-packs.md">Value and Type Parameter Packs</a></li>
|
|||
|
|
<li>SE-0394: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0394-swiftpm-expression-macros.md">Package Manager Support for Custom Macros</a></li>
|
|||
|
|
<li>SE-0395: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0395-observability.md">Observation</a></li>
|
|||
|
|
<li>SE-0396: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0396-never-codable.md">Conform <code class="language-plaintext highlighter-rouge">Never</code> to <code class="language-plaintext highlighter-rouge">Codable</code></a></li>
|
|||
|
|
<li>SE-0397: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0397-freestanding-declaration-macros.md">Freestanding Declaration Macros</a></li>
|
|||
|
|
<li>SE-0398: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0398-variadic-types.md">Allow Generic Types to Abstract Over Packs</a></li>
|
|||
|
|
<li>SE-0399: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0399-tuple-of-value-pack-expansion.md">Tuple of value pack expansion</a></li>
|
|||
|
|
<li>SE-0400: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0400-init-accessors.md">Init Accessors</a></li>
|
|||
|
|
<li>SE-0401: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0401-remove-property-wrapper-isolation.md">Remove Actor Isolation Inference caused by Property Wrappers</a></li>
|
|||
|
|
<li>SE-0402: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0402-extension-macros.md">Generalize <code class="language-plaintext highlighter-rouge">conformance</code> macros as <code class="language-plaintext highlighter-rouge">extension</code> macros</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>SSWG 2023 Annual Update</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/sswg-update-2023/"/>
|
|||
|
|
<updated>2023-08-17T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/sswg-update-2023/</id>
|
|||
|
|
<content type="html"><p>Once a year, the Swift Server workgroup (SSWG) reflects on recent community accomplishments and lays out focus areas for the year ahead.</p>
|
|||
|
|
|
|||
|
|
<p>Since <a href="/blog/sswg-update/">our last update</a>, the Swift on server ecosystem has welcomed new projects, seen significant progress in the adoption of structured concurrency, improved its tooling, and more.</p>
|
|||
|
|
|
|||
|
|
<p>Let’s start by reviewing the progress made in 2022 then look ahead at the goals for the next 12 months.</p>
|
|||
|
|
|
|||
|
|
<h2 id="2022-in-review">2022 in Review</h2>
|
|||
|
|
|
|||
|
|
<h3 id="continued-focus-on-growing-the-ecosystem">Continued focus on growing the ecosystem</h3>
|
|||
|
|
|
|||
|
|
<p>The ecosystem has seen a number of new libraries introduced including:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>a <a href="https://github.com/swift-server/swift-kafka-gsoc">Kafka client library</a> that started as a GSoC project</li>
|
|||
|
|
<li>a <a href="https://github.com/apple/swift-cassandra-client">Cassandra client library</a> released by Apple and pitched to the <a href="/sswg/incubation-process.html">SSWG incubation process</a></li>
|
|||
|
|
<li>a <a href="https://github.com/GraphQLSwift/GraphQL">GraphQL</a> library pitched to the SSWG incubation process</li>
|
|||
|
|
<li>a <a href="https://github.com/funcmike/rabbitmq-nio">RabbitMQ library</a></li>
|
|||
|
|
<li>a Memcached client library was proposed as a GSoC project</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>There were also three new packages proposed and accepted into the SSWG’s incubation process:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://github.com/swift-server/sswg/blob/main/proposals/0019-graphql.md">GraphQL and Graphiti libraries</a></li>
|
|||
|
|
<li><a href="https://github.com/swift-server/sswg/blob/main/proposals/0020-distributed-actor-cluster.md">Distributed Actors Cluster implementation</a></li>
|
|||
|
|
<li><a href="https://github.com/swift-server/sswg/blob/main/proposals/0021-swift-cassandra-client.md">Swift Cassandra client</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="continuing-the-concurrency-journey">Continuing the concurrency journey</h3>
|
|||
|
|
|
|||
|
|
<p>We are happy to see that the adoption of Swift Concurrency in the ecosystem has progressed significantly. All libraries in the SSWG incubation process have adopted new <code class="language-plaintext highlighter-rouge">async</code>/<code class="language-plaintext highlighter-rouge">await</code> APIs where applicable and are continuing to roll out <code class="language-plaintext highlighter-rouge">Sendable</code> support.</p>
|
|||
|
|
|
|||
|
|
<p>We are also seeing a trend of new APIs using only Swift Concurrency, and new projects with internals written using Swift Concurrency, like the <a href="https://github.com/swift-server/swift-kafka-gsoc">Kafka client library</a>.</p>
|
|||
|
|
|
|||
|
|
<p>We’re also excited to see the introduction of <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0392-custom-actor-executors.md">Custom Actor Executors</a>. The introduction of Custom Actor Executors offers more control over the behavior of concurrent code, helps improve performance, and will enable us to bridge more code into Swift concurrency.</p>
|
|||
|
|
|
|||
|
|
<h3 id="expanding-the-tooling">Expanding the tooling</h3>
|
|||
|
|
|
|||
|
|
<p>Notable highlights in tooling include:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>The <a href="https://marketplace.visualstudio.com/items?itemName=sswg.swift-lang">Swift Extension for Visual Studio Code</a> reached version 1.0.0 and added new features like Swift Package plugin integration, Test Coverage and Test Explorer support, and more.</li>
|
|||
|
|
<li>Swift Package plugins have seen adoption in many libraries, from formatters and linters, to code generators such as <a href="https://github.com/apple/swift-protobuf/tree/main/Plugins/SwiftProtobufPlugin">SwiftProtobuf</a>, <a href="https://github.com/grpc/grpc-swift/tree/main/Plugins/GRPCSwiftPlugin">gRPC swift</a>, <a href="https://github.com/amzn/smoke-framework-application-generate/tree/main/Plugins">Smoke</a>, and <a href="https://soto.codes/2022/12/build-plugin-experiments.html">Soto</a>.</li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swiftly">Swiftly</a> is now available to try out and provides a simple way to install Swift on Linux and switch between versions.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="improving-build-times">Improving build times</h3>
|
|||
|
|
|
|||
|
|
<p>There have been a number of improvements to build times for Swift projects, including compiler optimizations, new build systems, and package manager enhancements.</p>
|
|||
|
|
|
|||
|
|
<p>Swift Crypto Extras continues to add new APIs that allow libraries to avoid vending their own copies of BoringSSL. This, combined with the new <a href="https://www.swift.org/blog/swift-certificates-and-asn1/">Swift Certificates and ASN.1 libraries</a>, helps libraries like <a href="https://github.com/swift-server/webauthn-swift">WebAuthn Swift</a> avoid including their own cryptography libraries and instead use these new packages and APIs. This avoids compiling the same code multiple times and provides a significant speed improvement during compilation.</p>
|
|||
|
|
|
|||
|
|
<p>Additionally, SSWG member Gwynne <a href="https://github.com/apple/swift/pull/64312">merged a PR for Swift 5.9</a> that offers a 90% improvement to link time and memory usage on Linux, which should greatly help when building Swift applications in constrained environments.</p>
|
|||
|
|
|
|||
|
|
<h3 id="increasing-adoption-of-server-side-swift">Increasing adoption of server-side Swift</h3>
|
|||
|
|
|
|||
|
|
<p>The SSWG has continued to work with the community to increase adoption of Swift on the server:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>The SSWG Guides and incubation processes have been migrated to <a href="http://Swift.org">Swift.org</a> to make them more discoverable.</li>
|
|||
|
|
<li><a href="https://swiftpackageindex.com/swift-server/async-http-client/documentation/asynchttpclient">Many</a> <a href="https://swiftpackageindex.com/swift-server/RediStack/documentation/redistack">of</a> <a href="https://swiftpackageindex.com/apple/swift-nio/documentation/nio">the</a> <a href="https://swiftpackageindex.com/apple/swift-log/documentation/logging">Swift</a> <a href="https://swiftpackageindex.com/apple/swift-metrics/documentation/coremetrics">server</a> <a href="https://swiftpackageindex.com/swift-server/swift-aws-lambda-runtime/documentation/awslambdaruntime">packages</a> have adopted Swift Package Index documentation hosting to make discovering and using packages easier.</li>
|
|||
|
|
<li>The SSWG has created a survey to better understand the Swift on server community and help ensure efforts are applied to the right areas.</li>
|
|||
|
|
<li>We are observing an increase in the number of conference talks focused on production success stories and technical deep dives, reflecting a maturity in adoption and recognition of Swift on server.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="goals-for-2023">Goals for 2023</h2>
|
|||
|
|
|
|||
|
|
<p>The SSWG believes 2023 is turning out to be another exciting year for Swift on the server, with a continued focus on the following goals:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Continued focus on growing the ecosystem</li>
|
|||
|
|
<li>Adoption of structured concurrency</li>
|
|||
|
|
<li>Expand the documentation and guides</li>
|
|||
|
|
<li>Improve tooling</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="continued-focus-on-growing-the-ecosystem-1">Continued focus on growing the ecosystem</h3>
|
|||
|
|
|
|||
|
|
<p>In addition to supporting existing libraries, there are a number of areas of focus for this year:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>a Swift-native Memcached client</li>
|
|||
|
|
<li>a common connection pool library to make it easy to adopt connection pooling</li>
|
|||
|
|
<li>a shared middleware implementation for use in web frameworks like Smoke, Hummingbird, and Vapor</li>
|
|||
|
|
<li>Encouraging adoption of distributing tracing to round out the <a href="https://swiftpackageindex.com/apple/swift-distributed-tracing/1.0.1/documentation/tracing">observability story</a></li>
|
|||
|
|
<li>Better showcases of Swift on server deployments and success stories</li>
|
|||
|
|
<li>Better visibility of Swift as a server language</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="adoption-of-structured-concurrency">Adoption of structured concurrency</h3>
|
|||
|
|
|
|||
|
|
<p>The SSWG believe that structured concurrency is a key feature that will make Swift on server stand out and provide a clear benefit to the ecosystem.</p>
|
|||
|
|
|
|||
|
|
<p>Some plans for this year include:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Produce an adoption guide for structured concurrency covering best practices around <code class="language-plaintext highlighter-rouge">Sendable</code>, <code class="language-plaintext highlighter-rouge">async</code>/<code class="language-plaintext highlighter-rouge">await</code>, <code class="language-plaintext highlighter-rouge">TaskGroup</code>, and <code class="language-plaintext highlighter-rouge">Task</code> APIs.</li>
|
|||
|
|
<li>Apply concurrency best practices to core ecosystem libraries such as <a href="https://github.com/swift-server/swift-service-lifecycle">swift-service-lifecycle</a>.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="expand-the-documentation-and-guides">Expand the documentation and guides</h3>
|
|||
|
|
|
|||
|
|
<p>Documentation can always be improved and the SSWG will continue to expand our guides and usage documentation for the ecosystem.</p>
|
|||
|
|
|
|||
|
|
<p>The SSWG are working with the Swift Website Workgroup to add guides for those new to Swift on the server as well as ensure that the existing guides can be easily found.</p>
|
|||
|
|
|
|||
|
|
<p>The SSWG also plan to expand the documentation in key areas like security and deployment, covering topics like GitHub’s Dependabot and AWS’s Swift support in their CDK.</p>
|
|||
|
|
|
|||
|
|
<p>Some of the upcoming design changes to <a href="https://www.swift.org">Swift.org</a> will help place Swift on server documentation in a more prominent position to increase visibility.</p>
|
|||
|
|
|
|||
|
|
<h3 id="improve-tooling">Improve tooling</h3>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/swift-server/swiftly">Swiftly</a> is growing in popularity on Linux for managing multiple toolchains, and the SSWG would like to port it to Windows and macOS as well.</p>
|
|||
|
|
|
|||
|
|
<p>There are a number of other tooling enhancements being explored, including:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Adding support for Swift Package Manager to GitHub’s dependabot</li>
|
|||
|
|
<li>Investigating Canonical’s Chiseled Containers to see if we can provide Swift containers with a very small footprint and a hardened security profile</li>
|
|||
|
|
<li>Investigating what we can do with Swift Package plugins to improve the deployment experience of Swift on server</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="new-sswg-members">New SSWG Members</h2>
|
|||
|
|
|
|||
|
|
<p>The SSWG is happy to welcome four new members:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Dave Moser - Dave joined the SSWG in May. Dave is part of the solution architecture team driving Swift on AWS, and has been involved with the Swift on server efforts for the last couple of years.</li>
|
|||
|
|
<li>Jimmy McDermott - Jimmy also joined the SSWG in May and represents Transeo. Jimmy has been involved with Swift on server since Vapor’s early days and is the CTO of Transeo, where he and his team use Vapor to scale services to millions of users.</li>
|
|||
|
|
<li>Franz Busch - Franz officially joined the SSWG on October 23rd and works on the SwiftNIO team at Apple.</li>
|
|||
|
|
<li>Joannis Orlandos - Joannis joined the SSWG at the start of this year. Joannis was a core contributor to Vapor and maintains a number of libraries in the ecosystem including <a href="https://github.com/orlandos-nl/MongoKitten">MongoKitten</a>.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Franz takes over from Fabian Fett who has completed a two year stint on the SSWG. Dave takes over from Todd Varland who also completed a long stint on the SSWG. Kaitlin Mahar has changed roles at MongoDB and also completed a number of years on the SSWG. We are extremely grateful for all they’ve done in their time on the SSWG and thank them for their hard work!</p>
|
|||
|
|
|
|||
|
|
<h2 id="going-forward">Going Forward</h2>
|
|||
|
|
|
|||
|
|
<p>If you have any ideas to share with the SSWG or want to pitch a library to the SSWG Incubation Process, please get in touch with us, either <a href="https://forums.swift.org/c/server/43">via the forums</a> or through Slack.</p>
|
|||
|
|
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Introducing Swift HTTP Types</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/introducing-swift-http-types/"/>
|
|||
|
|
<updated>2023-07-10T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/introducing-swift-http-types/</id>
|
|||
|
|
<content type="html"><p>We’re excited to announce a new open source package called <a href="https://github.com/apple/swift-http-types">Swift HTTP Types</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Building upon insights from Swift on server, app developers, and the broader Swift community, Swift HTTP Types is designed to provide a shared set of currency types for client/server HTTP operations in Swift.</p>
|
|||
|
|
|
|||
|
|
<h2 id="http-in-swift">HTTP in Swift</h2>
|
|||
|
|
|
|||
|
|
<p>Networking in Swift is ubiquitous for many use cases today, spanning clients, servers, intermediaries, and many other participants across the internet and other networks. HTTP is among the most popular networking technologies, powering daily experiences across the world.</p>
|
|||
|
|
|
|||
|
|
<p>On Apple platforms, the system HTTP implementation is exposed via the <code class="language-plaintext highlighter-rouge">URLSession</code> API in the Foundation framework. For Swift on server projects, the recommended HTTP stack is implemented in <a href="https://github.com/apple/swift-nio">SwiftNIO</a>.</p>
|
|||
|
|
|
|||
|
|
<p>To provide the best possible experience for using HTTP in Swift, shared currency types, useful across many projects, are essential.</p>
|
|||
|
|
|
|||
|
|
<h2 id="swift-http-types">Swift HTTP Types</h2>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-http-types">Swift HTTP Types</a> provides a common representation of the core building blocks of HTTP messages.</p>
|
|||
|
|
|
|||
|
|
<p><code class="language-plaintext highlighter-rouge">HTTPRequest</code> and <code class="language-plaintext highlighter-rouge">HTTPResponse</code> represent HTTP messages for both client and server use cases. By adopting them across multiple projects, more code can be shared between clients and servers, eliminating the cost of converting between types when working with multiple frameworks.</p>
|
|||
|
|
|
|||
|
|
<p>These types are built Swift-first to represent every valid HTTP message. Their representations are focused on modern HTTP versions like HTTP/3 and HTTP/2, while also retaining compatibility with HTTP/1.1.</p>
|
|||
|
|
|
|||
|
|
<p>As the package matures, our goal is to replace SwiftNIO’s <code class="language-plaintext highlighter-rouge">HTTPRequestHead</code> and <code class="language-plaintext highlighter-rouge">HTTPResponseHead</code> as well as the HTTP message details of Foundation’s <code class="language-plaintext highlighter-rouge">URLRequest</code> and <code class="language-plaintext highlighter-rouge">URLResponse</code>.</p>
|
|||
|
|
|
|||
|
|
<p>The new currency types are designed to be suitable for use in any HTTP scenario and are not tied to any existing framework, eliminating the need for duplicate HTTP abstractions.</p>
|
|||
|
|
|
|||
|
|
<h2 id="example-usage">Example Usage</h2>
|
|||
|
|
|
|||
|
|
<p>The API is designed to offer ergonomic ways to perform the most common HTTP operations, while scaling cleanly to represent advanced use cases.</p>
|
|||
|
|
|
|||
|
|
<p>At their core, HTTP requests are comprised of a method, a scheme, an authority, and a path:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">request</span> <span class="o">=</span> <span class="kt">HTTPRequest</span><span class="p">(</span><span class="nv">method</span><span class="p">:</span> <span class="o">.</span><span class="k">get</span><span class="p">,</span> <span class="nv">scheme</span><span class="p">:</span> <span class="s">"https"</span><span class="p">,</span> <span class="nv">authority</span><span class="p">:</span> <span class="s">"www.example.com"</span><span class="p">,</span> <span class="nv">path</span><span class="p">:</span> <span class="s">"/"</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>We can also create the same request from a Foundation URL:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">var</span> <span class="nv">request</span> <span class="o">=</span> <span class="kt">HTTPRequest</span><span class="p">(</span><span class="nv">method</span><span class="p">:</span> <span class="o">.</span><span class="k">get</span><span class="p">,</span> <span class="nv">url</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"https://www.example.com/"</span><span class="p">)</span><span class="o">!</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>We can change the method, or other properties, after the fact:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">request</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="o">.</span><span class="n">post</span>
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">path</span> <span class="o">=</span> <span class="s">"/upload"</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Creating a response is similarly straightforward:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">response</span> <span class="o">=</span> <span class="kt">HTTPResponse</span><span class="p">(</span><span class="nv">status</span><span class="p">:</span> <span class="o">.</span><span class="n">ok</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>We can access and modify header fields using the <code class="language-plaintext highlighter-rouge">headerFields</code> property:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">userAgent</span><span class="p">]</span> <span class="o">=</span> <span class="s">"MyApp/1.0"</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Common header fields are built-in, and we can easily provide extensions for custom header fields and values, so we can use the same convenient syntax in our business logic:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">extension</span> <span class="kt">HTTPField</span><span class="o">.</span><span class="kt">Name</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">static</span> <span class="k">let</span> <span class="nv">myCustomHeader</span> <span class="o">=</span> <span class="kt">Self</span><span class="p">(</span><span class="s">"My-Custom-Header"</span><span class="p">)</span><span class="o">!</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">myCustomHeader</span><span class="p">]</span> <span class="o">=</span> <span class="s">"custom-value"</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>We can directly set the value of the header field, including an array of values:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="nv">raw</span><span class="p">:</span> <span class="o">.</span><span class="n">acceptLanguage</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s">"en-US"</span><span class="p">,</span> <span class="s">"zh-Hans-CN"</span><span class="p">]</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Accessing header fields is much the same, and we can use system-defined fields or our own extensions:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">userAgent</span><span class="p">]</span> <span class="c1">// "MyApp/1.0"</span>
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">myCustomHeader</span><span class="p">]</span> <span class="c1">// "custom-value"</span>
|
|||
|
|
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">acceptLanguage</span><span class="p">]</span> <span class="c1">// "en-US, zh-Hans-CN"</span>
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="nv">raw</span><span class="p">:</span> <span class="o">.</span><span class="n">acceptLanguage</span><span class="p">]</span> <span class="c1">// ["en-US", "zh-Hans-CN"]</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="integrating-with-foundation">Integrating with Foundation</h3>
|
|||
|
|
|
|||
|
|
<p>Using <code class="language-plaintext highlighter-rouge">URLSession</code>, we can easily create a new <code class="language-plaintext highlighter-rouge">HTTPRequest</code> to send a POST request to “www.example.com”. Setting a custom <code class="language-plaintext highlighter-rouge">User-Agent</code> header field value on this request is intuitive and integrates with the type system to offer auto-completions:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">var</span> <span class="nv">request</span> <span class="o">=</span> <span class="kt">HTTPRequest</span><span class="p">(</span><span class="nv">method</span><span class="p">:</span> <span class="o">.</span><span class="n">post</span><span class="p">,</span> <span class="nv">url</span><span class="p">:</span> <span class="kt">URL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"https://www.example.com/upload"</span><span class="p">)</span><span class="o">!</span><span class="p">)</span>
|
|||
|
|
<span class="n">request</span><span class="o">.</span><span class="n">headerFields</span><span class="p">[</span><span class="o">.</span><span class="n">userAgent</span><span class="p">]</span> <span class="o">=</span> <span class="s">"MyApp/1.0"</span>
|
|||
|
|
<span class="k">let</span> <span class="p">(</span><span class="nv">responseBody</span><span class="p">,</span> <span class="nv">response</span><span class="p">)</span> <span class="o">=</span> <span class="k">try</span> <span class="k">await</span> <span class="kt">URLSession</span><span class="o">.</span><span class="n">shared</span><span class="o">.</span><span class="nf">upload</span><span class="p">(</span><span class="nv">for</span><span class="p">:</span> <span class="n">request</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="n">requestBody</span><span class="p">)</span>
|
|||
|
|
<span class="k">guard</span> <span class="n">response</span><span class="o">.</span><span class="n">status</span> <span class="o">==</span> <span class="o">.</span><span class="n">created</span> <span class="k">else</span> <span class="p">{</span>
|
|||
|
|
<span class="c1">// Handle error</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="integrating-with-swiftnio">Integrating with SwiftNIO</h3>
|
|||
|
|
|
|||
|
|
<p>SwiftNIO integration will be available in the <a href="https://github.com/apple/swift-nio-extras">swift-nio-extras</a> package when this package becomes stable. To configure a NIO channel handler for use with the new HTTP types, we can add <code class="language-plaintext highlighter-rouge">HTTP2FramePayloadToHTTPServerCodec</code> before our other channel handlers:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">NIOTSListenerBootstrap</span><span class="p">(</span><span class="nv">group</span><span class="p">:</span> <span class="kt">NIOTSEventLoopGroup</span><span class="p">())</span>
|
|||
|
|
<span class="o">.</span><span class="n">childChannelInitializer</span> <span class="p">{</span> <span class="n">channel</span> <span class="k">in</span>
|
|||
|
|
<span class="n">channel</span><span class="o">.</span><span class="nf">configureHTTP2Pipeline</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">server</span><span class="p">)</span> <span class="p">{</span> <span class="n">channel</span> <span class="k">in</span>
|
|||
|
|
<span class="n">channel</span><span class="o">.</span><span class="n">pipeline</span><span class="o">.</span><span class="nf">addHandlers</span><span class="p">([</span>
|
|||
|
|
<span class="kt">HTTP2FramePayloadToHTTPServerCodec</span><span class="p">(),</span>
|
|||
|
|
<span class="kt">ExampleChannelHandler</span><span class="p">()</span>
|
|||
|
|
<span class="p">])</span>
|
|||
|
|
<span class="p">}</span><span class="o">.</span><span class="n">map</span> <span class="p">{</span> <span class="n">_</span> <span class="nf">in</span> <span class="p">()</span> <span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="o">.</span><span class="nf">tlsOptions</span><span class="p">(</span><span class="n">tlsOptions</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Our example channel implementation processes both <code class="language-plaintext highlighter-rouge">HTTPRequest</code> and <code class="language-plaintext highlighter-rouge">HTTPResponse</code> types:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">final</span> <span class="kd">class</span> <span class="kt">ExampleChannelHandler</span><span class="p">:</span> <span class="kt">ChannelDuplexHandler</span> <span class="p">{</span>
|
|||
|
|
<span class="kd">typealias</span> <span class="kt">InboundIn</span> <span class="o">=</span> <span class="kt">HTTPTypeServerRequestPart</span>
|
|||
|
|
<span class="kd">typealias</span> <span class="kt">OutboundOut</span> <span class="o">=</span> <span class="kt">HTTPTypeServerResponsePart</span>
|
|||
|
|
|
|||
|
|
<span class="kd">func</span> <span class="nf">channelRead</span><span class="p">(</span><span class="nv">context</span><span class="p">:</span> <span class="kt">ChannelHandlerContext</span><span class="p">,</span> <span class="nv">data</span><span class="p">:</span> <span class="kt">NIOAny</span><span class="p">)</span> <span class="p">{</span>
|
|||
|
|
<span class="k">switch</span> <span class="nf">unwrapInboundIn</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="p">{</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">head</span><span class="p">(</span><span class="k">let</span> <span class="nv">request</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Handle request headers</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">body</span><span class="p">(</span><span class="k">let</span> <span class="nv">body</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Handle request body</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">end</span><span class="p">(</span><span class="k">let</span> <span class="nv">trailers</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Handle complete request</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">response</span> <span class="o">=</span> <span class="kt">HTTPResponse</span><span class="p">(</span><span class="nv">status</span><span class="p">:</span> <span class="o">.</span><span class="n">ok</span><span class="p">)</span>
|
|||
|
|
<span class="n">context</span><span class="o">.</span><span class="nf">write</span><span class="p">(</span><span class="nf">wrapOutboundOut</span><span class="p">(</span><span class="o">.</span><span class="nf">head</span><span class="p">(</span><span class="n">response</span><span class="p">)),</span> <span class="nv">promise</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span>
|
|||
|
|
<span class="n">context</span><span class="o">.</span><span class="nf">writeAndFlush</span><span class="p">(</span><span class="nf">wrapOutboundOut</span><span class="p">(</span><span class="o">.</span><span class="nf">end</span><span class="p">(</span><span class="kc">nil</span><span class="p">)),</span> <span class="nv">promise</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h2 id="request-and-response-body">Request and Response Body</h2>
|
|||
|
|
|
|||
|
|
<p>HTTP request and response bodies are not currently part of this package.</p>
|
|||
|
|
|
|||
|
|
<p>Please continue to use existing the mechanisms: <code class="language-plaintext highlighter-rouge">Data</code> and <code class="language-plaintext highlighter-rouge">InputStream</code> for Foundation and <code class="language-plaintext highlighter-rouge">ByteBuffer</code> for SwiftNIO.</p>
|
|||
|
|
|
|||
|
|
<p>We are interested in exploring proposals with the community to provide body handling in the future.</p>
|
|||
|
|
|
|||
|
|
<h2 id="get-involved">Get Involved</h2>
|
|||
|
|
|
|||
|
|
<p>The experience and expertise from this community is invaluable in creating the building blocks for a great HTTP experience in Swift.</p>
|
|||
|
|
|
|||
|
|
<p>The version of Swift HTTP Types we’re releasing today is a starting point for feedback and discussion with the community.</p>
|
|||
|
|
|
|||
|
|
<p>You can get started by:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Trying out the <a href="https://github.com/apple/swift-http-types">swift-http-types package</a></li>
|
|||
|
|
<li>Participating in discussions with the <a href="https://forums.swift.org/tag/http">#http tag on the Swift forums</a></li>
|
|||
|
|
<li>Opening <a href="https://github.com/apple/swift-http-types/issues">issues and contributing</a> for any problems you find</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>We’re looking forward to exploring the future of HTTP in Swift together.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Introducing Swift OpenAPI Generator</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/introducing-swift-openapi-generator/"/>
|
|||
|
|
<updated>2023-06-12T07:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/introducing-swift-openapi-generator/</id>
|
|||
|
|
<content type="html"><p>We’re excited to announce a set of open source libraries designed to help both client and server developers streamline their workflow around HTTP communication using the industry‑standard OpenAPI specification.</p>
|
|||
|
|
|
|||
|
|
<h2 id="what-is-openapi">What is OpenAPI?</h2>
|
|||
|
|
|
|||
|
|
<p><a href="https://www.openapis.org/">OpenAPI</a> is a specification for documenting HTTP services. An OpenAPI document is written in either YAML or JSON, and can be read by tools to help automate workflows, such as generating the necessary code to send and receive HTTP requests.</p>
|
|||
|
|
|
|||
|
|
<p>By serving as the source of truth, OpenAPI solves the problem of communicating the API contract between a service and its clients. It removes the need to read potentially inaccurate, handwritten documentation, or to observe network traffic, just to figure out the correct way to call a service. It helps you avoid this time‑consuming, repetitive, and error‑prone work – not just when adopting a service for the first time, but also as the service continues to evolve.</p>
|
|||
|
|
|
|||
|
|
<p>To see OpenAPI and its benefits in action, let’s consider a simple service called <code class="language-plaintext highlighter-rouge">GreetingService</code> that:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>listens for an HTTP <code class="language-plaintext highlighter-rouge">GET</code> request at the <code class="language-plaintext highlighter-rouge">/greet</code> endpoint</li>
|
|||
|
|
<li>with an optional query parameter called <code class="language-plaintext highlighter-rouge">name</code>,</li>
|
|||
|
|
<li>and returns the HTTP status code <code class="language-plaintext highlighter-rouge">200 OK</code>, alongside a JSON body, which might look like this:</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
|
|||
|
|
</span><span class="nl">"message"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"Hello, Jane!"</span><span class="w">
|
|||
|
|
</span><span class="p">}</span><span class="w">
|
|||
|
|
</span></code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Such a service can be described using the OpenAPI document below:</p>
|
|||
|
|
|
|||
|
|
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">openapi</span><span class="pi">:</span> <span class="s1">'</span><span class="s">3.0.3'</span>
|
|||
|
|
<span class="na">info</span><span class="pi">:</span>
|
|||
|
|
<span class="na">title</span><span class="pi">:</span> <span class="s">GreetingService</span>
|
|||
|
|
<span class="na">version</span><span class="pi">:</span> <span class="s">1.0.0</span>
|
|||
|
|
<span class="na">servers</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="na">url</span><span class="pi">:</span> <span class="s2">"</span><span class="s">http://localhost:8080"</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Localhost"</span>
|
|||
|
|
<span class="na">paths</span><span class="pi">:</span>
|
|||
|
|
<span class="na">/greet</span><span class="pi">:</span>
|
|||
|
|
<span class="na">get</span><span class="pi">:</span>
|
|||
|
|
<span class="na">operationId</span><span class="pi">:</span> <span class="s">getGreeting</span>
|
|||
|
|
<span class="na">parameters</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">name</span>
|
|||
|
|
<span class="na">in</span><span class="pi">:</span> <span class="s">query</span>
|
|||
|
|
<span class="na">schema</span><span class="pi">:</span>
|
|||
|
|
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
|
|||
|
|
<span class="na">responses</span><span class="pi">:</span>
|
|||
|
|
<span class="s1">'</span><span class="s">200'</span><span class="err">:</span>
|
|||
|
|
<span class="na">description</span><span class="pi">:</span> <span class="s">A success response with a greeting.</span>
|
|||
|
|
<span class="na">content</span><span class="pi">:</span>
|
|||
|
|
<span class="na">application/json</span><span class="pi">:</span>
|
|||
|
|
<span class="na">schema</span><span class="pi">:</span>
|
|||
|
|
<span class="na">$ref</span><span class="pi">:</span> <span class="s2">"</span><span class="s">#/components/schemas/Greeting"</span>
|
|||
|
|
<span class="na">components</span><span class="pi">:</span>
|
|||
|
|
<span class="na">schemas</span><span class="pi">:</span>
|
|||
|
|
<span class="na">Greeting</span><span class="pi">:</span>
|
|||
|
|
<span class="na">properties</span><span class="pi">:</span>
|
|||
|
|
<span class="na">message</span><span class="pi">:</span>
|
|||
|
|
<span class="na">type</span><span class="pi">:</span> <span class="s">string</span>
|
|||
|
|
<span class="na">required</span><span class="pi">:</span>
|
|||
|
|
<span class="pi">-</span> <span class="s">message</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>This simple OpenAPI document defines the structure of the HTTP request and response, including the HTTP method, URL path and query parameters, HTTP status code and content type, and uses <a href="https://json-schema.org">JSON Schema</a> to describe the structure of the response body.</p>
|
|||
|
|
|
|||
|
|
<p>OpenAPI also allows defining additional details not shown above, such as query items and request bodies (see <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md">OpenAPI 3.0.3 specification</a> for more details).</p>
|
|||
|
|
|
|||
|
|
<h2 id="swift-openapi-generator">Swift OpenAPI Generator</h2>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-openapi-generator">Swift OpenAPI Generator</a> is a SwiftPM plugin that takes an OpenAPI document and generates either the client code to perform HTTP calls or the server code to handle those calls. The generated code translates between a type‑safe representation of each operation’s input and output, and the underlying HTTP request and response.</p>
|
|||
|
|
|
|||
|
|
<p>So whether developing an app that serves as a client of <code class="language-plaintext highlighter-rouge">GreetingService</code> or implementing <code class="language-plaintext highlighter-rouge">GreetingService</code> itself, Swift OpenAPI Generator generates the networking code for you, allowing you to focus on the core logic.</p>
|
|||
|
|
|
|||
|
|
<h3 id="adopting-the-plugin">Adopting the Plugin</h3>
|
|||
|
|
|
|||
|
|
<p>To use the Swift OpenAPI Generator plugin, you need to:</p>
|
|||
|
|
|
|||
|
|
<ol>
|
|||
|
|
<li>Add package dependencies for:
|
|||
|
|
<ul>
|
|||
|
|
<li>The package plugin (<a href="https://github.com/apple/swift-openapi-generator">swift-openapi-generator</a>), which performs code generation at build time</li>
|
|||
|
|
<li>The runtime library (<a href="https://github.com/apple/swift-openapi-runtime">swift-openapi-runtime</a>), which contains protocol definitions used by the generated code and extension libraries</li>
|
|||
|
|
<li>A transport implementation, which allows plugging in your chosen HTTP client library or server framework</li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li>Enable the package plugin on your target and add target dependencies for the runtime and transport libraries.</li>
|
|||
|
|
<li>Add the following two files to your target:
|
|||
|
|
<ul>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">openapi.yaml</code>, the OpenAPI document describing your API.</li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">openapi-generator-config.yaml</code>, a configuration file for the plugin, which controls whether to generate client or server code.</li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ol>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>Tip: For more information about adopting the plugin in your Swift package or Xcode project, check out our step-by-step <a href="https://swiftpackageindex.com/apple/swift-openapi-generator/tutorials/swift-openapi-generator">tutorials</a>.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<h3 id="using-a-generated-api-client">Using a Generated API Client</h3>
|
|||
|
|
|
|||
|
|
<p>When developing a client, such as an iOS app, you are provided with two generated types:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">APIProtocol</code>, a Swift protocol that contains one method per OpenAPI operation.
|
|||
|
|
<ul>
|
|||
|
|
<li>In the case of <code class="language-plaintext highlighter-rouge">GreetingService</code>, it contains a single method called <code class="language-plaintext highlighter-rouge">getGreeting</code>.</li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Client</code>, a Swift struct that implements <code class="language-plaintext highlighter-rouge">APIProtocol</code>, which is used to make API calls to the server.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Below is example code to instantiate the client and fetch a greeting from the server:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">OpenAPIRuntime</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">OpenAPIURLSession</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Instantiate your chosen transport library.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">transport</span><span class="p">:</span> <span class="kt">ClientTransport</span> <span class="o">=</span> <span class="kt">URLSessionTransport</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Create a client to connect to a server URL documented in the OpenAPI document.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">client</span> <span class="o">=</span> <span class="kt">Client</span><span class="p">(</span>
|
|||
|
|
<span class="nv">serverURL</span><span class="p">:</span> <span class="k">try</span> <span class="kt">Servers</span><span class="o">.</span><span class="nf">server1</span><span class="p">(),</span>
|
|||
|
|
<span class="nv">transport</span><span class="p">:</span> <span class="n">transport</span>
|
|||
|
|
<span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Make the HTTP call using a type-safe method.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">response</span> <span class="o">=</span> <span class="k">try</span> <span class="k">await</span> <span class="n">client</span><span class="o">.</span><span class="nf">getGreeting</span><span class="p">(</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">query</span><span class="p">:</span> <span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"Jane"</span><span class="p">)))</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Switch over the HTTP response status code.</span>
|
|||
|
|
<span class="k">switch</span> <span class="n">response</span> <span class="p">{</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">ok</span><span class="p">(</span><span class="k">let</span> <span class="nv">okResponse</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Switch over the response content type.</span>
|
|||
|
|
<span class="k">switch</span> <span class="n">okResponse</span><span class="o">.</span><span class="n">body</span> <span class="p">{</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">json</span><span class="p">(</span><span class="k">let</span> <span class="nv">greeting</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Print the greeting message.</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="s">"👋 </span><span class="se">\(</span><span class="n">greeting</span><span class="o">.</span><span class="n">message</span><span class="se">)</span><span class="s">"</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="k">case</span> <span class="o">.</span><span class="nf">undocumented</span><span class="p">(</span><span class="nv">statusCode</span><span class="p">:</span> <span class="k">let</span> <span class="nv">statusCode</span><span class="p">,</span> <span class="n">_</span><span class="p">):</span>
|
|||
|
|
<span class="c1">// Handle HTTP response status codes not documented in the OpenAPI document.</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="s">"🥺 undocumented response: </span><span class="se">\(</span><span class="n">statusCode</span><span class="se">)</span><span class="s">"</span><span class="p">)</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>Note: While the sample code above uses the <a href="https://github.com/apple/swift-openapi-urlsession">URLSession-based client transport</a>, there are other client transport implementations, or you can create your own.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<h3 id="using-generated-api-server-stubs">Using Generated API Server Stubs</h3>
|
|||
|
|
|
|||
|
|
<p>When developing a server, you get two generated types for use in your code:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">APIProtocol</code>, a protocol that contains one method per OpenAPI operation, the same as in the client example above.</li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">APIProtocol.registerHandlers</code>, a method on <code class="language-plaintext highlighter-rouge">APIProtocol</code> that registers one handler per OpenAPI operation, which calls the <code class="language-plaintext highlighter-rouge">getGreeting</code> method that you implement.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Below is example code to implement a simple handler and use it to start the server:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">import</span> <span class="kt">OpenAPIRuntime</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">OpenAPIVapor</span>
|
|||
|
|
<span class="kd">import</span> <span class="kt">Vapor</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// A server implementation of the GreetingService API.</span>
|
|||
|
|
<span class="kd">struct</span> <span class="kt">Handler</span><span class="p">:</span> <span class="kt">APIProtocol</span> <span class="p">{</span>
|
|||
|
|
|
|||
|
|
<span class="kd">func</span> <span class="nf">getGreeting</span><span class="p">(</span>
|
|||
|
|
<span class="n">_</span> <span class="nv">input</span><span class="p">:</span> <span class="kt">Operations</span><span class="o">.</span><span class="n">getGreeting</span><span class="o">.</span><span class="kt">Input</span>
|
|||
|
|
<span class="p">)</span> <span class="k">async</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">Operations</span><span class="o">.</span><span class="n">getGreeting</span><span class="o">.</span><span class="kt">Output</span> <span class="p">{</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">message</span> <span class="o">=</span> <span class="s">"Hello, </span><span class="se">\(</span><span class="n">input</span><span class="o">.</span><span class="n">query</span><span class="o">.</span><span class="n">name</span> <span class="p">??</span> <span class="s">"Stranger"</span><span class="se">)</span><span class="s">!"</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">greeting</span> <span class="o">=</span> <span class="kt">Components</span><span class="o">.</span><span class="kt">Schemas</span><span class="o">.</span><span class="kt">Greeting</span><span class="p">(</span><span class="nv">message</span><span class="p">:</span> <span class="n">message</span><span class="p">)</span>
|
|||
|
|
<span class="k">return</span> <span class="o">.</span><span class="nf">ok</span><span class="p">(</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">body</span><span class="p">:</span> <span class="o">.</span><span class="nf">json</span><span class="p">(</span><span class="n">greeting</span><span class="p">)))</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
<span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Create the Vapor app.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">app</span> <span class="o">=</span> <span class="kt">Vapor</span><span class="o">.</span><span class="kt">Application</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Create the transport.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">transport</span><span class="p">:</span> <span class="kt">ServerTransport</span> <span class="o">=</span> <span class="kt">VaporTransport</span><span class="p">(</span><span class="nv">routesBuilder</span><span class="p">:</span> <span class="n">app</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Create the request handler, which contains your server logic.</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">handler</span> <span class="o">=</span> <span class="kt">Handler</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Register the generated routes on the transport.</span>
|
|||
|
|
<span class="k">try</span> <span class="n">handler</span><span class="o">.</span><span class="nf">registerHandlers</span><span class="p">(</span><span class="nv">on</span><span class="p">:</span> <span class="n">transport</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="c1">// Start the server.</span>
|
|||
|
|
<span class="k">try</span> <span class="n">app</span><span class="o">.</span><span class="nf">run</span><span class="p">()</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>Note: While the sample code above uses the <a href="https://github.com/swift-server/swift-openapi-vapor">Vapor-based server transport</a>, there are other server transport implementations, or you can create your own.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<h2 id="transport-implementations">Transport Implementations</h2>
|
|||
|
|
|
|||
|
|
<p>Swift OpenAPI Generator works with any HTTP client or server library by abstracting the HTTP library interface in the protocols <a href="https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/clienttransport"><code class="language-plaintext highlighter-rouge">ClientTransport</code></a> and <a href="https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/servertransport"><code class="language-plaintext highlighter-rouge">ServerTransport</code></a>. Similar to projects like <a href="https://github.com/apple/swift-log#selecting-a-logging-backend-implementation-applications-only">swift-log</a>, Swift OpenAPI Generator uses the <em>API package</em> approach for greater extensibility.</p>
|
|||
|
|
|
|||
|
|
<p>Below are some examples of existing transport implementations that you can try out today:</p>
|
|||
|
|
|
|||
|
|
<h3 id="client-transport-implementations">Client Transport Implementations</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://github.com/apple/swift-openapi-urlsession">apple/swift-openapi-urlsession</a></li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-async-http-client">swift-server/swift-openapi-async-http-client</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="server-transport-implementations">Server Transport Implementations</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-vapor">swift-server/swift-openapi-vapor</a></li>
|
|||
|
|
<li><a href="https://github.com/swift-server/swift-openapi-hummingbird">swift-server/swift-openapi-hummingbird</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="whats-next">What’s Next</h2>
|
|||
|
|
|
|||
|
|
<p>The project is being open sourced early in its development so the community can provide feedback and help us arrive at a stable 1.0 release.</p>
|
|||
|
|
|
|||
|
|
<p>The initial focus was on implementing features defined by <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md">version 3.0.3</a> of the OpenAPI specification, with ongoing work toward supporting <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md">OpenAPI 3.1</a>.</p>
|
|||
|
|
|
|||
|
|
<p>While Swift OpenAPI Generator supports most of the commonly used features of OpenAPI, there are still several features left to implement, and progress is tracked publicly using GitHub <a href="https://github.com/apple/swift-openapi-generator/issues">issues</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="get-involved">Get Involved</h2>
|
|||
|
|
|
|||
|
|
<p>Check out the repositories, open issues, pull requests, and let us know what you think in the Swift <a href="https://forums.swift.org/c/server">forums</a>.</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="https://developer.apple.com/wwdc23/10171">Meet Swift OpenAPI Generator</a> at WWDC23</li>
|
|||
|
|
<li>Swift OpenAPI Generator: <a href="https://github.com/apple/swift-openapi-generator">https://github.com/apple/swift-openapi-generator</a></li>
|
|||
|
|
<li>Swift OpenAPI Runtime: <a href="https://github.com/apple/swift-openapi-runtime">https://github.com/apple/swift-openapi-runtime</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>We’re excited about what Swift OpenAPI Generator can do for the Swift community by reducing the amount of time it takes to connect to an HTTP service or implement one yourself.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Using Upcoming Feature Flags</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/using-upcoming-feature-flags/"/>
|
|||
|
|
<updated>2023-05-30T06:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/using-upcoming-feature-flags/</id>
|
|||
|
|
<content type="html"><p>Beginning in Swift 5.8 you can flexibly adopt upcoming Swift features using a new compiler flag and compilation condition. This post describes the problem upcoming feature flags solve, their benefits, and how to get started using them in your projects.</p>
|
|||
|
|
|
|||
|
|
<h2 id="source-breaking-changes">Source-Breaking Changes</h2>
|
|||
|
|
|
|||
|
|
<p>Each new release of Swift adds features and capabilities. These changes go through the <a href="https://github.com/apple/swift-evolution/blob/main/process.md">Swift Evolution process</a> where they are proposed, discussed by the community, and accepted.</p>
|
|||
|
|
|
|||
|
|
<p>One important consideration for all changes to Swift is <em>source compatibility</em>. To be source compatible, existing Swift code must continue to compile and behave as expected with new versions of the compiler.</p>
|
|||
|
|
|
|||
|
|
<p>To help meet this strong goal, the Swift project maintains an extensive <a href="/documentation/source-compatibility/">source compatibility test suite</a>. Proposed changes are tested to ensure they do not introduce source-breaking changes. In addition, each evolution proposal includes a discussion of source compatibility.</p>
|
|||
|
|
|
|||
|
|
<p>On rare occasions, a proposed change that breaks source compatibility is considered important enough to be accepted. These source-breaking changes are not introduced immediately, but wait until the next major version of Swift.</p>
|
|||
|
|
|
|||
|
|
<h2 id="an-example-regex-literals">An Example: Regex Literals</h2>
|
|||
|
|
<p>One example of a source-breaking change is the syntax for Regex literals introduced in Swift 5.7.</p>
|
|||
|
|
|
|||
|
|
<p>The desired literal syntax is to enclose the regex pattern in forward slashes, which is the convention for regular expressions in many different tools and languages:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="sr">/[a-zA-Z_][0-9a-zA-Z_]*/</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>However, there are cases where this new syntax would break existing code, as detailed in <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0354-regex-literals.md#source-compatibility">the SE-0354 proposal</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Even though the source incompatibility would not affect many projects and is not likely to be a difficult fix in affected projects, it is still a breaking change.</p>
|
|||
|
|
|
|||
|
|
<p>Therefore, in Swift 5.7, regex literals only support the extended literal delimiters:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="sr">#/[a-zA-Z_][0-9a-zA-Z_]*/#</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>The source breaking change does not come into effect until the next major language version — Swift 6.</p>
|
|||
|
|
|
|||
|
|
<p>However, it would be beneficial for developers to be able to opt into using the ‘bare slash’ syntax for Regex literals now, rather than wait until Swift 6.</p>
|
|||
|
|
|
|||
|
|
<p>To allow this, when Swift 5.7 was introduced, a new compiler flag <code class="language-plaintext highlighter-rouge">-enable-bare-slash-regex</code> was added. For any target with this flag set, the Swift 6 syntax is accepted.</p>
|
|||
|
|
|
|||
|
|
<p>SDKs that shipped with Xcode 14 have this flag set by default, so you may already be using this syntax.</p>
|
|||
|
|
|
|||
|
|
<h2 id="a-generalized-solution">A Generalized Solution</h2>
|
|||
|
|
<p>The idea of being able to adopt upcoming changes sooner rather than later is a good one. However, adding an ever-increasing number of separate compiler flags for each upcoming feature does not scale well.</p>
|
|||
|
|
|
|||
|
|
<p>To address this, Swift evolution proposal <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md">SE-0362</a>, implemented in Swift 5.8, details a generalized mechanism for enabling upcoming features.</p>
|
|||
|
|
|
|||
|
|
<p>Instead of creating a different compiler flag for each upcoming feature, the compiler gains one new flag that is followed by the name of the feature to be enabled:</p>
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> -enable-upcoming-feature SomeUpcomingFeature
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>For example, to enable the upcoming Regex literal syntax you would use:</p>
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> -enable-upcoming-feature BareRegexLiteralSyntax
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>In Swift Package Manager manifests you specify these using a new <code class="language-plaintext highlighter-rouge">SwiftSetting</code>:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">.</span><span class="nf">enableUpcomingFeature</span><span class="p">(</span><span class="s">"BareSlashRegexLiterals"</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<h3 id="checking-for-features-in-code">Checking For Features In Code</h3>
|
|||
|
|
|
|||
|
|
<p>SE-0362 also introduces a new <code class="language-plaintext highlighter-rouge">hasFeature()</code> compilation condition that checks whether a feature is enabled. This allows you to write code that uses a feature if present or uses alternate code if not present.</p>
|
|||
|
|
|
|||
|
|
<p>You specify which feature by using its upcoming feature flag as an argument to <code class="language-plaintext highlighter-rouge">hasFeature()</code>, as shown in the example below.</p>
|
|||
|
|
|
|||
|
|
<p>Note that since <code class="language-plaintext highlighter-rouge">hasFeature()</code> was introduced with the Swift 5.8 compiler, earlier versions do not recognize it. You may need to check the compiler version when using it.</p>
|
|||
|
|
|
|||
|
|
<p>For example:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">#if compiler(&gt;=5.8)</span>
|
|||
|
|
<span class="cp">#if hasFeature(BareSlashRegexLiterals)</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="sr">/.../</span>
|
|||
|
|
<span class="cp">#else</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="sr">#/.../#</span>
|
|||
|
|
<span class="cp">#endif</span>
|
|||
|
|
<span class="cp">#else</span>
|
|||
|
|
<span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">NSRegularExpression</span><span class="p">(</span><span class="nv">pattern</span><span class="p">:</span> <span class="s">"..."</span><span class="p">)</span>
|
|||
|
|
<span class="cp">#endif</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>The section <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md#feature-detection-in-source-code">Feature detection in source code</a> in SE-0362 discusses the use of <code class="language-plaintext highlighter-rouge">hasFeature()</code> in detail.</p>
|
|||
|
|
|
|||
|
|
<h2 id="benefits-of-enabling-upcoming-features">Benefits Of Enabling Upcoming Features</h2>
|
|||
|
|
|
|||
|
|
<p>There are two significant benefits to enabling upcoming features in your code.</p>
|
|||
|
|
|
|||
|
|
<p>First, you’ll find out immediately if your code will require changes. This lets you discover the scope of any work needed and gives you the flexibility to update your code now or when it best fits your schedule.</p>
|
|||
|
|
|
|||
|
|
<p>Second, you can start using the upcoming features right away. All new code you write incorporates these changes, easing your eventual move to the next major language version. You’ll also begin building ‘muscle memory’ and experience with the upcoming syntax and behavior.</p>
|
|||
|
|
|
|||
|
|
<h2 id="how-to-enable-upcoming-features">How To Enable Upcoming Features</h2>
|
|||
|
|
<p>You enable an upcoming feature by setting the compiler flag for a given target.</p>
|
|||
|
|
|
|||
|
|
<p>To enable multiple features, use the compiler flag multiple times, once per enabled feature.</p>
|
|||
|
|
|
|||
|
|
<p>This allows you to adopt features in a very flexible manner, target by target, feature by feature.</p>
|
|||
|
|
|
|||
|
|
<h3 id="in-xcode">In Xcode</h3>
|
|||
|
|
<p>For Xcode projects, add the compiler flags to the ‘Other Swift Flags’ build setting:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>In the project navigator, select the project</li>
|
|||
|
|
<li>In the project editor, select the desired target or the project itself</li>
|
|||
|
|
<li>Select the Build Settings tab</li>
|
|||
|
|
<li>Make sure the All scope button is selected</li>
|
|||
|
|
<li>Search for ‘swift flags’ to find the Other Swift Flags build setting</li>
|
|||
|
|
<li>Double-click to add one or more <code class="language-plaintext highlighter-rouge">-enable-upcoming-feature</code> flags to the setting</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>The screenshot below shows three upcoming features being enabled:</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/upcoming-feature-flags-blog/upcoming-feature-flags-xcode.png" alt="Screen capture of Xcode project editor with app target, Build Settings tab, and All scope bar button selected. Displaying the Other Swift Flags build setting and a popover showing the list of flags -enable-upcoming-feature, ConciseMagicFile, -enable-upcoming-feature, ExistentialAny, -enable-upcoming-feature, BareSlashRegexLiterals" width="680" /></p>
|
|||
|
|
|
|||
|
|
<p>If your project uses <code class="language-plaintext highlighter-rouge">xcconfig</code> configuration files, you can improve the readability of multiple settings by using a backslash to have the build setting span multiple lines:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">OTHER_SWIFT_FLAGS</span> <span class="o">=</span> <span class="err">$</span><span class="p">(</span><span class="n">inherited</span><span class="p">)</span> <span class="p">\</span>
|
|||
|
|
<span class="o">-</span><span class="n">enable</span><span class="o">-</span><span class="n">upcoming</span><span class="o">-</span><span class="n">feature</span> <span class="kt">ConciseMagicFile</span> <span class="p">\</span>
|
|||
|
|
<span class="o">-</span><span class="n">enable</span><span class="o">-</span><span class="n">upcoming</span><span class="o">-</span><span class="n">feature</span> <span class="kt">BareSlashRegexLiterals</span> <span class="p">\</span>
|
|||
|
|
<span class="o">-</span><span class="n">enable</span><span class="o">-</span><span class="n">upcoming</span><span class="o">-</span><span class="n">feature</span> <span class="kt">ExistentialAny</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h3 id="in-swiftpm-packages">In SwiftPM Packages</h3>
|
|||
|
|
<p>For a Swift package, enable upcoming features for a target in its <code class="language-plaintext highlighter-rouge">SwiftSetting</code> array in the package manifest:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">.</span><span class="nf">target</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"MyTarget"</span><span class="p">,</span>
|
|||
|
|
<span class="nv">dependencies</span><span class="p">:[</span><span class="o">.</span><span class="n">fancyLibrary</span><span class="p">],</span>
|
|||
|
|
<span class="nv">swiftSettings</span><span class="p">:</span>
|
|||
|
|
<span class="p">[</span><span class="o">.</span><span class="nf">enableUpcomingFeature</span><span class="p">(</span><span class="s">"ConciseMagicFile"</span><span class="p">),</span>
|
|||
|
|
<span class="o">.</span><span class="nf">enableUpcomingFeature</span><span class="p">(</span><span class="s">"BareSlashRegexLiterals"</span><span class="p">),</span>
|
|||
|
|
<span class="o">.</span><span class="nf">enableUpcomingFeature</span><span class="p">(</span><span class="s">"ExistentialAny"</span><span class="p">)])</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>You will also need to update the tools version specified in the manifest to 5.8 or later:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// swift-tools-version: 5.8</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<h2 id="finding-upcoming-feature-flags">Finding Upcoming Feature Flags</h2>
|
|||
|
|
|
|||
|
|
<p>Use the <a href="/swift-evolution/">Swift Evolution Dashboard</a> to find upcoming feature flags:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Filter to see all proposals with an upcoming feature flag</li>
|
|||
|
|
<li>Search for upcoming feature flags by name</li>
|
|||
|
|
<li>View upcoming feature flags for proposals that define one</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Each dashboard entry links to full Swift Evolution proposal where the upcoming feature flag is defined. Details on the changes that the flag enables are in the body of the proposal, typically in the <em>Source Compatibility</em> section.</p>
|
|||
|
|
|
|||
|
|
<p>It’s also important to note that most changes to Swift maintain source compatibility and therefore do not have an upcoming feature flag.</p>
|
|||
|
|
|
|||
|
|
<h2 id="upcoming-feature-flags-added-in-swift-58">Upcoming Feature Flags Added In Swift 5.8</h2>
|
|||
|
|
|
|||
|
|
<p>As of Swift 5.8, the current set of upcoming feature flags are:</p>
|
|||
|
|
|
|||
|
|
<h4 id="se-0274-concise-magic-file-names"><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0274-magic-file.md">SE-0274</a>: Concise magic file names</h4>
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">#file</code> literal generates a string with the format <code class="language-plaintext highlighter-rouge">&lt;module-name&gt;/&lt;file-name&gt;</code> instead of the full file path.</p>
|
|||
|
|
|
|||
|
|
<p>Upcoming Feature Flag: <code class="language-plaintext highlighter-rouge">ConciseMagicFile</code></p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0274-magic-file.md#source-compatibility">Read Full Details</a></p>
|
|||
|
|
|
|||
|
|
<h4 id="se-0286-forward-scan-matching-for-trailing-closures"><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0286-forward-scan-trailing-closures.md">SE-0286</a>: Forward-scan matching for trailing closures</h4>
|
|||
|
|
<p>Some existing methods can be ambiguous or fail to type check when called using multiple trailing closures. In these cases, provide the closures as regular arguments.</p>
|
|||
|
|
|
|||
|
|
<p>Upcoming Feature Flag: <code class="language-plaintext highlighter-rouge">ForwardTrailingClosures </code></p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0286-forward-scan-trailing-closures.md#mitigating-the-source-compatibility-impact-swift--6">Read Full Details</a></p>
|
|||
|
|
|
|||
|
|
<h4 id="se-0335-introduce-existential-any"><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md">SE-0335</a>: Introduce existential any</h4>
|
|||
|
|
<p>The <code class="language-plaintext highlighter-rouge">any</code> keyword must be used when a protocol is used as an existential type.</p>
|
|||
|
|
|
|||
|
|
<p>Example:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@protocol</span> <span class="kt">Drawable</span> <span class="p">{</span> <span class="p">}</span>
|
|||
|
|
|
|||
|
|
<span class="k">let</span> <span class="nv">drawable</span><span class="p">:</span> <span class="kd">any</span> <span class="kt">Drawable</span> <span class="c1">// Use of 'any' keyword required</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>Upcoming Feature Flag: <code class="language-plaintext highlighter-rouge">ExistentialAny </code></p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md#source-compatibility">Read Full Details</a></p>
|
|||
|
|
|
|||
|
|
<h4 id="se-0354-regex-literals"><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0354-regex-literals.md">SE-0354</a>: Regex literals</h4>
|
|||
|
|
<p>Allows Regex literals to use forward slash as the delimiter.</p>
|
|||
|
|
|
|||
|
|
<p>Example:</p>
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">regex</span> <span class="o">=</span> <span class="sr">/[a-zA-Z_][0-9a-zA-Z_]*/</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
<p>Upcoming Feature Flag: <code class="language-plaintext highlighter-rouge">BareSlashRegexLiterals </code></p>
|
|||
|
|
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0354-regex-literals.md#source-compatibility">Read Full Details</a></p>
|
|||
|
|
|
|||
|
|
<h2 id="get-started-today">Get Started Today</h2>
|
|||
|
|
|
|||
|
|
<p>Enabling upcoming features gives you a flexible way to migrate your code to adopt changes coming in the next major release of Swift at your own pace, feature by feature, target by target.</p>
|
|||
|
|
|
|||
|
|
<p>You can start looking into these features today in a low-risk way by creating a test branch of your project and enabling upcoming features one at a time, one target at a time.</p>
|
|||
|
|
|
|||
|
|
<p>Of course, on a team, code migration of this sort needs to be planned and communicated.</p>
|
|||
|
|
|
|||
|
|
<p>These new capabilities in Swift 5.8 give you and your team additional lead time and flexibility to investigate, plan, and schedule any changes needed to adopt upcoming features.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Evolving the Swift Workgroups</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/evolving-swift-project-workgroups/"/>
|
|||
|
|
<updated>2023-05-18T06:30:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/evolving-swift-project-workgroups/</id>
|
|||
|
|
<content type="html"><p>Today, the Swift Core Team is announcing forward-looking changes to the structure of Swift, the work, and the people around it. These changes include new groups, names, organization, as well as inclusion as a first-class concept for each group:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p>We are organizing all workgroups into two tiers — steering groups and workgroups.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>We are incorporating the core mission of Diversity in Swift in all workgroups.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>We are creating the Ecosystem Steering Group and Contributor Experience Workgroups to provide vital support for the growing Swift developer ecosystem and community.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Let’s dive into the details.</p>
|
|||
|
|
|
|||
|
|
<h2 id="steering-groups-and-workgroups">Steering Groups and Workgroups</h2>
|
|||
|
|
|
|||
|
|
<p>Until today, the Swift project used “team” and “workgroup” interchangeably to describe groups working together on some community effort or area of responsibility.</p>
|
|||
|
|
|
|||
|
|
<p>Aside from using “team” for the Core Team, we will consistently use the term <strong>group</strong>.</p>
|
|||
|
|
|
|||
|
|
<p>Each group will have a clear charter and focus. Groups can also have <strong>subgroups</strong> that are smaller scoped units of focus under another group.</p>
|
|||
|
|
|
|||
|
|
<p>There are two kinds of groups:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p><strong>Steering groups</strong> are responsible for the overall strategic direction in a broad area or a necessary process that affects the entire community.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><strong>Workgroups</strong> represent functional areas of the project and drive work in a particular area. Subgroups of workgroups help further refine tasks and deliverables. Workgroups are long-term and focus on a specific domain. Various active contributors lead workgroups.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>The purpose of workgroups is to provide structure to help support contributors in organizing and driving activity. However, workgroups are only one of the ways to organize and contribute to Swift. Most contributions and community activities begin and grow organically. Once an effort reaches sufficient momentum and size where it could benefit from support from the Swift project, forming a workgroup for that effort makes sense.</p>
|
|||
|
|
|
|||
|
|
<p>Note that the <a href="https://github.com/apple/swift-evolution/blob/main/process.md">evolution workgroups</a> as described in the Swift Evolution process, can either be steering groups or workgroups. Evolution workgroups are groups that utilize or manage the Swift Evolution process in some way to achieve their core charter.</p>
|
|||
|
|
|
|||
|
|
<h3 id="adopting-the-groups-terminology">Adopting the “Groups” Terminology</h3>
|
|||
|
|
|
|||
|
|
<p>We are adjusting the names of the current groups and “teams” to match the new terminology.</p>
|
|||
|
|
|
|||
|
|
<p>Steering groups:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>The <strong>Language Workgroup</strong> becomes the <strong>Language Steering Group</strong>, and continues to use the Swift Evolution process to help drive the language forward. The group’s membership will change over time as contributors are recognized for their active participation in helping shape the direction of the Swift language.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Workgroups:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p>The <strong>Server Workgroup</strong>, often referred to as the “Swift on Server Workgroup,” promotes the use of Swift for developing and deploying server applications.
|
|||
|
|
The workgroup has helped <a href="/sswg/incubation-process.html">incubate</a> more than twenty critical server libraries, some of which the workgroup members developed together with the rest of the community. It also published in-depth guides for developing, deploying, and troubleshooting server applications written in Swift.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <strong>Documentation Workgroup</strong> helps guide the documentation experience for Swift. The workgroup shepherds the development of <a href="https://github.com/apple/swift-docc">Swift-DocC</a> features that bring exciting ways to customize and enhance the experience of authored API documentation. The group also published a revamped version of <em><a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/">The Swift Programming Language</a></em> book written using DocC and maintained by the open source community.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <strong>Website Workgroup</strong> helps guide the evolution on the <a href="http://swift.org/">Swift.org</a> website. Since its inception, the website workgroup has helped review and integrate community-driven improvements to the website, including the introduction of server development guides in collaboration with the server workgroup, integration of the Swift Evolution dashboard, and numerous documentation and language fixes. The workgroup has also established a process for community-driven blog posts (initially piloted by the Diversity in Swift workgroup) designed to provide opportunities for community members to showcase their journey with Swift.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>The <strong>C++ Interoperability Workgroup</strong> works to build and advance the interoperability support between Swift and C++, prototyping and proposing changes to Swift that go through the Swift Evolution process.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>Overseeing the steering and workgroups is the <strong>Swift Core Team</strong>. We briefly considered adjusting its name to adopt the “group” terminology, but decided to retain its “team” name because it has been in use for so long and is widely recognized by the community. The Swift Core team, is a body that provides cohesion and strategic alignment across the Swift community’s various Groups and initiatives. The Project Lead appoints members of the Core Team to bring a mixture of experience, expertise, and leadership so the group may act as effective stewards for the Swift project and its community. The Core Team’s membership will change over time, and the size and shape will evolve with the Swift project’s needs. The Core Team does not make decisions by voting but by general consensus, with the Project Lead stepping in to resolve discussions.</p>
|
|||
|
|
|
|||
|
|
<h2 id="extending-diversity-in-swift">Extending Diversity in Swift</h2>
|
|||
|
|
|
|||
|
|
<p>The Diversity in Swift Workgroup’s mission is to identify pathways to contribute outside the main Swift codebase by creating intentional, concerted efforts to bring new voices to the community. Its achievements are lasting: we now have a community-written blog post process, mentoring programs, and specific community groups for developers to connect with others who have similar experiences and backgrounds, such as Women in Swift, Black in Swift, and Pride in Swift.</p>
|
|||
|
|
|
|||
|
|
<p>Inclusion and diversity are fundamental values in the Swift project that need to be ingrained in the project’s day-to-day operation.</p>
|
|||
|
|
|
|||
|
|
<p>Today, Diversity in Swift is growing as a shared responsibility throughout the Swift project structure. Each group will designate an individual to serve in the new, rotating role of a Diversity in Swift champion. Diversity in Swift champions across all groups will work together to guide their respective groups to participate in initiatives such as the Swift Mentorship Program and form new initiatives. They will provide a feedback channel for members of the Swift community to discuss the topic of inclusion and diversity.</p>
|
|||
|
|
|
|||
|
|
<p>The current members and initiatives of the Diversity in Swift Workgroup will be spread out among the other groups and incorporated into their respective charters. New groups formed in the future will be required to designate a Diversity in Swift champion and address how the workgroup will uphold our values of inclusion in the charter.</p>
|
|||
|
|
|
|||
|
|
<h2 id="announcing-new-groups">Announcing New Groups</h2>
|
|||
|
|
|
|||
|
|
<p>Over the coming weeks, the Swift project will add two new groups to provide support in areas of growing momentum in the Swift project. This overall picture of groups will look as follows:</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/evolving-workgroups-blog/community-structure.png" alt="Swift Workgroups Diagram" /></p>
|
|||
|
|
|
|||
|
|
<h3 id="ecosystem-steering-group">Ecosystem Steering Group</h3>
|
|||
|
|
|
|||
|
|
<p>Notably, we will be creating a new <strong>Ecosystem Steering Group.</strong></p>
|
|||
|
|
|
|||
|
|
<p>Successful programming languages have an extensive supporting system focused on developer experience and productivity through tooling, documentation, and other development resources.</p>
|
|||
|
|
|
|||
|
|
<p>The new Ecosystem Steering Group will focus on growing that support structure for Swift. It will support the evolution of developer and documentation tooling, the Swift.org website, the package manager, and the package ecosystem. The steering group will also support the work to bring Swift to additional platforms and the tooling to make creating such ports easier. Finally, the group will support the growth of Swift in standard or industry-leading developer productivity tooling including cloud-based IDEs and continuous integration systems.</p>
|
|||
|
|
|
|||
|
|
<p>A follow-up announcement will provide additional details on the charter of the Ecosystem Steering Group, its scope and responsibilities. With its charter formalized, the new steering group will form an additional set of workgroups to drive specific initiatives within its charter. The Core Team will choose the inaugural members of the Ecosystem Steering Group.</p>
|
|||
|
|
|
|||
|
|
<h3 id="contributor-experience-workgroup">Contributor Experience Workgroup</h3>
|
|||
|
|
|
|||
|
|
<p>Finally, a new <strong>Contributor Experience Workgroup</strong> will create new pathways into the open source Swift community, including the Swift Mentorship Program and Community Groups.</p>
|
|||
|
|
|
|||
|
|
<p>This shift in stewardship will enable the Diversity in Swift champions to focus on diversity being both at the core and pervasive throughout the project and Swift community, while the Contributor Experience group will support all forms of contributing to the Swift project.</p>
|
|||
|
|
|
|||
|
|
<p>The new Contributor Experience workgroup will explore providing community members with the best support system and mechanics. Some example investments from this new workgroup will be improvements to the process and documentation for contributing code, bug reports, discussion on the Swift Forums, and more.</p>
|
|||
|
|
|
|||
|
|
<p>For more details, please see the <a href="/contributor-experience-workgroup">Contributor Experience Workgroup Charter</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="next-steps-and-you">Next Steps and You</h2>
|
|||
|
|
|
|||
|
|
<p>If you’re interested in getting involved, check out the charters of the above groups, or read about other ways to <a href="/contributing/">contribute to the project</a>. If you have contributed and don’t fall neatly into one of the groups above, keep going! All contributions are valuable.</p>
|
|||
|
|
|
|||
|
|
<p>If you want to keep up with these changes, we invite you to join us for the kick-off of our Contributor Meeting series, occurring quarterly. Keep an eye out for more information on the Swift forums.</p>
|
|||
|
|
|
|||
|
|
<p>Onward!</p>
|
|||
|
|
|
|||
|
|
<h3 id="previous-related-announcements">Previous Related Announcements</h3>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="/blog/documentation-workgroup/">Documentation Workgroup announcement</a></li>
|
|||
|
|
<li><a href="/blog/language-workgroup/">Language Workgroup announcement</a></li>
|
|||
|
|
<li><a href="/blog/website-open-source/">Website Workgroup announcement</a></li>
|
|||
|
|
<li><a href="/blog/server-api-workgroup/">Server Workgroup announcement</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Foundation Package Preview Now Available</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/foundation-preview-now-available/"/>
|
|||
|
|
<updated>2023-04-26T06:30:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/foundation-preview-now-available/</id>
|
|||
|
|
<content type="html"><p>I’m pleased to announce that a preview of the <a href="https://www.swift.org/blog/future-of-foundation/">future of Foundation</a> is now available on <a href="https://github.com/apple/swift-foundation">GitHub</a>!</p>
|
|||
|
|
|
|||
|
|
<p>This preview provides a unified implementation of Foundation, written in Swift, that is faster, safer, and more approachable to new contributors.</p>
|
|||
|
|
|
|||
|
|
<p>A new Foundation Workgroup will run reviews of proposed Foundation API and coordinate the needs of the Swift community with Apple engineering.</p>
|
|||
|
|
|
|||
|
|
<p>While the new package is not yet complete, it provides the first building blocks of our unified Swift implementation and I am eager to provide it to the Swift community for early testing and contributions.</p>
|
|||
|
|
|
|||
|
|
<h2 id="current-state">Current State</h2>
|
|||
|
|
|
|||
|
|
<p>The following types are available in the preview package, with more to come later. Many types, including <code class="language-plaintext highlighter-rouge">JSONEncoder</code>, <code class="language-plaintext highlighter-rouge">Calendar</code>, <code class="language-plaintext highlighter-rouge">TimeZone</code>, and <code class="language-plaintext highlighter-rouge">Locale</code> are all-new Swift implementations. <code class="language-plaintext highlighter-rouge">FormatStyle</code> and <code class="language-plaintext highlighter-rouge">ParseStyle</code> available as open source for the first time.</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>FoundationEssentials</strong>
|
|||
|
|
<ul>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">AttributedString</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Data</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Date</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">DateInterval</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">JSONEncoder</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">JSONDecoder</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Predicate</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">String</code> extensions</li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">UUID</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><strong>Internationalization</strong>
|
|||
|
|
<ul>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Calendar</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">TimeZone</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">Locale</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">DateComponents</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">FormatStyle</code></li>
|
|||
|
|
<li><code class="language-plaintext highlighter-rouge">ParseStrategy</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>For internationalization support on non-Darwin platforms, we created a separate package named <em><a href="https://github.com/apple/swift-foundation-icu">FoundationICU</a></em>. This repository contains the necessary ICU implementations and data from the upstream <a href="https://github.com/apple-oss-distributions/ICU">Apple OSS Distribution ICU</a>. Using a common version of ICU will result in more reliable and consistent results when formatting dates, times and numbers.</p>
|
|||
|
|
|
|||
|
|
<blockquote>
|
|||
|
|
<p>Note: The Foundation Preview package depends on the under-development <a href="https://www.swift.org/download">Swift 5.9 toolchain</a>.</p>
|
|||
|
|
</blockquote>
|
|||
|
|
|
|||
|
|
<h2 id="performance">Performance</h2>
|
|||
|
|
|
|||
|
|
<p>Being written in Swift, this new implementation provides some major benefits over the previous C and Objective-C versions.</p>
|
|||
|
|
|
|||
|
|
<p><code class="language-plaintext highlighter-rouge">Locale</code>, <code class="language-plaintext highlighter-rouge">TimeZone</code> and <code class="language-plaintext highlighter-rouge">Calendar</code> no longer require bridging from Objective-C. Common tasks like getting a fixed <code class="language-plaintext highlighter-rouge">Locale</code> are an order of magnitude faster for Swift clients. <code class="language-plaintext highlighter-rouge">Calendar</code>’s ability to calculate important dates can take better advantage of Swift’s value semantics to avoid intermediate allocations, resulting in over a 20% improvement in some benchmarks. Date formatting using <code class="language-plaintext highlighter-rouge">FormatStyle</code> also has some major performance upgrades, showing a massive 150% improvement in a benchmark of formatting with a standard date and time template.</p>
|
|||
|
|
|
|||
|
|
<p>Even more exciting are the improvements to JSON decoding in the new package. Foundation has a brand-new Swift implementation for <code class="language-plaintext highlighter-rouge">JSONDecoder</code> and <code class="language-plaintext highlighter-rouge">JSONEncoder</code>, eliminating costly roundtrips to and from the Objective-C collection types. The tight integration of parsing JSON in Swift for initializing <code class="language-plaintext highlighter-rouge">Codable</code> types improves performance, too. In benchmarks parsing <a href="https://www.boost.org/doc/libs/master/libs/json/doc/html/json/benchmarks.html">test data</a>, there are improvements in decode time from 200% to almost 500%.</p>
|
|||
|
|
|
|||
|
|
<h2 id="governance">Governance</h2>
|
|||
|
|
|
|||
|
|
<p>The success of the Swift language is a great example of what is possible when a community comes together with a shared interest.</p>
|
|||
|
|
|
|||
|
|
<p>For Foundation, our goal is to create the best fundamental data types and internationalization features, and make them available to Swift developers everywhere. It will take advantage of emerging features in the language as they are added, and enable library and app authors to build higher level API with confidence.</p>
|
|||
|
|
|
|||
|
|
<p>Moving Foundation into this future requires not only an improved implementation, but also an improved process for using it outside of Apple’s platforms. Therefore, Foundation now has a path for the community to add new API for the benefit of Swift developers on every platform.</p>
|
|||
|
|
|
|||
|
|
<p>The Foundation package is an independent project in its early incubation stages. Inspired by the workgroups in the Swift project, it will have a workgroup to (a) oversee <a href="https://github.com/apple/swift-foundation/blob/main/Evolution.md">community API proposals</a> and (b) to closely coordinate with developments in the Swift project and those on Apple’s platforms. In the future, we will explore how to sunset the existing <a href="https://github.com/apple/swift-corelibs-foundation">swift-corelibs-foundation</a> and migrate to using the new version of Foundation created by this project.</p>
|
|||
|
|
|
|||
|
|
<p>The workgroup will meet regularly to review proposals, look at emerging trends in the Swift ecosystem, and discuss how the library can evolve to best meet our common goals. The initial members of the workgroup will be announced in the coming weeks.</p>
|
|||
|
|
|
|||
|
|
<h2 id="next-steps">Next Steps</h2>
|
|||
|
|
|
|||
|
|
<p>Quality and performance are our two most important goals for the project. Therefore, the plans for the first half of 2023 are continuing refinement of the core API, adding to our suites of unit and performance tests, and expanding to other platforms where possible, using the most relevant code from <a href="https://github.com/apple/swift-corelibs-foundation">swift-corelibs-foundation</a>.</p>
|
|||
|
|
|
|||
|
|
<p>As a secondary goal, the project requests community proposals to add new APIs with focused scope to round out existing API functionality in Foundation. This will pave the way to explore how to add significant new APIs as the project progresses. In 2023, we aim to accept a small number of proposals with corresponding Swift implementations. The experience from reviewing and accepting those new APIs will help to refine the API proposal process and facilitate scaling up to more API contributions in the future.</p>
|
|||
|
|
|
|||
|
|
<p>Later this year, the porting will continue with high-quality Swift implementations of additional Foundation API such as <code class="language-plaintext highlighter-rouge">URL</code>, <code class="language-plaintext highlighter-rouge">Bundle</code>, <code class="language-plaintext highlighter-rouge">FileManager</code>, <code class="language-plaintext highlighter-rouge">FileHandle</code>, <code class="language-plaintext highlighter-rouge">Process</code>, <code class="language-plaintext highlighter-rouge">SortDescriptor</code>, <code class="language-plaintext highlighter-rouge">SortComparator</code> and more.</p>
|
|||
|
|
|
|||
|
|
<h2 id="contributions">Contributions</h2>
|
|||
|
|
|
|||
|
|
<p>Foundation welcomes contributions from the community. The project uses the <a href="https://forums.swift.org/c/related-projects/foundation/99">Swift forums for discussion</a> and <a href="https://github.com/apple/swift-foundation/issues">GitHub Issues</a> for tracking bugs, feature requests, and other work. Please see the <a href="https://github.com/apple/swift-foundation/blob/main/CONTRIBUTING.md">CONTRIBUTING</a> document for more information, including the process for accepting community contributions for new API in Foundation.</p>
|
|||
|
|
|
|||
|
|
<p>I’m excited to start this new chapter in the development of Foundation.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift 5.8 Released!</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-5.8-released/"/>
|
|||
|
|
<updated>2023-03-30T11:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-5.8-released/</id>
|
|||
|
|
<content type="html"><p>Swift 5.8 is now officially released! 🎉 This release includes major additions to the <a href="#language-and-standard-library">language and standard library</a>, including <code class="language-plaintext highlighter-rouge">hasFeature</code> to support piecemeal adoption of upcoming features, an improved <a href="#developer-experience">developer experience</a>, improvements to tools in the Swift ecosystem including <a href="#swift-docc">Swift-DocC</a>, <a href="#swift-package-manager">Swift Package Manager</a>, and <a href="#swiftsyntax">SwiftSyntax</a>, refined <a href="#windows-platform">Windows support</a>, and more.</p>
|
|||
|
|
|
|||
|
|
<p>Thank you to everyone in the Swift community who made this release possible. Your Swift Forums discussions, bug reports, pull requests, educational content, and other contributions are always appreciated!</p>
|
|||
|
|
|
|||
|
|
<p>For a quick dive into some of what’s new in Swift 5.8, check out this <a href="https://github.com/twostraws/whats-new-in-swift-5-8">playground</a> put together by Paul Hudson.</p>
|
|||
|
|
|
|||
|
|
<p><a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/">The Swift Programming Language</a> book has been updated for Swift 5.8 and is now published with DocC. This is the official Swift guide and a great entry point for those new to Swift. The Swift community also maintains a number of <a href="/documentation/tspl/#translations">translations</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="language-and-standard-library">Language and Standard Library</h2>
|
|||
|
|
|
|||
|
|
<p>Swift 5.8 enables you to start incrementally preparing your projects for Swift 6 by <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md">using <em>upcoming features</em></a>. By default, upcoming features are disabled. To enable a feature, pass the compiler flag <code class="language-plaintext highlighter-rouge">-enable-upcoming-feature</code> followed by the feature’s identifier.</p>
|
|||
|
|
|
|||
|
|
<p>Feature identifiers can also be <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md#feature-detection-in-source-code">used in source code</a> using <code class="language-plaintext highlighter-rouge">#if hasFeature(FeatureIdentifier)</code> so that code can still compile with older tools where the upcoming feature is not available.</p>
|
|||
|
|
|
|||
|
|
<p>Swift 5.8 includes upcoming features for the following Swift evolution proposals:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>SE-0274: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0274-magic-file.md">Concise magic file names</a> (<code class="language-plaintext highlighter-rouge">ConciseMagicFile</code>)</li>
|
|||
|
|
<li>SE-0286: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0286-forward-scan-trailing-closures.md">Forward-scan matching for trailing closures</a> (<code class="language-plaintext highlighter-rouge">ForwardTrailingClosures</code>)</li>
|
|||
|
|
<li>SE-0335: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0335-existential-any.md">Introduce existential any</a> (<code class="language-plaintext highlighter-rouge">ExistentialAny</code>)</li>
|
|||
|
|
<li>SE-0354: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0354-regex-literals.md">Regex literals</a> (<code class="language-plaintext highlighter-rouge">BareSlashRegexLiterals</code>)</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>For example, building the following file at <code class="language-plaintext highlighter-rouge">/Users/example/Desktop/0274-magic-file.swift</code> in a module called <code class="language-plaintext highlighter-rouge">MagicFile</code> with <code class="language-plaintext highlighter-rouge">-enable-experimental-feature ConciseMagicFile</code> will opt into the concise format for <code class="language-plaintext highlighter-rouge">#file</code> and <code class="language-plaintext highlighter-rouge">#filePath</code> described in SE-0274:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">print</span><span class="p">(</span><span class="k">#file</span><span class="p">)</span>
|
|||
|
|
<span class="nf">print</span><span class="p">(</span><span class="k">#filePath</span><span class="p">)</span>
|
|||
|
|
<span class="nf">fatalError</span><span class="p">(</span><span class="s">"Something bad happened!"</span><span class="p">)</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>The above code will produce the following output:</p>
|
|||
|
|
|
|||
|
|
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>MagicFile/0274-magic-file.swift
|
|||
|
|
/Users/example/Desktop/0274-magic-file.swift
|
|||
|
|
Fatal error: Something bad happened!: file MagicFile/0274-magic-file.swift, line 3
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Swift 5.8 also includes <em>conditional attributes</em> to reduce the maintenance cost of libraries that support multiple Swift tools versions. <code class="language-plaintext highlighter-rouge">#if</code> checks can now surround attributes on a declaration, and a new <code class="language-plaintext highlighter-rouge">hasAttribute(AttributeName)</code> conditional directive can be used to check whether the compiler version has support for the attribute with the name <code class="language-plaintext highlighter-rouge">AttributeName</code> in the current language mode:</p>
|
|||
|
|
|
|||
|
|
<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">#if hasAttribute(preconcurrency)</span>
|
|||
|
|
<span class="kd">@preconcurrency</span>
|
|||
|
|
<span class="cp">#endif</span>
|
|||
|
|
<span class="kd">protocol</span> <span class="kt">P</span><span class="p">:</span> <span class="kt">Sendable</span> <span class="p">{</span> <span class="o">...</span> <span class="p">}</span>
|
|||
|
|
</code></pre></div></div>
|
|||
|
|
|
|||
|
|
<p>Swift 5.8 brings other language and standard library enhancements, including <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0375-opening-existential-optional.md">unboxing for <code class="language-plaintext highlighter-rouge">any</code> arguments to optional parameters</a>, <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0373-vars-without-limits-in-result-builders.md">local wrapped properties in result builders</a>, <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0369-add-customdebugdescription-conformance-to-anykeypath.md">improved debug printing for key paths</a>, and more.</p>
|
|||
|
|
|
|||
|
|
<p>You can find the complete list of Swift Evolution proposals that were implemented in Swift 5.8 in the <a href="#swift-evolution-appendix">Swift Evolution Appendix</a> below.</p>
|
|||
|
|
|
|||
|
|
<h2 id="developer-experience">Developer Experience</h2>
|
|||
|
|
|
|||
|
|
<h3 id="improved-result-builder-implementation">Improved Result Builder Implementation</h3>
|
|||
|
|
|
|||
|
|
<p>The result builder implementation has been reworked in Swift 5.8 to greatly improve compile-time performance, code completion results, and diagnostics. The Swift 5.8 result builder implementation enforces stricter type inference that matches the semantics in <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0289-result-builders.md">SE-0289: Result Builders</a>, which has an impact on some existing code that relied on invalid type inference.</p>
|
|||
|
|
|
|||
|
|
<p>The new implementation takes advantage of the <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0326-extending-multi-statement-closure-inference.md">extended multi-statement closure inference</a> introduced in Swift 5.7 and applies the result builder transformation exactly as specified by the result builder proposal - a source-level transformation which is type-checked like a multi-statement closure. Doing so enables the compiler to take advantage of all the benefits of the improved closure inference for result builder-transformed code, including optimized type-checking performance (especially in invalid code) and improved error messages.</p>
|
|||
|
|
|
|||
|
|
<p>For more details, please refer to the <a href="https://forums.swift.org/t/improved-result-builder-implementation-in-swift-5-8/63192">Swift Forums post</a> that outlines the improvements and provides more information about invalid inference scenarios.</p>
|
|||
|
|
|
|||
|
|
<h2 id="ecosystem">Ecosystem</h2>
|
|||
|
|
|
|||
|
|
<h3 id="swift-docc">Swift-DocC</h3>
|
|||
|
|
|
|||
|
|
<p>As <a href="https://www.swift.org/blog/tspl-on-docc/">announced in February</a>, The Swift Programming Language book has been converted to Swift-DocC and made <a href="https://github.com/apple/swift-book">open source</a>, and with it came some enhancements to Swift-DocC itself in the form of <a href="https://www.swift.org/documentation/docc/options">option directives</a> you can use to change the behavior of your generated documentation. Swift-DocC has also added some new directives to create more <a href="https://www.swift.org/documentation/docc/api-reference-syntax#creating-custom-page-layouts">dynamic documentation pages</a>, including <a href="https://www.swift.org/documentation/docc/row">Grid-based layouts</a> and <a href="https://www.swift.org/documentation/docc/tab">tab navigators</a>.</p>
|
|||
|
|
|
|||
|
|
<p>To take things even further, you can now <a href="https://www.swift.org/documentation/docc/customizing-the-appearance-of-your-documentation-pages">customize the appearance of your documentation pages</a> with color, font, and icon customizations. Navigation also took a step forward with quick navigation, allowing fuzzy in-project search:</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/5.8-blog/docc-fuzzy-search.png" alt="A DocC documentation page showing a quick navigation overlay showing fuzzy documentation search" /></p>
|
|||
|
|
|
|||
|
|
<p>Swift-DocC also now supports documenting extensions to types from other modules. This is an opt-in feature and can be <a href="https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-extended-types">enabled by adding the <code class="language-plaintext highlighter-rouge">--include-extended-types</code> flag when using the Swift-DocC plugin</a>.</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/5.8-blog/docc-extended-type.png" alt="A documentation page featuring an extension to the standard library's Collection type." /></p>
|
|||
|
|
|
|||
|
|
<h3 id="swift-package-manager">Swift Package Manager</h3>
|
|||
|
|
|
|||
|
|
<p>Following are some highlights from the changes introduced to the <a href="https://github.com/apple/swift-package-manager">Swift Package Manager</a> in Swift 5.8:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md">SE-0362</a>: Targets can now specify the upcoming language features they require. <code class="language-plaintext highlighter-rouge">Package.swift</code> manifest syntax has been expanded with an API to include setting <code class="language-plaintext highlighter-rouge">enableUpcomingFeature</code> and <code class="language-plaintext highlighter-rouge">enableExperimentalFeature</code> flags at the target level.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0378-package-registry-auth.md">SE-0378</a>: Token authentication when interacting with a package registry is now supported. The <code class="language-plaintext highlighter-rouge">swift package-registry</code> command has two new subcommands <code class="language-plaintext highlighter-rouge">login</code> and <code class="language-plaintext highlighter-rouge">logout</code> for adding/removing registry credentials.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>Exposing an executable product that consists solely of a binary target that is backed by an artifact bundle is now allowed. This allows vending binary executables as their own separate package, independently of the plugins that are using them.</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>In packages using tools version 5.8 or later, Foundation is no longer implicitly imported into package manifests. If Foundation APIs are used, the module needs to be imported explicitly.</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>See the <a href="https://github.com/apple/swift-package-manager/blob/main/CHANGELOG.md#swift-58">Swift Package Manager changelog</a> for the complete list of changes.</p>
|
|||
|
|
|
|||
|
|
<h3 id="swiftsyntax">SwiftSyntax</h3>
|
|||
|
|
|
|||
|
|
<p>With the Swift 5.8-aligned release of <a href="https://github.com/apple/swift-syntax">SwiftSyntax</a>, SwiftSyntax contains a completely re-written parser that is implemented entirely in Swift instead of relying on the C++ parser to produce a SwiftSyntax tree. While the Swift compiler still uses the old parser implemented in C++, the eventual goal is to replace the old parser entirely. The new parser has a number of advantages:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>Contributing to or depending on SwiftSyntax is now as easy as any other Swift package. This greatly lowers the barrier of entry for new contributors and adopters.</li>
|
|||
|
|
<li>The new parser has been designed with error recovery as a primary goal. It is more tolerant of parsing errors and produces better error messages.</li>
|
|||
|
|
<li>SwiftSyntaxBuilder allows generating source code in a declarative way using a mixture of result builders and string interpolation. An example can be found <a href="https://github.com/apple/swift-syntax/blob/release/5.8/Examples/CodeGenerationUsingSwiftSyntaxBuilder.swift">here</a>.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h3 id="windows-platform">Windows Platform</h3>
|
|||
|
|
|
|||
|
|
<p>Swift 5.8 continues the incremental improvements to the Windows toolchain. Some of the important work that has gone into this release cycle includes:</p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>The Windows toolchain has reduced some of its dependency on environment variables. <code class="language-plaintext highlighter-rouge">DEVELOPER_DIR</code> was previously needed to locate components and this is no longer required. This cleans up the installation and enables us to get closer to per-user installation.</li>
|
|||
|
|
<li>ICU has been changed to static linking. This reduces the number of files that need to be distributed and reduces the number of dependencies that a shipping product requires. This was made possible by the removal of the ICU dependency in the Swift standard library.</li>
|
|||
|
|
<li>Some of the initial work to support C++ interop on Windows has been merged and is available in the toolchain. This includes the work towards modularising the Microsoft C++ Runtime (msvcprt).</li>
|
|||
|
|
<li>The <code class="language-plaintext highlighter-rouge">vcruntime</code> module has been renamed to <code class="language-plaintext highlighter-rouge">visualc</code>. This better reflects the module and paves the road for future enhancements for bridging the Windows platform libraries.</li>
|
|||
|
|
<li>A significant amount of work for improving path handling in the Swift Package Manager has been merged. This should help make Swift Package Manager more robust on Windows and improve interactions with SourceKit-LSP.</li>
|
|||
|
|
<li>SourceKit-LSP has benefited from several robustness improvements. Cross-module references are now more reliable and C/C++ references have been improved thanks to the enhanced path handling in SwiftPM which ensures that files are correctly identified.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="downloads">Downloads</h2>
|
|||
|
|
|
|||
|
|
<p>Official binaries are <a href="https://swift.org/download/">available for download</a> from <a href="http://swift.org/">Swift.org</a> for Xcode, Windows, and Linux. The Swift 5.8 compiler is also included in <a href="https://apps.apple.com/app/xcode/id497799835">Xcode 14.3</a>.</p>
|
|||
|
|
|
|||
|
|
<h2 id="swift-evolution-appendix">Swift Evolution Appendix</h2>
|
|||
|
|
|
|||
|
|
<p>The following language, standard library, and Swift Package Manager proposals were accepted through the <a href="https://github.com/apple/swift-evolution">Swift Evolution</a> process and <a href="https://apple.github.io/swift-evolution/#?version=5.8">implemented in Swift 5.8</a>.</p>
|
|||
|
|
|
|||
|
|
<p><strong>Language and Standard Library</strong></p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>SE-0274: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0274-magic-file.md">Concise magic file names</a></li>
|
|||
|
|
<li>SE-0362: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md">Piecemeal adoption of upcoming language improvements</a></li>
|
|||
|
|
<li>SE-0365: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0365-implicit-self-weak-capture.md">Allow implicit self for weak self captures, after self is unwrapped</a></li>
|
|||
|
|
<li>SE-0367: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0367-conditional-attributes.md">Conditional compilation for attributes</a></li>
|
|||
|
|
<li>SE-0368: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0368-staticbigint.md">StaticBigInt</a></li>
|
|||
|
|
<li>SE-0369: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0369-add-customdebugdescription-conformance-to-anykeypath.md">Add CustomDebugStringConvertible conformance to AnyKeyPath</a></li>
|
|||
|
|
<li>SE-0370: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0370-pointer-family-initialization-improvements.md">Pointer Family Initialization Improvements and Better Buffer Slices</a></li>
|
|||
|
|
<li>SE-0372: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0372-document-sorting-as-stable.md">Document Sorting as Stable</a></li>
|
|||
|
|
<li>SE-0373: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0373-vars-without-limits-in-result-builders.md">Lift all limitations on variables in result builders</a></li>
|
|||
|
|
<li>SE-0375: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0375-opening-existential-optional.md">Opening existential arguments to optional parameters</a></li>
|
|||
|
|
<li>SE-0376: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0376-function-back-deployment.md">Function Back Deployment</a></li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p><strong>Swift Package Manager</strong></p>
|
|||
|
|
|
|||
|
|
<ul>
|
|||
|
|
<li>SE-0362: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md">Piecemeal adoption of upcoming language improvements</a></li>
|
|||
|
|
<li>SE-0378: <a href="https://github.com/apple/swift-evolution/blob/main/proposals/0378-package-registry-auth.md">Package Registry Authentication</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Swift Package Index gains Apple sponsorship</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-package-index-developer-spotlight/"/>
|
|||
|
|
<updated>2023-03-24T04:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-package-index-developer-spotlight/</id>
|
|||
|
|
<content type="html"><p>Building a thriving open source ecosystem is important to Swift’s success, and open source packages are the building blocks that help power countless Swift projects. As the number of packages increases, discovery becomes critical for developers needing to find the tools and libraries that help them build their apps and services.</p>
|
|||
|
|
|
|||
|
|
<p>Over the last three years, the <a href="https://swiftpackageindex.com">Swift Package Index</a> has become a popular destination for searching and discovering packages to help developers with their work.</p>
|
|||
|
|
|
|||
|
|
<p>Recognizing the valuable resource the Swift Package Index provides to the community, the service is now sponsored by Apple.</p>
|
|||
|
|
|
|||
|
|
<p>The post below is a Developer Spotlight from Swift Package Index creators <a href="https://daveverwer.com">Dave Verwer</a> and <a href="https://mastodon.social/@finestructure">Sven A. Schmidt</a> about their journey building the index into what it is today.</p>
|
|||
|
|
|
|||
|
|
<hr />
|
|||
|
|
|
|||
|
|
<p>Our goal for the Swift Package Index has always been to help people make better decisions about the package dependencies they include in their projects.</p>
|
|||
|
|
|
|||
|
|
<p>When we first launched the website in 2020, we initially tackled package metadata and search. The site polls a <a href="https://github.com/SwiftPackageIndex/PackageList/blob/main/packages.json">list of known packages</a>, clones every repository, analyses the package manifest and git history, and makes that metadata searchable. It’s more than a simple metadata search, though, and we designed the package page to expose essential information that enables developers to make informed decisions about their dependencies. It answers questions like how long a package has been in development, how the author has licensed the code, whether pull requests and issues are being monitored and responded to, and more. At first glance, a package page on the index can look similar to its GitHub repository page, but we focus the metadata to be relevant to potential user of the package.</p>
|
|||
|
|
|
|||
|
|
<p>As the site grew, we decided to add package compatibility testing. Swift packages can be used in apps across various platforms but there’s no easy way to determine compatibility for each platform. How did we tackle it? If you’re imagining that we attempt to build each package in the index for every permutation of four Swift versions and five platforms every time the default branch moves forward or the author tags a release, you’d be correct! The “build system”, as we now call it, processes an average of 5,000 builds per day and has completed more than five million builds in total. It’s such a large operation that it needs its own custom monitoring app:</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/swift-package-index-developer-spotlight-blog/pipelines-app.png" alt="A screenshot of the internal Swift Package Index app, Pipelines. It shows the status of several pending, running, passed, and failed package builds." /></p>
|
|||
|
|
|
|||
|
|
<p>All those build results go to build the concise compatibility matrix that shows the platform and Swift version requirements you see on <a href="https://swiftpackageindex.com/apple/swift-markdown">every package page</a>.</p>
|
|||
|
|
|
|||
|
|
<p>Last year we turned to documentation. Highlighting packages that have documentation aligns with the site’s goal of making better decisions about dependencies, but we decided that detecting and highlighting wasn’t enough. Instead, we decided to offer the community a platform to build and host versioned documentation for free. Any package author can now opt-in to documentation generation, and once the build system has completed a successful build, we’ll host versioned DocC documentation. You can see an example of this with the <a href="https://swiftpackageindex.com/apple/swift-markdown/documentation">documentation for swift-markdown</a>. The community adopted this feature quickly, and we now have 300+ packages opted in, and our storage requirements are climbing quickly:</p>
|
|||
|
|
|
|||
|
|
<p><img src="/assets/images/swift-package-index-developer-spotlight-blog/docc-storage-growth.png" alt="A chart showing documentation storage rising over time from zero in May 2022 to 35Gb in February 2023 with a sharp increase at the end of December 2022" /></p>
|
|||
|
|
|
|||
|
|
<p>The Swift Package Index doesn’t <em>merely</em> index Swift packages, it <em>is an</em> open-source Swift package! It runs as a <a href="https://swiftpackageindex.com/vapor/vapor">vapor</a> app and depends on many other packages, such as <a href="https://swiftpackageindex.com/vapor/fluent">fluent</a> and the <a href="https://swiftpackageindex.com/vapor/fluent-postgres-driver">Postgres driver</a> for database access, <a href="https://swiftpackageindex.com/JohnSundell/Plot">Plot</a> and <a href="https://swiftpackageindex.com/JohnSundell/Ink">Ink</a> to render HTML, <a href="https://swiftpackageindex.com/pointfreeco/swift-snapshot-testing">swift-snapshot-testing</a> for testing, and more.</p>
|
|||
|
|
|
|||
|
|
<p>Running a site like this takes constant maintenance, and we have merged more than 1,200 pull requests and deployed over 600 releases (about four per week) since launching three years ago. We also have a growing community of <a href="https://github.com/SwiftPackageIndex/SwiftPackageIndex-Server/graphs/contributors">external contributors</a> that help improve the site every day.</p>
|
|||
|
|
|
|||
|
|
<p>Finally, with the community in mind, we also started a podcast called <a href="https://swiftpackageindexing.transistor.fm">Swift Package Indexing</a>, where we discuss progress with feature development and pick a selection of packages from around the community for each episode.</p>
|
|||
|
|
|
|||
|
|
<p>We couldn’t be more proud to see Apple support our project and join our <a href="https://swiftpackageindex.com/supporters">other community and corporate sponsors</a> to ensure we can continue providing this service for many more years to come. Thank you to Apple and everyone who makes it possible to run this site.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>Introducing Swift Certificates and Swift ASN.1</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/swift-certificates-and-asn1/"/>
|
|||
|
|
<updated>2023-03-07T05:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/swift-certificates-and-asn1/</id>
|
|||
|
|
<content type="html"><p>I’m excited to announce two new open source Swift packages: <a href="https://github.com/apple/swift-certificates">swift-certificates</a> and <a href="https://github.com/apple/swift-asn1">swift-asn1</a>. Together, these libraries provide developers a faster and safer implementation of X.509 certificates, a critical technology that powers the security of TLS.</p>
|
|||
|
|
|
|||
|
|
<h2 id="x509-and-asn1">X.509 and ASN.1</h2>
|
|||
|
|
|
|||
|
|
<h3 id="what-are-x509-certificates">What are X.509 certificates?</h3>
|
|||
|
|
|
|||
|
|
<p>X.509 certificates are a commonly-used identity format to cryptographically attest to the identity of an actor in a system. They form part of the X.509 standard for defining a public key infrastructure (PKI). X.509-style PKIs are commonly used in cases where it is necessary to delegate the authority to attest to an actor’s identity to a small number of trusted parties, called Certificate Authorities.</p>
|
|||
|
|
|
|||
|
|
<p>Most of us experience X.509 in the form of TLS certificates, but they have a wide range of other uses such as code-signing and token exchange.</p>
|
|||
|
|
|
|||
|
|
<p>Server-side applications make frequent use of X.509 certificates. At a minimum, most web servers will load a TLS certificate to secure their network connections.</p>
|
|||
|
|
|
|||
|
|
<p>Many more complex use cases exist, from dynamically provisioning TLS certificates using <a href="https://www.rfc-editor.org/rfc/rfc8555.html">ACME</a> to validating identities using x5c. This makes a fully-featured X.509 library a powerful asset for a server-side ecosystem.</p>
|
|||
|
|
|
|||
|
|
<h3 id="what-is-asn1">What is ASN.1?</h3>
|
|||
|
|
|
|||
|
|
<p>The layout of the X.509 certificate type is defined using a data type definition language called ASN.1 (Abstract Syntax Notation One).</p>
|
|||
|
|
|
|||
|
|
<p>ASN.1 is extremely flexible and complex. Types can be defined and recursively referenced. Fields can be named and tagged. Fields can be optional or defaulted. Human readable comments can be applied, often applying further constraints on top of what ASN.1 is capable of expressing.</p>
|
|||
|
|
|
|||
|
|
<p>ASN.1 is the name of the format used to define the types, but there is more than one method of serializing an ASN.1 type. These methods are called “encoding rules” and there are a lot of them. The vast majority of cryptographic use cases for ASN.1 use the Distinguished Encoding Rules (DER) or the Basic Encoding Rules (BER).</p>
|
|||
|
|
|
|||
|
|
<p>For the certificates use case, the fact that X.509 certificates are defined in ASN.1 and serialized using DER means that in order to provide a powerful, safe, Swift-native X.509 library, we need to build out an ASN.1 library as well.</p>
|
|||
|
|
|
|||
|
|
<h2 id="new-packages">New Packages</h2>
|
|||
|
|
|
|||
|
|
<h3 id="swift-asn1">Swift ASN.1</h3>
|
|||
|
|
|
|||
|
|
<p>Swift ASN.1 provides two major pieces of functionality: an implementation of the common ASN.1 currency types, and an implementation of DER serialization and deserialization. This is sufficient for implementation of the majority of the cryptographic use cases for DER, including for swift-certificates.</p>
|
|||
|
|
|
|||
|
|
<p>Swift ASN.1 provides these security-critical parsing and serializing services using entirely memory-safe code with low overhead.</p>
|
|||
|
|
|
|||
|
|
<p>Making this parser safe is particularly valuable as a major goal of DER parsers is to parse untrusted user input. Memory safety bugs in ASN.1 parsing commonly lead to high severity issues.</p>
|
|||
|
|
|
|||
|
|
<h3 id="swift-certificates">Swift Certificates</h3>
|
|||
|
|
|
|||
|
|
<p>Swift Certificates has been released at an early stage in order to get community feedback, so it’s missing some functionality that will be needed for widespread use. Right now it can:</p>
|
|||
|
|
|
|||
|
|
<ol>
|
|||
|
|
<li>Parse the majority of X.509 certificates that comply with RFC 5280 and are used in the Web PKI.</li>
|
|||
|
|
<li>Perform X.509 chain building.</li>
|
|||
|
|
<li>Support pluggable X.509 verification policies.</li>
|
|||
|
|
<li>Support pluggable OCSP resolution.</li>
|
|||
|
|
</ol>
|
|||
|
|
|
|||
|
|
<p>Version 1.0 will be ready once the package has a sufficiently robust X.509 verifier that can safely support the WebPKI use case.</p>
|
|||
|
|
|
|||
|
|
<p>Our medium-term goal is to replace swift-nio-ssl’s BoringSSL-based X.509 implementation with Swift Certificates. This should provide substantial performance improvements to all applications using TLS and add memory safety to a substantial attack surface. We also intend to add support for Certificate Signing Requests, opening the door for more automated interaction with certificate issuance services.</p>
|
|||
|
|
|
|||
|
|
<h2 id="get-involved">Get involved</h2>
|
|||
|
|
|
|||
|
|
<p>Please keep an eye on the repositories (<a href="https://github.com/apple/swift-certificates">swift-certificates</a>, <a href="https://github.com/apple/swift-asn1">swift-asn1</a>), open issues and pull requests, and try to use the code and report back.</p>
|
|||
|
|
|
|||
|
|
<p>We’re really excited for what Swift Certificates can do for the Swift community, and we look forward to seeing it unlock a wide range of new use-cases and technologies.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>“The Swift Programming Language” book now published with DocC</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/tspl-on-docc/"/>
|
|||
|
|
<updated>2023-02-16T10:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/tspl-on-docc/</id>
|
|||
|
|
<content type="html"><p>We’re happy to announce that <a href="https://docs.swift.org/swift-book/documentation/the-swift-programming-language/">The Swift Programming Language</a> book (TSPL) is now published using <a href="https://github.com/apple/swift-docc">Swift-DocC</a>, starting with Swift 5.8. TSPL is now ready to start accepting content contributions, under the direction of the Swift Documentation Workgroup.</p>
|
|||
|
|
|
|||
|
|
<p>This is a major step for the book. It was first release as open source in August 2022 and since then, we’ve merged over 50 pull requests as we converted to DocC. We also made enhancements to DocC based on what we learned working on the book, like adding control over automatic see-also sections and new on-page navigation. Other DocC content that guides developers through a linear narrative, like the documentation for large or complex packages, can also take advantage of these enhancements.</p>
|
|||
|
|
|
|||
|
|
<h2 id="get-involved">Get involved</h2>
|
|||
|
|
|
|||
|
|
<p><strong>Contribute content to TSPL.</strong>
|
|||
|
|
For some ideas of what you can write about, see the project’s <a href="https://github.com/apple/swift-book/milestone/2">GitHub issues page</a> and the recently accepted <a href="https://www.swift.org/swift-evolution/">Swift Evolution proposals</a>. For details about making contributions, see the <a href="https://github.com/apple/swift-book/blob/main/CONTRIBUTING.md">CONTRIBUTING.md</a> file in the Git repository, including when to pitch large changes in the <a href="https://forums.swift.org/c/92">Swift Documentation forum category</a>.</p>
|
|||
|
|
|
|||
|
|
<p><strong>Contribute to a translation project.</strong>
|
|||
|
|
<a href="https://www.swift.org/documentation/tspl/#translations">Translations</a> of TSPL can now use the same publication pipeline as the English version of TSPL. Contributors to translations can follow changes in the English version by watching pitch threads on the Swift forum and pull requests in GitHub.</p>
|
|||
|
|
|
|||
|
|
<p><strong>Improve DocC support for long-form content.</strong>
|
|||
|
|
There are more opportunities to contribute to an improved documentation experience, like adding support for interactive and offline content, and support for tested code listings. For more ideas, see the GitHub issues pages for <a href="https://github.com/apple/swift-book/milestone/2">TSPL</a> and <a href="https://github.com/apple/swift-docc/issues">DocC</a>.</p>
|
|||
|
|
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
<entry>
|
|||
|
|
<title>The Future of Foundation</title>
|
|||
|
|
|
|||
|
|
<author>
|
|||
|
|
|
|||
|
|
<name>Swift.org</name>
|
|||
|
|
|
|||
|
|
</author>
|
|||
|
|
<link href="https://swift.org/blog/future-of-foundation/"/>
|
|||
|
|
<updated>2022-12-09T04:00:00-04:00</updated>
|
|||
|
|
<id>https://swift.org/blog/future-of-foundation/</id>
|
|||
|
|
<content type="html"><p>The Foundation framework is used in nearly all Swift projects. It provides both a base layer of functionality for fundamentals like strings, collections, and dates, as well as setting conventions for writing great Swift code.</p>
|
|||
|
|
|
|||
|
|
<p>Today, we have some exciting announcements for the future of Foundation.</p>
|
|||
|
|
|
|||
|
|
<h2 id="going-open">Going Open</h2>
|
|||
|
|
<p>When Swift <a href="/blog/welcome/">began life as an open source project</a>, we wanted to open not just the language itself, but the ecosystem around it. Foundation has been instrumental in the success of decades of software and has been an integral part of the Swift developer experience from the beginning, and we knew it had to be included in the open source offering.</p>
|
|||
|
|
|
|||
|
|
<p>The <a href="https://github.com/apple/swift-corelibs-foundation">swift-corelibs-foundation</a> project helped launch the open source Swift version of Foundation in 2016, wrapping a Swift layer around the preexisting, open source C implementation of Foundation.</p>
|
|||
|
|
|
|||
|
|
<p>In the intervening years, Swift has grown both technologically (e.g. ABI stability), as well as socially, attracting a diverse community of participants bound together by their interest in Swift.</p>
|
|||
|
|
|
|||
|
|
<p>With that growth, the time has come to reevaluate the strategy of an open source Foundation.</p>
|
|||
|
|
|
|||
|
|
<h2 id="going-further">Going Further</h2>
|
|||
|
|
<p>Today, we are announcing a new open source Foundation project, written in Swift, for Swift.</p>
|
|||
|
|
|
|||
|
|
<p>This achieves a number of technical goals:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>No more wrapped C code.</strong> With a native Swift implementation of Foundation, the framework no longer pays conversion costs between C and Swift, resulting in faster performance. A Swift implementation, developed as a package, also makes it easier for Swift developers to inspect, understand, and contribute code.</li>
|
|||
|
|
<li><strong>Provide the option of smaller, more granular packages.</strong> Rewriting Foundation provides an opportunity to match its architecture to evolving use cases. Developers want to keep their binary sizes small, and a new <em>FoundationEssentials</em> package will provide the most important types in Foundation with no system dependencies to help accomplish this. A separate <em>FoundationInternationalization</em> package will be available when you need to work with localized content such as formatted dates and time. Other packages will continue to provide XML support and networking. A new <em>FoundationObjCCompatibility</em> package will contain legacy APIs which are useful for certain applications.</li>
|
|||
|
|
<li><strong>Unify Foundation implementations.</strong> Multiple implementations of any API risks divergent behavior and ultimately bugs when moving code across platforms. This new Foundation package will serve as the core of a single, canonical implementation of Foundation, regardless of platform.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<p>And this also achieves an important community goal:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Open contribution process.</strong> Open source projects are at their best when the community of users can participate and become a community of developers. A new, open contribution process will be available to enable all developers to contribute new API to Foundation.</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h2 id="going-together">Going Together</h2>
|
|||
|
|
<p>We’re excited to start discussing these plans with everyone <a href="https://forums.swift.org/t/what-s-next-for-foundation/61939">on the Swift forums</a>. The project itself will launch on GitHub in 2023.</p>
|
|||
|
|
</content>
|
|||
|
|
</entry>
|
|||
|
|
|
|||
|
|
</feed>
|