This question already has answers here:
What is this macro for at the beginning of a class definition?
(3 answers)
Closed 7 years ago.
When looking at source code for libraries in C++ I often see things like this:
#define API_MACRO
class API_MACRO className
{
//Class stuff
};
In addition I see things like the following with method signatures:
void API_MACRO functionName();
So my question is what is this for and what is this practice called? I tried looking it up online but found nothing. It doesn't seem to offer any benefit or practical use...especially since these functions and classes are already wrapped up inside of namespaces.
How do you make your function or class show up for public use in a Unix shared library or a Windows DLL?
Each one has its own method. Luckily they are similar enough that a macro can handle it.
For GCC you want
#define DLLEXPORT __attribute__((visibility("default")))
For Windows MSVC you want
#define DLLEXPORT __declspec( dllexport )
And if you are linking to a DLL in Windows you need the definitions to be marked
#define DLLEXPORT __declspec( dllimport )
Those lines above were copied from a project of mine and API_MACRO may be a better name, because DLLEXPORT doesn't make a lot of sense when importing.
The API_MACRO is conditionally defined. Typically in this usage, it is defined as __declspec(dllimport) or __declspec(dllexport), or nothing at all when not using MSVC's dynamic linking language extension for whatever reason.
Thus, the definition would usually be found in the build system, which determines whether it's being built under Windows as consuming or building the DLL.
Related
I am currently working on a project with some old poorly documented code, and am trying to navigate my way through the various .h files that they have provided complete documentation on the use of all of the functions contained (the definitions are held in .lib and .dll files). One of the .h files has functions the are not only declared, but defined with either simple return statements or empty statements as such
class DLL ExampleLibraryClass {
public:
int exampleGetValue() {return 0;}
void exampleSetValue(Type val) {;}
void exampleActionFxn() {;}
};
These would be functions that I expect to return current variable states or perform certain actions, which is why this puzzles me.
Additionally:
I have used Dependency Walker and found that each function does have a matching definition in a dll.
The Keyword DLL has been defined with
#ifndef _PWSDLL_
# define _PWSDLL_
# define WINCALL _stdcall
# ifdef _USRDLL
# define DLL __declspec(dllexport)
# else
# define DLL __declspec(dllimport)
# endif
#endif
_USRDLL is not defined and therefore DLL is defined as __declspec(dllimport)
My question revolves less about the apparent effect of the empty definitions (which do nothing I suppose, and have already been discussed on SO) and more about why the .h file has been written this way and how to utilize the file. Is this a common or known practice? Will the linker still look for definitions to the function in my linked libraries? Are there other pieces of code that I should look for for more clues? Or perhaps in the broadest sense, how should I respond to this?
Many thanks, and please let me know if you need more information to address this, I am unsure what exactly is important in this matter.
EDIT: Added forgotten return types in example code.
EDIT: Added note about DLL definition.
One scenario where you put this code to some use would be to override the functions. These functions hold some default code and could be overridden later.
I recently came across this sort of code in someone's opengl shader class and am not sure of its use.
As I understand it from reading IBM's documentation, the #define ONEWORD will remove any occurence of ONEWORD in the subsequent text.
What is the purpose of having ONEWORD in this code at all if all occurrences are removed? What does having a token like that, after a class keyword but before a class name, really mean?
I've only used #define for include guards in the past so this is entirely new for me.
#define ONEWORD
class ONEWORD FooClass
{
FooClass();
~FooClass();
};
The code I saw this in is here: https://dl.dropbox.com/u/104992465/glsl.h
Just in case I've made its context too abstract.
It's to allow you to easily add compiler specific keywords to your class declaration. For instance with Visual Studio, if you wanted to put this class in a DLL, you would change your definition to
#define ONEWORD __declspec( dllexport )
See here for another example
Oh, so after looking at the actual code, it's not ONEWORD, but rather GLSAPI. These XYZ_API macros are often used for conditionally specifying platform-specific linkage, such as some __attributes__ which require different treatment on, for example, Windows and Unixes. So you can expect GLSAPI to be defined in one of the header files (maybe in config.h) like this:
#ifdef WIN32
# define GLSAPI __dllimport
#elif defined __linux__
# define GLSAPI __attribute__((visibility("visible")))
#else
# define GLSAPI
#endif
(Pseudo-code, I'm not sure about all the attributes and linkage "qualifiers", but you can look them up in the code.)
I'm trying to understand some C++ code which has the following class syntax:
class Q_MONKEY_EXPORT BasePlugin : public QObject
{
// some code comes here
};
I cannot understand the syntax class Q_MONKEY_EXPORT BasePlugin. To me it looks like if there are two names for the class. What exactly does this kind of syntax mean in C++?
Q_MONKEY_EXPORT is most likely a #define somewhere. Defines like that are sometimes required, for example when the class is in a library and needs to be exported when the header file is included from somewhere else. In that case, the define resolves to something like __declspec(dllexport) (the exact syntax will depend on the tools you are using).
That's most probably a preprocessor directive telling the compiler the symbol is to be exported.
It's probably defined as:
#define Q_MONKEY_EXPORT _declspec(dllexport)
which will cause your class to be exported to the dll.
The full declaration will be expanded, before compilation, to:
class _declspec(dllimport) BasePlugin : public QObject
{
// some code comes here
};
EDIT:
As David Heffernan pointed out, macros like these are generally used to let the compiler know whether it needs to import or export the symbols. Usually defined as dllimport for outside modules and dllexport when building the module. I doubt that's the case here, since the name suggests exporting, but it's best to check the documentation or actually go to the definition.
Q_MONKEY_EXPORT is a macro (all upper case is convention for macro) that typically resolves to something like __declspec(dllexport) when you are building the DLL and resolves to __declspec(dllimport) when you are using the DLL.
You can find out exactly what it is by reading your include files.
I found this in Ogre Framework
class _OgreSampleClassExport Sample_Character : public SdkSample {
...
...
and it's define like this
#define _OgreSampleClassExport
Why we want to have this macro variable?
Presumably so a special qualifier, such as __declspec(dllexport), could be added to such classes by modifying (or conditionally defining) the define:
#define _OgreSampleClassExport __declspec(dllexport)
It's to allow for future exports. Ogre may just strictly be a statically linked library at the moment, but if the authors ever decide to support dynamically-linked libraries (aka shared libraries on some platforms), they will need to write code like:
class
#ifdef EXPORTING
__declspec(dllexport)
#else
__declspec(dllimport)
#endif
Sample_Character [...]
... and that's just for MSVC. Normally they'd have to go through the effort to do this to Sample_Character and all other classes they provide through their library. Making a single macro to be defined later is much easier as they'll only need to do this in one place.
I have seen instances of __declspec in the code that I am reading. What is it? And when would I need to use this construct?
This is a Microsoft specific extension to the C++ language which allows you to attribute a type or function with storage class information.
Documentation
__declspec (C++)
The canonical examples are __declspec(dllimport) and __declspec(dllexport), which instruct the linker to import and export (respectively) a symbol from or to a DLL.
// header
__declspec(dllimport) void foo();
// code - this calls foo() somewhere in a DLL
foo();
(__declspec(..) just wraps up Microsoft's specific stuff - to achieve compatibility, one would usually wrap it away with macros)
It is mostly used for importing symbols from / exporting symbols to a shared library (DLL). Both Visual C++ and GCC compilers support __declspec(dllimport) and __declspec(dllexport). Other uses (some Microsoft-only) are documented in the MSDN.
Another example to illustrate the __declspec keyword:
When you are writing a Windows Kernel Driver, sometimes you want to write your own prolog/epilog code sequences using inline assembler code, so you could declare your function with the naked attribute.
__declspec( naked ) int func( formal_parameters ) {}
Or
#define Naked __declspec( naked )
Naked int func( formal_parameters ) {}
Please refer to naked (C++)
Essentially, it's the way Microsoft introduces its C++ extensions so that they won't conflict with future extensions of standard C++. With __declspec, you can attribute a function or class; the exact meaning varies depending on the nature of __declspec. __declspec(naked), for example, suppresses prolog/epilog generation (for interrupt handlers, embeddable code, etc), __declspec(thread) makes a variable thread-local, and so on.
The full list of __declspec attributes is available on MSDN, and varies by compiler version and platform.
I know it's been eight years but I wanted to share this piece of code found in MRuby that shows how __declspec() can bee used at the same level as the export keyword.
/** Declare a public MRuby API function. */
#if defined(MRB_BUILD_AS_DLL)
#if defined(MRB_CORE) || defined(MRB_LIB)
# define MRB_API __declspec(dllexport)
#else
# define MRB_API __declspec(dllimport)
#endif
#else
# define MRB_API extern
#endif