1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
//! Rusty bindings for Apple libraries, brought to you by //! [@NikolaiVazquez](https://twitter.com/NikolaiVazquez). //! //! # Index //! //! 1. [Donate](#donate) //! 2. [Usage](#usage) //! 1. [Feature Flags](#feature-flags) //! 3. [Goals](#goals) //! 1. [Idiomatic Rust](#idiomatic-rust) //! 2. [Zero Cost](#zero-cost) //! 4. [License](#license) //! 5. [Modules](#modules) //! 6. [Macros](#macros) //! //! # Donate //! //! If this project is useful to you, consider //! [sponsoring me](https://github.com/sponsors/nvzqz) or //! [donating directly](https://www.paypal.me/nvzqz)! //! //! Doing so enables me to create high-quality open source software like this. //! ❤️ //! //! # Usage //! //! This library is available [on crates.io][crate] and can be used in your //! project by adding the following to your project's [`Cargo.toml`]: //! //! ```toml //! [dependencies.fruity] //! version = "0.2.0" //! ``` //! //! ## Feature Flags //! //! Each module for a library or framework has its own //! [feature flag](https://doc.rust-lang.org/cargo/reference/features.html) //! with the same name. //! //! For example, this is how you enable the [`foundation`] module: //! //! ```toml //! [dependencies.fruity] //! version = "0.2.0" //! features = ["foundation"] //! ``` //! //! This feature transitively enables the [`objc`] and [`core_graphics`] //! features/modules. //! //! # Goals //! //! ## Idiomatic Rust //! //! Fruity makes interfacing with these C and Objective-C APIs feel natural in //! Rust. //! //! - **Automatic Reference Counting.** //! //! Fruity takes advantage of Rust's //! [ownership model](https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html) //! to handle object reference counting for you. //! //! [`NSObject`](objc::NSObject) is a smart pointer that calls //! [`retain`](https://developer.apple.com/documentation/objectivec/1418956-nsobject/1571946-retain) //! on [`Clone`] and //! [`release`](https://developer.apple.com/documentation/objectivec/1418956-nsobject/1571957-release) //! on [`Drop`]. This is exactly how Rust's [`Arc<T>`](std::sync::Arc) works. //! //! - **`Option<NSObject>`.** //! //! In Objective-C, all objects are nullable unless marked with `_Nonnull`. //! This often leads to either very defensive checks or careless ignoring of //! null objects. //! //! Fruity reverses that and instead makes all objects (such as //! [`NSObject`](objc::NSObject)) //! non-null by default. An object can be made nullable by wrapping it with //! [`Option<T>`](Option). //! //! To make FFI safe and easy, the following Objective-C and Rust types are //! ABI-compatible: //! //! - `NSObject * _Nonnull` and `NSObject` //! //! - `NSObject * _Nullable` and `Option<NSObject>` //! //! This is because [`NSObject`](objc::NSObject) is a //! [`#[repr(transparent)]`](https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent) //! wrapper around a //! [`NonNull<T>`](std::ptr::NonNull) pointer. //! //! - **`Result<T, NSError>`.** //! //! In Objective-C, methods take a pointer to where an //! [`NSError`](https://developer.apple.com/documentation/foundation/nserror) //! is placed upon failure. This makes it easy to avoid error handling and //! assume the happy path, which can lead to bugs when errors occur. //! //! Fruity instead returns a [`Result`](Result), which is the canonical way to //! handle errors in Rust. This ensures that errors must be acknowledged in //! some way. //! //! - **Natural inheritance.** //! //! Most of these types are classes that inherit from each other. Because true //! inheritance is not possible in Rust, Fruity uses //! [`Deref`](std::ops::Deref) to model Objective-C subclassing. //! //! ## Zero Cost //! //! Using Fruity to interface with Objective-C libraries should have as little //! runtime cost as writing the same code directly in Objective-C. //! //! This is true for the following: //! //! - **Calling object methods.** //! //! Method dispatch is always direct and does not need the error checking //! overhead of other wrappers that use the //! [`objc::msg_send!`](https://docs.rs/objc/0.2.*/objc/macro.msg_send.html) //! macro. This also reduces the size of your program by not emitting panics //! that would otherwise never get called. //! //! This library is carefully written to ensure that calls to //! [`objc_msgSend`](https://developer.apple.com/documentation/objectivec/1456712-objc_msgsend) //! are always done with the correct object type, method selector, and //! arguments. //! //! - **Getting a static class.** //! //! Getters like `NSString::class` retrieve the class directly through its //! symbol. This is instantaneous, especially when compared to calling into //! the Objective-C runtime via //! [`objc_getClass`](https://developer.apple.com/documentation/objectivec/1418952-objc_getclass). //! //! - **Creating an [`NSString`](foundation::NSString) from a Rust string //! literal.** //! //! The [`ns_string!`](ns_string) macro creates an `NSString` literal (i.e. //! `@"string"`) at compile time. There is no runtime //! dispatch/allocation/initialization cost. //! //! Some parts of this library are still not zero cost. Your help would be much //! appreciated here! //! //! These are: //! //! - **The `selector!` macro.** See //! [issue #2](https://github.com/nvzqz/fruity/issues/2) //! for details. //! //! # License //! //! This project is released under either the //! [MIT License](https://github.com/nvzqz/fruity/blob/main/LICENSE-MIT) or //! [Apache License (Version 2.0)](https://github.com/nvzqz/fruity/blob/main/LICENSE-APACHE), //! at your choosing. //! //! [crate]: https://crates.io/crates/fruity //! [`Cargo.toml`]: https://doc.rust-lang.org/cargo/reference/manifest.html // This crate is only available for 32/64 bit x86 and ARM systems. #![cfg(any( target_arch = "x86", target_arch = "x86_64", target_arch = "arm", target_arch = "aarch64", ))] #![deny(improper_ctypes)] // #![warn(rust_2018_idioms)] #![warn(missing_docs)] pub(crate) mod common; #[macro_use] pub mod core; // This module is not for public use. It is an implementation detail of macros // exposed by this crate. #[doc(hidden)] pub mod _priv; #[macro_use] pub mod objc; pub mod app_kit; pub mod cf_network; pub mod core_animation; pub mod core_audio; pub mod core_foundation; pub mod core_graphics; pub mod core_image; pub mod core_services; pub mod core_text; pub mod core_video; pub mod dispatch; pub mod foundation; pub mod io_kit; pub mod system_configuration; pub mod ui_kit;