Add image doc projectimage-authoring

16 files changed, 734 insertions, 1 deletions

diff --git a/doc/source/image/elements/base.bst b/doc/source/image/elements/base.bst
new file mode 100644
index 000000000..b43bea8f1
--- /dev/null
+++ b/doc/source/image/elements/base.bst
@@ -0,0 +1,7 @@
+# elements/base.bst
+
+kind: import
+sources:
+- kind: docker
+  url: https://registry.hub.docker.com/library/buildstream/image-tools/
+  track: latest
diff --git a/doc/source/image/elements/contents.bst b/doc/source/image/elements/contents.bst
new file mode 100644
index 000000000..f00cf9520
--- /dev/null
+++ b/doc/source/image/elements/contents.bst
@@ -0,0 +1,7 @@
+# elements/contents.bst
+
+kind: stack
+description: The image contents
+depends:
+  - contents/hello.bst
+  - contents/busybox.bst
diff --git a/doc/source/image/elements/contents/busybox.bst b/doc/source/image/elements/contents/busybox.bst
new file mode 100644
index 000000000..985152856
--- /dev/null
+++ b/doc/source/image/elements/contents/busybox.bst
@@ -0,0 +1,52 @@
+# elements/contents/busybox.bst
+
+kind: manual
+
+sources:
+- kind: tar
+  url: busybox:busybox-1.27.2.tar.bz2
+depends:
+- filename: base.bst
+  type: build
+- filename: contents/musl.bst
+  type: runtime
+
+environment:
+  PATH: /usr/bin:/bin:/usr/sbin:/sbin:/tools/bin:/tools/sbin
+
+config:
+  configure-commands:
+  # Busybox's default config has everything enabled.
+  - make defconfig KCONFIG_NOTIMESTAMP=1
+
+  # None of this is needed because we have kmod; and it actually breaks the
+  # Linux build because depmod isn't compatible enough with util-linux's.
+  - sed -e 's/CONFIG_DEPMOD=y.*/# CONFIG_DEPMOD is not set/' -i .config
+  - sed -e 's/CONFIG_INSMOD=y.*/# CONFIG_INSMOD is not set/' -i .config
+  - sed -e 's/CONFIG_MODPROBE=y.*/# CONFIG_MODPROBE is not set/' -i .config
+  - sed -e 's/CONFIG_MODPROBE_SMALL=y.*/# CONFIG_MODPROBE_SMALL is not set/' -i .config
+  - sed -e 's/CONFIG_LSMOD=y.*/# CONFIG_LSMOD is not set/' -i .config
+  - sed -e 's/CONFIG_RMMOD=y.*/# CONFIG_RMMOD is not set/' -i .config
+
+  build-commands:
+  - make KCONFIG_NOTIMESTAMP=1
+
+  install-commands:
+  - |
+    # Note here we intentionally ignore '%{prefix}', this is going into '/'
+    make CONFIG_PREFIX="%{install-root}" KCONFIG_NOTIMESTAMP=1 install &&
+    chmod 6755 "%{install-root}/bin/busybox"
+
+  # We need to prepare the system for creating files in /etc later
+  # (/etc/fstab, for example)
+  - mkdir -p "%{install-root}/etc"
+
+public:
+  bst:
+    split-rules:
+      runtime:
+        (>):
+        - |
+          /bin/*
+        - |
+          /sbin/*
diff --git a/doc/source/image/elements/contents/hello.bst b/doc/source/image/elements/contents/hello.bst
new file mode 100644
index 000000000..2bbddb4f6
--- /dev/null
+++ b/doc/source/image/elements/contents/hello.bst
@@ -0,0 +1,12 @@
+# elements/contents/hello.bst
+
+kind: import
+
+sources:
+  - kind: local
+    path: files/hello
+    directory: /usr/bin
+
+depends:
+  - filename: contents/busybox.bst
+    type: runtime
diff --git a/doc/source/image/elements/contents/musl.bst b/doc/source/image/elements/contents/musl.bst
new file mode 100644
index 000000000..d591ab2d1
--- /dev/null
+++ b/doc/source/image/elements/contents/musl.bst
@@ -0,0 +1,16 @@
+# elements/contents/musl.bst
+
+kind: autotools
+
+sources:
+- kind: tar
+  url: https://www.musl-libc.org/releases/musl-1.1.18.tar.gz
+
+  ref: d017ee5d01aec0c522a1330fdff06b1e428cb409e1db819cc4935d5da4a5a118
+depends:
+- filename: base.bst
+  type: build
+
+config:
+  configure-commands:
+  - '%{configure}'
diff --git a/doc/source/image/elements/image-x86_64.bst b/doc/source/image/elements/image-x86_64.bst
new file mode 100644
index 000000000..f2af428c3
--- /dev/null
+++ b/doc/source/image/elements/image-x86_64.bst
@@ -0,0 +1,50 @@
+# elements/image-x86_64.bst
+
+# Specify the plugin reference - we want to import the x86image plugin
+# from buildstream-external
+kind: x86image
+description: Create a deployment of a Linux system
+depends:
+  - filename: image/system.bst
+    type: build
+  - filename: base.bst
+    type: build
+
+# Boot image settings; the defaults can work, but you almost certainly
+# want to customize them to match your image requirements.
+#
+# These settings are tailored to this specific project, don't just
+# blindly copy.
+variables:
+  # Size of the disk to create
+  #
+  # Should be able to calculate this based on the space
+  # used, however it must be a multiple of (63 * 512) bytes
+  # as mtools wants a size that is divisible by sectors (512 bytes)
+  # per track (63).
+  boot-size: 16M
+  rootfs-size: 69M
+  sector-size: 512
+  swap-size: 40K
+  kernel-args: root=/dev/sda2 rootfstype=ext4 init=/sbin/init console=ttyS0
+  kernel-name: vmlinuz-4.14.3
+
+config:
+  # The element that should be staged into "/". It must contain
+  # all the tools required to generate the image
+  base: base.bst
+
+  # The element that should be staged into %{build-root}. It is expected
+  # to be the system that you're planning to turn into an image.
+  input: image/system.bst
+
+  # This is technically not necessary, but convenient for trying
+  # things out :)
+  final-commands:
+    (>):
+    - |
+      cat > %{install-root}/run-in-qemu.sh << EOF
+      #!/bin/sh
+      qemu-system-x86_64 -drive file=sda.img,format=raw -nographic
+      EOF
+      chmod +x %{install-root}/run-in-qemu.sh
diff --git a/doc/source/image/elements/image/initramfs/initramfs-gz.bst b/doc/source/image/elements/image/initramfs/initramfs-gz.bst
new file mode 100644
index 000000000..900e9ffc0
--- /dev/null
+++ b/doc/source/image/elements/image/initramfs/initramfs-gz.bst
@@ -0,0 +1,28 @@
+# elements/image/initramfs/initramfs-gz.bst
+
+kind: script
+description: The compressed initramfs
+
+depends:
+- filename: image/initramfs/initramfs.bst
+  type: build
+- filename: contents.bst
+  type: build
+
+variables:
+  cwd: "%{build-root}"
+
+config:
+  layout:
+  - element: contents.bst
+    destination: /
+  - element: image/initramfs/initramfs.bst
+    destination: "%{build-root}"
+
+  commands:
+  - mkdir -p %{install-root}/boot
+  # We need to ensure exec permissions here.
+  # See: https://gitlab.com/BuildStream/buildstream/issues/84
+  - chmod +x ./sbin/init ./sbin/shutdown
+  - (find . -print0 | cpio -0 -H newc -o) |
+    gzip -c > %{install-root}/boot/initramfs.gz
diff --git a/doc/source/image/elements/image/initramfs/initramfs-scripts.bst b/doc/source/image/elements/image/initramfs/initramfs-scripts.bst
new file mode 100644
index 000000000..45762a451
--- /dev/null
+++ b/doc/source/image/elements/image/initramfs/initramfs-scripts.bst
@@ -0,0 +1,8 @@
+# elements/image/initramfs/initramfs-scripts.bst
+
+kind: import
+
+sources:
+- kind: local
+  path: files/initramfs-scripts
+  directory: /sbin
diff --git a/doc/source/image/elements/image/initramfs/initramfs.bst b/doc/source/image/elements/image/initramfs/initramfs.bst
new file mode 100644
index 000000000..ae1216667
--- /dev/null
+++ b/doc/source/image/elements/image/initramfs/initramfs.bst
@@ -0,0 +1,14 @@
+# elements/image/initramfs/initramfs.bst
+
+kind: compose
+description: Initramfs composition
+
+depends:
+  - filename: contents.bst
+    type: build
+  - filename: image/initramfs/initramfs-scripts.bst
+    type: build
+
+config:
+  include:
+  - runtime
diff --git a/doc/source/image/elements/image/linux.bst b/doc/source/image/elements/image/linux.bst
new file mode 100644
index 000000000..e9f0a02f0
--- /dev/null
+++ b/doc/source/image/elements/image/linux.bst
@@ -0,0 +1,299 @@
+# elements/image/linux.bst
+
+kind: manual
+
+depends:
+- filename: base.bst
+  type: build
+
+sources:
+- kind: tar
+  url: kernel:linux/kernel/v4.x/linux-4.14.3.tar.xz
+  ref: b628134ebb63ec82cb3e304a10aab2fd306fe79212e75ce81d8af73463c80366
+config:
+  configure-commands:
+  - sed -i 's|#!/bin/bash|#!/bin/ash|' scripts/config
+  - make defconfig
+  - scripts/config -e PACKET
+  - scripts/config -e SATA_AHCI
+  - scripts/config -e ATA_GENERIC
+  - scripts/config -e HAVE_IDE
+  - scripts/config -d BLK_DEV_IDE_SATA
+  - scripts/config -e BTRFS_FS
+  - scripts/config -e BTRFS_FS_POSIX_ACL
+  - scripts/config -e DEVTMPFS
+  - scripts/config -e DEVTMPFS_MOUNT
+  - scripts/config -e CONFIG_FHANDLE
+  - scripts/config -e DEVPTS_MULTIPLE_INSTANCES
+  - scripts/config -e CGROUPS
+  - scripts/config -e AUTOFS4_FS
+  - scripts/config --set-str UEVENT_HELPER_PATH ''
+  - scripts/config -e EXT2_FS
+  - scripts/config -e EXT2_FS_XATTR
+  - scripts/config -e EXT2_FS_POSIX_ACL
+  - scripts/config -e EXT2_FS_SECURITY
+  - scripts/config -e EXT2_FS_XIP
+  - scripts/config -e EXT3_FS
+  - scripts/config -d EXT3_DEFAULTS_TO_ORDERED
+  - scripts/config -e EXT3_FS_XATTR
+  - scripts/config -e EXT3_FS_POSIX_ACL
+  - scripts/config -e EXT3_FS_SECURITY
+  - scripts/config -e EXT4_FS
+  - scripts/config -e EXT4_FS_XATTR
+  - scripts/config -e EXT4_FS_POSIX_ACL
+  - scripts/config -e EXT4_FS_SECURITY
+  - scripts/config -d EXT4_DEBUG
+  - scripts/config -e FUSE_FS
+  - scripts/config -e OVERLAY_FS
+  - scripts/config -e XFS_FS
+  - scripts/config -e LIBCRC32C
+  - scripts/config -d JBD_DEBUG
+  - scripts/config -d JBD2_DEBUG
+  - scripts/config -e BLK_DEV_LOOP
+  - scripts/config -d BLK_DEV_CRYPTOLOOP
+  - scripts/config -e CEPH_FS
+  - scripts/config --set-val BLK_DEV_LOOP_MIN_COUNT 8
+  - scripts/config -e DM_SNAPSHOT
+  - scripts/config -e VIRTIO
+  - scripts/config -e VIRTIO_RING
+  - scripts/config -e VIRTIO_PCI
+  - scripts/config -e VIRTIO_BALLOON
+  - scripts/config -e VIRTIO_BLK
+  - scripts/config -e VIRTIO_NET
+  - scripts/config -e VIRTIO_CONSOLE
+  - scripts/config -e HW_RANDOM_VIRTIO
+  - scripts/config -e 9P_FS
+  - scripts/config -e 9P_FSCACHE
+  - scripts/config -e 9P_FS_POSIX_ACL
+  - scripts/config -e NET_9P
+  - scripts/config -e NET_9P_VIRTIO
+  - scripts/config -e R8169
+  - scripts/config -e 8139TOO
+  - scripts/config -e 8139CP
+  - scripts/config -e ATL1
+  - scripts/config -e ATL1C
+  - scripts/config -e ATL1E
+  - scripts/config -e E100
+  - scripts/config -e E1000
+  - scripts/config -e E1000E
+  - scripts/config -e USB_USBNET
+  - scripts/config -e USB_NET_AX8817X
+  - scripts/config -e USB_NET_AX88179_178A
+  - scripts/config -e USB_NET_DM9601
+  - scripts/config -e IKCONFIG
+  - scripts/config -e IKCONFIG_PROC
+  - scripts/config -e SECCOMP
+  - scripts/config -d DEBUG_STACK_TRACE
+  - scripts/config -e NFSD
+  - scripts/config -e NFSD_V3
+  - scripts/config -e KVM
+  - scripts/config -e TUN
+  - scripts/config -e BRIDGE
+  - scripts/config -e VHOST_NET
+  - scripts/config -e NF_NAT
+  - scripts/config -e IP_NF_NAT
+  - scripts/config -e IP_NF_TARGET_MASQUERADE
+  - scripts/config -e FB_VESA
+  - scripts/config -e HOTPLUG_PCI
+  - scripts/config -e HOTPLUG_PCI_ACPI
+  - scripts/config -e VLAN_8021Q
+  - scripts/config -e BRIDGE_VLAN_FILTERING
+  - scripts/config -e BLK_DEV_NBD
+  - scripts/config -e BRIDGE_NF_EBTABLES
+  - scripts/config -e NETFILTER
+  - scripts/config -e NETFILTER_ADVANCED
+  - scripts/config -e NETFILTER_XT_MATCH_ADDRTYPE
+  - scripts/config -e OPENVSWITCH
+  - scripts/config -e OPENVSWITCH_VXLAN
+  - scripts/config -e CONFIG_OPENVSWITCH_GRE
+  - scripts/config -e NET_CLS_BASIC
+  - scripts/config -e NET_SCH_INGRESS
+  - scripts/config -e NET_ACT_POLICE
+  - scripts/config -e NET_IPGRE_DEMUX
+  - scripts/config -e NET_SCH_HTB
+  - scripts/config -e NET_SCH_HFSC
+  - scripts/config -e VXLAN
+  - scripts/config -e VETH
+  - scripts/config -e IP_NF_MATCH_AH
+  - scripts/config -e IP_NF_MATCH_ECN
+  - scripts/config -e IP_NF_MATCH_RPFILTER
+  - scripts/config -e IP_NF_MATCH_TTL
+  - scripts/config -e IP_NF_TARGET_SYNPROXY
+  - scripts/config -e IP_NF_TARGET_NETMAP
+  - scripts/config -e IP_NF_TARGET_REDIRECT
+  - scripts/config -e IP_NF_TARGET_CLUSTERIP
+  - scripts/config -e IP_NF_TARGET_ECN
+  - scripts/config -e IP_NF_TARGET_TTL
+  - scripts/config -e IP_NF_RAW
+  - scripts/config -e IP_NF_SECURITY
+  - scripts/config -e IP_NF_ARPTABLES
+  - scripts/config -e KVM_INTEL
+  - scripts/config -e NETFILTER_NETLINK_QUEUE
+  - scripts/config -e SCSI_NETLINK
+  - scripts/config -e NETFILTER_XT_TARGET_MARK
+  - scripts/config -e NETFILTER_XT_SET
+  - scripts/config -e IP_SET
+  - scripts/config -e IP_SET_BITMAP_IP
+  - scripts/config -e IP_SET_BITMAP_IPMAC
+  - scripts/config -e IP_SET_BITMAP_PORT
+  - scripts/config -e IP_SET_HASH_IP
+  - scripts/config -e IP_SET_HASH_IPMARK
+  - scripts/config -e IP_SET_HASH_IPPORT
+  - scripts/config -e IP_SET_HASH_IPPORTIP
+  - scripts/config -e IP_SET_HASH_IPPORTNET
+  - scripts/config -e IP_SET_HASH_MAC
+  - scripts/config -e IP_SET_HASH_NETPORTNET
+  - scripts/config -e IP_SET_HASH_NET
+  - scripts/config -e IP_SET_HASH_NETNET
+  - scripts/config -e IP_SET_HASH_NETPORT
+  - scripts/config -e IP_SET_HASH_NETIFACE
+  - scripts/config -e IP_SET_LIST_SET
+  - scripts/config -e NF_CONNTRACK_TIMEOUT
+  - scripts/config -e NF_CONNTRACK_TIMESTAMP
+  - scripts/config -e NF_CONNTRACK_EVENTS
+  - scripts/config -e NF_CONNTRACK_LABELS
+  - scripts/config -e NETFILTER_NETLINK_ACCT
+  - scripts/config -e NETFILTER_NETLINK_QUEUE_CT
+  - scripts/config -e NF_CT_PROTO_DCCP
+  - scripts/config -e NF_CT_PROTO_GRE
+  - scripts/config -e NF_CT_PROTO_SCTP
+  - scripts/config -e NF_CT_PROTO_UDPLITE
+  - scripts/config -e NF_CT_NETLINK_TIMEOUT
+  - scripts/config -e NF_CT_NETLINK_HELPER
+  - scripts/config -e NF_CONNTRACK_AMANDA
+  - scripts/config -e NF_CONNTRACK_H323
+  - scripts/config -e NF_CONNTRACK_BROADCAST
+  - scripts/config -e NF_CONNTRACK_NETBIOS_NS
+  - scripts/config -e NF_CONNTRACK_SNMP
+  - scripts/config -e NF_CONNTRACK_PPTP
+  - scripts/config -e NF_CONNTRACK_SANE
+  - scripts/config -e NF_CONNTRACK_TFTP
+  - scripts/config -e NF_LOG_COMMON
+  - scripts/config -e NF_NAT_PROTO_DCCP
+  - scripts/config -e NF_NAT_PROTO_UDPLITE
+  - scripts/config -e NF_NAT_PROTO_SCTP
+  - scripts/config -e NF_NAT_AMANDA
+  - scripts/config -e NF_NAT_TFTP
+  - scripts/config -e NF_TABLES
+  - scripts/config -e NF_TABLES_INET
+  - scripts/config -e NFT_COMPAT
+  - scripts/config -e NFT_EXTHDR
+  - scripts/config -e NFT_META
+  - scripts/config -e NFT_CT
+  - scripts/config -e NFT_LIMIT
+  - scripts/config -e NFT_NAT
+  - scripts/config -e NFT_QUEUE
+  - scripts/config -e NFT_REJECT
+  - scripts/config -e NFT_REJECT_INET
+  - scripts/config -e NFT_RBTREE
+  - scripts/config -e NFT_HASH
+  - scripts/config -e NFT_COUNTER
+  - scripts/config -e NFT_LOG
+  - scripts/config -e NFT_MASQ
+  - scripts/config -e NETFILTER_XT_CONNMARK
+  - scripts/config -e NETFILTER_XT_TARGET_AUDIT
+  - scripts/config -e NETFILTER_XT_TARGET_CHECKSUM
+  - scripts/config -e NETFILTER_XT_TARGET_CLASSIFY
+  - scripts/config -e NETFILTER_XT_TARGET_CT
+  - scripts/config -e NETFILTER_XT_TARGET_DSCP
+  - scripts/config -e NETFILTER_XT_TARGET_HMARK
+  - scripts/config -e NETFILTER_XT_TARGET_LED
+  - scripts/config -e NETFILTER_XT_TARGET_LOG
+  - scripts/config -e NETFILTER_XT_TARGET_NFQUEUE
+  - scripts/config -e NETFILTER_XT_TARGET_RATEEST
+  - scripts/config -e NETFILTER_XT_TARGET_TPROXY
+  - scripts/config -e NETFILTER_XT_TARGET_TCPOPTSTRIP
+  - scripts/config -e NETFILTER_XT_TARGET_TEE
+  - scripts/config -e NETFILTER_XT_TARGET_TRACE
+  - scripts/config -e NETFILTER_XT_TARGET_IDLETIMER
+  - scripts/config -e NETFILTER_XT_MATCH_BPF
+  - scripts/config -e NETFILTER_XT_MATCH_CLUSTER
+  - scripts/config -e NETFILTER_XT_MATCH_COMMENT
+  - scripts/config -e NETFILTER_XT_MATCH_CONNBYTES
+  - scripts/config -e NETFILTER_XT_MATCH_CONNLABEL
+  - scripts/config -e NETFILTER_XT_MATCH_CONNLIMIT
+  - scripts/config -e NETFILTER_XT_MATCH_CPU
+  - scripts/config -e NETFILTER_XT_MATCH_DCCP
+  - scripts/config -e NETFILTER_XT_MATCH_DEVGROUP
+  - scripts/config -e NETFILTER_XT_MATCH_DSCP
+  - scripts/config -e NETFILTER_XT_MATCH_ESP
+  - scripts/config -e NETFILTER_XT_MATCH_HASHLIMIT
+  - scripts/config -e NETFILTER_XT_MATCH_HELPER
+  - scripts/config -e NETFILTER_XT_MATCH_IPCOMP
+  - scripts/config -e NETFILTER_XT_MATCH_IPRANGE
+  - scripts/config -e NETFILTER_XT_MATCH_IPVS
+  - scripts/config -e NETFILTER_XT_MATCH_L2TP
+  - scripts/config -e NETFILTER_XT_MATCH_LENGTH
+  - scripts/config -e NETFILTER_XT_MATCH_LIMIT
+  - scripts/config -e NETFILTER_XT_MATCH_MAC
+  - scripts/config -e NETFILTER_XT_MATCH_MULTIPORT
+  - scripts/config -e NETFILTER_XT_MATCH_NFACCT
+  - scripts/config -e NETFILTER_XT_MATCH_OSF
+  - scripts/config -e NETFILTER_XT_MATCH_OWNER
+  - scripts/config -e NETFILTER_XT_MATCH_CGROUP
+  - scripts/config -e NETFILTER_XT_MATCH_PHYSDEV
+  - scripts/config -e NETFILTER_XT_MATCH_PKTTYPE
+  - scripts/config -e NETFILTER_XT_MATCH_QUOTA
+  - scripts/config -e NETFILTER_XT_MATCH_RATEEST
+  - scripts/config -e NETFILTER_XT_MATCH_REALM
+  - scripts/config -e NETFILTER_XT_MATCH_RECENT
+  - scripts/config -e NETFILTER_XT_MATCH_SCTP
+  - scripts/config -e NETFILTER_XT_MATCH_SOCKET
+  - scripts/config -e NETFILTER_XT_MATCH_STATISTIC
+  - scripts/config -e NETFILTER_XT_MATCH_STRING
+  - scripts/config -e NETFILTER_XT_MATCH_TCPMSS
+  - scripts/config -e NETFILTER_XT_MATCH_TIME
+  - scripts/config -e NETFILTER_XT_MATCH_U32
+  - scripts/config -e IP_VS
+  - scripts/config -e BRIDGE_NETFILTER
+  - scripts/config -e CRYPTO_CRC32C
+  - scripts/config -e CONFIGFS_FS
+  - scripts/config -e EXPERT
+  - scripts/config -e TARGET_CORE
+  - scripts/config -e ISCSI_TARGET
+  - scripts/config -e TCM_IBLOCK
+  - scripts/config -e TCM_FILEIO
+  - scripts/config -e TCM_PSCSI
+  - scripts/config -e TCM_USER
+  - scripts/config -e CONFIG_UIO
+  - scripts/config -e LOOPBACK_TARGET
+  - scripts/config -e TCM_FC
+  - scripts/config -e LIBFC
+  - scripts/config -e SCSI_FC_ATTRS
+  - scripts/config -e SCSI_ISCSI_ATTRS
+  - scripts/config -e ISCSI_TCP
+  - scripts/config -e SCSI_LOWLEVEL
+  - scripts/config -e SCSI_VIRTIO
+  - scripts/config -e HYPERVISOR_GUEST
+  - scripts/config -e PARAVIRT
+  - scripts/config -e CONFIG_SND_INTEL8X0
+  - scripts/config -m CONFIG_DRM_CIRRUS_QEMU
+  - scripts/config -m CONFIG_DRM_BOCHS
+  - scripts/config -m CONFIG_DRM_VIRTIO_GPU
+  - scripts/config -e BT
+  - yes '' | make oldconfig
+  build-commands:
+  - make $MAKEFLAGS
+  install-commands:
+  - mkdir -p "%{install-root}"/boot
+  - make INSTALL_PATH="%{install-root}"/boot install
+  - make INSTALL_MOD_PATH="%{install-root}" modules_install
+  - install -d "%{install-root}%{prefix}/src/linux"
+  - |
+    (
+        printf 'Makefile\0'
+        printf 'Module.symvers\0'
+        find arch/x86 -maxdepth 1 -name 'Makefile*' -print0
+        find arch/x86 \( -name 'module.lds' -o -name 'Kbuild.platforms' -o -name 'Platform' \) -print0
+        find arch/x86 \( -type d -a \( -name include -o -name scripts \) \) -o \
+                                 \! -type d -a \( -path '*include/*' -o -path '*scripts/*' \) -print0
+        find include -name 'asm*' -prune -o -print0
+        find include/asm-generic -print0
+        find include/uapi -print0
+        find scripts -print0
+    ) | cpio -0pumd "%{install-root}%{prefix}/src/linux"
+public:
+  bst:
+    integration-commands:
+    - if which depmod; then (cd /usr/lib/modules && for version in *; do depmod -a
+      "$version"; done) fi
diff --git a/doc/source/image/elements/image/system.bst b/doc/source/image/elements/image/system.bst
new file mode 100644
index 000000000..80ebe8d8c
--- /dev/null
+++ b/doc/source/image/elements/image/system.bst
@@ -0,0 +1,16 @@
+# elements/image/system.bst
+
+kind: compose
+description: The system installed onto the image
+
+depends:
+  - filename: contents.bst
+    type: build
+  - filename: image/linux.bst
+    type: build
+  - filename: image/initramfs/initramfs-gz.bst
+    type: build
+
+config:
+  include:
+    - runtime
diff --git a/doc/source/image/files/hello/hello b/doc/source/image/files/hello/hello
new file mode 100755
index 000000000..e77d4e7d6
--- /dev/null
+++ b/doc/source/image/files/hello/hello
@@ -0,0 +1,3 @@
+#!/bin/ash
+
+echo 'Hello World!'
diff --git a/doc/source/image/files/initramfs-scripts/init b/doc/source/image/files/initramfs-scripts/init
new file mode 100644
index 000000000..d1d1042ba
--- /dev/null
+++ b/doc/source/image/files/initramfs-scripts/init
@@ -0,0 +1,132 @@
+#!/bin/sh
+trap 'exec /bin/sh' INT EXIT
+
+# We need proc for reading the kernel command line
+mount -n -t proc none /proc
+
+set -- $(cat /proc/cmdline)
+
+# We don't want to leave mount points around
+umount /proc
+
+rootwait=true # defaults to off in the kernel, I think it's more useful on
+for arg; do
+    case "$arg" in
+    root=LABEL=*)
+        if [ x"$root_type" != x ]; then
+            echo "Warning, multiple root= specified, using latest."
+        fi
+        root_type=label
+        root="${arg#root=LABEL=}"
+        ;;
+    root=UUID=*)
+        if [ x"$root_type" != x ]; then
+            echo "Warning, multiple root= specified, using latest."
+        fi
+        root_type=uuid
+        root="${arg#root=UUID=}"
+        ;;
+    root=*)
+        if [ x"$root_type" != x ]; then
+            echo "Warning, multiple root= specified, using latest."
+        fi
+        root_type=disk
+        root="${arg#root=}"
+        ;;
+    rootflags=*)
+        if [ x"$rootflags" != x ]; then
+            echo "Warning, multiple rootflags= specified, using latest."
+        fi
+        rootflags=",${arg#rootflags=}"
+        ;;
+    rootfstype=*)
+        if [ x"$rootfstype" != x ]; then
+            echo "Warning, multiple rootfstype= specified, using latest."
+        fi
+        rootfstype="${arg#rootfstype=}"
+        ;;
+    rootdelay=*)
+        if [ x"$rootdelay" != x ]; then
+            echo "Warning, multiple rootdelay= specified, using latest."
+        fi
+        rootdelay="${arg#rootdelay=}"
+        ;;
+    rootwait)
+        rootwait=true
+        ;;
+    norootwait)
+        rootwait=false
+        ;;
+    ro)
+        ro=ro
+        ;;
+    rw)
+        ro=rw
+        ;;
+    init=*)
+        init="${arg#init=}"
+        ;;
+    esac
+done
+
+
+if [ x"$rootdelay" != x ]; then
+    sleep "$rootdelay"
+fi
+
+if [ x"$rootfstype" = x ]; then
+    # Warn that busybox may not be able to auto-detect rootfs type
+    cat <<\EOF
+Warning, rootfs type not specified, auto-detection of type is slow and
+may fail. Please add rootfstype=$type to kernel command line.
+EOF
+fi
+
+mount -n -t devtmpfs devtmpfs /dev
+
+while true; do
+    case "$root_type" in
+    disk)
+        if mount -n -t "${rootfstype}" -o "${ro-rw}""$rootflags" "$root" /mnt; then
+            break
+        else
+            echo disk $root not found
+            blkid
+        fi
+        ;;
+    label)
+        disk="$(findfs LABEL="$root")"
+        if [ x"$disk" = x ]; then
+            echo disk with label $root not found
+            blkid
+        else
+            mount -n -t "${rootfstype}" -o "${ro-rw}""$rootflags" "$disk" /mnt && break
+        fi
+        ;;
+    uuid)
+        disk="$(findfs UUID="$root")"
+        if [ x"$disk" = x ]; then
+            echo disk with UUID $root not found
+            blkid
+        else
+            mount -n -t "${rootfstype}" -o "${ro-rw}""$rootflags" "$disk" /mnt && break
+        fi
+        ;;
+    '')
+        echo "Error, no root specified"
+        exit 1
+        ;;
+    esac
+    if "$rootwait"; then
+        echo Trying again in 0.5 seconds
+        sleep 0.5
+    fi
+done
+umount -n /dev
+
+# We dont create any static device nodes while building,
+# device nodes will be created by systemd but before that
+# we at least need the console
+mknod -m 0600 /mnt/dev/console c 5 1
+
+exec switch_root -c /dev/console /mnt "${init-/sbin/init}"
diff --git a/doc/source/image/files/initramfs-scripts/shutdown b/doc/source/image/files/initramfs-scripts/shutdown
new file mode 100644
index 000000000..0065bcc8f
--- /dev/null
+++ b/doc/source/image/files/initramfs-scripts/shutdown
@@ -0,0 +1,67 @@
+#!/bin/sh
+
+fail(){
+    echo "$@" >&2
+    # The behaviour on failure of systemd when shutting down without a
+    # shutdownramfs is to freeze if it fails, but the behaviour of an initramfs
+    # on failure is to drop you into a recovery shell. The latter seems more
+    # useful.
+    exec /bin/sh
+}
+
+startswith(){
+    # Filter out lines that don't start with $1
+    # grep ^EXPR is usually sufficient, but would require escaping of EXPR.
+    # Instead this compares the line to the line with its prefix stripped,
+    # so if the line is different, then it started with that prefix.
+    # It's ugly, but is less logic than escaping the regular expression and
+    # using grep, more reliable than not making any effort to escape, and
+    # less surprising than requiring the parameter to be pre-escaped.
+    while read -r line; do
+        if [ "${line#"$1"}" != "$line" ]; then
+            printf '%s\n' "$line"
+        fi
+    done
+}
+
+recursive_umount(){
+    # Recursively unmount every mountpoint under $1.
+    # This works by filtering to select mountpoints from mountinfo that start
+    # with the absolute path of the directory given.
+    # It unmounts in reverse-order, so that it may unmount dependent mounts
+    # first, and it has to handle the paths having octal escape sequences.
+    set -- "$(readlink -f "$1")"
+    cut -d' ' -f5 /proc/self/mountinfo | startswith "$1" \
+        | sort -r | while read -r mp; do
+        umount "$(echo -e "$mp")"
+    done
+}
+
+# Give the rootfs another chance to write its state to disk.
+sync
+
+# Kill any http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons/
+# as we don't have any facility to cleanly shut them down in this initramfs.
+killall5
+
+# Recursively unmount the old root, so they have a chance of performing
+# unmount-time cleanup.
+recursive_umount /oldroot
+
+case "$1" in
+reboot|poweroff|halt)
+        if ! "$1" -f; then
+            fail "$1 command failed"
+        fi
+        ;;
+kexec)
+        # probably don't have this, but we'll try anyway
+        if ! kexec -e; then
+            fail "$1 command failed"
+        fi
+        ;;
+*)
+        fail "Unrecognized shutdown verb $1"
+        ;;
+esac
+
diff --git a/doc/source/image/project.conf b/doc/source/image/project.conf
new file mode 100644
index 000000000..3e8ca6d3c
--- /dev/null
+++ b/doc/source/image/project.conf
@@ -0,0 +1,21 @@
+# project.conf
+
+name: test-image
+element-path: elements
+
+# Allow the project use any version higher than 0 of the x86image
+# plugin installed through pip from the bst-external package
+plugins:
+  - origin: pip
+    package-name: BuildStream-external
+    elements:
+      x86image: 0
+  - origin: pip
+    package-name: docker
+    elements:
+      docker: 0
+
+aliases:
+  kernel: https://www.kernel.org/pub/
+  gnu: http://ftp.gnu.org/gnu/
+  busybox: https://www.busybox.net/downloads/
diff --git a/doc/source/image_authoring.rst b/doc/source/image_authoring.rst
index 44431c31e..095a9c879 100644
--- a/doc/source/image_authoring.rst
+++ b/doc/source/image_authoring.rst
@@ -13,7 +13,8 @@ Building a Linux image
 
    This page does *not* list all files required for the project, it
    merely comments on noteworthy sections. See `this repository
-   <https://gitlab.com/tlater/image-test>`_ for the full project.
+   <https://gitlab.com/BuildStream/buildstream-examples/build-x86image>`_
+   for the full project.
 
 Setting up the project
 ~~~~~~~~~~~~~~~~~~~~~~