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

   1 PDCLib - Public Domain C Library
   2 ================================
   3
   4 License
   5 -------
   6
   7 PDCLib is distributed unter the Creative Commons CC0 License. You
   8 should have received a copy of the full legal text of this license
   9 as part of this distribution (COPYING.CC0). It is also available at
  10
  11 https://creativecommons.org/publicdomain/zero/1.0/legalcode
  12
  13 The following is a human-readable summary of that license.
  14
  15                        No Copyright
  16
  17 The person who associated a work with this deed has dedicated the
  18 work to the public domain by waiving all of his or her rights to
  19 the work worldwide under copyright law, including all related and
  20 neighboring rights, to the extent allowed by law.
  21
  22 You can copy, modify, distribute and perform the work, even for
  23 commercial purposes, all without asking permission. See Other
  24 Information below.
  25
  26                     Other Information
  27
  28 In no way are the patent or trademark rights of any person affected
  29 by CC0, nor are the rights that other persons may have in the work
  30 or in how the work is used, such as publicity or privacy rights.
  31
  32 Unless expressly stated otherwise, the person who associated a work
  33 with this deed makes no warranties about the work, and disclaims
  34 liability for all uses of the work, to the fullest extent permitted
  35 by applicable law.
  36
  37 When using or citing the work, you should not imply endorsement by
  38 the author or the affirmer.
  39
  40 What is it
  41 ----------
  42
  43 This is a C Standard Library. Nothing more, nothing less. No POSIX
  44 or other extensions, just what's defined in ISO/IEC 9899.
  45
  46 (Well, this is what it will be when the 1.0 release comes out. See
  47 the "Development Status" section to see what's implemented so far.)
  48
  49 Internals
  50 ---------
  51
  52 As a namespace convention, everything (files, typedefs, functions,
  53 macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.
  54 The standard defines any identifiers starting with '_' and a capital
  55 letter as reserved for the implementation, and since the chances of
  56 your compiler using an identifier in the _PDCLIB range are slim,
  57 any strictly conforming application should work with this library.
  58
  59 PDCLib consists of several parts:
  60
  61 1) standard headers;
  62 2) implementation files for standard functions;
  63 3) internal header files keeping complex stuff out of the standard
  64    headers;
  65 4) the central, platform-specific file _PDCLIB_config.h;
  66 5) platform-specific implementation files;
  67 6) platform-specific, optimized "overlay" implementations (optional).
  68
  69 The standard headers (in ./includes/) only contain what they are
  70 defined to contain. Where additional logic or macro magic is
  71 necessary, that is deferred to the internal files. This has been done
  72 so that the headers are actually educational as to what they provide
  73 (as opposed to how the library does it).
  74
  75 Note that there *might* be some feature to remove this additional
  76 level of indirection for a production release, to ease the workload
  77 put on the preprocessor.
  78
  79 There is a seperate implementation file (in ./function/{header}/) for
  80 every function defined by the standard, named {function}.c. Not only
  81 does this avoid linking in huge amounts of unused code when you use
  82 but a single function, it also allows the optimization overlay to work
  83 (see below).
  84
  85 (The directory ./functions/_PDCLIB/ contains internal and helper
  86 functions that are not part of the standard.)
  87
  88 Then there are internal header files (in ./internal/), which contain
  89 all the "black magic" and "code fu" that was kept out of the standard
  90 headers. You should not have to touch them if you want to adapt PDCLib
  91 to a new platform. Note that, if you *do* have to touch them, I would
  92 consider it a serious design flaw, and would be happy to fix it in the
  93 next PDCLib release. Any adaption work should be covered by the steps
  94 detailed below.
  95
  96 For adapting PDCLib to a new platform (the trinity of CPU, operating
  97 system, and compiler), make a copy of ./platform/example/ named
  98 ./platform/{your_platform}/, and modify the files of your copy to suit
  99 the constraints of your platform. When you are done, copy the contents
 100 of your platform directory over the source directory structure
 101 of PDCLib (or link them into the appropriate places). That should be
 102 all that is actually required to make PDCLib work for your platform.
 103
 104 Of course, your platform might provide more efficient replacements
 105 for the generic implementations offered by PDCLib. The math functions
 106 are an especially "juicy" target for optimization - while PDCLib does
 107 provide generic implementations for each of them, there are usually
 108 FPU opcodes that do the same job, only orders of magnitude faster. For
 109 this, you might want to create an "optimization overlay" for PDCLib.
 110
 111 Optimization Overlay
 112 --------------------
 113
 114 The basic idea of PDCLib is to provide a generic implementation that
 115 is useable even on platforms I have never heard of - for example, the
 116 OS and/or compiler *you* just wrote and now need a C library for. That
 117 is actually what PDCLib was written for: To provide a C library for
 118 compiler and OS builders that do not want the usual baggage of POSIX
 119 and GNU extensions, licensing considerations etc. etc.
 120
 121 Thus, PDCLib provides generic implementations. They do work, and do
 122 so correctly, but they are not very efficient when compared to hand-
 123 crafted assembler or compiler build-ins. So I wanted to provide a
 124 means to modify PDCLib to run more efficiently on a given platform,
 125 without cluttering the main branch with tons of #ifdef statements and
 126 "featureset #defines" that grow stale quickly.
 127
 128 The solution is the "optimization overlay". Every function has its
 129 own implementation file, which makes it possible to replace them
 130 piecemeal by copying a platform-specific overlay over the main PDCLib
 131 branch to create a PDCLib adapted / optimized for the platform in
 132 question. That overlay could be part of the PDCLib source tree (for
 133 established platforms where maintainers won't bother with PDCLib), or
 134 part of that platform's source tree (for under-development platforms
 135 PDCLib maintainers won't bother with).
 136
 137 So, to use PDCLib on your given platform, you unpack PDCLib (as you
 138 obviously have done already since you are reading this), and copy
 139 the overlay for your platform over the PDCLib source tree structure.
 140
 141 Development Status
 142 ------------------
 143
 144 v0.1 - 2004-12-12
 145 Freestanding-only C99 implementation without any overlay, and missing
 146 the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c
 147 values hardcoded into it; not sure whether to include enquire.c in the
 148 package, to leave <float.h> to the overlay, or devise some parameterized
 149 macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but
 150 I had to make the 0.1 release sometime so why not now.
 151
 152 v0.2 - 2005-01-12
 153 Adds implementations for <string.h> (excluding strerror()), INTN_C() /
 154 UINTN_C() macros, and some improvements in the internal headers.
 155 Test drivers still missing, but added warnings about that.
 156
 157 v0.3 - 2005-11-21
 158 Adds test drivers, fixes some bugs in <string.h>.
 159
 160 v0.4 - 2005-02-06
 161 Implementations for parts of <stdlib.h>. Still missing are the floating
 162 point conversions, and the wide-/multibyte-character functions.
 163
 164 v0.4.1 - 2006-11-16
 165 With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as
 166 a backport of bugfixes in the current development code.
 167 - #1  realloc( NULL, size ) fails           (fixed)
 168 - #2  stdlib.h - insufficient documentation (fixed)
 169 - #4  Misspelled name in credits            (fixed)
 170 - #5  malloc() splits off too-small nodes   (fixed)
 171 - #6  qsort() stack overflow                (fixed)
 172 - #7  malloc() bug in list handling         (fixed)
 173 - #8  strncmp() does not terminate at '\0'  (fixed)
 174 - #9  stdint.h dysfunctional                (fixed)
 175 - #10 NULL redefinition warnings            (fixed)
 176
 177 v0.5 - 2010-12-22
 178 Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,
 179 and strerror() from <string.h>.
 180 Still no locale / wide-char support. Enabled all GCC compiler warnings I
 181 could find, and fixed everything that threw a warning. (You see this,
 182 maintainers of Open Source software? No warnings whatsoever. Stop telling
 183 me it cannot be done.) Fixed all known bugs in the v0.4 release.
 184
 185
 186 A WORD ON THE v0.5 RELEASE
 187 ==========================
 188
 189 The v0.5 release is not well-tested. There are several things in it done
 190 in a way that I would never label "release quality". Some things are not
 191 even in the *structure* I would like them to be. An example for this is
 192 the current handling of errno values: It needlessly introduces dependency
 193 on PDCLib (because I use non-standard values), and the values are placed
 194 in the wrong header (_PDCLIB_int.h instead of _PDCLIB_glue.h where they
 195 would be more appropriate).
 196
 197 But at some point during the development toward the v0.5 release, I found
 198 that my current PDCLib work schedule simply does not allow me to wait
 199 until every piece of <stdio.h> is as I would like it to be. It would
 200 probably take another year or two, and my patience is UP.
 201
 202 I want this released, and I want to think about something else but
 203 <stdio.h> for some time.
 204
 205 So, expect significant change to how stdio is done in upcoming releases.
 206 Everything *WILL* be stable by the time v1.0 comes around, but until then
 207 you will have to accept that I can only deliver "hobby quality" for now.