[prev in list] [next in list] [prev in thread] [next in thread]
List: webkit-dev
Subject: Re: [webkit-dev] Proposal for a new way to handle porting #ifdefs
From: David Kilzer <ddkilzer () webkit ! org>
Date: 2009-05-05 14:33:49
Message-ID: 230368.91647.qm () web110801 ! mail ! gq1 ! yahoo ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
> 1b) WINCE actually includes plenty of WIN but in some cases
> does things differently. How to make this distinction without
> lots of && and ||?
There are various design patterns that may be used to alleviate macros, such as \
subclassing and use of delegates. Each case will probably require a specific \
solution, but many of the patterns should be reusable.
> 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.
I think Maciej said that part of this plan is to break up PLATFORM(MAC) into smaller \
pieces. I haven't looked at the Torch Mobile source code, but I suspect the same \
thing may need to be done in this case as well. When porting, it's very easy to lump \
features, library/framework dependencies (I'm thinking of CFNetwork vs. libcurl vs. \
libsoup), and true platform-specific code into a single macro. Part of this effort \
will be to clean that up.
Dave
________________________________
From: George Staikos <staikos@kde.org>
To: WebKit Development <webkit-dev@lists.webkit.org>
Sent: Monday, May 4, 2009 7:45:41 PM
Subject: Re: [webkit-dev] Proposal for a new way to handle porting #ifdefs
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/
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
[Attachment #5 (text/html)]
<html><head><style type="text/css"><!-- DIV {margin:0px;} \
--></style></head><body><div style="font-family:verdana, helvetica, \
sans-serif;font-size:10pt"><div><span class="Apple-style-span" style="font-family: \
'Courier New'; ">> 1b) WINCE actually includes plenty of WIN but in some \
cases</span></div><div><span class="Apple-style-span" style="font-family: 'Courier \
New'; ">> does things differently. How to make this distinction \
without</span></div><div><span class="Apple-style-span" style="font-family: 'Courier \
New'; ">> lots of && and ||?<br></span></div><div><font \
class="Apple-style-span" face="'Courier New'"><br></font></div><div><font \
class="Apple-style-span" face="'Courier New'">There are various design patterns that \
may be used to alleviate macros, such as subclassing and use of delegates. Each \
case will probably require a specific solution, but many of the patterns should be \
reusable.</font></div><div><font class="Apple-style-span" face="'Courier \
New'"><br></font></div><div><font class="Apple-style-span" face="'Courier New'">> \
2) We use PLATFORM(TORCHMOBILE) across multiple OS for things</font></div><div><font \
class="Apple-style-span" face="'Courier New'">> that are not necessarily platform \
specific but specific to our</font></div><div><font class="Apple-style-span" \
face="'Courier New'">> browsers. I guess this is similar to \
PLATFORM(CHROMIUM).</font></div><div><font class="Apple-style-span" face="'Courier \
New'">> Honestly I don't like filling the code with these but we \
all</font></div><div><font class="Apple-style-span" face="'Courier New'">> do it, \
including MAC. MAC tends to win the default right now.</font></div><div><font \
class="Apple-style-span" face="'Courier New'">> I'm not sure how best to handle \
this yet but I foresee a big</font></div><div><font class="Apple-style-span" \
face="'Courier New'">> mess if we aren't careful.<br></font></div><div><font \
class="Apple-style-span" face="'Courier New'"><br></font></div><div><font \
class="Apple-style-span" face="'Courier New'">I think Maciej said that part of this \
plan is to break up PLATFORM(MAC) into smaller pieces. I haven't looked at the \
Torch Mobile source code, but I suspect the same thing may need to be done in this \
case as well. When porting, it's very easy to lump features, library/framework \
dependencies (I'm thinking of CFNetwork vs. libcurl vs. libsoup), and true \
platform-specific code into a single macro. Part of this effort will be to \
clean that up.</font></div><div><font class="Apple-style-span" face="'Courier \
New'"><br></font></div><div><font class="Apple-style-span" face="'Courier \
New'">Dave</font></div><div><font class="Apple-style-span" face="'Courier \
New'"><br></font></div><div style="font-family:verdana, helvetica, \
sans-serif;font-size:10pt"><br><div style="font-family:Courier New, monaco, \
monospace, sans-serif;font-size:10pt"><font size="2" face="Tahoma"><hr \
size="1"><b><span style="font-weight: bold;">From:</span></b> George Staikos \
<staikos@kde.org><br><b><span style="font-weight: bold;">To:</span></b> WebKit \
Development <webkit-dev@lists.webkit.org><br><b><span style="font-weight: \
bold;">Sent:</span></b> Monday, May 4, 2009 7:45:41 PM<br><b><span \
style="font-weight: bold;">Subject:</span></b> Re: [webkit-dev] Proposal for a new \
way to handle porting #ifdefs<br></font><br> <br>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. :-)<br><br>Some comments I \
have:<br><br>1) In some cases some things apply to more than one OS so we \
have:<br>#if OS(x) || OS(y) || OS(z) ...<br>I think we should use:<br>#if \
OS(x,y,z)<br><br>1b) WINCE actually includes plenty of WIN but in some cases does \
things differently. How to make this distinction without lots of && and \
||?<br><br>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.<br><br>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).<br><br>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!<br><br><br>On 30-Apr-09, \
at 7:12 PM, Maciej Stachowiak wrote:<br><br>> <br>> I think our set of porting \
macros has become somewhat confused.<br>> <br>> 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.<br>> <br>> 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.<br>> <br>> 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.<br>> <br>> 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).<br>> <br>> <br>> \
Therefore, I propose that we change as follows:<br>> <br>> 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).<br>> \
<br>> 2) Phase out PLATFORM macros completely - each use should be converted to a \
policy choice, or a platform adaptation decision.<br>> <br>> 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.<br>> <br>> 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.<br>> <br>> <br>> Platform adaptation macros would be:<br>> \
<br>> OS() - underlying operating system; only to be used for mandated low-level \
services like virtual memory, not to choose a GUI toolkit<br>> \
Examples:<br>> OS(UNIX) - Any Unix-like \
OS<br>> OS(DARWIN) - Underlying OS is the base OS X \
environment<br>> OS(FREEBSD) - FreeBSD<br>> \
OS(WIN) - Any version of Windows<br>> \
OS(WINCE) - The embedded version of Windows<br>> <br>> COMPILER() - the \
compiler being used to build the project<br>> \
Examples:<br>> COMPILER(GCC) - GNU Compiler \
Collection<br>> COMPILER(MSVC) - Microsoft Visual \
C++<br>> COMPILER(RVCT) - ARM compiler<br>> \
<br>> HAVE() - specific system features (headers, functions or similar) that are \
present or not<br>> Examples:<br>> \
HAVE(MMAP) - mmap() function is available<br>> \
HAVE(ERRNO_H) - errno.h header is available<br>> \
HAVE(MADV_FREE) - madvise(MADV_FREE) is available<br>> <br>> <br>> Policy \
decision macros would be:<br>> <br>> USE() - use a particular third-party \
library or optional OS service<br>> Examples:<br>> \
USE(SKIA) - Use the Skia graphics library<br>> \
USE(CG) - Use CoreGraphics<br>> USE(V8) - Use \
the V8 JavaScript implementation<br>> USE(CFNET) - Use \
CFNetwork networking<br>> USE(NSURL_NET) - Use \
NSURLConnection-based networking<br>> USE(APPKIT) - \
Use AppKit views and events<br>> USE(GTK) - Use \
Gtk+<br>> USE(QT) - Use Qt<br>> \
USE(QUICKTIME) - Use the QuickTime media engine<br>> \
USE(QTKIT) - Use the QuickTime media engine via the Mac QTKit \
API<br>> USE(QUICKTIME_WIN) - Use the QuickTime media \
engine via its Windows API<br>> <br>> ENABLE() - turn on a specific feature of \
WebKit<br>> Examples:<br>> \
ENABLE(ACCESSIBILITY) - Enable support for assistive technologies (currently wrongly \
a HAVE)<br>> ENABLE(XSLT) - Include XSLT \
support<br>> ENABLE(OBJC_MAC_API) - Include Objective C \
API based on NSViews (current WebKit Mac)<br>> \
ENABLE(OBJC_DOM_API) - Include Objective C DOM bindings (may apply to other ObjC \
toolkits than AppKit)<br>> 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)<br>> ENABLE(VIDEO) - Enable support for the \
HTML5 Video element<br>> ENABLE(SVG) - Enable support \
for SVG (Scalable Vector Graphics)<br>> ENABLE(WML) - \
Enable support for WML<br>> <br>> <br>> <br>> Some macros that would be \
completely phased out, in favor of platform and policy decisions:<br>> <br>> \
PLATFORM(MAC) - A mix of things that should be USE(APPKIT), USE(NSURL_NET), \
ENABLE(OBJC_MAC_API) and a host of other things<br>> PLATFORM(WIN) - Hodgepodge of \
mandatory platform adaptation, optional platform adaptation, and choices specific to \
Apple's Mac Port<br>> PLATFORM(GTK) - Most of this would be replaced by USE(GTK) \
but perhaps different policy macros are appropriate in some cases.<br>> \
PLATFORM(CHROMIUM) - Grab-bag of various policy choices.<br>> <br>> <br>> 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.<br>> <br>> <br>> This is not a new policy yet. Right now I am \
just proposing it for discussion. Thoughts?<br><br>--<br>George Staikos<br>Torch \
Mobile Inc.<br><span><a target="_blank" \
href="http://www.torchmobile.com/">http://www.torchmobile.com/</a></span><br><br>_______________________________________________<br>webkit-dev \
mailing list<br><a ymailto="mailto:webkit-dev@lists.webkit.org" \
href="mailto:webkit-dev@lists.webkit.org">webkit-dev@lists.webkit.org</a><br><span><a \
target="_blank" href="http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev">http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev</a></span><br></div></div><div \
style="position:fixed"></div></div></body></html>
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic