1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
/*
* 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.
*/
|
