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

Mon May 4 19:45:41 PDT 2009

I really like this and it goes in the direction that I was hoping for  
as well.  Hopefully we can get the WINCE port merged upstream before  
we make this change. :-)

Some comments I have:

1) In some cases some things apply to more than one OS so we have:
#if OS(x) || OS(y) || OS(z) ...
I think we should use:
#if OS(x,y,z)

1b) WINCE actually includes plenty of WIN but in some cases does  
things differently.  How to make this distinction without lots of &&  
and ||?

2) We use PLATFORM(TORCHMOBILE) across multiple OS for things that  
are not necessarily platform specific but specific to our browsers.   
I guess this is similar to PLATFORM(CHROMIUM).  Honestly I don't like  
filling the code with these but we all do it, including MAC.  MAC  
tends to win the default right now.  I'm not sure how best to handle  
this yet but I foresee a big mess if we aren't careful.

3) I'm not sure that USE() really applies equally as you described.   
In some cases it applies to basically the whole system API used (QT),  
but in others it's just a support library (QUICKTIME).

Again, fully support these changes and perhaps some more too.  Just  
give us a bit of time to find the right way to merge the WINCE stuff  
in first please!

On 30-Apr-09, at 7: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?

--
George Staikos
Torch Mobile Inc.
http://www.torchmobile.com/