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

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