13 releases
0.3.5 | May 21, 2024 |
---|---|
0.3.3 | Apr 17, 2024 |
0.3.2 | Dec 3, 2023 |
0.3.1 | Jun 20, 2023 |
0.1.0 | Nov 22, 2021 |
#205 in macOS and iOS APIs
466,946 downloads per month
Used in 2,232 crates
(2 directly)
74KB
945 lines
objc-sys
Raw Rust bindings to the Objective-C runtime and ABI.
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
:
Raw bindings to Objective-C runtimes
These bindings contain almost no documentation, so it is highly
recommended to read Apple's documentation about the Objective-C
runtime, Apple's runtime reference, or to use
objc2::runtime
which provides a higher-level API.
Runtime Support
Objective-C has a runtime, different implementations of said runtime
exist, and they act in slightly different ways. By default, Apple
platforms link to Apple's runtime, but if you're using another runtime you
must tell it to this library using feature flags (you might have to
disable the default apple
feature first).
One could ask, why even bother supporting other runtimes? For me, the primary reasoning iss robustness. By testing with these alternative runtimes in CI, we become by extension much more confident that our implementation doesn't rely on brittle unspecified behaviour, and works across different macOS and iOS versions.
Apple's objc4
- Feature flag:
apple
.
This is used by default, and has the highest support priority (all of
objc2
will work with this runtime).
The supported runtime version (higher versions lets the compiler enable
newer optimizations, at the cost of not supporting older operating
systems) can be chosen using the standard X_DEPLOYMENT_TARGET
environment variables:
- macOS:
MACOSX_DEPLOYMENT_TARGET
, default10.12
,11.0
on Aarch64. - iOS / iPadOS:
IPHONEOS_DEPLOYMENT_TARGET
, default10.0
. - tvOS:
TVOS_DEPLOYMENT_TARGET
, default10.0
. - watchOS:
WATCHOS_DEPLOYMENT_TARGET
, default5.0
.
The default (and minimum) versions are the same as those Rust itself has.
GNUStep's libobjc2
- Feature flag:
gnustep-1-7
,gnustep-1-8
,gnustep-1-9
,gnustep-2-0
andgnustep-2-1
depending on the version you're using.
Microsoft's WinObjC
- Feature flag:
unstable-winobjc
.
Unstable: Hasn't been tested on Windows yet!
A fork based on GNUStep's
libobjc2
version 1.8, with very few user-facing changes.
ObjFW
- Feature flag:
unstable-objfw
.
Unstable: Doesn't work yet!
TODO.
Other runtimes
This library will probably only ever support "Modern"
Objective-C runtimes, since support for reference-counting primitives like
objc_retain
and objc_autoreleasePoolPop
is a vital requirement for
most applications.
This rules out the GCC libobjc
runtime (see
this), the mulle-objc
runtime and cocotron. (But
support for darling
may be added). More information on different
runtimes can be found in GNUStep's Objective-C Compiler and Runtime
FAQ.
Advanced linking configuration
This crate defines the links
key in Cargo.toml
so it's possible to
change the linking to libobjc
, see the relevant cargo
docs.
In the future, this crate may vendor the required source code to automatically build and link to the runtimes. Choosing static vs. dynamic linking here may also become an option.
Objective-C Compiler configuration
Objective-C compilers like clang
and gcc
requires configuring the
calling ABI to the runtime you're using:
clang
uses the-fobjc-runtime
flag, of which there are a few different options.gcc
uses the-fgnu-runtime
or-fnext-runtime
options. Note that Modern Objective-C features are ill supported.
This is relevant if you're building and linking to custom Objective-C
sources in a build script. To assist in compiling Objective-C sources,
this crate's build script expose the DEP_OBJC_0_3_CC_ARGS
environment
variable to downstream build scripts.
Example usage in your build.rs
(using the cc
crate) would be as
follows:
fn main() {
let mut builder = cc::Build::new();
builder.compiler("clang");
builder.file("my_objective_c_script.m");
for flag in std::env::var("DEP_OBJC_0_3_CC_ARGS").unwrap().split(' ') {
builder.flag(flag);
}
builder.compile("libmy_objective_c_script.a");
}
Design choices
It is recognized that the most primary consumer of this library will be
macOS and secondly iOS applications. Therefore it was chosen not to use
bindgen
[^1] in our build script to not add compilation cost to those
targets.
Deprecated functions are also not included for future compability, since they could be removed in any macOS release, and then our code would break. If you have a need for these, please open an issue and we can discuss it!
Some items (in particular the objc_msgSend_X
family) have cfg
s that
prevent their usage on different platforms; these are semver-stable in
the sense that they will only get less restrictive, never more.
[^1]: That said, most of this is created with the help of bindgen
's
commandline interface, so huge thanks to them!