260 lines
8.8 KiB
Rust
260 lines
8.8 KiB
Rust
//! # Objective-C interface and runtime bindings
|
|
//!
|
|
//! Objective-C is[^note] 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 simple method call.
|
|
//!
|
|
//! Most of the core libraries and frameworks that are in use on Apple systems
|
|
//! are 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.
|
|
//!
|
|
//! [^note]: Yes, I know, "was", Swift now exists. All the existing frameworks
|
|
//! are written in Objective-C though, so the point still holds.
|
|
//!
|
|
//!
|
|
//! ## Basic usage
|
|
//!
|
|
//! This example illustrates major parts of the functionality in this crate:
|
|
//!
|
|
//! First, we get a reference to the `NSObject`'s [`runtime::Class`] using the
|
|
//! [`class!`] macro.
|
|
//! Next, we creates a new [`runtime::Object`] pointer, and ensure it is
|
|
//! deallocated after we've used it by putting it into an [`rc::Owned`]
|
|
//! [`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<Object, _>` goes out of scope, and the object is released
|
|
//! and deallocated.
|
|
//!
|
|
#![cfg_attr(feature = "apple", doc = "```")]
|
|
#![cfg_attr(not(feature = "apple"), doc = "```no_run")]
|
|
//! use objc2::{class, msg_send, msg_send_id};
|
|
//! use objc2::ffi::NSUInteger;
|
|
//! use objc2::rc::{Id, Owned, Shared};
|
|
//! use objc2::runtime::Object;
|
|
//!
|
|
//! let cls = class!(NSObject);
|
|
//!
|
|
//! // Creation
|
|
//!
|
|
//! let obj1: Id<Object, Owned> = unsafe { msg_send_id![cls, new] };
|
|
//! let obj2: Id<Object, Owned> = unsafe {
|
|
//! // Equivalent to using `new`
|
|
//! msg_send_id![msg_send_id![cls, alloc], init]
|
|
//! };
|
|
//!
|
|
//! // 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: cls] };
|
|
//! assert!(is_kind);
|
|
//!
|
|
//! // We're going to create a new reference to the first object, so
|
|
//! // relinquish mutable ownership.
|
|
//! let obj1: Id<Object, Shared> = obj1.into();
|
|
//! let obj1_self: Id<Object, Shared> = unsafe { msg_send_id![&obj1, self] };
|
|
//! let is_equal: bool = unsafe { msg_send![&obj1, isEqual: &*obj1_self] };
|
|
//! assert!(is_equal);
|
|
//!
|
|
//! // Deallocation on drop
|
|
//! ```
|
|
//!
|
|
//! Note that this very simple 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 just as easily accidentally made `hash` an `f32`, or any
|
|
//! other type, and this would trigger undefined behaviour!
|
|
//!
|
|
//! Making the ergonomics better is something that is currently being worked
|
|
//! on, the [`foundation`] module contains more ergonomic usage of at
|
|
//! least parts of the `Foundation` framework.
|
|
//!
|
|
//! Anyhow, all of this `unsafe` nicely leads us to another feature that this
|
|
//! crate has:
|
|
//!
|
|
//! [`runtime::Class`]: crate::runtime::Class
|
|
//! [`runtime::Object`]: crate::runtime::Object
|
|
//! [`rc::Owned`]: crate::rc::Owned
|
|
//! [`rc::Id`]: crate::rc::Id
|
|
//! [`foundation`]: crate::foundation
|
|
//!
|
|
//!
|
|
//! ## Encodings and message type verification
|
|
//!
|
|
//! The Objective-C runtime includes encodings for each method that describe
|
|
//! the argument and return types. See the [`objc2-encode`] crate for the
|
|
//! full overview of what this is (its types are re-exported in this crate).
|
|
//!
|
|
//! The important part is: To make message sending safer, all arguments and
|
|
//! return values for messages must implement [`Encode`]. This allows the Rust
|
|
//! compiler to prevent you from passing e.g. a [`Box`] into Objective-C,
|
|
//! which would both be UB and leak the box.
|
|
//!
|
|
//! 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), but it gets us much closer to it!
|
|
//!
|
|
//! To use this functionality, enable the `"verify_message"` cargo feature
|
|
//! while debugging. With this feature enabled, encodings are checked 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 panics when the feature is enabled:
|
|
//!
|
|
#![cfg_attr(
|
|
all(feature = "apple", feature = "verify_message"),
|
|
doc = "```should_panic"
|
|
)]
|
|
#![cfg_attr(
|
|
not(all(feature = "apple", feature = "verify_message")),
|
|
doc = "```no_run"
|
|
)]
|
|
//! # use objc2::{class, msg_send, msg_send_id};
|
|
//! # use objc2::rc::{Id, Owned};
|
|
//! # use objc2::runtime::Object;
|
|
//! #
|
|
//! # let cls = class!(NSObject);
|
|
//! # let obj1: Id<Object, Owned> = unsafe { msg_send_id![cls, new] };
|
|
//! #
|
|
//! // Wrong return type - this is UB!
|
|
//! let hash1: f32 = unsafe { msg_send![&obj1, hash] };
|
|
//! ```
|
|
//!
|
|
//! [`objc2-encode`]: objc2_encode
|
|
//! [`Box`]: std::boxed::Box
|
|
//!
|
|
//!
|
|
//! ## Crate features
|
|
//!
|
|
//! This crate exports several optional cargo features, see [`Cargo.toml`] for
|
|
//! an overview and description of these.
|
|
//!
|
|
//! [`Cargo.toml`]: https://github.com/madsmtm/objc2/blob/master/objc2/Cargo.toml
|
|
//!
|
|
//!
|
|
//! ## Support for other Operating Systems
|
|
//!
|
|
//! The bindings can be used on Linux or *BSD utilizing the
|
|
//! [GNUstep Objective-C runtime](https://www.github.com/gnustep/libobjc2),
|
|
//! see the [`objc-sys`][`objc_sys`] crate for how to configure this.
|
|
//!
|
|
//!
|
|
//! ## Other functionality
|
|
//!
|
|
//! That was a quick introduction, this library also has [support for handling
|
|
//! exceptions][exc], [the ability to dynamically declare Objective-C
|
|
//! classes][declare], [advanced reference-counting utilities][rc], and more -
|
|
//! peruse the documentation at will!
|
|
//!
|
|
//! [exc]: crate::exception
|
|
//! [declare]: crate::declare
|
|
//! [rc]: crate::rc
|
|
|
|
#![no_std]
|
|
#![cfg_attr(
|
|
feature = "unstable-autoreleasesafe",
|
|
feature(negative_impls, auto_traits)
|
|
)]
|
|
#![cfg_attr(feature = "unstable-c-unwind", feature(c_unwind))]
|
|
#![cfg_attr(feature = "unstable-docsrs", feature(doc_auto_cfg))]
|
|
#![warn(elided_lifetimes_in_paths)]
|
|
#![warn(missing_docs)]
|
|
#![deny(non_ascii_idents)]
|
|
#![warn(unreachable_pub)]
|
|
#![deny(unsafe_op_in_unsafe_fn)]
|
|
#![warn(clippy::cargo)]
|
|
#![warn(clippy::ptr_as_ptr)]
|
|
// Update in Cargo.toml as well.
|
|
#![doc(html_root_url = "https://docs.rs/objc2/0.3.0-beta.3.patch-leaks.3")]
|
|
|
|
#[cfg(not(feature = "alloc"))]
|
|
compile_error!("The `alloc` feature currently must be enabled.");
|
|
|
|
#[cfg(not(feature = "std"))]
|
|
compile_error!("The `std` feature currently must be enabled.");
|
|
|
|
extern crate alloc;
|
|
extern crate std;
|
|
|
|
// The example uses NSObject without doing the __gnustep_hack
|
|
#[cfg(all(feature = "apple", doctest))]
|
|
#[doc = include_str!("../README.md")]
|
|
extern "C" {}
|
|
|
|
pub use objc2_encode as encode;
|
|
pub use objc_sys as ffi;
|
|
|
|
#[doc(no_inline)]
|
|
pub use objc2_encode::{Encode, EncodeArguments, Encoding, RefEncode};
|
|
|
|
pub use crate::class_type::ClassType;
|
|
pub use crate::message::{Message, MessageArguments, MessageReceiver};
|
|
#[cfg(feature = "malloc")]
|
|
pub use crate::verify::VerificationError;
|
|
|
|
#[cfg(feature = "objc2-proc-macros")]
|
|
#[doc(hidden)]
|
|
pub use objc2_proc_macros::__hash_idents;
|
|
|
|
#[cfg(not(feature = "objc2-proc-macros"))]
|
|
#[doc(hidden)]
|
|
#[macro_export]
|
|
macro_rules! __hash_idents {
|
|
// Noop; used to make our other macros a bit easier to read
|
|
($($x:tt)*) => {$($x)*};
|
|
}
|
|
|
|
#[doc(hidden)]
|
|
pub mod __macro_helpers;
|
|
mod cache;
|
|
mod class_type;
|
|
pub mod declare;
|
|
pub mod exception;
|
|
#[cfg(feature = "foundation")]
|
|
pub mod foundation;
|
|
mod macros;
|
|
mod message;
|
|
pub mod rc;
|
|
pub mod runtime;
|
|
#[cfg(test)]
|
|
mod test_utils;
|
|
#[cfg(feature = "malloc")]
|
|
mod verify;
|
|
|
|
/// Hacky way to make GNUStep link properly to Foundation while testing.
|
|
///
|
|
/// This is a temporary solution to make our CI work for now!
|
|
#[doc(hidden)]
|
|
#[cfg(feature = "gnustep-1-7")]
|
|
pub mod __gnustep_hack {
|
|
use super::runtime::Class;
|
|
|
|
extern "C" {
|
|
// The linking changed in libobjc2 v2.0
|
|
#[cfg_attr(feature = "gnustep-2-0", link_name = "._OBJC_CLASS_NSObject")]
|
|
#[cfg_attr(not(feature = "gnustep-2-0"), link_name = "_OBJC_CLASS_NSObject")]
|
|
static OBJC_CLASS_NSObject: Class;
|
|
// Others:
|
|
// __objc_class_name_NSObject
|
|
// _OBJC_CLASS_REF_NSObject
|
|
}
|
|
|
|
pub unsafe fn get_class_to_force_linkage() -> &'static Class {
|
|
unsafe { core::ptr::read_volatile(&&OBJC_CLASS_NSObject) }
|
|
}
|
|
|
|
#[test]
|
|
fn ensure_linkage() {
|
|
unsafe { get_class_to_force_linkage() };
|
|
}
|
|
}
|