[webkit-dev] Proposal for a new way to handle porting #ifdefs

[Maciej Stachowiak]

I think our set of porting macros has become somewhat confused.

Originally, our idea was that a port represents primarily adaptation  
to a particular platform. However, over time it has become clear that  
most of what is decided by a port is not platform adaptation, but  
rather policy decisions. For example, ports decide to have different  
features enabled, or to use different sets of system functionality on  
the same underlying OS.

In addition, I think the catchall top-level PLATFORM create confusion,  
because it is not totally clear if they are policy decisions, platform  
adaptation decisions, or what.

Third, it seems wrong that the policy choices of every port are  
represented as a bunch of ifdef tomfoolery inside a single Platform.h  
file.

And fourth, many ports often run on the same OS, but with a different  
set of choices - for example on Mac OS X it is possible to build the  
Mac, Chromium, Gtk, Qt and Wx ports (at least).


Therefore, I propose that we change as follows:

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).

2) Phase out PLATFORM macros completely - each use should be converted  
to a policy choice, or a platform adaptation decision.

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.

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.


Platform adaptation macros would be:

OS() - underlying operating system; only to be used for mandated low- 
level services like virtual memory, not to choose a GUI toolkit
     Examples:
         OS(UNIX) - Any Unix-like OS
         OS(DARWIN) - Underlying OS is the base OS X environment
         OS(FREEBSD) - FreeBSD
         OS(WIN) - Any version of Windows
         OS(WINCE) - The embedded version of Windows

COMPILER() - the compiler being used to build the project
     Examples:
         COMPILER(GCC) - GNU Compiler Collection
         COMPILER(MSVC) - Microsoft Visual C++
         COMPILER(RVCT) - ARM compiler

HAVE() - specific system features (headers, functions or similar) that  
are present or not
     Examples:
         HAVE(MMAP) - mmap() function is available
         HAVE(ERRNO_H) - errno.h header is available
         HAVE(MADV_FREE) - madvise(MADV_FREE) is available


Policy decision macros would be:

USE() - use a particular third-party library or optional OS service
     Examples:
         USE(SKIA) - Use the Skia graphics library
         USE(CG) - Use CoreGraphics
         USE(V8) - Use the V8 JavaScript implementation
         USE(CFNET) - Use CFNetwork networking
         USE(NSURL_NET) - Use NSURLConnection-based networking
         USE(APPKIT) - Use AppKit views and events
         USE(GTK) - Use Gtk+
         USE(QT) - Use Qt
         USE(QUICKTIME) - Use the QuickTime media engine
         USE(QTKIT) - Use the QuickTime media engine via the Mac QTKit  
API
         USE(QUICKTIME_WIN) - Use the QuickTime media engine via its  
Windows API

ENABLE() - turn on a specific feature of WebKit
     Examples:
        ENABLE(ACCESSIBILITY) - Enable support for assistive  
technologies (currently wrongly a HAVE)
        ENABLE(XSLT) - Include XSLT support
        ENABLE(OBJC_MAC_API) - Include Objective C API based on  
NSViews (current WebKit Mac)
        ENABLE(OBJC_DOM_API) - Include Objective C DOM bindings (may  
apply to other ObjC toolkits than AppKit)
        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)
        ENABLE(VIDEO) - Enable support for the HTML5 Video element
        ENABLE(SVG) - Enable support for SVG (Scalable Vector Graphics)
        ENABLE(WML) - Enable support for WML



Some macros that would be completely phased out, in favor of platform  
and policy decisions:

PLATFORM(MAC) - A mix of things that should be USE(APPKIT),  
USE(NSURL_NET), ENABLE(OBJC_MAC_API) and a host of other things
PLATFORM(WIN) - Hodgepodge of mandatory platform adaptation, optional  
platform adaptation, and choices specific to Apple's Mac Port
PLATFORM(GTK) - Most of this would be replaced by USE(GTK) but perhaps  
different policy macros are appropriate in some cases.
PLATFORM(CHROMIUM) - Grab-bag of various policy choices.


I believe that with this new proposal, ifdefs in the code would be  
much more understandable. Any time something is ifdef'd, it would be  
clear why - is this to support a given public API? Is it to support a  
particular feature or variant behavior? Is it to make use of an  
underlying library? Is it just something you *have* to do on the OS?  
As a side effect, it would somewhat discourage scattered trivial  
behavior differences, since it would be necessary to name and explain  
them instead of just putting them behind a catchall ifdef. I believe  
every porter has been an offender on this front, Apple included, and  
it's probably best to minimize this sort of thing.


This is not a new policy yet. Right now I am just proposing it for  
discussion. Thoughts?


Regards,
Maciej