Changes between Version 3 and Version 4 of Porting Macros plan


Ignore:
Timestamp:
Jan 3, 2010 11:08:47 PM (14 years ago)
Author:
mjs@apple.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Porting Macros plan

    v3 v4  
    33== Original Proposal ==
    44
    5 1. Strictly separate platform adaptation (mandatory to run on a given OS, compiler, or CPU at all) from policy choices (what features to enable, what optional libraries to use).
     5 1. Strictly separate platform adaptation (mandatory to run on a given OS, compiler, or CPU at all) from policy choices (what features to enable, what optional libraries to use).
    66
    7 2. Phase out PLATFORM macros completely - each use should be converted to a policy choice, or a platform adaptation decision.
     7 2. Phase out PLATFORM macros completely - each use should be converted to a policy choice, or a platform adaptation decision.
    88
    9 3. Instead of ports being defined by a top-level PLATFORM macro, I propose that each port should have its own header file to define policy decisions. For example, I'd propose that the system Mac OS X WebKit should use PortCocoa.h, and the WebKit used by Safari for Windows should use PortWinCG.h. There may also be a PortIPhone.h. These port definition headers would live in their own top-level WebKit module. Each one would be completely owned by whoever is generally considered the "owner" of a given port. Because related ports on different platforms may wish to share policy choices, it's ok for Port headers to include shared headers for some choices. For example, all Apple-maintained ports may include PortApple.h. We could go even further and have PortDefault.h to make default choices of what features are enabled, that ports would have to explicitly override.
     9 3. Instead of ports being defined by a top-level PLATFORM macro, I propose that each port should have its own header file to define policy decisions. For example, I'd propose that the system Mac OS X WebKit should use PortCocoa.h, and the WebKit used by Safari for Windows should use PortWinCG.h. There may also be a PortIPhone.h. These port definition headers would live in their own top-level WebKit module. Each one would be completely owned by whoever is generally considered the "owner" of a given port. Because related ports on different platforms may wish to share policy choices, it's ok for Port headers to include shared headers for some choices. For example, all Apple-maintained ports may include PortApple.h. We could go even further and have PortDefault.h to make default choices of what features are enabled, that ports would have to explicitly override.
    1010
    11 4. Platform adaptation macros would still be defined in Platform.h based on sniffing the environment, this would include things like the compiler, the underlying OS, available libc functions, and so forth.
     11 4. Platform adaptation macros would still be defined in Platform.h based on sniffing the environment, this would include things like the compiler, the underlying OS, available libc functions, and so forth.
    1212
    1313
    1414Platform adaptation macros would be:
    1515
    16 OS() - underlying operating system; only to be used for mandated low-level services like virtual memory, not to choose a GUI toolkit
    17    Examples:
    18        OS(UNIX) - Any Unix-like OS
    19        OS(DARWIN) - Underlying OS is the base OS X environment
    20        OS(FREEBSD) - FreeBSD
    21        OS(WIN) - Any version of Windows
    22        OS(WINCE) - The embedded version of Windows
     16 * OS() - underlying operating system; only to be used for mandated low-level services like virtual memory, not to choose a GUI toolkit
     17    * OS(UNIX) - Any Unix-like OS
     18    * OS(DARWIN) - Underlying OS is the base OS X environment
     19    * OS(FREEBSD) - FreeBSD
     20    * OS(WIN) - Any version of Windows
     21    * OS(WINCE) - The embedded version of Windows
    2322
    24 COMPILER() - the compiler being used to build the project
    25    Examples:
    26        COMPILER(GCC) - GNU Compiler Collection
    27        COMPILER(MSVC) - Microsoft Visual C++
    28        COMPILER(RVCT) - ARM compiler
     23 * COMPILER() - the compiler being used to build the project
     24    * COMPILER(GCC) - GNU Compiler Collection
     25    * COMPILER(MSVC) - Microsoft Visual C++
     26    * COMPILER(RVCT) - ARM compiler
    2927
    30 CPU() - the target CPU architecture
    31     Examples:
    32         CPU(X86)
    33         CPU(X86_64)
    34         CPU(ARM)
    35         CPU(BIG_ENDIAN)
    36         CPU(MIDDLE_ENDIAN)
     28 * CPU() - the target CPU architecture
     29     * CPU(X86)
     30     * CPU(X86_64)
     31     * CPU(ARM)
     32     * CPU(BIG_ENDIAN)
     33     * CPU(MIDDLE_ENDIAN)
    3734
    38 HAVE() - specific system features (headers, functions or similar) that are present or not
    39    Examples:
    40        HAVE(MMAP) - mmap() function is available
    41        HAVE(ERRNO_H) - errno.h header is available
    42        HAVE(MADV_FREE) - madvise(MADV_FREE) is available
     35 * HAVE() - specific system features (headers, functions or similar) that are present or not
     36    * HAVE(MMAP) - mmap() function is available
     37    * HAVE(ERRNO_H) - errno.h header is available
     38    * HAVE(MADV_FREE) - madvise(MADV_FREE) is available
    4339
    4440
    4541Policy decision macros would be:
    4642
    47 USE() - use a particular third-party library or optional OS service
    48    Examples:
    49        USE(SKIA) - Use the Skia graphics library
    50        USE(CG) - Use CoreGraphics
    51        USE(V8) - Use the V8 JavaScript implementation
    52        USE(CFNET) - Use CFNetwork networking
    53        USE(NSURL_NET) - Use NSURLConnection-based networking
    54        USE(APPKIT) - Use AppKit views and events
    55        USE(GTK) - Use Gtk+
    56        USE(QT) - Use Qt
    57        USE(QUICKTIME) - Use the QuickTime media engine
    58        USE(QTKIT) - Use the QuickTime media engine via the Mac QTKit API
    59        USE(QUICKTIME_WIN) - Use the QuickTime media engine via its Windows API
     43 * USE() - use a particular third-party library or optional OS service
     44    * USE(SKIA) - Use the Skia graphics library
     45    * USE(CG) - Use CoreGraphics
     46    * USE(V8) - Use the V8 JavaScript implementation
     47    * USE(CFNET) - Use CFNetwork networking
     48    * USE(NSURL_NET) - Use NSURLConnection-based networking
     49    * USE(APPKIT) - Use AppKit views and events
     50    * USE(GTK) - Use Gtk+
     51    * USE(QT) - Use Qt
     52    * USE(QUICKTIME) - Use the QuickTime media engine
     53    * USE(QTKIT) - Use the QuickTime media engine via the Mac QTKit API
     54    * USE(QUICKTIME_WIN) - Use the QuickTime media engine via its Windows API
    6055
    61 ENABLE() - turn on a specific feature of WebKit
    62    Examples:
    63       ENABLE(ACCESSIBILITY) - Enable support for assistive technologies (currently wrongly a HAVE)
    64       ENABLE(XSLT) - Include XSLT support
    65       ENABLE(OBJC_MAC_API) - Include Objective C API based on NSViews (current WebKit Mac)
    66       ENABLE(OBJC_DOM_API) - Include Objective C DOM bindings (may apply to other ObjC toolkits than AppKit)
    67       ENABLE(JSC) - Enable use of the JavaScriptCore implementation (inconsistent with V8 because JSC is a WebKit feature but V8 is an external dependency, even though they serve similar purposes)
    68       ENABLE(VIDEO) - Enable support for the HTML5 Video element
    69       ENABLE(SVG) - Enable support for SVG (Scalable Vector Graphics)
    70       ENABLE(WML) - Enable support for WML
     56 * ENABLE() - turn on a specific feature of WebKit
     57    * ENABLE(ACCESSIBILITY) - Enable support for assistive technologies (currently wrongly a HAVE)
     58    * ENABLE(XSLT) - Include XSLT support
     59    * ENABLE(OBJC_MAC_API) - Include Objective C API based on NSViews (current WebKit Mac)
     60    * ENABLE(OBJC_DOM_API) - Include Objective C DOM bindings (may apply to other ObjC toolkits than AppKit)
     61    * ENABLE(JSC) - Enable use of the JavaScriptCore implementation (inconsistent with V8 because JSC is a WebKit feature but V8 is an external dependency, even though they serve similar purposes)
     62    * ENABLE(VIDEO) - Enable support for the HTML5 Video element
     63    * ENABLE(SVG) - Enable support for SVG (Scalable Vector Graphics)
     64    * ENABLE(WML) - Enable support for WML
    7165
    7266Some macros that would be completely phased out, in favor of platform and policy decisions:
    7367
    74 PLATFORM(MAC) - A mix of things that should be USE(APPKIT), USE(NSURL_NET), ENABLE(OBJC_MAC_API) and a host of other things
    75 PLATFORM(WIN) - Hodgepodge of mandatory platform adaptation, optional platform adaptation, and choices specific to Apple's Mac Port
    76 PLATFORM(GTK) - Most of this would be replaced by USE(GTK) but perhaps different policy macros are appropriate in some cases.
    77 PLATFORM(CHROMIUM) - Grab-bag of various policy choices.
     68 * PLATFORM(MAC) - A mix of things that should be USE(APPKIT), USE(NSURL_NET), ENABLE(OBJC_MAC_API) and a host of other things
     69 * PLATFORM(WIN) - Hodgepodge of mandatory platform adaptation, optional platform adaptation, and choices specific to Apple's Mac Port
     70 * PLATFORM(GTK) - Most of this would be replaced by USE(GTK) but perhaps different policy macros are appropriate in some cases.
     71 * PLATFORM(CHROMIUM) - Grab-bag of various policy choices.