pd.if.org Git - pdclib/blob - Readme.txt

   1 PDCLib - Public Domain C Library\r
   2 ================================\r
   3 \r
   4 License\r
   5 -------\r
   6 \r
   7 Written in 2003-2012 by Martin "Solar" Baute,\r
   8            2012-     by Owen Shepherd\r
   9 \r
  10 To the extent possible under law, the author(s) have dedicated all copyright \r
  11 and related and neighboring rights to this software to the public domain \r
  12 worldwide. This software is distributed without any warranty.\r
  13 \r
  14 You should have received a copy of the CC0 Public Domain Dedication along with \r
  15 this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.\r
  16 \r
  17 NOTE: Some configuration options may include components under non-public domain\r
  18       conditions. In particular, selecting ptmalloc3 as the malloc \r
  19       implementation will cause the incorporation of elements under the BSD \r
  20       license.\r
  21 \r
  22 What is it\r
  23 ----------\r
  24 \r
  25 This is a C Standard Library - what's defined in ISO/IEC 9899 "Information \r
  26 technology — Programming languages — C" or extensions to the above defined in\r
  27 ISO/IEC 14882 "Information technology — Programming languages — C++". A few \r
  28 extensions may optionally be provided.\r
  29 \r
  30 Terms for extensions\r
  31 --------------------\r
  32 Extensions are permitted where their inclusion is reasonable, they are widely\r
  33 used, in  keeping with the spirit of the standard, and do not convey \r
  34 additional requirements upon the target system, and do not needlessly duplicate\r
  35 functionality already contained within the standard.\r
  36 \r
  37 As an example: strdup is in, because (a) it can be implemented entirely in \r
  38 terms of existing standard C functions and (b) is very widely used. Something\r
  39 like open, write or close would not be considered, because it implies POSIXy \r
  40 assumptions.\r
  41 \r
  42 Internals\r
  43 ---------\r
  44 \r
  45 As a namespace convention, everything (files, typedefs, functions,\r
  46 macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.\r
  47 The standard defines any identifiers starting with '_' and a capital\r
  48 letter as reserved for the implementation, and since the chances of\r
  49 your compiler using an identifier in the _PDCLIB range are slim,\r
  50 any strictly conforming application should work with this library.\r
  51 \r
  52 PDCLib consists of several parts:\r
  53 \r
  54 1) standard headers;\r
  55 2) implementation files for standard functions;\r
  56 3) internal header files keeping complex stuff out of the standard\r
  57    headers;\r
  58 4) the central, platform-specific file _PDCLIB_config.h;\r
  59 5) platform-specific implementation files;\r
  60 \r
  61 The standard headers (in ./includes/) only contain what they are\r
  62 defined to contain. Where additional logic or macro magic is\r
  63 necessary, that is deferred to the internal files. This has been done\r
  64 so that the headers are actually educational as to what they provide\r
  65 (as opposed to how the library does it).\r
  66 \r
  67 There is a seperate implementation file (in ./function/{header}/) for\r
  68 every function defined by the standard, named {function}.c. Not only\r
  69 does this avoid linking in huge amounts of unused code when you use\r
  70 but a single function, it also allows the optimization overlay to work\r
  71 (see below).\r
  72 \r
  73 (The directory ./functions/_PDCLIB/ contains internal and helper\r
  74 functions that are not part of the standard.)\r
  75 \r
  76 Then there are internal header files (in ./internal/), which contain\r
  77 all the "black magic" and "code fu" that was kept out of the standard\r
  78 headers. You should not have to touch them if you want to adapt PDCLib\r
  79 to a new platform. Note that, if you *do* have to touch them, I would\r
  80 consider it a serious design flaw, and would be happy to fix it in the\r
  81 next PDCLib release. Any adaption work should be covered by the steps\r
  82 detailed below.\r
  83 \r
  84 For adapting PDCLib to a new platform (the trinity of CPU, operating\r
  85 system, and compiler), make a copy of ./platform/example/ named\r
  86 ./platform/{your_platform}/, and modify the files of your copy to suit\r
  87 the constraints of your platform. When you are done, copy the contents\r
  88 of your platform directory over the source directory structure\r
  89 of PDCLib (or link them into the appropriate places). That should be\r
  90 all that is actually required to make PDCLib work for your platform.\r
  91 \r
  92 Future directions\r
  93 -----------------\r
  94 Obviously, full C89, C99 and C11 conformance; and full support for the \r
  95 applicable portions of C++98, C++03 and C++11.\r
  96 \r
  97 Support for "optimization overlays." These would allow efficient \r
  98 implementations of certain functions on individual platforms, for example \r
  99 memcpy, strcpy and memset. This requires further work to only compile in one\r
 100 version of a given function.\r
 101 \r
 102 Development Status\r
 103 ------------------\r
 104 \r
 105 v0.1 - 2004-12-12\r
 106 Freestanding-only C99 implementation without any overlay, and missing\r
 107 the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c\r
 108 values hardcoded into it; not sure whether to include enquire.c in the\r
 109 package, to leave <float.h> to the overlay, or devise some parameterized\r
 110 macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but\r
 111 I had to make the 0.1 release sometime so why not now.\r
 112 \r
 113 v0.2 - 2005-01-12\r
 114 Adds implementations for <string.h> (excluding strerror()), INTN_C() /\r
 115 UINTN_C() macros, and some improvements in the internal headers.\r
 116 Test drivers still missing, but added warnings about that.\r
 117 \r
 118 v0.3 - 2005-11-21\r
 119 Adds test drivers, fixes some bugs in <string.h>.\r
 120 \r
 121 v0.4 - 2005-02-06\r
 122 Implementations for parts of <stdlib.h>. Still missing are the floating\r
 123 point conversions, and the wide-/multibyte-character functions.\r
 124 \r
 125 v0.4.1 - 2006-11-16\r
 126 With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as\r
 127 a backport of bugfixes in the current development code.\r
 128 - #1  realloc( NULL, size ) fails           (fixed)\r
 129 - #2  stdlib.h - insufficient documentation (fixed)\r
 130 - #4  Misspelled name in credits            (fixed)\r
 131 - #5  malloc() splits off too-small nodes   (fixed)\r
 132 - #6  qsort() stack overflow                (fixed)\r
 133 - #7  malloc() bug in list handling         (fixed)\r
 134 - #8  strncmp() does not terminate at '\0'  (fixed)\r
 135 - #9  stdint.h dysfunctional                (fixed)\r
 136 - #10 NULL redefinition warnings            (fixed)\r
 137 \r
 138 v0.5 - 2010-12-22\r
 139 Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,\r
 140 and strerror() from <string.h>.\r
 141 Still no locale / wide-char support. Enabled all GCC compiler warnings I\r
 142 could find, and fixed everything that threw a warning. (You see this,\r
 143 maintainers of Open Source software? No warnings whatsoever. Stop telling\r
 144 me it cannot be done.) Fixed all known bugs in the v0.4 release.\r
 145 \r
 146 Near Future\r
 147 -----------\r
 148 Current development directions are:\r
 149 \r
 150 Implement portions of the C11 standard that have a direct impact on the way \r
 151 that PDCLib itself is built. For example, in order to support multithreading,\r
 152 PDCLib needs a threading abstraction; therefore, C11's thread library is being\r
 153 implemented to provide the backing for this (as there is no purpose in \r
 154 implementing two abstractions)\r
 155 \r
 156 Cleanup portions of <stdio.h>, particularly the backend. _PDCLIB_fillbuffer and\r
 157 _PDCLIB_flushbuffer in particular do not feel 'well' factored and need to know\r
 158 too much about FILE's internals. \r
 159 \r
 160 Modularize the library somewhat. This can already be seen with components under \r
 161 "opt/". This structure is preliminary; it will likely change as the process \r
 162 continues.