Documentation for sdk-example-cluster

Also, rename from just 'sdk' so that it's clear this is an example of usage
of the 'sdk' write extension.

Reviewed-By: Richard Maw (on IRC)
Reviewed-By: Lars Wirzenius (on IRC)

2 files changed, 46 insertions, 18 deletions

diff --git a/sdk-example-cluster.morph b/sdk-example-cluster.morph
new file mode 100644
index 00000000..da0a6fff
--- /dev/null
+++ b/sdk-example-cluster.morph
@@ -0,0 +1,46 @@
+name: sdk
+kind: cluster
+description: |
+  An example of creating a cross-compile SDK for an embedded Baserock system.
+
+  This cluster demonstrates how you can use the 'sdk' write extension to
+  produce a cross-compile SDK tarball for an Baserock applicance. In this
+  example the system is assumed to run on ARMv7, and the SDK is built to
+  run on any x86_32 GNU/Linux system.
+
+  The SDK is a Baserock system itself, containing just 'build-essential' and a
+  'cross-toolchain' stratum. The SDK system also includes the target
+  appliance's system, as a 'subsystem', so that the libraries and headers are
+  available when building.
+
+  This cluster deploys the SDK system using the 'sdk' write extension, which
+  produces a tarball with a small shell header. When the shell header is
+  executed, and passed a directory name on the commandline, it extracts the SDK
+  to that path and patches the binaries so that they execute correctly from
+  that directory.
+
+  Deploying the applicate system artifact to the target device should be
+  done with a separate cluster morphology, because you will often want to
+  do this without rebuilding the SDK.
+
+  You must build each system with `morph build` before deploying. We recommend
+  doing this all from your Baserock development machine, using a Baserock
+  ARM distributed build network to produce the system artifact. Once both
+  system artifacts are cached locally, the `morph deploy` command will produce
+  a self-extracting shell script/tarball following the 'location' field.
+
+  See the documentation of the sdk.write extension for more information.
+systems:
+- morph: armv7lhf-cross-toolchain-system-x86_32-generic
+  deploy:
+    sdk:
+      type: sdk
+      location: armv7lhf-cross-toolchain-system-x86_32-generic.sh
+      PREFIX: /usr
+      TARGET: armv7lhf-baserock-linux-gnueabi
+  subsystems:
+  - morph: devel-system-armv7lhf-highbank
+    deploy:
+      sysroot:
+        type: sysroot
+        location: usr/armv7lhf-baserock-linux-gnueabi/sys-root
diff --git a/sdk.morph b/sdk.morph
deleted file mode 100644
index c7eb3e44..00000000
--- a/sdk.morph
+++ /dev/null
@@ -1,18 +0,0 @@
-name: sdk
-kind: cluster
-description: |
-  Create SDK binaries for all supported targets
-systems:
-- morph: armv7lhf-cross-toolchain-system-x86_32-generic
-  deploy:
-    sdk:
-      type: sdk
-      location: armv7lhf-cross-toolchain-system-x86_32-generic.sh
-      PREFIX: /usr
-      TARGET: armv7lhf-baserock-linux-gnueabi
-  subsystems:
-  - morph: devel-system-armv7lhf-highbank
-    deploy:
-      sysroot:
-        type: sysroot
-        location: usr/armv7lhf-baserock-linux-gnueabi/sys-root