docs/dev/parrot_api.pod

   1 # Copyright (C) 2007, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/dev/parrot_api.pod - Notes on the PARROT_EXPORT macro
   7
   8
   9 =head1 OVERVIEW
  10
  11 Some compilers and platforms export all symbols either by default or through
  12 a switch. Others have no such mechanism and either need a list of symbols to
  13 export or need the symbols annotating in the source.
  14
  15 The C<PARROT_EXPORT> macro exists for the purpose of annotating symbols that
  16 should be exported. One day, it may be used to express which functions are in
  17 the Parrot extension API and which are not. For now it should be used to mark
  18 anything that will be used by a shared library or by the main Parrot executable
  19 when Parrot is built as a shared library.
  20
  21
  22 =head1 USAGE NOTES
  23
  24 Incorrect usage of C<PARROT_EXPORT> can break the build on some platforms,
  25 especially Win32. The rules for how to use it are as follows.
  26
  27 =over 4
  28
  29 =item If you decorate a function with C<PARROT_EXPORT> in a .c file, you must
  30 also decorate the symbol with C<PARROT_EXPORT> in all .h files that mention it.
  31
  32 =item If the symbol appears in more than one header file, all of them must
  33 have C<PARROT_EXPORT> or none of them should. Some with and some without won't
  34 work.
  35
  36 =back
  37
  38 # vim: expandtab shiftwidth=2 tw=70:
  39