wiki:Porting Macros plan
Last modified 2 years ago Last modified on 04/21/12 18:26:26

Porting Macros Plan

Original Proposal

  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).
  1. Phase out PLATFORM macros completely - each use should be converted to a policy choice, or a platform adaptation decision.
  1. 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.
  1. 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:

  • COMPILER() - the compiler being used to build the project
  • CPU() - the target CPU architecture
  • OS() - underlying operating system; only to be used for mandated low-level services like virtual memory, not to choose a GUI toolkit
    • OS(UNIX) - Any Unix-like OS
    • OS(DARWIN) - Underlying OS is the base OS X environment
    • OS(FREEBSD) - FreeBSD
    • OS(WINDOWS) - Any version of Windows
    • OS(WINCE) - The embedded version of Windows
  • HAVE() - specific system features (headers, functions or similar) that are present or not
    • 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
    • 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
    • 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)

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.

Actual macros

  • COMPILER() - the compiler being used to build the project
    • COMPILER(GCC) - GNU Compiler Collection
    • COMPILER(MSVC) - Microsoft Visual C++
    • COMPILER(MSVC7) - Microsoft Visual C++ 7 (also defined the above)
    • COMPILER(RVCT) - ARM compiler
    • COMPILER(MINGW) - MinGW GCC
    • COMPILER(WINSCW) - CodeWarrior for Symbian emulator
  • CPU() - the target CPU architecture
    • CPU(ALPHA) - DEC Alpha
    • CPU(IA64) - Itanium / IA-64
    • CPU(PPC) - PowerPC 32-bit
    • CPU(PPC64) - PowerPC 64-bit
    • CPU(SH4) - SuperH SH-4
    • CPU(SPARC) - any SPARC, true for CPU(SPARC32) and CPU(SPARC64)
    • CPU(SPARC32) - SPARC 32-bit
    • CPU(SPARC64) - SPARC 64-bit
    • CPU(X86) - i386 / x86 32-bit
    • CPU(X86_64) - AMD64 / Intel64 / x86_64 64-bit
    • CPU(ARM) - ARM, any version
    • CPU(ARMV5_OR_LOWER) - ARM instruction set v5 or earlier (cutoff point for some interesting ARM features)
    • CPU(ARM_TRADITIONAL) - Thumb2 is not available, only traditional ARM (v4 or greater)
    • CPU(ARM_THUMB2) - Thumb2 instruction set is available
    • CPU(BIG_ENDIAN) - big-endian architecture (if neither this or the next one is set, assume little-endian)
    • CPU(MIDDLE_ENDIAN) - middle-endian architecture
  • HAVE()
    • HAVE(ACCESSIBILITY)
    • HAVE(COMPUTED_GOTO)
    • HAVE(ERRNO_H)
    • HAVE(LANGINFO_H)
    • HAVE(MADV_FREE)
    • HAVE(MADV_FREE_REUSE)
    • HAVE(MADV_DONTNEED)
    • HAVE(MERGESORT)
    • HAVE(MMAP)
    • HAVE(POSIX_MEMALIGN)
    • HAVE(PTHREAD_RWLOCK)
    • HAVE(PTHREAD_SETNAME_NP)
    • HAVE(READLINE)
    • HAVE(RUNLOOP_TIMER)
    • HAVE(SBRK)
    • HAVE(SIGNAL_H)
    • HAVE(STRINGS_H)
    • HAVE(SYS_PARAM_H)
    • HAVE(SYS_TIME_H)
    • HAVE(SYS_TIMEB_H)
    • HAVE(VIRTUALALLOC)
  • USE()
    • USE(ACCELERATED_COMPOSITING)
    • USE(ATSUI)
    • USE(CFNETWORK)
    • USE(CORE_TEXT)
    • USE(CURL)
    • USE(FONT_FAST_PATH)
    • USE(GLIB_ICU_UNICODE_HYBRID)
    • USE(GLIB_UNICODE)
    • USE(GOOGLEURL)
    • USE(ICU_UNICODE)
    • USE(INTERPRETER)
    • USE(JAVASCRIPTCORE_BINDINGS)
    • USE(JIT_STUB_ARGUMENT_VA_LIST)
    • USE(JSC)
    • USE(JSVALUE32_64)
    • USE(JSVALUE64)
    • USE(LOCKFREE_THREADSAFESHARED)
    • USE(PLUGIN_HOST_PROCESS)
    • USE(PTHREADS)
    • USE(QT4_UNICODE)
    • USE(QUERY_PERFORMANCE_COUNTER)
    • USE(QXMLQUERY)
    • USE(QXMLSTREAM)
    • USE(SAFARI_THEME)
    • USE(SOUP)
    • USE(V8)
    • USE(WINCE_UNICODE)
    • USE(WININET)
    • USE(WXGC)

See also this thread on webkit-dev, which discusses this idea: http://lists.macosforge.org/pipermail/webkit-dev/2009-April/007494.html