|
| 1 | +# Porting code from other platforms to WebAssembly |
| 2 | + |
| 3 | +In the form that's currently standardized and supported by browsers and other hosts, WebAssembly |
| 4 | +is a 32-bit architecture. You have to take this into account when porting code from other |
| 5 | +platforms, since `Int` type is a signed 32-bit integer, and `UInt` is an unsigned 32-bit integer |
| 6 | +when building with SwiftWasm. You'll need to audit codepaths that cast 64-bit integers to `Int` |
| 7 | +or `UInt`, and a good amount of cross-platform test coverage can help with that. |
| 8 | + |
| 9 | +Additionally, there a differences in APIs exposed by the standard C library and Swift core |
| 10 | +libraries which we discuss in the next few subsections. |
| 11 | + |
| 12 | +## `WASILibc` module |
| 13 | + |
| 14 | +When porting existing projects from other platforms to SwiftWasm you might stumble upon code that |
| 15 | +relies on importing a platform-specific [C |
| 16 | +library](https://en.wikipedia.org/wiki/C_standard_library) module directly. It looks like `import |
| 17 | +Glibc` on Linux, or `import Darwin` on Apple platforms. Fortunately, most of the standard C library |
| 18 | +APIs are available when using SwiftWasm, you just need to use `import WASILibc` to get access to it. |
| 19 | +Most probably you want to preserve compatibility with other platforms, thus your imports would look |
| 20 | +like this: |
| 21 | + |
| 22 | +```swift |
| 23 | +#if canImport(Darwin) |
| 24 | +import Darwin |
| 25 | +#elseif canImport(Glibc) |
| 26 | +import Glibc |
| 27 | +#elseif canImport(WASILibc) |
| 28 | +import WASILibc |
| 29 | +#endif |
| 30 | +``` |
| 31 | + |
| 32 | +### Limitations |
| 33 | + |
| 34 | +WebAssembly and [WASI](https://wasi.dev/) provide a constrained environment, which currently does |
| 35 | +not directly support multi-threading, or filesystem access in the browser. Thus, you should not |
| 36 | +expect these APIs to work when importing `WASILibc`. Please be aware of these limitations when |
| 37 | +porting your code, which also has an impact on what [can be supported in the Swift |
| 38 | +Foundation](#swift-foundation-and-dispatch) at the moment. |
| 39 | + |
| 40 | +## Swift Foundation and Dispatch |
| 41 | + |
| 42 | +[The Foundation core library](https://swift.org/core-libraries/#foundation) is available in |
| 43 | +SwiftWasm, but in a limited capacity. The main reason is that [the Dispatch core |
| 44 | +library](https://swift.org/core-libraries/#libdispatch) is unavailable due to [the lack of |
| 45 | +standardized multi-threading support](https://github.com/swiftwasm/swift/issues/1887) in WebAssembly |
| 46 | +and SwiftWasm itself. Many Foundation APIs rely on the presence of Dispatch under the hood, |
| 47 | +specifically file system access and threading helpers. A few other types are unavailable in browsers |
| 48 | +or aren't standardized in WASI hosts, such as support for sockets and low-level networking, or |
| 49 | +support for time zone files, and they had to be disabled. These types are therefore absent in |
| 50 | +SwiftWasm Foundation: |
| 51 | + |
| 52 | +* `FoundationNetworking` types, such as `URLSession` and related APIs |
| 53 | +* `FileManager` |
| 54 | +* `Host` |
| 55 | +* `Notification` |
| 56 | +* `NotificationQueue` |
| 57 | +* `NSKeyedArchiver` |
| 58 | +* `NSKeyedArchiverHelpers` |
| 59 | +* `NSKeyedCoderOldStyleArray` |
| 60 | +* `NSKeyedUnarchiver` |
| 61 | +* `NSNotification` |
| 62 | +* `NSSpecialValue` |
| 63 | +* `Port` |
| 64 | +* `PortMessage` |
| 65 | +* `Process` |
| 66 | +* `ProcessInfo` |
| 67 | +* `PropertyListEncoder` |
| 68 | +* `RunLoop` |
| 69 | +* `Stream` |
| 70 | +* `Thread` |
| 71 | +* `Timer` |
| 72 | +* `UserDefaults` |
| 73 | + |
| 74 | +Related functions and properties on other types are also absent or disabled. We would like to make |
| 75 | +them available in the future as soon as possible, and [we invite you to |
| 76 | +contribute](../contribution-guide/index.md) and help us in achieving this goal! |
0 commit comments