-
-
Notifications
You must be signed in to change notification settings - Fork 367
/
objc_interface.dd
369 lines (294 loc) · 11.6 KB
/
objc_interface.dd
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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
Ddoc
$(SPEC_S Interfacing to Objective-C,
$(P
D has limited support for interfacing with Objective-C. It supports
external classes and calling instance methods. It is only available on
OS X, compiling for 64bit.
)
$(P
Fully working example is available at
$(LINK2 #usage-example, the bottom).
)
$(SECTION2 $(LNAME2 external-class, Declaring an External Class))
---
extern (Objective-C)
interface NSString
{
const(char)* UTF8String() @selector("UTF8String");
}
---
$(P
Currently all Objective-C classes need to be declared as interfaces in
D. All Objective-C classes that should be accessible from within D
need to be declared with the $(LINK2 #objc-linkage, Objective-C linkage).
)
$(P
The $(LINK2 #selector-attribute, `@selector`) attribute indicates which
Objective-C selector should be used when calling this method from D.
This attribute needs to be attached to all methods.
)
$(SECTION2 $(LNAME2 instance-method, Calling an Instance Method))
$(P
Calling an Objective-C instance method uses the same syntax as calling
regular D methods:
)
---
const(char)* result = object.UTF8String();
---
$(P
When the compiler sees a call to a method with Objective-C linkage it
will generate a call similar to how an Objective-C compiler would call
the method.
)
$(SECTION2 $(LNAME2 selector-attribute, The `@selector` Attribute))
$(P
The `@selector` attribute is a compiler recognized
$(LINK2 attribute.html#uda, UDA). It is used to tell the compiler which
selector to use when calling an Objective-C method.
)
$(P
Selectors in Objective-C can contain characters that are not valid in D
identifiers, `:`. D supports method overloading while Objective-C
achieves something similar by using different selectors. For these two
reasons it is better to be able to specify the selectors manually in D,
instead of trying to infer it. This allows to have a more natural names
for the methods in D. Example:
)
---
extern (Objective-C)
interface NSString
{
NSString initWith(in char*) @selector("initWithUTF8String:");
NSString initWith(NSString) @selector("initWithString:");
}
---
$(P
Here the method `initWith` is overloaded with two versions, one
accepting `in char*`, the other one `NSString`. These two methods are
mapped to two different Objective-C selectors, `initWithUTF8String:`
and `initWithString:`.
)
$(P
The attribute is defined in druntime in
$(LINK2 phobos/core_attribute.html, `core.attribute`) and aliased in
$(LINK2 phobos/object.html, `object`), meaning it will be implicitly
imported. The attribute is only defined when the version identifier
$(LINK2 #objc-version-identifier, `D_ObjectiveC`) is enabled.
)
$(SECTION3 $(LNAME2 compiler-checks, Compiler Checks))
$(P
The compiler performs the following checks to enforce the correct usage
of the `@selector` attribue:
)
$(UL
$(LI
The attribue can only be attached to methods with Objective-C
linkage
)
$(LI The attribue can only be attached once to a method)
$(LI The attribue cannot be attached to a template method)
$(LI
The number of colons in the selector needs to match the number of
parameters the method is declared with
)
)
$(P If any of the checks fail, a compile error will occur.)
$(SECTION2
$(LNAME2 objc-version-identifier, The `D_ObjectiveC` Version Identifier)
)
$(P
The `D_ObjectiveC` version identifier is a predefined version
identifier. It is enabled if Objective-C support is available for the
target.
)
$(SECTION2 $(LNAME2 objc-linkage, Objective-C Linkage))
$(P
Objective-C linkage is achieved by attaching the `extern (Objective-C)`
attribute to an interface. Example:
)
---
extern (Objective-C)
interface NSObject
{
NSObject init() @selector("init");
}
---
$(P
All methods inside an interface declared as `extern (Objective-C)` will
get implicit Objective-C linkage.
)
$(P
The linkage is recognized on all platforms but will issue a compile
error if it is used on a platform where Objective-C support is not
available. This allows to easily hide Objective-C declarations from
platforms where it is not available using the
$(LINK2 version.html#version, `version`) statement, without resorting to
string mixins or other workarounds.
)
$(SECTION2 $(LNAME2 memory-management, Memory Management))
$(P
The preferred way to do memory management in Objective-C is to use
Automatic Reference Counting, $(LINK2 https://developer.apple.com/library/mac/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html, ARC).
This is not supported in D, therefore manual memory management is
required to be used instead. This is achieved by calling $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/index.html#//apple_ref/occ/intfm/NSObject/release, `release`)
on an Objective-C instance, like in the old days of Objective-C.
)
$(SECTION2 $(LNAME2 frameworks, Frameworks))
$(P
Most Objective-C code is bundled in something called a "Framework".
This is basically a regular directory, with the `.framework` extension
and a specific directory layout. A framework contains a dynamic
library, all public header files and any resources (images, sounds and
so on) required by the framework.
)
$(P
These directories are recognized by some tools, like the Objective-C
compiler and linker, to be frameworks. To link with a framework from
DMD, use the following flags:
)
---
-L-framework -L<Framework>
---
$(P
Where `<Framework>` is the name of the framework to link with, without
the `.framework` extension. The two `-L` flags are required because the
linker expects a space between the `-framework` flag and the name of
the framework. DMD cannot handle this and will instead interpet the
name of the framework as a separate flag.
)
$(SECTION3 $(LNAME2 framework-paths, Framework Paths))
$(P
Using the above flag, the linker will search in the standard framework
paths. The standard search paths for frameworks are:
)
$(UL
$(LI `/System/Library/Frameworks`)
$(LI `/Library/Frameworks`)
)
$(P
The following flag from DMD can be used to add a new path in which to
search for frameworks:
)
---
-L-F<framework_path>
---
$(P
For more information see the $(LINK2 https://developer.apple.com/library/ios/documentation/MacOSX/Conceptual/BPFrameworks/Tasks/IncludingFrameworks.html, reference documentation)
and the `ld` man page.
)
$(SECTION2 $(LNAME2 usage-example, Full Usage Example))
$(P
Since the only parts of Objective-C that is currently supported is
calling instance methods, this example demonstrates how the Objective-C
runtime can be used to achieve a running example.
)
$(P
This example will create an Objective-C string, `NSString`, and log the
message using `NSLog` to stderr.
)
---
extern (Objective-C)
interface Class
{
NSString alloc() @selector("alloc");
}
---
$(P
This interface is used to emulate the $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ObjCRuntimeRef/#//apple_ref/c/tdef/Class, `Class`)
type available in the Objective-C runtime. The instance method `alloc`
will be used to emulate a class method in `NSObject`,
$(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSObject_Class/#//apple_ref/occ/clm/NSObject/alloc, alloc).
)
---
extern (Objective-C)
interface NSString
{
NSString initWithUTF8String(in char* str) @selector("initWithUTF8String:");
void release() @selector("release");
}
---
$(P
This is a simplified declaration of the $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/, `NSString`)
class. The $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/#//apple_ref/occ/instm/NSString/initWithUTF8String:, `initWithUTF8String:`)
method will be used to convert a C string in UTF-8 to an Objective-C
string, `NSString`. The $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Protocols/NSObject_Protocol/index.html#//apple_ref/occ/intfm/NSObject/release, `release`)
method is used to release an deallocate the string. Since D doesn't
support $(LINK2 https://developer.apple.com/library/mac/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html, ARC)
it's needed to manually release Objective-C instances.
)
---
extern (C) Class objc_lookUpClass(in char* name)
---
$(P
The $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ObjCRuntimeRef/#//apple_ref/c/func/objc_lookUpClass, `objc_lookUpClass`)
function is used to get the class definition of the class with the
given name.
)
---
extern (C) void NSLog(NSString, ...);
---
$(P
This $(LINK2 https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation_Functions/index.html#//apple_ref/c/func/NSLog, `NSLog`)
function prints a message to the System Log facility, i.e. to stderr
and Console.
)
---
auto cls = objc_lookUpClass("NSString");
---
$(P Get the class definition of `NSString`.)
---
auto str = cls.alloc();
---
$(P Allocate an instance of the class, `NSString`.)
---
str = str.initWithUTF8String("Hello World!")
---
$(P Initialize the Objective-C string using a C string.)
---
NSLog(str);
---
$(P
Log the string to stderr, this will print something like this in the
terminal:
)
---
2015-07-18 13:14:27.978 main[11045:2934950] Hello World!
---
---
str.release();
---
$(P Release and deallocate the string.)
$(P All steps combined look like this:)
---
module main;
extern (Objective-C)
interface Class
{
NSString alloc() @selector("alloc");
}
extern (Objective-C)
interface NSString
{
NSString initWithUTF8String(in char* str) @selector("initWithUTF8String:");
void release() @selector("release");
}
extern (C) void NSLog(NSString, ...);
extern (C) Class objc_lookUpClass(in char* name);
void main()
{
auto cls = objc_lookUpClass("NSString");
auto str = cls.alloc().initWithUTF8String("Hello World!");
NSLog(str);
str.release();
}
---
$(P
When compiling the application remember to link with the required
libraries, in this case the Foundation framework. Example:
)
---
dmd -L-framework -LFoundation main.d
---
)
Macros:
TITLE=Interfacing to Objective-C