Module ffi

objc2

Module ffi 

Source
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 the runtime module 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).

§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.

§Objective-C Compiler configuration

Objective-C compilers like clang and gcc requires configuring the calling ABI to the runtime you’re using:

Furthermore, there are various flags that are expected in modern Objective-C, that are off by default. In particular you might want to enable the -fobjc-exceptions and -fobjc-arc flags.

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");

    builder.flag("-fobjc-exceptions");
    builder.flag("-fobjc-arc");
    builder.flag("-fobjc-runtime=..."); // If not compiling for Apple

    builder.compile("libmy_objective_c_script.a");
}

§Design choices

It is recognized that the most primary consumer of this module will be macOS and secondly iOS applications. Therefore it was chosen not to use bindgen1 in our build script to not add compilation cost to those targets.

Deprecated functions are also not included for future compatibility, 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.

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

Structs§

objc_method_description
Describes an Objective-C method.
objc_property
An opaque type that describes a property in a class.
objc_property_attribute_t
Describes an Objective-C property attribute.
objc_super
Specifies data used when sending messages to superclasses.

Constants§

NODeprecated
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
YESDeprecated
nil
A quick alias for a null_mut object / instance.

Functions§

_objc_msgForward⚠Apple
_objc_msgForward_stret⚠Apple and non-AArch64
class_addIvar⚠
class_addMethod⚠
class_addProperty⚠
class_addProtocol⚠
class_conformsToProtocol⚠
class_copyIvarList⚠
The return value is deallocated with free.
class_copyMethodList⚠
The returned array is deallocated with free.
class_copyPropertyList⚠
The returned array is deallocated with free.
class_copyProtocolList⚠
The returned array is deallocated with free.
class_createInstance⚠
class_getClassMethod⚠
class_getClassVariable⚠
class_getImageName⚠Apple
class_getInstanceMethod⚠
class_getInstanceSize⚠
class_getInstanceVariable⚠
class_getIvarLayout⚠
class_getMethodImplementation⚠
class_getMethodImplementation_stret⚠Non-AArch64
class_getName⚠
class_getProperty⚠
class_getSuperclass⚠
class_getVersion⚠
class_getWeakIvarLayout⚠Apple
class_isMetaClass⚠
class_replaceMethod⚠
class_replaceProperty⚠
class_respondsToSelector⚠
class_setIvarLayout⚠
class_setVersion⚠
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⚠
imp_implementationWithBlock⚠
imp_removeBlock⚠
ivar_getName⚠
ivar_getOffset⚠
ivar_getTypeEncoding⚠
method_copyArgumentType⚠
The return value is deallocated with free.
method_copyReturnType⚠
The return value is deallocated with free.
method_exchangeImplementations⚠
method_getArgumentType⚠
method_getDescription⚠Apple
method_getImplementation⚠
method_getName⚠
method_getNumberOfArguments⚠
method_getReturnType⚠
method_getTypeEncoding⚠
method_invoke⚠Apple
method_invoke_stret⚠Apple and non-AArch64
method_setImplementation⚠
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⚠
objc_autorelease⚠
objc_autoreleasePoolPop⚠
objc_autoreleasePoolPush⚠
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⚠
The returned array is deallocated with free.
objc_copyWeak⚠
objc_destroyWeak⚠
objc_destructInstance⚠DeprecatedApple
objc_disposeClassPair⚠
objc_duplicateClass⚠Apple
objc_end_catch⚠gnustep-1-7, or Apple and not (macOS and x86)
objc_enumerationMutation⚠Apple
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⚠
objc_getClass⚠
objc_getClassList⚠
objc_getFutureClass⚠DeprecatedApple
objc_getMetaClass⚠
objc_getProtocol⚠
objc_getRequiredClass⚠
objc_initWeak⚠
objc_loadWeak⚠
objc_loadWeakRetained⚠
objc_lookUpClass⚠
objc_moveWeak⚠
objc_msgSend⚠
objc_msgSendSuper⚠Apple
objc_msgSendSuper_stret⚠Apple and non-AArch64
objc_msgSend_fp2ret⚠Apple and x86-64
objc_msgSend_fpret⚠(x86-64 or x86)
objc_msgSend_stret⚠Non-AArch64
objc_msg_lookup⚠gnustep-1-7
objc_msg_lookup_stret⚠
objc_msg_lookup_super⚠gnustep-1-7
objc_msg_lookup_super_stret⚠
objc_registerClassPair⚠
objc_registerProtocol⚠
objc_release⚠
objc_removeAssociatedObjects⚠
objc_removeExceptionHandler⚠Apple and macOS and non-x86
objc_retain⚠
objc_retainAutorelease⚠
objc_retainAutoreleaseReturnValue⚠
objc_retainAutoreleasedReturnValue⚠
objc_retainBlock⚠
objc_setAssociatedObject⚠
objc_setEnumerationMutationHandler⚠Apple
objc_setExceptionMatcher⚠Apple and not (macOS and x86)
objc_setExceptionPreprocessor⚠Apple and not (macOS and x86)
objc_setForwardHandler⚠Apple
objc_setUncaughtExceptionHandler⚠Apple and not (macOS and x86)
objc_storeStrong⚠
objc_storeWeak⚠
objc_sync_enter⚠
objc_sync_exit⚠
objc_terminate⚠Apple and not (macOS and x86)
object_copy⚠DeprecatedApple
object_dispose⚠Deprecated
object_getClass⚠
object_getClassName⚠
object_getIndexedIvars⚠
object_getInstanceVariable⚠Deprecated
object_getIvar⚠
object_isClass⚠Apple
object_setClass⚠
object_setInstanceVariable⚠Deprecated
object_setIvar⚠
property_copyAttributeList⚠
The returned array is deallocated with free.
property_copyAttributeValue⚠
property_getAttributes⚠
property_getName⚠
protocol_addMethodDescription⚠
protocol_addProperty⚠
protocol_addProtocol⚠
protocol_conformsToProtocol⚠
protocol_copyMethodDescriptionList⚠
The returned array is deallocated with free.
protocol_copyPropertyList⚠
The returned array is deallocated with free.
protocol_copyProtocolList⚠
The returned array is deallocated with free.
protocol_getMethodDescription⚠
protocol_getName⚠
protocol_getProperty⚠
protocol_isEqual⚠
sel_getName⚠
sel_getUid⚠
sel_isEqual⚠
sel_isMapped⚠Apple
sel_registerName⚠

Type Aliases§

BOOLDeprecated
IMPDeprecated
NSInteger
A signed integer value type.
NSUInteger
Describes an unsigned integer.
idDeprecated
A mutable pointer to an object / instance.
objc_AssociationPolicy
Policies related to associative references.
objc_classDeprecated
objc_ivarDeprecated
objc_methodDeprecated
objc_objectDeprecated