File: waffle_feature_test_macros.7.xml

package info (click to toggle)
waffle 1.6.1-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 3,092 kB
  • sloc: ansic: 19,173; xml: 2,906; cpp: 489; objc: 465; sh: 100; makefile: 20
file content (117 lines) | stat: -rw-r--r-- 4,021 bytes parent folder | download | duplicates (2)
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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">

<!--
  Copyright Intel 2013

  This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
  US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
-->

<refentry
    id="waffle_feature_test_macros"
    xmlns:xi="http://www.w3.org/2001/XInclude">

  <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->

  <refmeta>
    <refentrytitle>waffle_feature_test_macros</refentrytitle>
    <manvolnum>7</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>waffle_feature_test_macros</refname>
    <refpurpose>Macros to control definitions exposed by Waffle's headers</refpurpose>
  </refnamediv>

  <refentryinfo>
    <title>Waffle Manual</title>
    <productname>waffle</productname>
    <xi:include href="common/author-chad.versace.xml"/>
    <xi:include href="common/copyright.xml"/>
    <xi:include href="common/legalnotice.xml"/>
  </refentryinfo>

  <refsynopsisdiv>
    <synopsis>
<constant>WAFFLE_API_VERSION</constant>
<constant>WAFFLE_API_EXPERIMENTAL</constant>
    </synopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      Waffle's feature test macros allow the programmer to control the definitions that are exposed by Waffle's headers
      when a program is compiled.
      
      Conversely, the macros allow the programmer to control which Waffle features a program's source relies on.
    </para>
    <para>
      In order to be effective, a feature test macro must be defined before including any header files.  This can be done
      either in the compilation command (cc -DMACRO=value) or by defining the macro within the source code before including
      any headers.
    </para>
    <refsect2>
      <title>Specification of feature test macro requirements in manual pages</title>
      <para>
        When a function requires that a feature test macro be defined, the manual page docments it in the SYNOPSIS.

        When an enum or macro requires that a feature test macro be defined, the manual page documents it either in the
        SYNOPSIS or where the enum or macro first appears in the page.
      </para>
    </refsect2>
    <refsect2>
      <title>List of feature test macros</title>
      <variablelist>
        <varlistentry>
          <term><constant>WAFFLE_API_VERSION</constant> (since waffle 1.3)</term>
          <listitem>
            <para>
              This macro controls the API version exposed by Waffle's headers.

              The value
              <code>((<parameter>major</parameter> &lt;&lt; 8) | <parameter>minor</parameter>)</code>
              exposes the API of
              Waffle <parameter>major</parameter>.<parameter>minor</parameter>.

              For example, the value 0x0103 exposes the API of Waffle 1.3.

              If this macro is undefined, then the headers expose the API of Waffle 1.2.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><constant>WAFFLE_API_EXPERIMENTAL</constant></term>
          <listitem>
            <para>
              This macro exposes experimental features in Waffle's headers.

              Experimental features may be altered or removed without notice and do not belong to Waffle's stable API.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </refsect2>

  </refsect1>

  <xi:include href="common/issues.xml"/>

  <refsect1>
    <title>See Also</title>

    <para>
      <simplelist>
        <member><citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>,
        <member><citerefentry><refentrytitle>feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
      </simplelist>
    </para>
  </refsect1>

</refentry>

<!--
vim:tw=120 et ts=2 sw=2:
-->