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::Id. 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 Id 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::Id; use objc2::runtime::{NSObject, NSObjectProtocol};

// Creation

let obj1: Id = 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: Id = 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:

[`NSObject`]: crate::runtime::NSObject
[`rc::Id`]: crate::rc::Id
[the framework crates]: crate::topics::about_generated


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