Crate objc_sys

Expand description

§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, default 10.12, 11.0 on Aarch64.
iOS / iPadOS: IPHONEOS_DEPLOYMENT_TARGET, default 10.0.
tvOS: TVOS_DEPLOYMENT_TARGET, default 10.0.
watchOS: WATCHOS_DEPLOYMENT_TARGET, default 5.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 and gnustep-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¹ 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 cfgs that prevent their usage on different platforms; these are semver-stable in the sense that they will only get less restrictive, never more.

That said, most of this is created with the help of bindgen’s commandline interface, so huge thanks to them! ↩

Structs§

objc_class: An opaque type that represents an Objective-C class.
objc_ivar: An opaque type that represents an instance variable.
objc_method: A type that represents a method in a class definition.
objc_method_description: Describes an Objective-C method.
objc_object: An opaque type that represents an object / an instance of a class.
objc_property: An opaque type that describes a property in a class.
objc_property_attribute_t: Describes an Objective-C property attribute.
objc_protocol: Opaque type for Objective-C protocols.
objc_selector: An opaque type that represents a method selector.
objc_super: Specifies data used when sending messages to superclasses.

Constants§

NO: The equivalent of false for Objective-C’s BOOL type.
NSIntegerMax: The maximum value for a NSInteger.
NSIntegerMin: The minimum value for a NSInteger.
NSUIntegerMax: The maximum value for a NSUInteger.
Nil: A quick alias for a null_mut class.
OBJC_ASSOCIATION_ASSIGN: Specifies a weak reference to the associated object.
OBJC_ASSOCIATION_COPY: Specifies that the associated object is copied.
OBJC_ASSOCIATION_COPY_NONATOMIC: Specifies that the associated object is copied.
OBJC_ASSOCIATION_RETAIN: Specifies a strong reference to the associated object.
OBJC_ASSOCIATION_RETAIN_NONATOMIC: Specifies a strong reference to the associated object.
OBJC_SYNC_NOT_INITIALIZEDApple: Only relevant before macOS 10.13
OBJC_SYNC_NOT_OWNING_THREAD_ERRORApple
OBJC_SYNC_SUCCESSApple
OBJC_SYNC_TIMED_OUTApple: Only relevant before macOS 10.13
YES: The equivalent of true for Objective-C’s BOOL type.
nil: A quick alias for a null_mut object / instance.

Functions§

_objc_msgForward^⚠Apple
_objc_msgForward_stret^⚠Apple and non-AArch64
class_addIvar^⚠Non-unstable-objfw
class_addMethod^⚠
class_addProperty^⚠Non-unstable-objfw
class_addProtocol^⚠Non-unstable-objfw
class_conformsToProtocol^⚠
class_copyIvarList^⚠Non-unstable-objfw: The return value is deallocated with free.
class_copyMethodList^⚠Non-unstable-objfw: The returned array is deallocated with free.
class_copyPropertyList^⚠Non-unstable-objfw: The returned array is deallocated with free.
class_copyProtocolList^⚠Non-unstable-objfw: The returned array is deallocated with free.
class_createInstance^⚠Non-unstable-objfw
class_getClassMethod^⚠Non-unstable-objfw
class_getClassVariable^⚠Non-unstable-objfw
class_getImageName^⚠Apple
class_getInstanceMethod^⚠Non-unstable-objfw
class_getInstanceSize^⚠
class_getInstanceVariable^⚠Non-unstable-objfw
class_getIvarLayout^⚠Non-unstable-objfw
class_getMethodImplementation^⚠
class_getMethodImplementation_stret^⚠unstable-objfw or non-AArch64
class_getName^⚠
class_getProperty^⚠Non-unstable-objfw
class_getSuperclass^⚠
class_getVersion^⚠Non-unstable-objfw
class_getWeakIvarLayout^⚠Apple
class_isMetaClass^⚠
class_replaceMethod^⚠
class_replaceProperty^⚠Non-unstable-objfw
class_respondsToSelector^⚠
class_setIvarLayout^⚠Non-unstable-objfw
class_setVersion^⚠Non-unstable-objfw
class_setWeakIvarLayout^⚠Apple
free^⚠: The Objective-C runtime has several methods, usually with “copy” in their name, whose return value is allocated with C’s malloc and deallocated with C’s free method.
imp_getBlock^⚠Non-unstable-objfw
imp_implementationWithBlock^⚠Non-unstable-objfw
imp_removeBlock^⚠Non-unstable-objfw
ivar_getName^⚠Non-unstable-objfw
ivar_getOffset^⚠Non-unstable-objfw
ivar_getTypeEncoding^⚠Non-unstable-objfw
method_copyArgumentType^⚠Non-unstable-objfw: The return value is deallocated with free.
method_copyReturnType^⚠Non-unstable-objfw: The return value is deallocated with free.
method_exchangeImplementations^⚠Non-unstable-objfw
method_getArgumentType^⚠Non-unstable-objfw
method_getDescription^⚠Apple
method_getImplementation^⚠Non-unstable-objfw
method_getName^⚠Non-unstable-objfw
method_getNumberOfArguments^⚠Non-unstable-objfw
method_getReturnType^⚠Non-unstable-objfw
method_getTypeEncoding^⚠Non-unstable-objfw
method_invoke^⚠Apple
method_invoke_stret^⚠Apple and non-AArch64
method_setImplementation^⚠Non-unstable-objfw
objc_addExceptionHandler^⚠Apple and macOS and non-x86
objc_alloc^⚠Apple and not (macOS and x86)
objc_allocWithZone^⚠Apple and not (macOS and x86)
objc_allocateClassPair^⚠
objc_allocateProtocol^⚠Non-unstable-objfw
objc_autorelease^⚠
objc_autoreleasePoolPop^⚠Non-unstable-objfw
objc_autoreleasePoolPush^⚠Non-unstable-objfw
objc_autoreleaseReturnValue^⚠
objc_begin_catch^⚠gnustep-1-7, or Apple and not (macOS and x86)
objc_constructInstance^⚠DeprecatedApple
objc_copyClassList^⚠: The returned array is deallocated with free.
objc_copyClassNamesForImage^⚠Apple
objc_copyImageNames^⚠Apple: The returned array is deallocated with free.
objc_copyProtocolList^⚠Non-unstable-objfw: The returned array is deallocated with free.
objc_copyWeak^⚠
objc_destroyWeak^⚠
objc_destructInstance^⚠DeprecatedApple
objc_disposeClassPair^⚠Non-unstable-objfw
objc_duplicateClass^⚠Apple
objc_end_catch^⚠gnustep-1-7, or Apple and not (macOS and x86)
objc_enumerationMutation^⚠Apple or unstable-objfw
objc_exception_rethrow^⚠Apple and non-gnustep-1-7 and not (macOS and x86)
objc_exception_throw^⚠: See objc-exception.h.
objc_exception_try_enter^⚠Apple and macOS and x86
objc_exception_try_exit^⚠Apple and macOS and x86
objc_getAssociatedObject^⚠Non-unstable-objfw
objc_getClass^⚠
objc_getClassList^⚠
objc_getFutureClass^⚠DeprecatedApple
objc_getMetaClass^⚠Non-unstable-objfw
objc_getProtocol^⚠Non-unstable-objfw
objc_getRequiredClass^⚠
objc_initWeak^⚠
objc_loadWeak^⚠
objc_loadWeakRetained^⚠
objc_lookUpClass^⚠
objc_moveWeak^⚠
objc_msgSend^⚠Non-unstable-objfw
objc_msgSendSuper^⚠Apple
objc_msgSendSuper_stret^⚠Apple and non-AArch64
objc_msgSend_fp2ret^⚠Apple and x86-64
objc_msgSend_fpret^⚠Non-unstable-objfw and (x86-64 or x86)
objc_msgSend_stret^⚠Non-unstable-objfw and non-AArch64
objc_msg_lookup^⚠gnustep-1-7 or unstable-objfw
objc_msg_lookup_stret^⚠unstable-objfw
objc_msg_lookup_super^⚠gnustep-1-7 or unstable-objfw
objc_msg_lookup_super_stret^⚠unstable-objfw
objc_registerClassPair^⚠
objc_registerProtocol^⚠Non-unstable-objfw
objc_release^⚠
objc_removeAssociatedObjects^⚠Non-unstable-objfw
objc_removeExceptionHandler^⚠Apple and macOS and non-x86
objc_retain^⚠
objc_retainAutorelease^⚠
objc_retainAutoreleaseReturnValue^⚠
objc_retainAutoreleasedReturnValue^⚠
objc_retainBlock^⚠
objc_setAssociatedObject^⚠Non-unstable-objfw
objc_setEnumerationMutationHandler^⚠Apple or unstable-objfw
objc_setExceptionMatcher^⚠Apple and not (macOS and x86)
objc_setExceptionPreprocessor^⚠Apple and not (macOS and x86)
objc_setForwardHandler^⚠Apple or unstable-objfw
objc_setUncaughtExceptionHandler^⚠Apple and not (macOS and x86), or unstable-objfw
objc_storeStrong^⚠
objc_storeWeak^⚠
objc_sync_enter^⚠
objc_sync_exit^⚠
objc_terminate^⚠Apple and not (macOS and x86)
object_copy^⚠DeprecatedApple
object_dispose^⚠DeprecatedNon-unstable-objfw
object_getClass^⚠
object_getClassName^⚠
object_getIndexedIvars^⚠Non-unstable-objfw
object_getInstanceVariable^⚠DeprecatedNon-unstable-objfw
object_getIvar^⚠Non-unstable-objfw
object_isClass^⚠Apple
object_setClass^⚠
object_setInstanceVariable^⚠DeprecatedNon-unstable-objfw
object_setIvar^⚠Non-unstable-objfw
property_copyAttributeList^⚠Non-unstable-objfw: The returned array is deallocated with free.
property_copyAttributeValue^⚠Non-unstable-objfw
property_getAttributes^⚠Non-unstable-objfw
property_getName^⚠Non-unstable-objfw
protocol_addMethodDescription^⚠Non-unstable-objfw
protocol_addProperty^⚠Non-unstable-objfw
protocol_addProtocol^⚠Non-unstable-objfw
protocol_conformsToProtocol^⚠
protocol_copyMethodDescriptionList^⚠Non-unstable-objfw: The returned array is deallocated with free.
protocol_copyPropertyList^⚠Non-unstable-objfw: The returned array is deallocated with free.
protocol_copyProtocolList^⚠Non-unstable-objfw: The returned array is deallocated with free.
protocol_getMethodDescription^⚠Non-unstable-objfw
protocol_getName^⚠
protocol_getProperty^⚠Non-unstable-objfw
protocol_isEqual^⚠
sel_getName^⚠
sel_getUid^⚠Non-unstable-objfw
sel_isEqual^⚠
sel_isMapped^⚠Apple
sel_registerName^⚠

Type Aliases§

BOOL: The Objective-C BOOL type.
IMP: A nullable pointer to the start of a method implementation.
NSInteger: A signed integer value type.
NSUInteger: Describes an unsigned integer.
SEL: An immutable pointer to a selector.
id: A mutable pointer to an object / instance.
objc_AssociationPolicy: Policies related to associative references.
objc_exception_handlerApple and macOS and non-x86: Remember that this is non-null!
objc_exception_matcherApple and not (macOS and x86): Remember that this is non-null!
objc_exception_preprocessorApple and not (macOS and x86): Remember that this is non-null!
objc_uncaught_exception_handlerApple and not (macOS and x86): Remember that this is non-null!

Crate objc_sysCopy item path