+$Id$
+
PDCLib - Public Domain C Library
================================
other software (with or without giving credit), and / or creating a
commercial product based on it.
+This permission is not revocable by the author.
+
This software is provided as-is. Use it at your own risk. There is
no warranty whatsoever, neither expressed nor implied, and by using
this software you accept that the author(s) shall not be held liable
under a "license" that should not be neccessary in the first place:
"Free" should have been enough.
+Unfortunately, German law does not even *allow* to declare a work to
+be "in the Public Domain", so the "free for all" license I intended
+had to be made expressively.
+
What is it
----------
---------
As a namespace convention, everything (files, typedefs, functions,
-macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB_*.
-As identifiers starting with '_' and a capital letter are reserved
-for the implementation, and the chances of you compiler using an
-identifier in the _PDCLIB_* range are slim, any strictly conforming
-application should work with PDCLib.
+macros) not defined in ISO/IEC 9899 is prefixed with _PDCLIB.
+The standard defines any identifiers starting with '_' and a capital
+letter as reserved for the implementation, and since the chances of
+your compiler using an identifier in the _PDCLIB range are slim,
+any strictly conforming application should work with this library.
PDCLib consists of several parts:
3) internal header files keeping complex stuff out of the standard
headers;
4) the central, platform-specific file _PDCLIB_config.h;
-5) optimization overlay implementation files (optional).
-
-The standard headers only contain what they are defined to contain.
-Where additional logic or macro magic is necessary, that is deferred
-to the internal files. This has been done so that the headers are
-actually educational as to what they provide (as opposed to how the
-library does it).
-
-There is a seperate implementation file for every function defined
-by the standard, named {function}.c. Not only does this avoid linking
-in huge amounts of unused code when you use but a single function,
-it also allows the optimization overlay to work (see below).
-
-Then there are internal header files, which contain all the "black
-magic" and "code fu" that were kept out of the standard headers. You
-should not have to touch them if you want to adapt PDCLib to a new
-platform. If you do, note that the PDCLib author would consider it
-a serious design flaw, and would be happy to fix it in the next PDCLib
-release. Any adaption work should be covered by the config header
-(and, possibly, the optimization overlay).
+5) platform-specific implementation files;
+6) platform-specific, optimized "overlay" implementations (optional).
+
+The standard headers (in ./includes/) only contain what they are
+defined to contain. Where additional logic or macro magic is
+necessary, that is deferred to the internal files. This has been done
+so that the headers are actually educational as to what they provide
+(as opposed to how the library does it).
+
+Note that there *might* be some feature to remove this additional
+level of indirection for a production release, to ease the workload
+put on the preprocessor.
+
+There is a seperate implementation file (in ./function/{header}/) for
+every function defined by the standard, named {function}.c. Not only
+does this avoid linking in huge amounts of unused code when you use
+but a single function, it also allows the optimization overlay to work
+(see below).
+
+(The directory ./functions/_PDCLIB/ contains internal and helper
+functions that are not part of the standard.)
+
+Then there are internal header files (in ./internal/), which contain
+all the "black magic" and "code fu" that was kept out of the standard
+headers. You should not have to touch them if you want to adapt PDCLib
+to a new platform. Note that, if you *do* have to touch them, I would
+consider it a serious design flaw, and would be happy to fix it in the
+next PDCLib release. Any adaption work should be covered by the steps
+detailed below.
For adapting PDCLib to a new platform (the trinity of CPU, operating
-system, and compiler), open _PDCLIB_config.h in your favourite text
-editor, have a look at the comments, and modify it as appropriate for
-your platform. That should be all that is actually required for such
-an adaption (see previous paragraph).
+system, and compiler), make a copy of ./platform/example/ named
+./platform/{your_platform}/, and modify the files of your copy to suit
+the constraints of your platform. When you are done, copy the contents
+of your platform directory over the source directory structure
+of PDCLib (or link them into the appropriate places). That should be
+all that is actually required to make PDCLib work for your platform.
Of course, your platform might provide more efficient replacements
for the generic implementations offered by PDCLib. The math functions
Optimization Overlay
--------------------
-The idea is to provide a generic implementation that is useable even
-on platforms the author never heard of - for example, the OS and/or
-compiler *you* just wrote and now need a C library for. That is
-actually what PDCLib was written for: To provide a C library for
+The basic idea of PDCLib is to provide a generic implementation that
+is useable even on platforms I have never heard of - for example, the
+OS and/or compiler *you* just wrote and now need a C library for. That
+is actually what PDCLib was written for: To provide a C library for
compiler and OS builders that do not want the usual baggage of POSIX
and GNU extensions, licensing considerations etc. etc.
Thus, PDCLib provides generic implementations. They do work, and do
so correctly, but they are not very efficient when compared to hand-
-crafted assembler or compiler build-ins. So the author wanted to
-provide a means to modify PDCLib to run more efficiently on a given
-platform, without cluttering the main branch with tons of #ifdef
-statements and "featureset defines" that grow stale quickly.
+crafted assembler or compiler build-ins. So I wanted to provide a
+means to modify PDCLib to run more efficiently on a given platform,
+without cluttering the main branch with tons of #ifdef statements and
+"featureset #defines" that grow stale quickly.
The solution is the "optimization overlay". Every function has its
-own implementation file, and _PDCLIB_config.h should be the only
-header that must be modified. So, a platform-specific overlay is
-copied over the main PDCLib branch - replacing _PDCLIB_config.h and
-any number of implementation files - to create a PDCLib adapted /
-optimized for the platform in question. That overlay could be part
-of the PDCLib source tree (for established platforms where maintainers
-won't bother with PDCLib), or part of that platform's source tree
-(for under-development platforms PDCLib maintainers won't bother with).
+own implementation file, which makes it possible to replace them
+piecemeal by copying a platform-specific overlay over the main PDCLib
+branch to create a PDCLib adapted / optimized for the platform in
+question. That overlay could be part of the PDCLib source tree (for
+established platforms where maintainers won't bother with PDCLib), or
+part of that platform's source tree (for under-development platforms
+PDCLib maintainers won't bother with).
So, to use PDCLib on your given platform, you unpack PDCLib (as you
obviously have done already since you are reading this), and copy
v0.3 - 2005-11-21
Adds test drivers, fixes some bugs in <string.h>.
-v0.4 - unreleased
-Implementations for parts of <stdlib.h>.
-(strtol, strtoul, atoi, atol, atoll, rand, srand, bsearch, qsort.)
+v0.4 - 2005-02-06
+Implementations for parts of <stdlib.h>. Still missing are the floating
+point conversions, and the wide-/multibyte-character functions.
+
+v0.4.1 - 2006-11-16
+With v0.5 (<stdio.h>) taking longer than expected, v0.4.1 was set up as
+a backport of bugfixes in the current development code.
+- #1 realloc( NULL, size ) fails (fixed)
+- #2 stdlib.h - insufficient documentation (fixed)
+- #4 Misspelled name in credits (fixed)
+- #5 malloc() splits off too-small nodes (fixed)
+- #6 qsort() stack overflow (fixed)
+- #7 malloc() bug in list handling (fixed)
+- #8 strncmp() does not terminate at '\0' (fixed)
+- #9 stdint.h dysfunctional (fixed)
+- #10 NULL redefinition warnings (fixed)
+
+v0.5 - 2010-12-22
+Implementations for <inttypes.h>, <errno.h>, most parts of <stdio.h>,
+and strerror() from <string.h>.
+Still no locale / wide-char support. Enabled all GCC compiler warnings I
+could find, and fixed everything that threw a warning. (You see this,
+maintainers of Open Source software? No warnings whatsoever. Stop telling
+me it cannot be done.) Fixed all known bugs in the v0.4 release.
+
+
+A WORD ON THE v0.5 RELEASE
+==========================
+
+The v0.5 release is not well-tested. There are several things in it done
+in a way that I would never label "release quality". Some things are not
+even in the *structure* I would like them to be. An example for this is
+the current handling of errno values: It needlessly introduces dependency
+on PDCLib (because I use non-standard values), and the values are placed
+in the wrong header (_PDCLIB_int.h instead of _PDCLIB_glue.h where they
+would be more appropriate).
+
+But at some point during the development toward the v0.5 release, I found
+that my current PDCLib work schedule simply does not allow me to wait
+until every piece of <stdio.h> is as I would like it to be. It would
+probably take another year or two, and my patience is UP.
+
+I want this released, and I want to think about something else but
+<stdio.h> for some time.
+
+So, expect significant change to how stdio is done in upcoming releases.
+Everything *WILL* be stable by the time v1.0 comes around, but until then
+you will have to accept that I can only deliver "hobby quality" for now.
+
projects / fw / pdclib / blobdiff