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

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