From ad07bf77f733d8d4c823c63fc2c423f57d063258 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pj@pehjota.net>
Date: Tue, 23 Feb 2016 13:57:55 -0500
Subject: README: New file

---
(limited to 'README')

diff --git a/README b/README
new file mode 100644
index 0000000..9f802aa
--- /dev/null
+++ b/README
@@ -0,0 +1,48 @@
+Eggshell Language
+=================
+
+Eggshell is an extension to (and proper superset of) shell command
+language as specified by the POSIX.1 Shell and Utilities (XCU) Volume
+and implemented by many Bourne- and Korn-compatible shells.  It enables
+programs to be written, compiled, and linked like C programs and then
+executed on any POSIX-conformant shell.
+
+Features
+--------
+
+  * Static global variables and functions that are visible and
+    persistent only within their translation unit
+  * Proper local variables that, unlike in shells with a "local" command, are
+    visible and persistent only within their function's frame in the call stack
+    and are not clobbered by recursive function calls
+  * Initialization function attribute
+  * Stack trace function
+
+Eggshell Toolchain
+==================
+
+eshtrans is a compiler (or "translator"), like the cc1 compiler of GCC.
+It parses Eggshell source files and generates shell command language
+object files.
+
+eshld is a build-time linker, like ld of GNU Binutils.  It reads object
+files built by eshtrans, adds a magic number ("#!") with interpreter
+path and Eggshell runtime library, and generates an output program.  The
+Eggshell runtime library "eshrt", somewhat like crt0 of GCC, defines
+functions for call stack management, function and translation unit
+context switching, declaration of static and local variables, and the
+calling of initialization functions.
+
+eshc (not yet written) is a compiler driver, like the gcc compiler
+driver of GCC.  It runs eshtrans and eshld.
+
+Portability
+===========
+
+Since the Eggshell toolchain translates programs into shell command language and
+implements Eggshell's features in a small and portable runtime library, Eggshell
+programs can be portable to any POSIX-conformant shell.
+
+The Eggshell toolchain is tested to build programs that run on GNU Bourne Again
+SHell (bash), Debian Almquist Shell (dash), BusyBox Almquist Shell (ash),
+KornShell (ksh93), MirBSD Korn Shell (mksh), and Z Shell (zsh).
--
cgit v0.9.1