Crate objc_sys

source ·
Expand description

§Raw bindings to Objective-C runtimes

These bindings contain almost no documentation, so it is highly recommended to read Apple’s documentation about the Objective-C runtime, Apple’s runtime reference, or to use objc2::runtime which provides a higher-level API.

§Runtime Support

Objective-C has a runtime, different implementations of said runtime exist, and they act in slightly different ways. By default, Apple platforms link to Apple’s runtime, but if you’re using another runtime you must tell it to this library using feature flags (you might have to disable the default apple feature first).

One could ask, why even bother supporting other runtimes? For me, the primary reasoning iss robustness. By testing with these alternative runtimes in CI, we become by extension much more confident that our implementation doesn’t rely on brittle unspecified behaviour, and works across different macOS and iOS versions.

§Apple’s objc4

  • Feature flag: apple.

This is used by default, and has the highest support priority (all of objc2 will work with this runtime).

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.12, 11.0 on Aarch64.
  • iOS / iPadOS: IPHONEOS_DEPLOYMENT_TARGET, default 10.0.
  • tvOS: TVOS_DEPLOYMENT_TARGET, default 10.0.
  • watchOS: WATCHOS_DEPLOYMENT_TARGET, default 5.0.

The default (and minimum) versions are the same as those Rust itself has.

§GNUStep’s libobjc2

  • Feature flag: gnustep-1-7, gnustep-1-8, gnustep-1-9, gnustep-2-0 and gnustep-2-1 depending on the version you’re using.

§Microsoft’s WinObjC

  • Feature flag: unstable-winobjc.

Unstable: Hasn’t been tested on Windows yet!

A fork based on GNUStep’s libobjc2 version 1.8, with very few user-facing changes.

§ObjFW

  • Feature flag: unstable-objfw.

Unstable: Doesn’t work yet!

TODO.

§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.

This rules out the GCC libobjc runtime (see this), the mulle-objc runtime and cocotron. (But support for darling may be added). More information on different runtimes can be found in GNUStep’s Objective-C Compiler and Runtime FAQ.

§Advanced linking configuration

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 configuration

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

This is relevant if you’re building and linking to custom Objective-C sources in a build script. To assist in compiling Objective-C sources, this crate’s build script expose the DEP_OBJC_0_3_CC_ARGS environment variable to downstream build scripts.

Example usage in your build.rs (using the cc crate) would be as follows:

ⓘ
fn main() {
    let mut builder = cc::Build::new();
    builder.compiler("clang");
    builder.file("my_objective_c_script.m");

    for flag in std::env::var("DEP_OBJC_0_3_CC_ARGS").unwrap().split(' ') {
        builder.flag(flag);
    }

    builder.compile("libmy_objective_c_script.a");
}

§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 bindgen1 in our build script to not add compilation cost to those targets.

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! ↩

Structs§

Constants§

Functions§

Type Aliases§