objc2

Objective-C interface and runtime bindings in Rust.

Most of the core libraries and frameworks that are in use on Apple systems are written in Objective-C; this crate enables you to interract with those.

This README is kept intentionally small in an effort to consolidate the documentation, see the Rust docs for more details.

This crate is part of the objc2 project, see that for related crates.

lib.rs:

Objective-C interface and runtime bindings

Quick links:

• All Topics.
• About framework crates.
• List of framework crates.

Objective-C was the standard programming language on Apple platforms like macOS, iOS, iPadOS, tvOS and watchOS. It is an object-oriented language centered around "sending messages" to its instances - this can for the most part be viewed as a function call.

It has since been superseded by Swift, but most of the core libraries and frameworks that are in use on Apple systems are still written in Objective-C, and hence we would like the ability to interract with these using Rust. This crate enables you to do that, in as safe a manner as possible.

Basic usage

This example illustrates major parts of the functionality in this crate:

First, we allocate a new NSObject using ClassType::alloc. Next, we initialize this object. It is ensured to be deallocated using rc::Retained. Now we're free to send messages to the object to our hearts desire using the msg_send! or msg_send_id! macros (depending on the return type of the method). Finally, the Retained goes out of scope, and the object is released and deallocated.

use objc2::{msg_send, msg_send_id, ClassType};
use objc2::ffi::NSUInteger;
use objc2::rc::Retained;
use objc2::runtime::{NSObject, NSObjectProtocol};

// Creation

let obj1: Retained<NSObject> = unsafe {
    msg_send_id![NSObject::alloc(), init]
};
// Or
let obj2 = NSObject::new();

// Usage

let hash1: NSUInteger = unsafe { msg_send![&obj1, hash] };
let hash2: NSUInteger = unsafe { msg_send![&obj2, hash] };
assert_ne!(hash1, hash2);

let is_kind: bool = unsafe {
    msg_send![&obj1, isKindOfClass: NSObject::class()]
};
assert!(is_kind);

let obj1_self: Retained<NSObject> = unsafe { msg_send_id![&obj1, self] };
assert_eq!(obj1, obj1_self);

// Deallocation on drop

Note that this example contains a lot of unsafe (which should all ideally be justified with a // SAFETY comment). This is required because our compiler can verify very little about the Objective-C invocation, including all argument and return types used in msg_send!. We could have accidentally made hash an f32, or any other type, and this would trigger undefined behaviour!

See the framework crates for much more ergonomic usage of the system frameworks like Foundation, AppKit, UIKit and so on.

Anyhow, all of this unsafe nicely leads us to another feature that this crate has:

Encodings and message type verification

The Objective-C runtime includes encodings for each method that describe the argument and return types. See the encode module for a full overview of what this is.

The important part is: To make message sending safer, all arguments and return values for messages must implement encode::Encode. This allows the Rust compiler to prevent you from passing e.g. a Vec into Objective-C, which would both be UB and leak the vector.

Furthermore, we can take advantage of the encodings provided by the runtime to verify that the types used in Rust actually match the types encoded for the method. This is not a perfect solution for ensuring safety (some Rust types have the same Objective-C encoding, but are not equivalent, such as &T and *const T), but it gets us much closer to it!

When debug_assertions are enabled we check the encoding every time you send a message, and the message send will panic if they are not equivalent.

To take the example above, if we changed the hash method's return type as in the following example, it'll panic if debug assertions are enabled:

#
#
// Wrong return type - this is UB!
let hash1: f32 = unsafe { msg_send![&obj1, hash] };
#

This library contains further such debug checks.

Crate features

This crate exports several optional cargo features, see Cargo.toml for an overview and description of these.

Support for other Operating Systems

The bindings can be used on Linux or *BSD utilizing the GNUstep Objective-C runtime, see the objc-sys crate for how to configure this.

Other functionality

That was a quick introduction, this library also has support for handling exceptions, [the ability to declare Objective-C classes][declare_class!], advanced reference-counting utilities, and more - peruse the documentation at will!