pd.if.org Git - pdclib.old/blob - Readme.rst

   1 ==============================================================\r
   2 PDCLib - the `Public Domain C Library <http://pdclib.e43.eu>`_\r
   3 ==============================================================\r
   4 \r
   5 What is it\r
   6 ==========\r
   7 \r
   8 This is a C Standard Library - what's defined in ISO/IEC 9899 "Information \r
   9 technology — Programming languages — C" or extensions to the above defined in\r
  10 ISO/IEC 14882 "Information technology — Programming languages — C++". A few \r
  11 extensions may optionally be provided.\r
  12 \r
  13 License\r
  14 =======\r
  15 \r
  16 Written in \r
  17  * 2003-2012 by Martin "Solar" Baute,\r
  18  * 2012-     by Owen Shepherd\r
  19 \r
  20 To the extent possible under law, the author(s) have dedicated all copyright \r
  21 and related and neighboring rights to this software to the public domain \r
  22 worldwide. This software is distributed without any warranty.\r
  23 \r
  24 You should have received a copy of the CC0 Public Domain Dedication along with \r
  25 this software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.\r
  26 \r
  27 Exceptions\r
  28 ----------\r
  29 \r
  30 Unicode Character Data\r
  31 ~~~~~~~~~~~~~~~~~~~~~~\r
  32 PDCLib necessarily includes Unicode character data derived from that provided by\r
  33 Unicode, Inc in its' implementation of the localization and wide character \r
  34 support (in particular for use by the ctype.h and wctype.h functions.)\r
  35 \r
  36 Unicode, Inc licenses that data under a license agreement which can be found at\r
  37 <http://www.unicode.org/copyright.html#Exhibit1>, or in the file \r
  38 UNICODE_DATA_LICENSE.txt. found in the same directory as this file.\r
  39 \r
  40 Test Suite\r
  41 ~~~~~~~~~~\r
  42 Portions of the test suite are under different licenses. Where this is the case, \r
  43 it is clearly noted in the relevant location.\r
  44 \r
  45 The license of this code has no bearing upon the licensing of the built library \r
  46 (as it does not comprise part of it).\r
  47 \r
  48 At the time this was written, this exception only applies to portions of the \r
  49 printf test suite, which are released under the terms of the 2-clause BSD \r
  50 license (see testing/printf_testcases.h for full details)\r
  51 \r
  52 Terms for extensions\r
  53 ====================\r
  54 Extensions are permitted only if they pass the following tests:\r
  55 \r
  56 Pre-existing wide usage\r
  57     On most systems, the system C library must maintain its application binary\r
  58     interface for long periods of time (potentially eternity). Existing wide \r
  59     usage demonstrates utility\r
  60 \r
  61 In keeping with the spirit of the standard\r
  62     The extension should respect the design, intentions and conventions of the C\r
  63     standard, and feel like a natural extension to the offered capability. \r
  64 \r
  65 Not system dependent\r
  66     The extension should not add any additional dependencies on the underlying \r
  67     system\r
  68 \r
  69 Non-duplicative\r
  70     Extensions should not duplicate functionality already provided by the \r
  71     standard\r
  72 \r
  73 Disabled by default\r
  74     PDCLib will always default to a "strictly conforming" mode exposing only\r
  75     functionality offered by the version of the standard specified by the\r
  76     __STDC_VERSION__, __STDC__ or __cplusplus macro; extensions will only be \r
  77     exposed when requested.\r
  78 \r
  79 Additionally, extra consideration will be given to extensions which are \r
  80 difficult or impossible to implement without access to internal structures of \r
  81 the C library.\r
  82 \r
  83 Conrete Examples:\r
  84 \r
  85 strndup\r
  86     **Included.** strndup is easily defined in terms of existing standard \r
  87     functions, follows  the standard's naming conventions, is in wide usage, and\r
  88     does not duplicate  features already provided.\r
  89 \r
  90 posix_memalign\r
  91     **Rejected.** Has existing wide usage, is not system dependent (can be \r
  92     implemented, albeit inefficiently, on top of malloc), but naming is not \r
  93     consistent with the naming used by the standard (posix_ prefix) and \r
  94     duplicates functionality provided by the C11 standard\r
  95 \r
  96 open, close, read, write, ...\r
  97     **Rejected.** Widely used, but duplicates functionality provided by the \r
  98     standard (FILE objects set to be unbuffered), and not able to implement full\r
  99     semantics (e.g. in relation to POSIX fork and other functionality from the \r
 100     same defining standard) in a platform-neutral way\r
 101 \r
 102 strl*\r
 103     **Rejected.** Used somewhat widely, in keeping with the standard, not system\r
 104     dependent, but duplicative of functionality provided by (optional) Annex K \r
 105     of the C standard. \r
 106 \r
 107 flockfile, funlockfile, getc_unlocked, putc_unlocked, fwrite_unlocked, ...\r
 108     **Accepted.** Provide functionality not provided by the standard (and \r
 109     useful in light of the C11 addition of threading). Can be trivially \r
 110     implemented in terms of the <threads.h> mutex functions and the bodies of \r
 111     the existing I/O functions, and impossible to implement externally\r
 112 \r
 113 Internals\r
 114 =========\r
 115 \r
 116 As a namespace convention, everything (files, typedefs, functions,\r
 117 macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.\r
 118 The standard defines any identifiers starting with '_' and a capital\r
 119 letter as reserved for the implementation, and since the chances of\r
 120 your compiler using an identifier in the _PDCLIB range are slim,\r
 121 any strictly conforming application should work with this library.\r
 122 \r
 123 PDCLib consists of several parts:\r
 124 \r
 125 1) standard headers;\r
 126 2) implementation files for standard functions;\r
 127 3) internal header files keeping complex stuff out of the standard\r
 128    headers;\r
 129 4) the central, platform-specific file _PDCLIB_config.h;\r
 130 5) platform-specific implementation files;\r
 131 \r
 132 The standard headers (in ./includes/) only contain what they are\r
 133 defined to contain. Where additional logic or macro magic is\r
 134 necessary, that is deferred to the internal files. This has been done\r
 135 so that the headers are actually educational as to what they provide\r
 136 (as opposed to how the library does it).\r
 137 \r
 138 There is a seperate implementation file (in ./function/{header}/) for\r
 139 every function defined by the standard, named {function}.c. Not only\r
 140 does this avoid linking in huge amounts of unused code when you use\r
 141 but a single function, it also allows the optimization overlay to work\r
 142 (see below).\r
 143 \r
 144 (The directory ./functions/_PDCLIB/ contains internal and helper\r
 145 functions that are not part of the standard.)\r
 146 \r
 147 Then there are internal header files (in ./internal/), which contain\r
 148 all the "black magic" and "code fu" that was kept out of the standard\r
 149 headers. You should not have to touch them if you want to adapt PDCLib\r
 150 to a new platform. Note that, if you *do* have to touch them, I would\r
 151 consider it a serious design flaw, and would be happy to fix it in the\r
 152 next PDCLib release. Any adaption work should be covered by the steps\r
 153 detailed below.\r
 154 \r
 155 For adapting PDCLib to a new platform (the trinity of CPU, operating\r
 156 system, and compiler), make a copy of ./platform/example/ named\r
 157 ./platform/{your_platform}/, and modify the files of your copy to suit\r
 158 the constraints of your platform. When you are done, copy the contents\r
 159 of your platform directory over the source directory structure\r
 160 of PDCLib (or link them into the appropriate places). That should be\r
 161 all that is actually required to make PDCLib work for your platform.\r
 162 \r
 163 Future directions\r
 164 =================\r
 165 Obviously, full C89, C99 and C11 conformance; and full support for the \r
 166 applicable portions of C++98, C++03 and C++11 (the version which acomplishes \r
 167 this will be christened "1.0").\r
 168 \r
 169 Support for "optimization overlays." These would allow efficient \r
 170 implementations of certain functions on individual platforms, for example \r
 171 memcpy, strcpy and memset. This requires further work to only compile in one\r
 172 version of a given function.\r
 173 \r
 174 Post 1.0, support for C11 Annexe K "Bounds checking interfaces"\r
 175 \r
 176 Development Status\r
 177 ==================\r
 178 \r
 179 ``v0.1 - 2004-12-12``\r
 180     Freestanding-only C99 implementation without any overlay, and missing\r
 181     the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c\r
 182     values hardcoded into it; not sure whether to include enquire.c in the\r
 183     package, to leave <float.h> to the overlay, or devise some parameterized\r
 184     macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but\r
 185     I had to make the 0.1 release sometime so why not now.\r
 186 \r
 187 ``v0.2 - 2005-01-12``\r
 188     Adds implementations for <string.h> (excluding strerror()), INTN_C() /\r
 189     UINTN_C() macros, and some improvements in the internal headers.\r
 190     Test drivers still missing, but added warnings about that.\r
 191 \r
 192 ``v0.3 - 2005-11-21``\r
 193     Adds test drivers, fixes some bugs in <string.h>.\r
 194 \r
 195 ``v0.4 - 2005-02-06``\r
 196     Implementations for parts of <stdlib.h>. Still missing are the floating\r
 197     point conversions, and the wide-/multibyte-character functions.\r
 198 \r
 199 ``v0.4.1 - 2006-11-16``\r
 200     With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as\r
 201     a backport of bugfixes in the current development code.\r
 202 \r
 203     - #1 realloc( NULL, size ) fails\r
 204     - #2 stdlib.h - insufficient documentation\r
 205     - #4  Misspelled name in credits\r
 206     - #5  malloc() splits off too-small nodes\r
 207     - #6  qsort() stack overflow\r
 208     - #7  malloc() bug in list handling\r
 209     - #8  strncmp() does not terminate at '\0'\r
 210     - #9  stdint.h dysfunctional\r
 211     - #10 NULL redefinition warnings\r
 212 \r
 213 ``v0.5 - 2010-12-22``\r
 214     Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,\r
 215     and strerror() from <string.h>.\r
 216     Still no locale / wide-char support. Enabled all GCC compiler warnings I\r
 217     could find, and fixed everything that threw a warning. (You see this,\r
 218     maintainers of Open Source software? No warnings whatsoever. Stop telling\r
 219     me it cannot be done.) Fixed all known bugs in the v0.4 release.\r
 220 \r
 221 Near Future\r
 222 ===========\r
 223 Current development directions are:\r
 224 \r
 225 Implement portions of the C11 standard that have a direct impact on the way \r
 226 that PDCLib itself is built. For example, in order to support multithreading,\r
 227 PDCLib needs a threading abstraction; therefore, C11's thread library is being\r
 228 implemented to provide the backing for this (as there is no purpose in \r
 229 implementing two abstractions)\r
 230 \r
 231 Modularize the library somewhat. This can already be seen with components under \r
 232 "opt/". This structure is preliminary; it will likely change as the process \r
 233 continues.