/**
\defgroup fcpptexport fcppt.export
\ingroup fcpptmain
\brief Macros related to library visibility

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref symbol_introduction</li>
	<li>\ref symbol_library</li>
	<li>\ref symbol_vtable</li>
	<li>\ref symbol_list</li>
	<li>\ref symbol_compiler</li>
	<li>\ref symbol_static</li>
	<li>\ref symbol_headers</li>
</ul>

</td>
</tr>
</table>

\section symbol_introduction Introduction

When building a library, several platforms have different notions of
<em>library visibility</em> that the library author has to consider. A symbol
(like a function or global object) can be hidden in the library or it can be
made public for other libraries or programs to use (for POSIX systems it is
slightly more complex, but the two mentioned cases are the ones that really
matter). Furthermore the library author has to specify whether a symbol is
currently being exported or imported (because some platforms like Windows need
this).

\note
Although every symbol can be made public under a POSIX system by default, this
is still not recommended, because you have to specify the visibility for
Windows anyway and libraries with only public symbols tend to have an
unnecessarily large interface.

\section symbol_library Defining library interfaces

Several macros are provided to make a symbol public. Because it is necessary to
specify whether a symbol is currently imported or exported, some additional
work needs to be done by the library author and the build system to ensure that
this is always correctly specified. The common way to do this is to define some
kind of macro when the library is being built, which means the symbols are
currently exported. This macro will not be defined in all other cases, which
means the symbols are currently imported.

In the following example the macro <code>MYLIB_EXPORTS</code> is defined
by the build system if the library is currently being built. This macro
is used to define <code>MYLIB_SYMBOL</code> to either #FCPPT_SYMBOL_EXPORT
or #FCPPT_SYMBOL_IMPORT .

\snippet visibility.cpp visibility_macros

<code>MYLIB_SYMBOL</code> can then be used to export a function.

\snippet visibility.cpp visibility_export_function

The definition of the function doesn't need anything special.

\snippet visibility.cpp visibility_define_function

\section symbol_vtable Exporting a vtable of a class

If a class's vtable needs to be exported, a special macro #FCPPT_SYMBOL_CLASS must be used. This macro doesn't need to change
whether the vtable is currently imported or exported.

\see #FCPPT_SYMBOL_CLASS  for a detailed explanation on when this
is necessary.

\snippet visibility.cpp visibility_export_vtable1
\snippet visibility.cpp visibility_export_vtable2

\section symbol_list List of things to export

Generally, every object with external linkage must be exported.
This includes:

<ul>

<li>Functions (free or in a class), constructors and destructors which are
defined inside the library need a conditional symbol like
<code>MYLIB_SYMBOL</code> at their declaration, and nothing special at their
definition.</li>

<li>Objects with external linkage defined inside the library are handled like
functions.
\snippet visibility.cpp visibility_export_object

\snippet visibility.cpp visibility_define_object
</li>

<li>Classes that need their vtables to be exported must use #FCPPT_SYMBOL_CLASS at their definition.

\see \ref symbol_vtable.
</li>

<li>
An explicitly instantiated template function needs everything that a normal
function would need, but is also needs an #FCPPT_SYMBOL_EXPORT_FUNCTION_INSTANTIATION at its explicit instantiation.

In the following example, a templated function is explicitly instantiated and
exported. The function declaration needs a conditional symbol like
<code>MYLIB_SYMBOL</code> because a normal function would also need it.

\snippet visibility.cpp visibility_export_template_function

The explicit instantiation needs an additional #FCPPT_SYMBOL_EXPORT_FUNCTION_INSTANTIATION. It is important that this comes
after the <code>template</code> keyword but before the rest of the explicit
function instantiation.

\snippet visibility.cpp visibility_define_template_function
</li>

<li>
An explicitly instantiated template class is handled in a similarly to
explicitly instantiated functions.

In the following example, a templated class is explicitly instantiated and
exported. The class definition is, again, as if it was a normal class.

\snippet visibility.cpp visibility_export_template_class

The explicit instantiation needs an additional #FCPPT_SYMBOL_EXPORT_CLASS_INSTANTIATION. It must be placed after the
<code>class</code> or <code>struct</code> keyword and before the rest of the
type.

\warning If you fail to put the macro at the right place, some compilers
may ignore the visibility attributes without any warnings.

\snippet visibility.cpp visibility_define_template_class
</li>
</ul>

\section symbol_compiler Compiler specific usage

Library visibility is only useful if a shared library is being built and if the
symbols of the shared library are hidden by default. Here is some advice
how to use different build systems:
<ul>

<li>For gcc and clang, you should use the option
<code>-fvisibility=hidden</code>. Only then will all the symbols be hidden by
default, so that making symbols public actually does anything.</li>

<li>gcc might ignore #FCPPT_SYMBOL_EXPORT_FUNCTION_INSTANTIATION  or
#FCPPT_SYMBOL_EXPORT_CLASS_INSTANTIATION  if an implicit instantiation of
the same type already took place in the same translation unit. You must ensure
that this does not happen by creating separate translation units for every type
you wish to explicitly instantiate and export.</li>

</ul>

\section symbol_static Static linking

For static linking to work, all of the attributes must be disabled. To do that,
we are first going to introduce a macro <code>MYLIB_STATIC</code> that is
defined <em>both</em> when the static library is being built <em>and</em> when
the library should be used statically.

\snippet visibility.cpp visibility_macros_static

You also have to make sure that the macros for explicit template instantiations
are empty if <code>MYLIB_STATIC</code> is defined. These two macros should be
used instead of the ones provided by fcppt.

\snippet visibility.cpp visibility_macros_instantiation_static

\section symbol_headers Header files
<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>symbol/export.hpp</code></td>
<td>Contains #FCPPT_SYMBOL_EXPORT .</td>
</tr>
<tr>
<td><code>symbol/import.hpp</code></td>
<td>Contains #FCPPT_SYMBOL_IMPORT .</td>
</tr>
<tr>
<td><code>symbol/class.hpp</code></td>
<td>Contains #FCPPT_SYMBOL_CLASS .</td>
</tr>
<tr>
<td><code>symbol/export_class_instantiation.hpp</code></td>
<td>Contains #FCPPT_SYMBOL_EXPORT_CLASS_INSTANTIATION .</td>
</tr>
<tr>
<td><code>symbol/export_function_instantiation.hpp</code></td>
<td>Contains #FCPPT_SYMBOL_EXPORT_FUNCTION_INSTANTIATION .</td>
</tr>
</table>

*/
