X-Git-Url: https://pd.if.org/git/?a=blobdiff_plain;f=Readme.txt;h=77762e5ffedc03ef9a2a2ac8e70d3d3a1941ba4a;hb=82ad725339311dab6bc2c28524e71d0cfaacab25;hp=7e2a6c75ae7774b21669f318c30f05f45cfee857;hpb=acc89aa5b4b903446f1334e24cf47e54cabfbfd4;p=pdclib
diff --git a/Readme.txt b/Readme.txt
index 7e2a6c7..77762e5 100644
--- a/Readme.txt
+++ b/Readme.txt
@@ -1,131 +1,162 @@
-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 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
-incidential 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.
-
-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_*.
-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.
-
-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) 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).
-
-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).
-
-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 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
-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.
-
-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).
-
-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.
-
+PDCLib - Public Domain C Library
+================================
+
+License
+-------
+
+Written in 2003-2012 by Martin "Solar" Baute,
+ 2012- by Owen Shepherd
+
+To the extent possible under law, the author(s) have dedicated all copyright
+and related and neighboring rights to this software to the public domain
+worldwide. This software is distributed without any warranty.
+
+You should have received a copy of the CC0 Public Domain Dedication along with
+this software. If not, see .
+
+NOTE: Some configuration options may include components under non-public domain
+ conditions. In particular, selecting ptmalloc3 as the malloc
+ implementation will cause the incorporation of elements under the BSD
+ license.
+
+What is it
+----------
+
+This is a C Standard Library - what's defined in ISO/IEC 9899 "Information
+technology â Programming languages â C" or extensions to the above defined in
+ISO/IEC 14882 "Information technology â Programming languages â C++". A few
+extensions may optionally be provided.
+
+Terms for extensions
+--------------------
+Extensions are permitted where their inclusion is reasonable, they are widely
+used, in keeping with the spirit of the standard, and do not convey
+additional requirements upon the target system, and do not needlessly duplicate
+functionality already contained within the standard.
+
+As an example: strdup is in, because (a) it can be implemented entirely in
+terms of existing standard C functions and (b) is very widely used. Something
+like open, write or close would not be considered, because it implies POSIXy
+assumptions.
+
+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;
+
+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).
+
+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.
+
+Future directions
+-----------------
+Obviously, full C89, C99 and C11 conformance; and full support for the
+applicable portions of C++98, C++03 and C++11.
+
+Support for "optimization overlays." These would allow efficient
+implementations of certain functions on individual platforms, for example
+memcpy, strcpy and memset. This requires further work to only compile in one
+version of a given function.
+
+Development Status
+------------------
+
+v0.1 - 2004-12-12
+Freestanding-only C99 implementation without any overlay, and missing
+the INTN_C() / UINTN_C() macros. still has the enquire.c
+values hardcoded into it; not sure whether to include enquire.c in the
+package, to leave to the overlay, or devise some parameterized
+macro magic as for / . 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 (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 .
+
+v0.4 - 2005-02-06
+Implementations for parts of . Still missing are the floating
+point conversions, and the wide-/multibyte-character functions.
+
+v0.4.1 - 2006-11-16
+With v0.5 () 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 , , most parts of ,
+and strerror() from .
+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.
+
+Near Future
+-----------
+Current development directions are:
+
+Implement portions of the C11 standard that have a direct impact on the way
+that PDCLib itself is built. For example, in order to support multithreading,
+PDCLib needs a threading abstraction; therefore, C11's thread library is being
+implemented to provide the backing for this (as there is no purpose in
+implementing two abstractions)
+
+Cleanup portions of , particularly the backend. _PDCLIB_fillbuffer and
+_PDCLIB_flushbuffer in particular do not feel 'well' factored and need to know
+too much about FILE's internals.
+
+Modularize the library somewhat. This can already be seen with components under
+"opt/". This structure is preliminary; it will likely change as the process
+continues.
\ No newline at end of file