/*
 * This file documents the process of porting JACK to new platforms.
 * It is part of the JACK reference manual, built using doxygen.
 */

/**

@page porting-guide Porting JACK

The @ref index is designed to be portable to any system supporting the
relevant POSIX and C language standards.  It currently works with
GNU/Linux and Mac OS X on several different processor architectures.
This document describes the steps needed to port JACK to another
platform, and the methods used to provide portability.

  - @ref portrequirements
  - @ref portoverview
  - @ref portopsys
  - @ref portcpu
  - @ref portissues

@section portrequirements Requirements

  - Each platform should build directly from CVS or from a tarball
  using the GNU @c ./configure tools.  Platform-specific toolsets can
  by used for development, but the GNU tools should at least work for
  basic distribution and configuration.

  - For long-term maintainability we want to minimize the use of
  conditional compilation in source files.

  - We should provide generic versions of all system-dependent
  headers, so platforms need only provide those they modify.

  - In some cases, operating system-specific information must be able
  to override processor-specific data.

@section portoverview Overview

JACK relies on two types of platform-specific headers:

  - @ref portopsys
  - @ref portcpu

OS-specific headers take precedence over CPU-specific headers.

The JACK @c configure.host script and its system-dependent header
directories were adapted from the @c libstdc++-v3 component of the GNU
Compiler Collective, <http://gcc.gnu.org>.


@section portlang C Language Dependencies

JACK is written to conform with C99, as defined in International
Standard ISO/IEC 9899:1999.  Because many existing compilers do not
fully support this standard, some new features should be avoided for
portablility reasons.  For example, variables should not be declared
in the middle of a compound statement, because many compilers still
cannot handle that language extension.


@section portopsys Operating System Dependencies

JACK is written for a POSIX environment compliant with IEEE Std
1003.1-2001, ISO/IEC 9945:2003, including the POSIX Threads Extension
(1003.1c-1995) and the Realtime and Realtime Threads feature groups.
When some needed POSIX feature is missing on a platform, the preferred
solution is to provide a substitute, as with the @c fakepoll.c
implementation for Mac OS X.

Whenever possible, OS dependencies should be auto-detected by @c
configure.  Sometimes they can be isolated in OS-specific header
files, found in subdirectories of @c config/os and referenced with a
@c <sysdeps/xxx.h> name.

If conditional compilation must be used in mainline
platform-independent code, avoid using the system name.  Instead, @c
\#define a descriptive name in @c <config.h>, and test it like this:

@code
  \#ifdef JACK_USE_MACH_THREADS
          allocate_mach_serverport(engine, client);
          client->running = FALSE;
  \#endif
@endcode

Be sure to place any generic implementation alternative in the @c
\#else or use an @c \#ifndef, so no other code needs to know your
conditional labels.

@section portissues Issues Not Addressed

  - Cross-compilation has not been tested, or even thought through in
  much detail.  The @a host is the system on which JACK will run.
  This may differ from the @a build system doing the compilation.
  These are selected using the standard @c ./configure options @c
  --host and @c --build.  Usually, @c ./config.guess can print the
  appropriate canonical name for any system on which it runs.

  - Platform-specific build tools like Apple's Project Builder are not
  well-supported.

*/