Changes between Initial Version and Version 1 of ExportingSymbols


Ignore:
Timestamp:
Mar 21, 2012 9:21:31 PM (10 years ago)
Author:
morrita@google.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ExportingSymbols

    v1 v1  
     1= Exporting Symbols =
     2
     3Some ports limit the exported symbols. We need to mark API symbols as exported when we use it outside the library.
     4Since 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
     6There 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
     10An export list is a text file which contains the list of exporting symbols.
     11Linkers refer these files to decide which symbols should be exported.
     12
     13Ports 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
     31Inline annotations is compiler-specific qualifiers which are encapsulated by a set of macros.
     32These 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
     42Inline 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
     55Here 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
     69For 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
     74For 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
     85TODO: Write port specific way to do this.