xeno-config.1 9.35 KB
Newer Older
Philippe Gerum's avatar
Philippe Gerum committed
1 2 3
'\" t
.\"     Title: xeno-config
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
Philippe Gerum's avatar
Philippe Gerum committed
4
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
Philippe Gerum's avatar
Philippe Gerum committed
5
.\"      Date: 2014/08/03
Philippe Gerum's avatar
Philippe Gerum committed
6
.\"    Manual: Xenomai Manual
Philippe Gerum's avatar
Philippe Gerum committed
7
.\"    Source: Xenomai 3.0.4
Philippe Gerum's avatar
Philippe Gerum committed
8 9
.\"  Language: English
.\"
Philippe Gerum's avatar
Philippe Gerum committed
10
.TH "XENO\-CONFIG" "1" "2014/08/03" "Xenomai 3\&.0\&.4" "Xenomai Manual"
Philippe Gerum's avatar
Philippe Gerum committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
Philippe Gerum's avatar
Philippe Gerum committed
31
xeno-config \- Retrieve Xenomai build flags and configuration
Philippe Gerum's avatar
Philippe Gerum committed
32 33 34 35 36
.SH "SYNOPSIS"
.sp
\fBxeno\-config\fR
.sp
\fBxeno\-config\fR \fB\-\-v\fR | \fB\-\-verbose\fR
Philippe Gerum's avatar
Philippe Gerum committed
37 38 39 40 41 42 43 44 45
.sp
\fBxeno\-config\fR \fB\-\-help\fR
.sp
\fBxeno\-config\fR \fB\-\-info\fR
.sp
\fBxeno\-config\fR \fB\-\-core\fR
.sp
\fBxeno\-config\fR \fB\-\-version\fR
.sp
Philippe Gerum's avatar
Philippe Gerum committed
46
\fBxeno\-config\fR [\fB\-\-cc\fR] [\fB\-\-ccld\fR] [\fB\-\-arch\fR] [\fB\-\-prefix\fR] [\fB\-\-posix|alchemy|rtdm|psos|vxworks|smokey\fR] [\fB\-\-compat\fR] [\fB\-\-auto\-init\fR|\fBno\-auto\-init\fR] [\fB\-\-auto\-init\-solib\fR] [\fB\-\-mode\-check\fR|\fBno\-mode\-check\fR] [\fB\-\-cflags\fR] [\fB\-\-ldflags\fR] [\fB\-\-library\-dir\fR|\fBlibdir\fR|\fBuser\-libdir\fR]
Philippe Gerum's avatar
Philippe Gerum committed
47 48
.SH "DESCRIPTION"
.sp
Philippe Gerum's avatar
Philippe Gerum committed
49
\fBxeno\-config\fR is a shell script which is aimed at retrieving the Xenomai build configuration data, such as the compiler and linker flags required for building applications\&. For this reason, \fBxeno\-config\fR is typically used in Makefiles\&.
Philippe Gerum's avatar
Philippe Gerum committed
50
.sp
Philippe Gerum's avatar
Philippe Gerum committed
51
\fBxeno\-config \-\-verbose\fR dumps the build configuration data in a human\-readable format\&.
Philippe Gerum's avatar
Philippe Gerum committed
52
.sp
Philippe Gerum's avatar
Philippe Gerum committed
53
Invoking \fBxeno\-config\fR without any options is equivalent to running \fBxeno\-config \-\-verbose \-\-help\fR\&.
Philippe Gerum's avatar
Philippe Gerum committed
54 55 56 57
.SH "OPTIONS"
.PP
\fB\-\-v, \-\-verbose\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
58
Output all configuration information in a human\-readable format\&.
Philippe Gerum's avatar
Philippe Gerum committed
59 60 61 62
.RE
.PP
\fB\-\-help\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
63
Output the list of available command\-line options\&. The command exits immediately after completion\&.
Philippe Gerum's avatar
Philippe Gerum committed
64 65 66 67
.RE
.PP
\fB\-\-version\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
68
Output the Xenomai version\&.
Philippe Gerum's avatar
Philippe Gerum committed
69 70 71 72
.RE
.PP
\fB\-\-cc\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
73 74 75 76 77 78
Output the path to the C compiler command used to build the Xenomai libraries and utilities, which is therefore suitable for compiling a Xenomai application\&.
.RE
.PP
\fB\-\-ccld\fR
.RS 4
Output a C compiler command suitable for linking a Xenomai application\&.
Philippe Gerum's avatar
Philippe Gerum committed
79 80 81 82
.RE
.PP
\fB\-\-arch\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
83
Output the target CPU architecture Xenomai was compiled for, e\&.g\&. arm, x86, powerpc etc\&. This may differ from the CPU architecture of the current system, if cross\-compiling\&.
Philippe Gerum's avatar
Philippe Gerum committed
84 85 86 87
.RE
.PP
\fB\-\-prefix\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
88
Output the absolute path to the Xenomai installation directory\&.
Philippe Gerum's avatar
Philippe Gerum committed
89 90
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
91
\fB\-\-[skin=]{posix, alchemy, rtdm, psos, vxworks, smokey, cobalt}\fR
Philippe Gerum's avatar
Philippe Gerum committed
92
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
Select the API/skin for which
\fBxeno\-config\fR
should print the information required\&. The
\fBskin=\fR
prefix is optional and may be omitted, e\&.g\&.
\fB\-\-posix\fR
is equivalent to
\fB\-\-skin=posix\fR, selecting the POSIX API\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
Philippe Gerum's avatar
Philippe Gerum committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
\fB\-\-native\fR and \fB\-\-skin=native\fR are accepted for backward compatibility purpose\&. They are stricly equivalent as passing \fB\-\-alchemy \-\-compat\fR\&. Likewise, passing \fB\-\-rtdm\fR or \fB\-\-skin=rtdm\fR is stricly equivalent as passing \fB\-\-posix\fR, enabling POSIX I/O routines to be wrapped to their respective Xenomai implementation\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCaution\fR
.ps -1
.br
.sp
Over Cobalt, only \fBxeno\-config \-\-posix \-\-ldflags\fR (or \fB\-\-rtdm\fR as an alias) returns the proper linker flags to cause POSIX routines invoked by the application to be wrapped to their respective Xenomai implementation\&. No other API will imply such wrapping\&. For this reason, \fB\-\-cobalt \-\-ldflags\fR should be used for linking exclusively against the Cobalt library (i\&.e\&. libcobalt\&.so) \fBwithout\fR symbol wrapping\&. Conversely, mentioning \fB\-\-posix\fR along with other API switches with \fB\-\-ldflags\fR will cause POSIX symbol wrapping to take place, e\&.g\&. use \fB\-\-posix \-\-alchemy \-\-ldflags\fR for mixed API support with POSIX symbol wrapping\&.
Philippe Gerum's avatar
Philippe Gerum committed
132
.sp .5v
Philippe Gerum's avatar
Philippe Gerum committed
133 134 135 136
.RE
.PP
\fB\-\-cflags\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
137 138 139
Output the C compiler command\-line options (\fICFLAGS\fR) which are required to compile applications based on the selected Xenomai API/skin\&.
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
140 141
\fB\-\-ldflags\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
142
Output the C compiler command\-line options (\fILDFLAGS\fR) which are required to link applications based on the selected Xenomai API/skin\&.
Philippe Gerum's avatar
Philippe Gerum committed
143 144
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
145
\fB\-\-library\-dir, \-\-libdir, \-\-user\-libdir\fR
Philippe Gerum's avatar
Philippe Gerum committed
146
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
147
These switches are synonyms, for retrieving the absolute path to the Xenomai libraries\&.
Philippe Gerum's avatar
Philippe Gerum committed
148 149
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
150
\fB\-\-auto\-init\fR, \fB\-\-no\-auto\-init\fR
Philippe Gerum's avatar
Philippe Gerum committed
151
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
152 153 154 155 156 157 158 159 160
All Xenomai APIs but POSIX are based on the Copperplate library, which automatically initializes when the application process starts\&.
\fB\-\-no\-auto\-init\fR
can be passed to disable such initialization\&. In such a case, the application code shall call the
copperplate_init()
routine manually, as part of its initialization chores on behalf on the
main()
routine,
\fBbefore\fR
any real\-time service is invoked\&.
Philippe Gerum's avatar
Philippe Gerum committed
161
.RE
Philippe Gerum's avatar
Philippe Gerum committed
162
.sp
Philippe Gerum's avatar
Philippe Gerum committed
163 164
This flag makes sense when passed along with \-\-ldflags only\&. \fBxeno\-config\fR enables the Copperplate auto\-init feature by default\&.
.PP
Philippe Gerum's avatar
Philippe Gerum committed
165 166 167 168 169 170 171 172 173 174 175
\fB\-\-mode\-check\fR, \fB\-\-no\-mode\-check\fR
.RS 4
Over Cobalt, a set of standard routines which may invoke regular Linux system calls can trigger an assertion failure on entry, if the caller must leave the real\-time mode (aka "secondary mode switch") to execute such routine\&.
.RE
.sp
The assertion failure is triggered if the calling thread has set the PTHREAD_WARNSW flag by a call to pthread_setmode_np()\&.
.sp
By default, the mode checking routines are substituted to the original ones using the symbol wrapping mechanism also used for interposing on POSIX services\&. \fB\-\-no\-mode\-check\fR disables such substitution\&.
.sp
These flags make sense when passed along with \-\-ldflags only\&.
.PP
Philippe Gerum's avatar
Philippe Gerum committed
176 177 178 179 180 181
\fB\-\-auto\-init\-solib\fR
.RS 4
This switch enables the auto\-initialization feature described above for a shared library target instead of a pure executable\&. The main difference resides in a position\-independent (PIC) glue code being used for bootstrapping the initialization\&.
.RE
.sp
The bootstrap code runs when the shared library is attached to a running executable, either because it appears in the static dependencies of this executable, or when loaded dynamically via the dlopen() interface\&.
Philippe Gerum's avatar
Philippe Gerum committed
182
.PP
Philippe Gerum's avatar
Philippe Gerum committed
183
\fB\-\-core\fR
Philippe Gerum's avatar
Philippe Gerum committed
184
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
185 186 187 188 189 190
Output the name of the real\-time core the current Xenomai installation was built for\&. The possible values are
\fIcobalt\fR
or
\fImercury\fR, depending on the configuration switch
\fB\-\-with\-core\fR
used for building the Xenomai libraries and utilities\&.
Philippe Gerum's avatar
Philippe Gerum committed
191 192
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
193
\fB\-\-compat\fR
Philippe Gerum's avatar
Philippe Gerum committed
194
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
195 196 197
Enable the Xenomai 2\&.x compatibility mode for the API/skin selected\&. This switch affects the
\fIAlchemy\fR
and POSIX APIs, turning on a set of source\-level compatibility wrappers when present\&.
Philippe Gerum's avatar
Philippe Gerum committed
198 199
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
200
\fB\-\-info\fR
Philippe Gerum's avatar
Philippe Gerum committed
201
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
202 203 204 205
Dump information about the running Xenomai\-enabled system\&. Unlike most other options,
\fB\-\-info\fR
is aimed at being used on the target system running Xenomai, for retrieving the current setup information\&. The output of such command is a valuable information when reporting any runtime issue to
the Xenomai mailing list\&. The command exits immediately after completion\&.
Philippe Gerum's avatar
Philippe Gerum committed
206 207 208 209 210
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
\fBDESTDIR\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
211
Xenomai\(cqs handling of
Philippe Gerum's avatar
Philippe Gerum committed
212
\fBDESTDIR\fR
Philippe Gerum's avatar
Philippe Gerum committed
213
is conformant to the GNU coding and installation standards, for generating pathnames rooted at some staging area on the build system\&. Such staging area is commonly NFS\-mounted from the target system running Xenomai\&.
Philippe Gerum's avatar
Philippe Gerum committed
214 215
.RE
.sp
Philippe Gerum's avatar
Philippe Gerum committed
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
If the \fBDESTDIR\fR variable is set in the environment of \fBxeno\-config\fR, its contents is prepended to all directory and file names based on the Xenomai installation root which may be output by the command\&.
.sp
If \fBDESTDIR\fR was set when installing Xenomai \- typically after cross\-compiling \- \fBDESTDIR\fR must be set to the same value before calling \fBxeno\-config\fR for accessing the target\-based directories and files from the build system\&.
.sp
e\&.g\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ configure \-\-prefix=/usr \-\-includedir=/usr/include/xenomai
$ make install DESTDIR=/nfsroot/target
$ DESTDIR=/nfsroot/target /nfsroot/target/bin/xeno\-config \-\-alchemy \-\-cflags
\-I/nfsroot/target/usr/include/xenomai/cobalt
\-I/nfsroot/target/usr/include/xenomai \-D_GNU_SOURCE
\-D_REENTRANT \-D__COBALT__
\-I/nfsroot/target/usr/include/xenomai/alchemy
.fi
.if n \{\
.RE
.\}
.SH "EXIT STATUS"
Philippe Gerum's avatar
Philippe Gerum committed
238 239 240
.PP
\fB0\fR
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
241
Success\&.
Philippe Gerum's avatar
Philippe Gerum committed
242 243
.RE
.PP
Philippe Gerum's avatar
Philippe Gerum committed
244
\fBnon\-zero\fR
Philippe Gerum's avatar
Philippe Gerum committed
245
.RS 4
Philippe Gerum's avatar
Philippe Gerum committed
246
Error\&.
Philippe Gerum's avatar
Philippe Gerum committed
247
.RE