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

[Gavin Barraclough]

Maciej,

This sounds good, and sounds like it could clean things up a lot.

In the breakdown below you don't explicitly mention what would happen  
to h/w specific macros like PLATFORM_X86, though you do mention 'CPU'  
in your email, OOI are you thinking something like?:

CPU()
     Examples:
         CPU(X86)
         CPU(X86_64)

cheers,
G.


On Apr 30, 2009, at 4:12 PM, Maciej Stachowiak wrote:

>
> 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
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev