Porting JACK

The JACK Audio Connection Kit 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.

Requirements

Each platform should build directly from CVS or from a tarball using the GNU ./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.

Overview

JACK relies on two types of platform-specific headers:

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

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

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.

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 fakepoll.c implementation for Mac OS X.

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

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

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

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

Processor Dependencies

JACK uses some low-level machine operations for thread-safe updates to shared memory. A low-level implementation of <sysdeps/atomicity.h> is provided for every target processor architecture. There is also a generic implementation using POSIX spin locks, but that is not a good enough solution for serious use.

The GCC package provides versions that work on most modern hardware. We've tried to keep things as close to the original as possible, while removing a bunch of os-specific files that didn't seem relevant. A primary goal has been to avoid changing the CPU-dependent <sysdeps/atomicity.h> headers.

The relevant GCC documentation provides some helpful background, especially the atomicity.h discussion at <http://gcc.gnu.org/onlinedocs/porting/Thread-safety.html>.

Issues Not Addressed

Cross-compilation has not been tested, or even thought through in much detail. The host is the system on which JACK will run. This may differ from the build system doing the compilation. These are selected using the standard ./configure options --host and --build. Usually, ./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.