Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how to use Swift Packages on Linux #313

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Document how to use Swift Packages on Linux #313

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8acacb5
Update README.md
b521f771d8991e6f1d8e65ae05a8d783 Jan 30, 2025
c0d288d
Update README.md
b521f771d8991e6f1d8e65ae05a8d783 Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions book/src/building/swift-packages/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,8 @@
# Creating Swift Packages
# Creating Swift Packages on macOS

In this chapter we'll walk through bundling your Rust library into a Swift Package.

> Swift Packages that contain binary dependencies are only available on Apple platforms.
>
> You cannot bundle your Rust code into a Swift Package if you plan to target Linux,
> Windows or any other non-Apple target.
>
> Instead, use a building approach from one of the other [building chapters](../README.md).
If you want to target linux, please see below.

## Project setup

Expand Down Expand Up @@ -238,3 +233,38 @@ cd SwiftProject
swift run
# You should see "Hello from Rust!" in your terminal.
```

# Usage on Linux
Usage on Linux is a little bit different than on macOS. This guide will help you set up SwiftPM and Cargo. The general workflow is:
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's explicitly mention the ways that it is different.

So, up here instead of saying it's "a little bit different" just summarize the main way(s) that it is different.

Then your guide below walks the user through addressing those differences.

* Set up Package.swift so that "cargo build" is called (You can use something like this here: "https://stackoverflow.com/questions/26971240/how-do-i-run-a-terminal-command-in-a-swift-script-e-g-xcodebuild" to invoke cargo during a swift build)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not depend on external sources.

Users should not need to hop around other links/sites/pages to figure out how this works, unless inlining the information is undesirable for some reason.

Let's instead just inline an example of what you mean here, vs. making the user go find and interpret a stackoverflow page.

* Set up swift-bridge according to the guide (see chapter "swiftc and cargo")
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Set up swift-bridge how? What does the user need to do? Everything in the guide? A couple things in the guide? Can be more explicit here.

* Link against swift-bridge and your library, like the one below:
```swift
targets: [
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's paste a complete file, unless there are so many lines that it's hard to understand.

This helps the reader better orient themselves towards what they're looking at.

Also, say what this file is. Explicitly say that this is a Package.swift

i.e. "like the Package.swift file below:"

.executableTarget(
name: "proj",
dependencies: [],
swiftSettings: [
.interoperabilityMode(.Cxx),
.unsafeFlags([
"generated/SwiftBridgeCore.swift", "generated/proj-rs/proj-rs.swift",
"-import-objc-header", "bridging-header.h",
]),
],
linkerSettings: [
.unsafeFlags([
"generated/SwiftBridgeCore.swift", "generated/proj-rs/proj-rs.swift",
"-import-objc-header", "bridging-header.h", "-Ltarget/debug", "-lcorpus",
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we change this example so that it supports both debug and release builds

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's explain what this -lcorpus flag does

])
])
],
```
* this ensures that the flags that are normally passed via swiftc are forwarded during swift-build
* Since the path of the resulting rust library "target/debug" depends on the build type, you can set a global variable like this:
```swift
#if DEBUG
let buildType = "debug"
#else
let buildType = "release"
#endif
```
Comment on lines +262 to +270
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this global variable set?