| 1 | = Exporting Symbols = |
| 2 | |
| 3 | Some ports limit the exported symbols. We need to mark API symbols as exported when we use it outside the library. |
| 4 | Since WebKit consists of a set of libraries (WTF, JavaScriptCore, WebCore, WebKit), each library need to export symbols if the API is used from a different library. |
| 5 | |
| 6 | There is two primary way to export symbols: '''export lists''' and '''inline annotations'''. Some ports use export lists. others use inline annotations, or even both. |
| 7 | |
| 8 | == Export Lists == |
| 9 | |
| 10 | An export list is a text file which contains the list of exporting symbols. |
| 11 | Linkers refer these files to decide which symbols should be exported. |
| 12 | |
| 13 | Ports have their own separate lists: |
| 14 | |
| 15 | * [source:/trunk/Source/WebCore/WebCore.exp.in] |
| 16 | * Mac port uses this to build WebCore.framework. |
| 17 | * [source:/trunk/Source/JavaScriptCore/JavaScriptCore.vcproj/JavaScriptCore/JavaScriptCore.def] |
| 18 | * Win ports use this to build JavaScriptCore.dll |
| 19 | |
| 20 | * [source:/trunk/Source/autotools/symbols.filter] |
| 21 | * GTK port uses this to build libwebkitgtk.so |
| 22 | * [source:/trunk/Source/WebKit2/mac/WebKit2.order] |
| 23 | * Mac WebKi2 port uses this to build WebKit2.framework |
| 24 | * [source:/trunk/Source/WebKit2/win/WebKit2.def] |
| 25 | * Apple Win port uses this to build WebKit2.dll |
| 26 | * [source:/trunk/Source/WebKit2/win/WebKit2CFLite.def] |
| 27 | * CFLite Win port uses this to build WebKit2.dll |
| 28 | |
| 29 | == Inline Annotations == |
| 30 | |
| 31 | Inline annotations is compiler-specific qualifiers which are encapsulated by a set of macros. |
| 32 | These macros are defined in following files: |
| 33 | |
| 34 | * [source:Source/JavaScriptCore/wtf/ExportMacros.h] |
| 35 | * WTF_EXPORT_PRIVATE |
| 36 | * [source:Source/JavaScriptCore/runtime/JSExportMacros.h] |
| 37 | * JS_EXPORT_PRIVATE, JS_EXPORTDATA |
| 38 | * [source:Source/WebCore/platform/PlatformExportMacros.h] |
| 39 | |
| 40 | * (TODO: List port specific definitions for WebKit API layer here.) |
| 41 | |
| 42 | Inline annotations are adopted as following: |
| 43 | |
| 44 | * Mac port uses WTF_EXPORT, WTF_EXPORT_PRIVATE, JS_EXPORT, JS_EXPORT_PRIVATE, JS_EXPORTDATA to export WTF and JSC symbols. |
| 45 | * Win ports use it JS_EXPORTDATA for exporting JSC static variables. |
| 46 | * Many port have use their own inline annotations to export their WebKit API. |
| 47 | |
| 48 | === Caveat === |
| 49 | |
| 50 | * You cannot export inline function. |
| 51 | * If you need to export C++ vtables (that rarely happens though), you need to add JS_EXPORT_PRIVATE or WTF_EXPORT_PRIVATE to the class definition. |
| 52 | |
| 53 | == How can I export my symbols? == |
| 54 | |
| 55 | Here are some typical scenarios when you need to care about symbol export: |
| 56 | |
| 57 | === Exporting WebCore symbols to use them from port WebKit implementations === |
| 58 | |
| 59 | * If you use it from Mac(WK1), you need to edit WebCore.exp.in. |
| 60 | * Otherwise you don't need to do anything about symbols. |
| 61 | |
| 62 | === Exporting JavaScriptCore/WTF symbols to use them from port WebCore === |
| 63 | |
| 64 | * You need to edit JavaScriptCore.def |
| 65 | * You need to add JS_EXPORT_PRIVATE or WTF_EXPORT_PRIVATE to the function. |
| 66 | |
| 67 | === Exporting WebCore symbols to use them from Internals object (WebCoreTestSupport) === |
| 68 | |
| 69 | For WTF/JavaScriptCore symbols, |
| 70 | |
| 71 | * You need to edit JavaScriptCore.def. |
| 72 | * You also need to add JS_EXPORT_PRIVATE or WTF_EXPORT_PRIVATE to exporting functions. |
| 73 | |
| 74 | For WebCore symbols, you need to edit following files... |
| 75 | |
| 76 | * WebCore.exp.in, symbols.filter, WebKit2.order, WebKit2.def, WebKit2CFLite.def |
| 77 | |
| 78 | === Exporting WTF/JavaScriptCore/WebCore symbols to use them from DumpRenderTree === |
| 79 | |
| 80 | * You shouldn't do it. |
| 81 | * If you inevitably need to do it, it's same as the Internals appraoch noted above. |
| 82 | |
| 83 | === Exporting WebKit API symbols to applications === |
| 84 | |
| 85 | TODO: Write port specific way to do this. |