objc2_sys

Raw Rust bindings to core Objective-C runtimes and ABIs.

Runtime Support

Apple's objc4

This is the default on Apple platforms:

#[cfg(any(
    target_os = "macos",
    target_os = "ios",
    target_os = "tvos",
    target_os = "watchos",
))]

The supported runtime version (higher versions lets the compiler enable newer optimizations, at the cost of not supporting older operating systems) can be chosen using the standard X_DEPLOYMENT_TARGET environment variables:

• macOS: MACOSX_DEPLOYMENT_TARGET
  • Default: 10.7 (same as Rust)
  • Minimum: 10.7
• iOS: IPHONEOS_DEPLOYMENT_TARGET
  • Default: 7.0 (same as Rust)
  • Minimum: 5.0 (theoretically)
• tvOS: TVOS_DEPLOYMENT_TARGET
  • Default: TODO
  • Minimum: 9.0 (theoretically)
• watchOS: WATCHOS_DEPLOYMENT_TARGET
  • Default: TODO
  • Minimum: 1.0 (theoretically)

Window's WinObjC

This is the default on #[cfg(target_os = "windows")].

This is essentially just a fork based on GNUStep's libobjc2 version 1.8, with very few user-facing changes.

GNUStep's libobjc2

This is the default on all other systems.

The version can be chosen by setting the standard (used by GNUStep already) RUNTIME_VERSION environment variable to one of the following:

• gnustep-1.7
• gnustep-1.8 (default)
• gnustep-1.9
• gnustep-2.0
• gnustep-2.1

If you wish to force using the GNUStep runtime on Apple or Windows systems, set the RUNTIME_VERSION environment variable to one of the values above.

Other runtimes

This library will probably only ever support "Modern" Objective-C runtimes, since support for reference-counting primitives like objc_retain and objc_autoreleasePoolPop is a vital requirement for most applications.

Just so we're being clear, this rules out the GCC libobjc runtime (see this), and the mulle-objc runtime. (But support for ObjFW may be added). More information on different runtimes can be found in GNUStep's Objective-C Compiler and Runtime FAQ.

Configuring linking

This crate defines the links key in Cargo.toml so it's possible to change the linking to libobjc, see the relevant cargo docs.

In the future, this crate may vendor the required source code to automatically build and link to the runtimes. Choosing static vs. dynamic linking here may also become an option.

Objective-C compiler ABI configuration

Objective-C compilers like clang and gcc requires configuring the calling ABI to the runtime you're using:

• clang uses the -fobjc-runtime flag, of which there are a few different options.
• gcc uses the -fgnu-runtime or -fnext-runtime options. Note that Modern Objective-C features are ill supported.

This is relevant if you're building and linking to custom Objective-C sources in a build script. In the future, this crate may expose build script metadata to help with selecting these (and other required) flags.

Design choices

It is recognized that the most primary consumer of this library will be macOS and secondly iOS applications. Therefore it was chosen not to use bindgen in our build script to not add compilation cost to those targets.1

Deprecated functions are also not included for future compability, since they could be removed in any macOS release, and then our code would break. If you have a need for these, please open an issue and we can discuss it!

Some items (in particular the objc_msgSend_X family) have cfgs that prevent their usage on different platforms; these are semver-stable in the sense that they will only get less restrictive, never more.

1 That said, most of this is created with the help of bindgen's commandline interface, so huge thanks to them!