C-Pluff C API 0.2.0
cpluffdef.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 * C-Pluff, a plug-in framework for C
3 * Copyright 2007 Johannes Lehtinen
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included
13 * in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 *-----------------------------------------------------------------------*/
23
24/** @file
25 * Common defines shared by C-Pluff C and C++ APIs.
26 * This file is automatically included by the top level C and C++
27 * API header files. There should be no need to include it explicitly.
28 */
29
30#ifndef CPLUFFDEF_H_
31#define CPLUFFDEF_H_
32
33
34/* ------------------------------------------------------------------------
35 * Version information
36 * ----------------------------------------------------------------------*/
37
38/**
39 * @defgroup versionInfo Version information
40 * @ingroup cDefines cxxDefines
41 *
42 * C-Pluff version information. Notice that this version information
43 * is static version information included in header files. The
44 * macros introduced here can be used for compile time checks.
45 */
46/*@{*/
47
48/**
49 * The C-Pluff release version string. This string identifies a specific
50 * version of the C-Pluff distribution. Compile time software compatibility
51 * checks should use #CP_VERSION_MAJOR and #CP_VERSION_MINOR instead.
52 */
53#define CP_VERSION "0.2.0"
54
55/**
56 * The major version number component of the release version. This is an
57 * integer.
58 */
59#define CP_VERSION_MAJOR 0
60
61/**
62 * The minor version number component of the release version. This is an
63 * integer.
64 */
65#define CP_VERSION_MINOR 2
66
67/*@}*/
68
69
70/* ------------------------------------------------------------------------
71 * Symbol visibility
72 * ----------------------------------------------------------------------*/
73
74/**
75 * @defgroup symbolVisibility Symbol visibility
76 * @ingroup cDefines cxxDefines
77 *
78 * Macros for controlling inter-module symbol visibility and linkage. These
79 * macros have platform specific values. #CP_EXPORT, #CP_IMPORT and #CP_HIDDEN
80 * can be reused by plug-in implementations for better portability. The
81 * complexity is mostly due to Windows DLL exports and imports.
82 *
83 * @anchor symbolVisibilityExample
84 * Each module should usually define its own macro to declare API symbols with
85 * #CP_EXPORT and #CP_IMPORT as necessary. For example, a mobule could define
86 * a macro @c MY_API in the API header file as follows.
87 *
88 * @code
89 * #ifndef MY_API
90 * # define MY_API CP_IMPORT
91 * #endif
92 * @endcode
93 *
94 * By default the API symbols would then be marked for import which is correct
95 * when client modules are including the API header file. When compiling the
96 * module itself the option @c -DMY_API=CP_EXPORT would be passed to the compiler to
97 * override the API header file and to mark the API symbols for export.
98 * The overriding definition could also be included in module source files or
99 * in an internal header file before including the API header file.
100 */
101/*@{*/
102
103/**
104 * @def CP_EXPORT
105 *
106 * Declares a symbol to be exported for inter-module usage. When compiling the
107 * module which defines the symbol this macro should be placed
108 * at the start of the symbol declaration to ensure that the symbol is exported
109 * to other modules. However, when compiling other modules the declaration of
110 * the symbol should start with #CP_IMPORT.
111 * See @ref symbolVisibilityExample "the example" of how to do this.
112 */
113
114/**
115 * @def CP_IMPORT
116 *
117 * Declares a symbol to be imported from another module. When compiling a
118 * module which uses the symbol this macro should be placed at the start of
119 * the symbol declaration to ensure that the symbol is imported from the
120 * defining module. However, when compiling the defining module the declaration
121 * of the symbol should start with #CP_EXPORT.
122 * See @ref symbolVisibilityExample "the example" of how to do this.
123 */
124
125/**
126 * @def CP_HIDDEN
127 *
128 * Declares a symbol hidden from other modules. This macro should be
129 * placed at the start of the symbol declaration to hide the symbol from other
130 * modules (if supported by the platform). This macro is not intended to be
131 * used with symbols declared as "static" which are already internal to the
132 * object file. Some platforms do not support hiding of symbols and therefore
133 * unique prefixes should be used for global symbols internal to the module
134 * even when they are declared using this macro.
135 */
136
137#if defined(_WIN32)
138# define CP_EXPORT __declspec(dllexport)
139# define CP_IMPORT extern __declspec(dllimport)
140# define CP_HIDDEN
141#elif defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
142# define CP_EXPORT
143# define CP_IMPORT extern
144# define CP_HIDDEN __attribute__ ((visibility ("hidden")))
145#else
146# define CP_EXPORT
147# define CP_IMPORT extern
148# define CP_HIDDEN
149#endif
150
151/*@}*/
152
153
154/* ------------------------------------------------------------------------
155 * GCC attributes
156 * ----------------------------------------------------------------------*/
157
158/**
159 * @defgroup cDefinesGCCAttributes GCC attributes
160 * @ingroup cDefines cxxDefines
161 *
162 * These macros conditionally define GCC attributes for declarations.
163 * They are used in C-Pluff API declarations to enable better optimization
164 * and error checking when using GCC. In non-GCC platforms they have
165 * empty values.
166 */
167/*@{*/
168
169/**
170 * @def CP_GCC_PURE
171 *
172 * Declares a function as pure function having no side effects.
173 * This attribute is supported in GCC since version 2.96.
174 * Such functions can be subject to common subexpression elimination
175 * and loop optimization.
176 */
177
178/**
179 * @def CP_GCC_NONNULL
180 *
181 * Specifies that some pointer arguments to a function should have
182 * non-NULL values. Takes a variable length list of argument indexes as
183 * arguments. This attribute is supported in GCC since version 3.3.
184 * It can be used for enhanced error checking and some optimizations.
185 */
186
187#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
188#define CP_GCC_PURE __attribute__((pure))
189#else
190#define CP_GCC_PURE
191#endif
192#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
193#define CP_GCC_NONNULL(...) __attribute__((nonnull (__VA_ARGS__)))
194#else
195#define CP_GCC_NONNULL(...)
196#endif
197
198/*@}*/
199
200#if 0
201#define const
202#endif
203
204#endif /*CPLUFFDEF_H_*/

Generated on Thu Mar 14 2024 01:52:04 for C-Pluff C API by doxygen 1.9.8