Changes between Initial Version and Version 1 of Porting Macros plan


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

--

Legend:

Unmodified
Added
Removed
Modified
  • Porting Macros plan

    v1 v1  
     1I propose that we change as follows:
     2
     31) 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).
     4
     52) Phase out PLATFORM macros completely - each use should be converted to a policy choice, or a platform adaptation decision.
     6
     73) 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.
     8
     94) 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.
     10
     11
     12Platform adaptation macros would be:
     13
     14OS() - underlying operating system; only to be used for mandated low-level services like virtual memory, not to choose a GUI toolkit
     15   Examples:
     16       OS(UNIX) - Any Unix-like OS
     17       OS(DARWIN) - Underlying OS is the base OS X environment
     18       OS(FREEBSD) - FreeBSD
     19       OS(WIN) - Any version of Windows
     20       OS(WINCE) - The embedded version of Windows
     21
     22COMPILER() - the compiler being used to build the project
     23   Examples:
     24       COMPILER(GCC) - GNU Compiler Collection
     25       COMPILER(MSVC) - Microsoft Visual C++
     26       COMPILER(RVCT) - ARM compiler
     27
     28HAVE() - specific system features (headers, functions or similar) that are present or not
     29   Examples:
     30       HAVE(MMAP) - mmap() function is available
     31       HAVE(ERRNO_H) - errno.h header is available
     32       HAVE(MADV_FREE) - madvise(MADV_FREE) is available
     33
     34
     35Policy decision macros would be:
     36
     37USE() - use a particular third-party library or optional OS service
     38   Examples:
     39       USE(SKIA) - Use the Skia graphics library
     40       USE(CG) - Use CoreGraphics
     41       USE(V8) - Use the V8 JavaScript implementation
     42       USE(CFNET) - Use CFNetwork networking
     43       USE(NSURL_NET) - Use NSURLConnection-based networking
     44       USE(APPKIT) - Use AppKit views and events
     45       USE(GTK) - Use Gtk+
     46       USE(QT) - Use Qt
     47       USE(QUICKTIME) - Use the QuickTime media engine
     48       USE(QTKIT) - Use the QuickTime media engine via the Mac QTKit API
     49       USE(QUICKTIME_WIN) - Use the QuickTime media engine via its Windows API
     50
     51ENABLE() - turn on a specific feature of WebKit
     52   Examples:
     53      ENABLE(ACCESSIBILITY) - Enable support for assistive technologies (currently wrongly a HAVE)
     54      ENABLE(XSLT) - Include XSLT support
     55      ENABLE(OBJC_MAC_API) - Include Objective C API based on NSViews (current WebKit Mac)
     56      ENABLE(OBJC_DOM_API) - Include Objective C DOM bindings (may apply to other ObjC toolkits than AppKit)
     57      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)
     58      ENABLE(VIDEO) - Enable support for the HTML5 Video element
     59      ENABLE(SVG) - Enable support for SVG (Scalable Vector Graphics)
     60      ENABLE(WML) - Enable support for WML
     61
     62
     63
     64Some macros that would be completely phased out, in favor of platform and policy decisions:
     65
     66PLATFORM(MAC) - A mix of things that should be USE(APPKIT), USE(NSURL_NET), ENABLE(OBJC_MAC_API) and a host of other things
     67PLATFORM(WIN) - Hodgepodge of mandatory platform adaptation, optional platform adaptation, and choices specific to Apple's Mac Port
     68PLATFORM(GTK) - Most of this would be replaced by USE(GTK) but perhaps different policy macros are appropriate in some cases.
     69PLATFORM(CHROMIUM) - Grab-bag of various policy choices.