22 releases
0.5.2 | May 21, 2024 |
---|---|
0.5.0 | Dec 3, 2023 |
0.4.1 | Jul 31, 2023 |
0.3.0-beta.5 | Feb 7, 2023 |
0.3.0-alpha.4 | Nov 22, 2021 |
#16 in macOS and iOS APIs
468,776 downloads per month
Used in 2,160 crates
(145 directly)
1MB
15K
SLoC
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:
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!