cpluffdef.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  * C-Pluff, a plug-in framework for C
00003  * Copyright 2007 Johannes Lehtinen
00004  * 
00005  * Permission is hereby granted, free of charge, to any person obtaining a
00006  * copy of this software and associated documentation files (the "Software"),
00007  * to deal in the Software without restriction, including without limitation
00008  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00009  * and/or sell copies of the Software, and to permit persons to whom the
00010  * Software is furnished to do so, subject to the following conditions:
00011  *
00012  * The above copyright notice and this permission notice shall be included
00013  * in all copies or substantial portions of the Software.
00014  *
00015  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00016  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00017  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00018  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
00019  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
00020  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
00021  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00022  *-----------------------------------------------------------------------*/
00023 
00024 /** @file
00025  * Common defines shared by C-Pluff C and C++ APIs.
00026  * This file is automatically included by the top level C and C++
00027  * API header files. There should be no need to include it explicitly.
00028  */
00029 
00030 #ifndef CPLUFFDEF_H_
00031 #define CPLUFFDEF_H_
00032 
00033 
00034 /* ------------------------------------------------------------------------
00035  * Version information
00036  * ----------------------------------------------------------------------*/
00037 
00038 /**
00039  * @defgroup versionInfo Version information
00040  * @ingroup cDefines cxxDefines
00041  *
00042  * C-Pluff version information. Notice that this version information
00043  * is static version information included in header files. The
00044  * macros introduced here can be used for compile time checks.
00045  */
00046 /*@{*/
00047 
00048 /**
00049  * The C-Pluff release version string. This string identifies a specific
00050  * version of the C-Pluff distribution. Compile time software compatibility
00051  * checks should use #CP_VERSION_MAJOR and #CP_VERSION_MINOR instead.
00052  */
00053 #define CP_VERSION "0.1.3"
00054 
00055 /**
00056  * The major version number component of the release version. This is an
00057  * integer.
00058  */
00059 #define CP_VERSION_MAJOR 0
00060 
00061 /**
00062  * The minor version number component of the release version. This is an
00063  * integer.
00064  */
00065 #define CP_VERSION_MINOR 1
00066 
00067 /*@}*/
00068 
00069 
00070 /* ------------------------------------------------------------------------
00071  * Symbol visibility
00072  * ----------------------------------------------------------------------*/
00073 
00074 /**
00075  * @defgroup symbolVisibility Symbol visibility
00076  * @ingroup cDefines cxxDefines
00077  *
00078  * Macros for controlling inter-module symbol visibility and linkage. These
00079  * macros have platform specific values. #CP_EXPORT, #CP_IMPORT and #CP_HIDDEN
00080  * can be reused by plug-in implementations for better portability. The
00081  * complexity is mostly due to Windows DLL exports and imports.
00082  *
00083  * @anchor symbolVisibilityExample
00084  * Each module should usually define its own macro to declare API symbols with
00085  * #CP_EXPORT and #CP_IMPORT as necessary. For example, a mobule could define
00086  * a macro @c MY_API in the API header file as follows.
00087  *
00088  * @code
00089  * #ifndef MY_API
00090  * #  define MY_API CP_IMPORT
00091  * #endif
00092  * @endcode
00093  *
00094  * By default the API symbols would then be marked for import which is correct
00095  * when client modules are including the API header file. When compiling the
00096  * module itself the option @c -DMY_API=CP_EXPORT would be passed to the compiler to
00097  * override the API header file and to mark the API symbols for export.
00098  * The overriding definition could also be included in module source files or
00099  * in an internal header file before including the API header file.
00100  */
00101 /*@{*/
00102 
00103 /**
00104  * @def CP_EXPORT
00105  *
00106  * Declares a symbol to be exported for inter-module usage. When compiling the
00107  * module which defines the symbol this macro should be placed
00108  * at the start of the symbol declaration to ensure that the symbol is exported
00109  * to other modules. However, when compiling other modules the declaration of
00110  * the symbol should start with #CP_IMPORT.
00111  * See @ref symbolVisibilityExample "the example" of how to do this.
00112  */
00113 
00114 /**
00115  * @def CP_IMPORT
00116  *
00117  * Declares a symbol to be imported from another module. When compiling a
00118  * module which uses the symbol this macro should be placed at the start of
00119  * the symbol declaration to ensure that the symbol is imported from the
00120  * defining module. However, when compiling the defining module the declaration
00121  * of the symbol should start with #CP_EXPORT.
00122  * See @ref symbolVisibilityExample "the example" of how to do this.
00123  */
00124 
00125 /**
00126  * @def CP_HIDDEN
00127  *
00128  * Declares a symbol hidden from other modules. This macro should be
00129  * placed at the start of the symbol declaration to hide the symbol from other
00130  * modules (if supported by the platform). This macro is not intended to be
00131  * used with symbols declared as "static" which are already internal to the
00132  * object file. Some platforms do not support hiding of symbols and therefore
00133  * unique prefixes should be used for global symbols internal to the module
00134  * even when they are declared using this macro. C++ code should generally use
00135  * this macro when declaring inline functions.
00136  */
00137 
00138 #if defined(_WIN32)
00139 #  define CP_EXPORT __declspec(dllexport)
00140 #  define CP_IMPORT extern __declspec(dllimport)
00141 #  define CP_HIDDEN
00142 #elif defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
00143 #  define CP_EXPORT
00144 #  define CP_IMPORT extern
00145 #  define CP_HIDDEN __attribute__ ((visibility ("hidden")))
00146 #else
00147 #  define CP_EXPORT
00148 #  define CP_IMPORT extern
00149 #  define CP_HIDDEN
00150 #endif
00151 
00152 /*@}*/
00153 
00154 
00155 /* ------------------------------------------------------------------------
00156  * GCC attributes
00157  * ----------------------------------------------------------------------*/
00158 
00159 /**
00160  * @defgroup cDefinesGCCAttributes GCC attributes
00161  * @ingroup cDefines cxxDefines
00162  *
00163  * These macros conditionally define GCC attributes for declarations.
00164  * They are used in C-Pluff API declarations to enable better optimization
00165  * and error checking when using GCC. In non-GCC platforms they have
00166  * empty values.
00167  */
00168 /*@{*/
00169 
00170 /**
00171  * @def CP_GCC_PURE
00172  *
00173  * Declares a function as pure function having no side effects.
00174  * This attribute is supported in GCC since version 2.96.
00175  * Such functions can be subject to common subexpression elimination
00176  * and loop optimization.
00177  */
00178 
00179 /**
00180  * @def CP_GCC_NONNULL
00181  *
00182  * Specifies that some pointer arguments to a function should have
00183  * non-NULL values. Takes a variable length list of argument indexes as
00184  * arguments. This attribute is supported in GCC since version 3.3.
00185  * It can be used for enhanced error checking and some optimizations.
00186  */
00187 
00188 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96)
00189 #define CP_GCC_PURE __attribute__((pure))
00190 #else
00191 #define CP_GCC_PURE
00192 #endif
00193 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
00194 #define CP_GCC_NONNULL(...) __attribute__((nonnull (__VA_ARGS__)))
00195 #else
00196 #define CP_GCC_NONNULL(...)
00197 #endif
00198 
00199 /*@}*/
00200 
00201 #endif /*CPLUFFDEF_H_*/

Generated on Thu Jun 7 05:13:36 2007 for C-Pluff C API by doxygen 1.5.1