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

Tue May 5 08:19:33 PDT 2009

On May 4, 2009, at 5:21 AM, Mario Bensi wrote:

> We pursued the same goal for a couple of years. Since our porting
> targets are various middleware & CE platforms, we had to identify and
> adapt WebKit needs at a better grained level than platform.
> In order to do this we collected all dependencies in a Browser
> Abstraction Layer (BAL directory). The configuration is handled by a
> Base directory (definition of types, platform specifications) and we
> use CMake to define platform specificities (and it's a great cross-
> platform tool).
>
> Sure the BAL model has still improvements ahead of it, but it has the
> merit of existing, being widely tester on a quite wide range of
> targets, configurations and libraries.

My understanding is that BAL injects a platform abstration layer under  
the platform abstraction layer that is the "WebCore/platform"  
directory. Also, I gather that BAL tries to do more things via runtime  
indirection and subclasses with virtual methods instead of WebCore's  
compile-time approach. To me, those aspects sound like they may not be  
good fits for our goals. But I would be glad to hear more details  
about BAL, and how it would compare to my proposal.

Regards,
Maciej

>
> Regards
> Mario
>
> Le Friday 01 May 2009 01:12:54 Maciej Stachowiak, vous avez écrit :
>> 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
>
>