-$Id$
-
-PDCLib - Public Domain C Library
-================================
-
-License
--------
-
-Permission is granted to use, modify, and / or redistribute at will.
-
-This includes removing authorship notices, re-use of code parts in
-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
-for any loss of data, loss of service, or other damages, be they
-incidental or consequential. Your only option other than accepting
-this is not to use the software at all.
-
-A case for Public Domain
-------------------------
-
-There was a time when you could just post a piece of code to usenet
-and say, "I give it away for free; perhaps it's useful for you."
-
-Then came the lawyers.
-
-There are building blocks in software engineering that are so basic
-that everyone should have free access to them without having to
-employ a complete legal department for advice. They should be FREE.
-Available for free, free of licensing implications, free of attached
-propaganda, free of everything but their useful self.
-
-Today, even the term "free" has to be defined by several paragraphs
-of legal blah-blah.
-
-Sick and tired of it, the author brought you this piece of software
-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
-----------
-
-This is a C Standard Library. Nothing more, nothing less. No POSIX
-or other extensions, just what's defined in ISO/IEC 9899.
-
-(Well, this is what it will be when the 1.0 release comes out. See
-the "Development Status" section to see what's implemented so far.)
-
-Internals
----------
-
-As a namespace convention, everything (files, typedefs, functions,
-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:
-
-1) standard headers;
-2) implementation files for standard functions;
-3) internal header files keeping complex stuff out of the standard
- headers;
-4) the central, platform-specific file _PDCLIB_config.h;
-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), 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
-are an especially "juicy" target for optimization - while PDCLib does
-provide generic implementations for each of them, there are usually
-FPU opcodes that do the same job, only orders of magnitude faster. For
-this, you might want to create an "optimization overlay" for PDCLib.
-
-Optimization Overlay
---------------------
-
-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 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, 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
-the overlay for your platform over the PDCLib source tree structure.
-
-Development Status
-------------------
-
-v0.1 - 2004-12-12
-Freestanding-only C99 implementation without any overlay, and missing
-the INTN_C() / UINTN_C() macros. <float.h> still has the enquire.c
-values hardcoded into it; not sure whether to include enquire.c in the
-package, to leave <float.h> to the overlay, or devise some parameterized
-macro magic as for <limits.h> / <stdint.h>. Not thoroughly tested, but
-I had to make the 0.1 release sometime so why not now.
-
-v0.2 - 2005-01-12
-Adds implementations for <string.h> (excluding strerror()), INTN_C() /
-UINTN_C() macros, and some improvements in the internal headers.
-Test drivers still missing, but added warnings about that.
-
-v0.3 - 2005-11-21
-Adds test drivers, fixes some bugs in <string.h>.
-
-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 / pdclib / commitdiff