pd.if.org Git - pdclib/blob - personalities/personality.txt

   1 /* ----------------------------------------------------------------------------
   2  * $Id$
   3  * ----------------------------------------------------------------------------
   4  * Public Domain C Library - http://pdclib.sourceforge.net
   5  * This code is Public Domain. Use, modify, and redistribute at will.
   6  * ----------------------------------------------------------------------------
   7  * Description of the personality concept
   8  * --------------------------------------------------------------------------*/
   9
  10 The PDCLib is aimed at providing a fully conforming implementation of the C
  11 standard library (ISO/IEC 9899) for diverse environments.
  12
  13 To faciliate adaption to new environments, platform-specific parts of the
  14 library have been seperated from the generic parts (e.g. the string functions,
  15 or the parsing of format strings in stdio.h).
  16
  17 The generic part is found in includes/ and functions/. It should be compilable
  18 on any platform given a compliant compiler.
  19
  20 The "personalized" part implements, for each supported environment, the non-
  21 generic parts of the library. Each supported environment is represented by a
  22 subdirectory (dubbed "personality module") in personalities/. Such a module
  23 usually requires a specific compiler on a specific hardware.
  24
  25 The concept of personality modules was favored over the traditional approach
  26 of '#ifdef', 'configure', and complex makefiles, because it isolates the
  27 environment dependencies in a limited number of files in a seperate directory, instead of spreading the dependency handling all over the code base. This
  28 approach also minimizes dependencies on the compilation environment, so that
  29 very minimalistic environments (which could e.g. not run a 'configure' script)
  30 could still compile the PDCLib.
  31
  32 A personality module consists of:
  33
  34 * standard '#define's and 'typedef's that are environment dependent (e.g. those
  35   defined in stdint.h and float.h);
  36
  37 * "abstract" '#define's that specify whether certain optional features are
  38   available in the environment or not (e.g. whether the environment supports
  39   the optional '_Imaginary' keyword, required in 'complex.h');
  40
  41 * "glue code", which binds standard library functions to support functions of
  42   the environment (e.g. the code actually allocating the memory passed out by
  43   malloc()).
  44
  45 * a (compiler-specific) solution for the type-generic math functions declared
  46   in tgmath.h.
  47
  48 In any case, it is sufficient to copy the contents of a personality module
  49 (consisting of the subdirectories functions/ and includes/) into the main
  50 directories of the same name. Your personalized copy of the PDCLib is now
  51 ready to be compiled.
  52
  53 /* ------------------------------------------------------------------------- */
  54
  55 ADDING A NEW ENVIRONMENT
  56
  57 In the personalities/ subdirectory, you will find a module named "template". In
  58 this module, you will find a complete description of all '#define's, 'typedef's
  59 and glue code functions that are required to build a new personality module.
  60
  61 A new personality module could be kept in our repository, or in the repository
  62 of the environment it refers to.
  63
  64 If you are an OS developer opting to use the PDCLib as your standard library,
  65 you would be well-advised to keep the personality module in your own repository
  66 since you have direct access there, and can make necessary changes yourself.
  67 If you are not an OS developer, or your OS can be considered stable and active
  68 enough to warrant its own personality module in the PDCLib repository, you are
  69 free to submit it; but keep two things in mind: Any code contributed to this
  70 project must be Public Domain, and any contribution must be reviewed by the
  71 maintainers first. Please double-check your code before submitting.