2006-12-09 Marcus Brinkmann <marcus@g10code.de>

	* src/Makefile.am (EXTRA_DIST): Add README.
	* src/README: New file.

1 files changed, 47 insertions, 0 deletions

diff --git a/src/README b/src/README
new file mode 100644
index 0000000..c415983
--- /dev/null
+++ b/src/README
@@ -0,0 +1,47 @@
+Notes on the source code
+========================
+
+The mechanism to generate the system error codes is delicate and
+fragile, but it's the best I could come up with that supports
+cross-compilation and dynamic self-configuration.  Here is how it
+works:
+
+1. Generate list of supported system error codes.
+
+mkerrcodes1.awk generates a list of supported system error codes from
+errnos.in.  Each entry in the list is protected with #ifdef/#endif,
+and contains a GPG_ERR_* marker.  The list is stored in "_mkerrcodes.h".
+
+2. The HOST cpp is run on _mkerrcodes.h.  This evaluates the known
+system error macros to something (may be a number, maybe a constant
+expression as on the GNU/Hurd), suppressing the unknown ones.  The
+output is piped into step 3.
+
+3. The cpp output is filtered with grep for only those lines which
+contain a GPG_ERR_* marker.  The output is piped into step 4.
+
+4. The filtered output is processed by mkerrcodes.awk, which produces
+a table of constant expressions plus GPG_ERR_* code string symbols in
+a format suitable for the C program mkerrcodes.c.  At this point we
+are crossing our fingers that the constant expressions produced by the
+system do not contain GPG_ERR_* markers.  The output is stored in
+mkerrcodes.h.
+
+5. The file mkerrcodes.h is included by mkerrcodes.c, which is
+compiled to a binary executable on the BUILD system.  At this point we
+are crossing our fingers that the constant expressions produced by the
+system do not depend on the build platform anymore.  The output is
+post-processed by mkerrcodes2.awk and stored in "code-from-errno.h",
+which is subsequently used in the library.
+
+-- Marcus
+
+ Copyright 2006 g10 Code GmbH
+
+ This file is free software; as a special exception the author gives
+ unlimited permission to copy and/or distribute it, with or without
+ modifications, as long as this notice is preserved.
+
+ This file is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+ implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.