[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-23 16:38:22
Message-ID: 890924.29003.qm () web110810 ! mail ! gq1 ! yahoo ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
Another aspect of this proposal is how to handle source files that have #if \
ENABLE(FEATURE)/#endif guards around all of their source code, for example:
Bug 25756: Explicit guards for ENABLE_GEOLOCATION
https://bugs.webkit.org/show_bug.cgi?id=25756
There are essentially two options here:
1. Add #if/#endif guards to entire source files, but include every file in every \
build system.
2. Make each build system smart enough to exclude source files that implement a \
feature, thus pushing the policy decision down (up?) into the build system (which is \
where most of the decisions are made today anyway).
I think #2 is a much cleaner way to handle this since it removes clutter from the \
code (at the cost of duplicating knowledge of which files go with with features into \
each build system).
Does anyone else have an opinion on this?
Dave
________________________________
From: Maciej Stachowiak <mjs@apple.com>
To: WebKit Development <webkit-dev@lists.webkit.org>
Sent: Thursday, April 30, 2009 4:12:54 PM
Subject: [webkit-dev] Proposal for a new way to handle porting #ifdefs
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@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>Another aspect of this proposal is how to handle \
source files that have #if ENABLE(FEATURE)/#endif guards around all of their source \
code, for example:</div><div><br></div><div>Bug 25756: Explicit guards for \
ENABLE_GEOLOCATION</div><div><span><a target="_blank" \
href="https://bugs.webkit.org/show_bug.cgi?id=25756">https://bugs.webkit.org/show_bug.cgi?id=25756</a></span></div><div><br></div><div>There \
are essentially two options here:</div><div><br></div><div>1. Add #if/#endif guards \
to entire source files, but include every file in every build \
system.</div><div><br></div><div>2. Make each build system smart enough to exclude \
source files that implement a feature, thus pushing the policy decision down \
(up?) into the build system (which is where most of the decisions are made today \
anyway).</div><div><br></div><div>I think #2 is a much cleaner way to handle this \
since it removes clutter from the code (at the cost of duplicating knowledge of which \
files go with with features into each build system).</div><div><br></div><div>Does \
anyone else have an opinion on \
this?</div><div><br></div><div>Dave</div><div><br></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> Maciej Stachowiak <mjs@apple.com><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> Thursday, April 30, 2009 4:12:54 PM<br><b><span \
style="font-weight: bold;">Subject:</span></b> [webkit-dev] Proposal for a new way to \
handle porting #ifdefs<br></font><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>Regards,<br>Maciej<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