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 The standard defines any identifiers starting with '_' and a capital
  58 letter as reserved for the implementation, and since the chances of
  59 your compiler using an identifier in the _PDCLIB_* range are slim,
  60 any strictly conforming 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) platform-specific implementation files;
  70 6) platform-specific, optimized "overlay" implementations (optional).
  71
  72 The standard headers (in ./includes/) only contain what they are
  73 defined to contain. Where additional logic or macro magic is
  74 necessary, that is deferred to the internal files. This has been done
  75 so that the headers are actually educational as to what they provide
  76 (as opposed to how the library does it).
  77
  78 Note that there *might* be some feature to remove this additional
  79 level of indirection for a production release, to ease the workload
  80 put on the preprocessor.
  81
  82 There is a seperate implementation file (in ./function/{header}/) for
  83 every function defined by the standard, named {function}.c. Not only
  84 does this avoid linking in huge amounts of unused code when you use
  85 but a single function, it also allows the optimization overlay to work
  86 (see below).
  87
  88 (The directory ./functions/_PDCLIB/ contains internal and helper
  89 functions that are not part of the standard.)
  90
  91 Then there are internal header files (in ./internal/), which contain
  92 all the "black magic" and "code fu" that was kept out of the standard
  93 headers. You should not have to touch them if you want to adapt PDCLib
  94 to a new platform. If you *do* have to touch them, note that the PDCLib
  95 author would consider it a serious design flaw, and would be happy to
  96 fix it in the next PDCLib release. Any adaption work should be covered
  97 by the steps detailed below.
  98
  99 For adapting PDCLib to a new platform (the trinity of CPU, operating
 100 system, and compiler), make a copy of the ./platform/example/ directory
 101 (named after your target platform), and modify the files of your copy
 102 to suit the constraints of your platform. When you are done, copy the
 103 contents of your platform directory over the source directory structure
 104 of PDCLib (or link them into the appropriate places). That should be
 105 all that is actually required to make PDCLib work for your platform.
 106
 107 Of course, your platform might provide more efficient replacements
 108 for the generic implementations offered by PDCLib. The math functions
 109 are an especially "juicy" target for optimization - while PDCLib does
 110 provide generic implementations for each of them, there are usually
 111 FPU opcodes that do the same job, only orders of magnitude faster. For
 112 this, you might want to create an "optimization overlay" for PDCLib.
 113
 114 Optimization Overlay
 115 --------------------
 116
 117 The idea is to provide a generic implementation that is useable even
 118 on platforms the author never heard of - for example, the OS and/or
 119 compiler *you* just wrote and now need a C library for. That is
 120 actually what PDCLib was written for: To provide a C library for
 121 compiler and OS builders that do not want the usual baggage of POSIX
 122 and GNU extensions, licensing considerations etc. etc.
 123
 124 Thus, PDCLib provides generic implementations. They do work, and do
 125 so correctly, but they are not very efficient when compared to hand-
 126 crafted assembler or compiler build-ins. So the author wanted to
 127 provide a means to modify PDCLib to run more efficiently on a given
 128 platform, without cluttering the main branch with tons of #ifdef
 129 statements and "featureset #defines" that grow stale quickly.
 130
 131 The solution is the "optimization overlay". Every function has its
 132 own implementation file, which makes it possible to replace them
 133 piecemeal by copying a platform-specific overlay over the main PDCLib
 134 branch to create a PDCLib adapted / optimized for the platform in
 135 question. That overlay could be part of the PDCLib source tree (for
 136 established platforms where maintainers won't bother with PDCLib), or
 137 part of that platform's source tree (for under-development platforms
 138 PDCLib maintainers won't bother with).
 139
 140 So, to use PDCLib on your given platform, you unpack PDCLib (as you
 141 obviously have done already since you are reading this), and copy
 142 the overlay for your platform over the PDCLib source tree structure.
 143
 144 Development Status
 145 ------------------
 146
 147 v0.1 - 2004-12-12
 148 Freestanding-only C99 implementation without any overlay, and missing
 149 the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c
 150 values hardcoded into it; not sure whether to include enquire.c in the
 151 package, to leave <float.h> to the overlay, or devise some parameterized
 152 macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but
 153 I had to make the 0.1 release sometime so why not now.
 154
 155 v0.2 - 2005-01-12
 156 Adds implementations for <string.h> (excluding strerror()), INTN_C() /
 157 UINTN_C() macros, and some improvements in the internal headers.
 158 Test drivers still missing, but added warnings about that.
 159
 160 v0.3 - 2005-11-21
 161 Adds test drivers, fixes some bugs in <string.h>.
 162
 163 v0.4 - 2005-02-06
 164 Implementations for parts of <stdlib.h>. Still missing are the floating
 165 point conversions, and the wide-/multibyte-character functions.
 166
 167 v0.5 - unreleased
 168 Implementations for parts of <stdio.h>. Still no locale / wide-char
 169 support. Enabled all GCC compiler warnings I could find, and fixed
 170 everything that threw a warning. (You see this, maintainers of Open
 171 Source software? No warnings whatsoever. Stop telling me it cannot
 172 be done.) Fixed all known bugs in the v0.4 release.