// ** The above line should force tbl to be a preprocessor **
// Man page for xeno-config
//
// Copyright (C) 2005, 2006 Romain Lenglet <rlenglet@users.forge.objectweb.org>
// Copyright (C) 2014 Philippe Gerum <rpm@xenomai.org>
//
// You may distribute under the terms of the GNU General Public
// License as specified in the file COPYING that comes with the
// Xenomai distribution.
//
//
XENO-CONFIG(1)
==============
:doctype: manpage
:revdate: 2014/08/03
:man source: Xenomai
:man version: {xenover}
:man manual: Xenomai Manual

NAME
-----
xeno-config - Retrieve Xenomai build flags and configuration

SYNOPSIS
---------
*xeno-config*

*xeno-config* *--v* | *--verbose*

*xeno-config* *--help*

*xeno-config* *--info*

*xeno-config* *--core*

*xeno-config* *--version*

*xeno-config* [*--cc*] [*--ccld*] [*--arch*] [*--prefix*] [*--posix|alchemy|rtdm|psos|vxworks|smokey*] [*--compat*] [*--auto-init*|*no-auto-init*] [*--auto-init-solib*] [*--mode-check*|*no-mode-check*] [*--cflags*] [*--ldflags*] [*--library-dir*|*libdir*|*user-libdir*]

DESCRIPTION
------------
*xeno-config* 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,
*xeno-config* is typically used in Makefiles.

*xeno-config --verbose* dumps the build configuration data in a
human-readable format.

Invoking *xeno-config* without any options is equivalent to running
*xeno-config --verbose --help*.

OPTIONS
--------
*--v, --verbose*::
Output all configuration information in a human-readable format.

*--help*:: Output the list of available command-line options. The
command exits immediately after completion.

*--version*::
Output the Xenomai version.

*--cc*::
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.

*--ccld*::
Output a C compiler command suitable for linking a Xenomai
application.

*--arch*::
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.

*--prefix*::
Output the absolute path to the Xenomai installation directory.

*--[skin=]{posix, alchemy, rtdm, psos, vxworks, smokey, cobalt}*::
Select the API/skin for which *xeno-config* should print the
information required. The *skin=* prefix is optional and may be
omitted, e.g. *--posix* is equivalent to *--skin=posix*, selecting the
POSIX API.

[NOTE]
*--native* and *--skin=native* are accepted for backward compatibility
purpose. They are stricly equivalent to passing *--alchemy --compat*.
Likewise, passing *--rtdm* or *--skin=rtdm* is stricly equivalent to
passing *--posix*, enabling POSIX I/O routines to be wrapped to their
respective Xenomai implementation.

[CAUTION]
Over Cobalt, only *xeno-config --posix --ldflags* (or *--rtdm* 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, *--cobalt --ldflags* should be used for linking exclusively
against the Cobalt library (i.e. +libcobalt.so+) *without* symbol
wrapping. Conversely, mentioning *--posix* along with other API
switches with *--ldflags* will cause POSIX symbol wrapping to take
place, e.g. use *--posix --alchemy --ldflags* for mixed API support
with POSIX symbol wrapping.

*--cflags*::
Output the C compiler command-line options (_CFLAGS_) which are required
to compile applications based on the selected Xenomai API/skin.

*--ldflags*::
Output the C compiler command-line options (_LDFLAGS_) which are
required to link applications based on the selected Xenomai API/skin.

*--library-dir, --libdir, --user-libdir*::
These switches are synonyms, for retrieving the absolute path to the
Xenomai libraries.

*--auto-init*::
*--no-auto-init*::

By default, a process started from an executable linked with flags
returned by *xeno-config --ldflags* performs Xenomai-related inits
automatically, before the +main()+ routine is entered.

Building with *--no-auto-init* disables such initialization. In this
case, the application code shall call the +xenomai_init()+ routine
manually, as part of its initialization chores on behalf on the
+main()+ routine, *before* any real-time service is invoked. See
+include/xenomai/init.h+.

NOTE: This flag only makes sense when passed along with --ldflags.

*--mode-check*::
*--no-mode-check*::

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.

The assertion failure is triggered if the calling thread has set the
PTHREAD_WARNSW flag by a call to +pthread_setmode_np()+.

By default, the mode checking routines are substituted to the original
ones using the symbol wrapping mechanism also used for interposing on
POSIX services. *--no-mode-check* disables such substitution.

These flags make sense when passed along with --ldflags only.

*--auto-init-solib*::

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.

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.

*--core*::
Output the name of the real-time core the current Xenomai installation
was built for. The possible values are _cobalt_ or _mercury_,
depending on the configuration switch *--with-core* used for building
the Xenomai libraries and utilities.

*--compat*::
Enable the Xenomai 2.x compatibility mode for the API/skin
selected. This switch affects the _Alchemy_ and POSIX APIs, turning on
a set of source-level compatibility wrappers when present.

*--info*::
Dump information about the running Xenomai-enabled system. Unlike most
other options, *--info* 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 mailto:xenomai@xenomai.org[the Xenomai mailing
list]. The command exits immediately after completion.

ENVIRONMENT VARIABLES
---------------------

*DESTDIR*::

Xenomai's handling of *DESTDIR* 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.

If the *DESTDIR* variable is set in the environment of *xeno-config*,
its contents is prepended to all directory and file names based on the
Xenomai installation root which may be output by the command.

If *DESTDIR* was set when installing Xenomai - typically after
cross-compiling - *DESTDIR* must be set to the same value before
calling *xeno-config* for accessing the target-based directories and
files from the build system.

e.g.

----------------------------------------------------------------------------
$ 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
----------------------------------------------------------------------------

EXIT STATUS
-----------

*0*:: Success.

*non-zero*:: Error.
