Crate objc2

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, advanced reference-counting utilities, and more - peruse the documentation at will!

Re-exports

• pub use objc_sys as ffi;
• pub use self::encode::Encode;
• pub use self::encode::Encoding;
• pub use self::encode::RefEncode;

Modules

• declareDeprecated
  Deprecated location for a few things that are now in the runtime module.
• encode
  Support for type-encodings.
• exception
  @throw and @try/@catch exceptions.
• mutability
  Marker types for class mutability.
• rc
  Reference counting utilities.
• runtime
  Direct runtime bindings.
• topicsNowhere
  Various explanations and topics of discussion.

Macros

• class
  Gets a reference to an AnyClass from the given name.
• declare_class
  Declare a new class.
• extern_class
  Create a new type to represent a class.
• extern_methods
  Define methods on an external class.
• extern_protocol
  Create a new trait to represent a protocol.
• msg_send
  Send a message to an object or class.
• msg_send_boolDeprecated
  Deprecated. Use msg_send! instead.
• msg_send_id
  msg_send! for methods returning id, NSObject*, or similar object pointers.
• sel
  Register a selector with the Objective-C runtime.

Traits

• ClassType
  Marks types that represent specific classes.
• DeclaredClass
  Marks types whose implementation is defined in Rust.
• Message
  Types that can be sent Objective-C messages.
• ProtocolType
  Marks types that represent specific protocols.