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_*/

C-Pluff, a plug-in framework for C
Copyright 2007 Johannes Lehtinen

Generated on Fri May 1 2020 01:06:58 for C-Pluff C API by doxygen 1.8.13