Changes between Initial Version and Version 1 of ExportingSymbols

Timestamp:

03/21/12 21:21:31 (14 months ago)

Author:

morrita@google.com

Comment:

--

ExportingSymbols

@@ +1 @@
+= Exporting Symbols =
+
+Some ports limit the exported symbols. We need to mark API symbols as exported when we use it outside the library.
+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.
+
+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.
+
+== Export Lists ==
+
+An export list is a text file which contains the list of exporting symbols.
+Linkers refer these files to decide which symbols should be exported.
+
+Ports have their own separate lists:
+
+ * [source:/trunk/Source/WebCore/WebCore.exp.in]
+   * Mac port uses this to build WebCore.framework. 
+ * [source:/trunk/Source/JavaScriptCore/JavaScriptCore.vcproj/JavaScriptCore/JavaScriptCore.def]
+   * Win ports use this to build JavaScriptCore.dll
+
+ * [source:/trunk/Source/autotools/symbols.filter]
+   * GTK port uses this to build libwebkitgtk.so
+ * [source:/trunk/Source/WebKit2/mac/WebKit2.order]
+   * Mac WebKi2 port uses this to build WebKit2.framework
+ * [source:/trunk/Source/WebKit2/win/WebKit2.def]
+   * Apple Win port uses this to build WebKit2.dll
+ * [source:/trunk/Source/WebKit2/win/WebKit2CFLite.def]
+   * CFLite Win port uses this to build WebKit2.dll
+
+== Inline Annotations ==
+
+Inline annotations is compiler-specific qualifiers which are encapsulated by a set of macros.
+These macros are defined in following files:
+
+ * [source:Source/JavaScriptCore/wtf/ExportMacros.h]
+  * WTF_EXPORT_PRIVATE
+ * [source:Source/JavaScriptCore/runtime/JSExportMacros.h]
+  * JS_EXPORT_PRIVATE, JS_EXPORTDATA
+ * [source:Source/WebCore/platform/PlatformExportMacros.h]
+
+ * (TODO: List port specific definitions for WebKit API layer here.)
+
+Inline annotations are adopted as following:
+
+ * Mac port uses WTF_EXPORT, WTF_EXPORT_PRIVATE, JS_EXPORT, JS_EXPORT_PRIVATE, JS_EXPORTDATA to export WTF and JSC symbols.
+ * Win ports use it JS_EXPORTDATA for exporting JSC static variables.
+ * Many port have use their own inline annotations to export their WebKit API.
+
+=== Caveat ===
+
+ * You cannot export inline function.
+ * 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.
+
+== How can I export my symbols? ==
+
+Here are some typical scenarios when you need to care about symbol export:
+
+=== Exporting WebCore symbols to use them from port WebKit implementations ===
+
+ * If you use it from Mac(WK1), you need to edit WebCore.exp.in.
+ * Otherwise you don't need to do anything about symbols.
+
+=== Exporting JavaScriptCore/WTF symbols to use them from port WebCore ===
+
+ * You need to edit JavaScriptCore.def
+ * You need to add JS_EXPORT_PRIVATE or WTF_EXPORT_PRIVATE to the function.
+
+=== Exporting WebCore symbols to use them from Internals object (WebCoreTestSupport) ===
+
+For WTF/JavaScriptCore symbols,
+
+ * You need to edit JavaScriptCore.def. 
+ * You also need to add JS_EXPORT_PRIVATE or WTF_EXPORT_PRIVATE to exporting functions.
+
+For WebCore symbols, you need to edit following files...
+
+ *  WebCore.exp.in, symbols.filter, WebKit2.order, WebKit2.def, WebKit2CFLite.def
+
+=== Exporting WTF/JavaScriptCore/WebCore symbols to use them from DumpRenderTree ===
+
+ * You shouldn't do it.
+ * If you inevitably need to do it, it's same as the Internals appraoch noted above.
+
+=== Exporting WebKit API symbols to applications ===
+
+TODO: Write port specific way to do this.