doc/namespace.texi

   1 @node A C++ namespace for gnulib
   2 @section A C++ namespace for gnulib
   3
   4 The function definitions provided by Gnulib (@code{.c} code) are meant
   5 to be compiled by a C compiler.  The header files (@code{.h} files),
   6 on the other hand, can be used in either C or C++.
   7
   8 By default, when used in a C++ compilation unit, the @code{.h} files
   9 declare the same symbols and overrides as in C mode, except that functions
  10 defined by Gnulib or by the system are declared as @samp{extern "C"}.
  11
  12 It is also possible to indicate to Gnulib to provide many of its symbols
  13 in a dedicated C++ namespace.  If you define the macro
  14 @code{GNULIB_NAMESPACE} to an identifier, many functions will be defined
  15 in the namespace specified by the identifier instead of the global
  16 namespace.  For example, after you have defined
  17 @smallexample
  18 #define GNULIB_NAMESPACE gnulib
  19 @end smallexample
  20 @noindent
  21 at the beginning of a compilation unit, Gnulib's @code{<fcntl.h>} header
  22 file will make available the @code{open} function as @code{gnulib::open}.
  23 The symbol @code{open} will still refer to the system's @code{open} function,
  24 with its platform specific bugs and limitations.
  25
  26 The symbols provided in the Gnulib namespace are those for which the
  27 corresponding header file contains a @code{_GL_CXXALIAS_RPL} or
  28 @code{_GL_CXXALIAS_SYS} macro invocation.
  29
  30 The benefits of this namespace mode are:
  31 @itemize
  32 @item
  33 Gnulib defines fewer symbols as preprocessor macros.  For example, on a
  34 platform where @code{open} has to be overridden, Gnulib normally does
  35 @code{#define open rpl_open}.  If your package has a class with a member
  36 @code{open}, for example a class @code{foo} with a method @code{foo::open},
  37 then if you define this member in a compilation unit that includes
  38 @code{<fcntl.h>} and use it in a compilation unit that does not include
  39 @code{<fcntl.h>}, or vice versa, you will get a link error.  Worse: You
  40 will not notice this problem on the platform where the system's @code{open}
  41 function works fine.  This problem goes away in namespace mode.
  42
  43 @item
  44 It provides a safety check whether the set of modules your package requests
  45 from Gnulib is sufficient.  For example, if you use the function
  46 @code{gnulib::open} in your code, and you forgot to request the module
  47 @samp{open} from Gnulib, you will get a compilation error (regardless of
  48 the platform).
  49 @end itemize
  50
  51 The drawback of this namespace mode is that the system provided symbols in
  52 the global namespace are still present, even when they contain bugs that
  53 Gnulib fixes.  For example, if you call @code{open (...)} in your code,
  54 it will invoke the possibly buggy system function, even if you have
  55 requested the module @samp{open} from gnulib-tool.
  56
  57 You can turn on the namespace mode in some compilation units and keep it
  58 turned off in others.  This can be useful if your package consists of
  59 an application layer that does not need to invoke POSIX functions and
  60 an operating system interface layer that contains all the OS function
  61 calls.  In such a situation, you will want to turn on the namespace mode
  62 for the application layer---to avoid many preprocessor macro
  63 definitions---and turn it off for the OS interface layer---to avoid
  64 the drawback of the namespace mode, mentioned above.