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

   1 $Id$
   2
   3 PDCLib - Public Domain C Library
   4 ================================
   5
   6 License
   7 -------
   8
   9 Permission is granted to use, modify, and / or redistribute at will.
  10
  11 This includes removing authorship notices, re-use of code parts in
  12 other software (with or without giving credit), and / or creating a
  13 commercial product based on it.
  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 What is it
  44 ----------
  45
  46 This is a C Standard Library. Nothing more, nothing less. No POSIX
  47 or other extensions, just what's defined in ISO/IEC 9899.
  48
  49 (Well, this is what it will be when the 1.0 release comes out. See
  50 the "Development Status" section to see what's implemented so far.)
  51
  52 Internals
  53 ---------
  54
  55 As a namespace convention, everything (files, typedefs, functions,
  56 macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB_*.
  57 As identifiers starting with '_' and a capital letter are reserved
  58 for the implementation, and the chances of you compiler using an
  59 identifier in the _PDCLIB_* range are slim, any strictly conforming
  60 application should work with PDCLib.
  61
  62 PDCLib consists of several parts:
  63
  64 1) standard headers;
  65 2) implementation files for standard functions;
  66 3) internal header files keeping complex stuff out of the standard
  67    headers;
  68 4) the central, platform-specific file _PDCLIB_config.h;
  69 5) optimization overlay implementation files (optional).
  70
  71 The standard headers only contain what they are defined to contain.
  72 Where additional logic or macro magic is necessary, that is deferred
  73 to the internal files. This has been done so that the headers are
  74 actually educational as to what they provide (as opposed to how the
  75 library does it).
  76
  77 There is a seperate implementation file for every function defined
  78 by the standard, named {function}.c. Not only does this avoid linking
  79 in huge amounts of unused code when you use but a single function,
  80 it also allows the optimization overlay to work (see below).
  81
  82 Then there are internal header files, which contain all the "black
  83 magic" and "code fu" that were kept out of the standard headers. You
  84 should not have to touch them if you want to adapt PDCLib to a new
  85 platform. If you do, note that the PDCLib author would consider it
  86 a serious design flaw, and would be happy to fix it in the next PDCLib
  87 release. Any adaption work should be covered by the config header
  88 (and, possibly, the optimization overlay).
  89
  90 For adapting PDCLib to a new platform (the trinity of CPU, operating
  91 system, and compiler), open _PDCLIB_config.h in your favourite text
  92 editor, have a look at the comments, and modify it as appropriate for
  93 your platform. That should be all that is actually required for such
  94 an adaption (see previous paragraph).
  95
  96 Of course, your platform might provide more efficient replacements
  97 for the generic implementations offered by PDCLib. The math functions
  98 are an especially "juicy" target for optimization - while PDCLib does
  99 provide generic implementations for each of them, there are usually
 100 FPU opcodes that do the same job, only orders of magnitude faster. For
 101 this, you might want to create an "optimization overlay" for PDCLib.
 102
 103 Optimization Overlay
 104 --------------------
 105
 106 The idea is to provide a generic implementation that is useable even
 107 on platforms the author never heard of - for example, the OS and/or
 108 compiler *you* just wrote and now need a C library for. That is
 109 actually what PDCLib was written for: To provide a C library for
 110 compiler and OS builders that do not want the usual baggage of POSIX
 111 and GNU extensions, licensing considerations etc. etc.
 112
 113 Thus, PDCLib provides generic implementations. They do work, and do
 114 so correctly, but they are not very efficient when compared to hand-
 115 crafted assembler or compiler build-ins. So the author wanted to
 116 provide a means to modify PDCLib to run more efficiently on a given
 117 platform, without cluttering the main branch with tons of #ifdef
 118 statements and "featureset defines" that grow stale quickly.
 119
 120 The solution is the "optimization overlay". Every function has its
 121 own implementation file, and _PDCLIB_config.h should be the only
 122 header that must be modified. So, a platform-specific overlay is
 123 copied over the main PDCLib branch - replacing _PDCLIB_config.h and
 124 any number of implementation files - to create a PDCLib adapted /
 125 optimized for the platform in question. That overlay could be part
 126 of the PDCLib source tree (for established platforms where maintainers
 127 won't bother with PDCLib), or part of that platform's source tree
 128 (for under-development platforms PDCLib maintainers won't bother with).
 129
 130 So, to use PDCLib on your given platform, you unpack PDCLib (as you
 131 obviously have done already since you are reading this), and copy
 132 the overlay for your platform over the PDCLib source tree structure.
 133
 134 Development Status
 135 ------------------
 136
 137 v0.1 - 2004-12-12
 138 Freestanding-only C99 implementation without any overlay, and missing
 139 the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c
 140 values hardcoded into it; not sure whether to include enquire.c in the
 141 package, to leave <float.h> to the overlay, or devise some parameterized
 142 macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but
 143 I had to make the 0.1 release sometime so why not now.
 144
 145 v0.2 - 2005-01-12
 146 Adds implementations for <string.h> (excluding strerror()), INTN_C() /
 147 UINTN_C() macros, and some improvements in the internal headers.
 148 Test drivers still missing, but added warnings about that.
 149
 150 v0.3 - 2005-11-21
 151 Adds test drivers, fixes some bugs in <string.h>.
 152
 153 v0.4 - 2005-02-06
 154 Implementations for parts of <stdlib.h>. Still missing are the floating
 155 point conversions, and the wide-/multibyte-character functions.
 156
 157 v0.5 - unreleased
 158 Implementations for parts of <stdio.h>. Bug fixes. Still no locale /
 159 wide-char support. Enabled all GCC compiler warnings I could find, and
 160 fixed everything that threw a warning. Fixed all open bugs in the v0.4
 161 release.
 162