Bring README a little bit closer to reality.

1 files changed, 33 insertions, 43 deletions

diff --git a/README b/README
index 05a49b99..16a44559 100644
--- a/README
+++ b/README
@@ -9,6 +9,7 @@ README for morph
 an embedded Linux solution. Some important points:
 
 * everything is built from **source in git**, not release tarballs
+  and not from uncommitted changes
 * a binary is called a **stratum**, and is a collection of software that forms 
   a whole, e.g., the core system for Baserock, the essential build tools 
   for Baserock, or the GNOME platform libraries
@@ -30,52 +31,45 @@ In other words:
 The build of a chunk or a stratum is controlled by a
 **morphology**, which consists of:
 
-* a name
 * type of result: chunk or stratum
-* for a chunk, a triple of git repository, branch, and commit reference
-* for a stratum, one or more such triplets
-* the commands for configuring, building, testing, and installing the project
+* for a chunk, lists of commands for configuring, building, testing, and
+  installing the program
+* for a stratum, one or more specifications of which chunks to build:
+  pairs of git repositories and commit references
 
 JSON is used for the morphology syntax. For example, to build a chunk:
 
     {
-        "name": "busybox",
         "kind": "chunk",
-        "source": {
-            "repo": "git://git.baserock.org/busybox/",
-            "ref": "HEAD",
-        },
         "configure-commands": [
-            "./configure --prefix=$PREFIX",
+            "./configure --prefix=$PREFIX"
         ],
         "build-commands": [
-            "make",
+            "make"
         ],
         "test-commands": [
-            "make check",
+            "make check"
         ],
         "install-commands": [
-            "make DESTDIR=$DESTDIR install",
+            "make DESTDIR=$DESTDIR install"
         ]
     }
 
 (Later, there will be defaults and things to make the morph files shorter.)
 
 To build a stratum:
-
     {
-        "name": "core",
         "kind": "stratum",
-        "source": [
+        "sources": [
             {
                 "repo": "git://git.baserock.org/busybox/",
-                "ref": "DEADBEEF",
+                "ref": "DEADBEEF"
             },
             {
                 "repo": "git://git.baserock.org/gzip/",
-                "ref": "CAFEBABE",
-            },
-        ],
+                "ref": "CAFEBABE"
+            }
+        ]
     }
 
 To use morph, create the relevant morphology files (`*.morph`),
@@ -93,26 +87,25 @@ Morphology spec
 A morphology is a JSON file with a single object (dict), with the
 following keys:
 
-* `name`: a string
 * `kind`: either `chunk` or `stratum`
-  - question: could this be deduced automatically?
-* `source`: either a single dict (for chunks), or a list of dicts
-   (for strata), with the following keys:
+* `sources`: a dict, whose keys are names and the corresponding values
+  are dicts with the following keys (the top level names are
+  for documentation only):
   - `repo`: URL to git repository
     - the URL may be relative to the value given to the
       `--git-base-url` option
   - `ref`: a reference to a commit (either a commit id, or `HEAD`)
-* chunks may also have the following keys:
-  - `configure-commands`: a list of strings giving shell commands
-    that should be executed to configure the software being built
-    (can also be a single string instead of a list)
-  - `build-commands`: similarly, commands for building the software
-  - `test-commands`: similarly, commands for running automatic tests
-    on the built (but uninstalled) software
-  - `install-commands` similarly, commands for installing the software
+* `configure-commands`: a list of strings giving shell commands
+  that should be executed to configure the software being built
+  (can also be a single string instead of a list)
+* `build-commands`: similarly, commands for building the software
+* `test-commands`: similarly, commands for running automatic tests
+  on the built (but uninstalled) software
+* `install-commands` similarly, commands for installing the software
 
 Unknown keys are errors. Known keys with the wrong kind of values
-result in an error.
+result in an error. Keys that are valid only for chunks are errors
+when given for strata, and vice versa.
 
 Commands run during the building of a chunk are passed on to the shell 
 for execution, and may refer to the following extra environment variables:
@@ -133,30 +126,27 @@ in the current working directory.
 
 During the build of a chunk, morph goes through the following steps:
 
-* clone the git repository into a fresh location
-  - note: later a way to cache the clones will be added, e.g., to use
-    any locally available git clones
 * export the files from git to a temporary location, so the build happens
   in a clean directory
 * configure, build, and test the software
-* create a temporary directory into which the software is installed
-* install the software there
+* install the software into a temporary directory
 * create a chunk file of the contents of the temporary directory
-* clean up by removing temporary stuff
+* clean up by removing all temporary stuff 
+  (a "make clean" target is **not** run)
 * put chunk and build log and other deliverables in their places
 
 For strata, morph does this instead:
 
+* build all chunks missing from the chunk directory
 * create a temporary directory
 * unpack all the chunks into the temporary directory
 * create a stratum file from the temporary directory
 * clean up
 * put stratum file and build log and other deliverables in their places
 
-For the first minimal, "hello world" version of morph, building a
-stratum does not build any missing chunks automatically. You have
-to build them manually.
-
+As a morph user, you should never need to build chunks manually.
+Just create stratum morphologies, and build those: the chunks get
+built automatically.
 
 File formats
 ------------