doc/porting.dox

   1 /*
   2  * This file documents the process of porting JACK to new platforms.
   3  * It is part of the JACK reference manual, built using doxygen.
   4  */
   5
   6 /**
   7
   8 @page porting-guide Porting JACK
   9
  10 The @ref index is designed to be portable to any system supporting the
  11 relevant POSIX and C language standards.  It currently works with
  12 GNU/Linux and Mac OS X on several different processor architectures.
  13 This document describes the steps needed to port JACK to another
  14 platform, and the methods used to provide portability.
  15
  16   - @ref portrequirements
  17   - @ref portoverview
  18   - @ref portopsys
  19   - @ref portcpu
  20   - @ref portissues
  21
  22 @section portrequirements Requirements
  23
  24   - Each platform should build directly from CVS or from a tarball
  25   using the GNU @c ./configure tools.  Platform-specific toolsets can
  26   by used for development, but the GNU tools should at least work for
  27   basic distribution and configuration.
  28
  29   - For long-term maintainability we want to minimize the use of
  30   conditional compilation in source files.
  31
  32   - We should provide generic versions of all system-dependent
  33   headers, so platforms need only provide those they modify.
  34
  35   - In some cases, operating system-specific information must be able
  36   to override processor-specific data.
  37
  38 @section portoverview Overview
  39
  40 JACK relies on two types of platform-specific headers:
  41
  42   - @ref portopsys
  43   - @ref portcpu
  44
  45 OS-specific headers take precedence over CPU-specific headers.
  46
  47 The JACK @c configure.host script and its system-dependent header
  48 directories were adapted from the @c libstdc++-v3 component of the GNU
  49 Compiler Collective, <http://gcc.gnu.org>.
  50
  51
  52 @section portlang C Language Dependencies
  53
  54 JACK is written to conform with C99, as defined in International
  55 Standard ISO/IEC 9899:1999.  Because many existing compilers do not
  56 fully support this standard, some new features should be avoided for
  57 portablility reasons.  For example, variables should not be declared
  58 in the middle of a compound statement, because many compilers still
  59 cannot handle that language extension.
  60
  61
  62 @section portopsys Operating System Dependencies
  63
  64 JACK is written for a POSIX environment compliant with IEEE Std
  65 1003.1-2001, ISO/IEC 9945:2003, including the POSIX Threads Extension
  66 (1003.1c-1995) and the Realtime and Realtime Threads feature groups.
  67 When some needed POSIX feature is missing on a platform, the preferred
  68 solution is to provide a substitute, as with the @c fakepoll.c
  69 implementation for Mac OS X.
  70
  71 Whenever possible, OS dependencies should be auto-detected by @c
  72 configure.  Sometimes they can be isolated in OS-specific header
  73 files, found in subdirectories of @c config/os and referenced with a
  74 @c <sysdeps/xxx.h> name.
  75
  76 If conditional compilation must be used in mainline
  77 platform-independent code, avoid using the system name.  Instead, @c
  78 \#define a descriptive name in @c <config.h>, and test it like this:
  79
  80 @code
  81   \#ifdef JACK_USE_MACH_THREADS
  82           allocate_mach_serverport(engine, client);
  83           client->running = FALSE;
  84   \#endif
  85 @endcode
  86
  87 Be sure to place any generic implementation alternative in the @c
  88 \#else or use an @c \#ifndef, so no other code needs to know your
  89 conditional labels.
  90
  91 @section portcpu Processor Dependencies
  92
  93 JACK uses some low-level machine operations for thread-safe updates to
  94 shared memory.  A low-level implementation of @c <sysdeps/atomicity.h>
  95 is provided for every target processor architecture.  There is also a
  96 generic implementation using POSIX spin locks, but that is not a good
  97 enough solution for serious use.
  98
  99 The GCC package provides versions that work on most modern hardware.
 100 We've tried to keep things as close to the original as possible, while
 101 removing a bunch of os-specific files that didn't seem relevant.  A
 102 primary goal has been to avoid changing the CPU-dependent @c
 103 <sysdeps/atomicity.h> headers.
 104
 105 The relevant GCC documentation provides some helpful background,
 106 especially the @c atomicity.h discussion at
 107 <http://gcc.gnu.org/onlinedocs/porting/Thread-safety.html>.
 108
 109
 110 @section portissues Issues Not Addressed
 111
 112   - Cross-compilation has not been tested, or even thought through in
 113   much detail.  The @a host is the system on which JACK will run.
 114   This may differ from the @a build system doing the compilation.
 115   These are selected using the standard @c ./configure options @c
 116   --host and @c --build.  Usually, @c ./config.guess can print the
 117   appropriate canonical name for any system on which it runs.
 118
 119   - Platform-specific build tools like Apple's Project Builder are not
 120   well-supported.
 121
 122 */