You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by ro...@apache.org on 2020/12/29 13:39:36 UTC
[buildstream] branch image-authoring created (now 201b39b)
This is an automated email from the ASF dual-hosted git repository.
root pushed a change to branch image-authoring
in repository https://gitbox.apache.org/repos/asf/buildstream.git.
at 201b39b Add image doc project
This branch includes the following new commits:
new 8213382 image_authoring.rst: Add image creation documentation
new 201b39b Add image doc project
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[buildstream] 02/02: Add image doc project
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
root pushed a commit to branch image-authoring
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 201b39b60921d4a0d6294ee6d64f575ccff71d19
Author: Tristan Maat <tr...@codethink.co.uk>
AuthorDate: Tue Feb 6 17:50:26 2018 +0000
Add image doc project
---
doc/source/image/elements/base.bst | 7 +
doc/source/image/elements/contents.bst | 7 +
doc/source/image/elements/contents/busybox.bst | 52 ++++
doc/source/image/elements/contents/hello.bst | 12 +
doc/source/image/elements/contents/musl.bst | 16 ++
doc/source/image/elements/image-x86_64.bst | 50 ++++
.../elements/image/initramfs/initramfs-gz.bst | 28 ++
.../elements/image/initramfs/initramfs-scripts.bst | 8 +
.../image/elements/image/initramfs/initramfs.bst | 14 +
doc/source/image/elements/image/linux.bst | 299 +++++++++++++++++++++
doc/source/image/elements/image/system.bst | 16 ++
doc/source/image/files/hello/hello | 3 +
doc/source/image/files/initramfs-scripts/init | 132 +++++++++
doc/source/image/files/initramfs-scripts/shutdown | 67 +++++
doc/source/image/project.conf | 21 ++
doc/source/image_authoring.rst | 3 +-
16 files changed, 734 insertions(+), 1 deletion(-)
diff --git a/doc/source/image/elements/base.bst b/doc/source/image/elements/base.bst
new file mode 100644
index 0000000..b43bea8
--- /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 0000000..f00cf95
--- /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 0000000..9851528
--- /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 0000000..2bbddb4
--- /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 0000000..d591ab2
--- /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 0000000..f2af428
--- /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 0000000..900e9ff
--- /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 0000000..45762a4
--- /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 0000000..ae12166
--- /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 0000000..e9f0a02
--- /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 0000000..80ebe8d
--- /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 0000000..e77d4e7
--- /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 0000000..d1d1042
--- /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 0000000..0065bcc
--- /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 0000000..3e8ca6d
--- /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 44431c3..095a9c8 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
~~~~~~~~~~~~~~~~~~~~~~
[buildstream] 01/02: image_authoring.rst: Add image creation
documentation
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
root pushed a commit to branch image-authoring
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 82133828a93bb3df4d0d8bd6ccbfa2e933a15c40
Author: Tristan Maat <tr...@codethink.co.uk>
AuthorDate: Tue Feb 6 16:59:19 2018 +0000
image_authoring.rst: Add image creation documentation
---
doc/source/image_authoring.rst | 333 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 333 insertions(+)
diff --git a/doc/source/image_authoring.rst b/doc/source/image_authoring.rst
new file mode 100644
index 0000000..44431c3
--- /dev/null
+++ b/doc/source/image_authoring.rst
@@ -0,0 +1,333 @@
+:orphan:
+
+.. _image_authoring:
+
+Authoring System Images
+=======================
+This section forms a guide to creating system images with BuildStream.
+
+Building a Linux image
+----------------------
+
+.. note::
+
+ 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.
+
+Setting up the project
+~~~~~~~~~~~~~~~~~~~~~~
+
+To create an image, we will want to use the x86image plugin from the
+``bst-external`` repository. The ``bst-external`` repository is a
+collection of plugins that are either too niche or unpolished to
+include as plugins in the main repository, but are useful for various
+purposes.
+
+If you have not already, install the latest version of this
+repository:
+
+.. code:: bash
+
+ git clone https://gitlab.com/BuildStream/bst-external.git
+ cd bst-external
+ pip3 install .
+
+This should make bst-external plugins available to buildstream. To use
+the x86image and docker plugins in our project, we need to set up
+plugins in our ``project.conf``:
+
+.. literalinclude:: image/project.conf
+ :caption: project.conf
+ :linenos:
+ :language: yaml
+ :lines: -17
+
+We also set aliases for all project pages we will be fetching sources
+from, should we later want to change their location (e.g. when we
+decide that we want to mirror the files in our datacenter for
+performance reasons):
+
+.. literalinclude:: image/project.conf
+ :caption: project.conf (continued)
+ :language: yaml
+ :lineno-start: 17
+ :linenos:
+ :lines: 18-
+
+Base System
+~~~~~~~~~~~
+
+The base system will be used to *build* the image and the project, but
+it won't be a part of the final result. It should contain everything
+that is required to build both the project and the tools required to
+create an image.
+
+The x86image plugin requires a specific set of tools to create an
+image. To make using this plugin easier, we provide an alpine-based
+base system using docker that contains all required tools:
+
+.. literalinclude:: image/elements/base.bst
+ :caption: elements/base.bst
+ :language: yaml
+ :linenos:
+
+This image only provides musl-libc and busybox for building, should
+your project require GNU tools it will be simpler to create your own
+and ensure that your base system includes the following packages:
+
+* parted
+* mtools
+* e2fsprogs
+* dosfstools
+* syslinux
+* nasm
+* autoconf
+* gcc
+* g++
+* make
+* gawk
+* bc
+* linux-headers
+
+
+Image Contents
+~~~~~~~~~~~~~~
+
+The final linux image will consist of several elements that can be
+broadly summarized in four scopes:
+
+1. A sysroot
+2. An initramfs
+3. A Linux kernel
+4. Project-specific elements
+
+A sysroot
++++++++++
+
+Before we create the elements to make an actual image, we will set up
+the sysroot that will form the user space. For this tutorial, we will
+create a very simple system.
+
+The sysroot must contain everything required to run a Linux system -
+this will usually be `GNU coreutils
+<https://www.gnu.org/software/coreutils/coreutils.html>`_ or `BusyBox
+<https://www.busybox.net/about.html>`_ - and any runtime dependencies,
+if these tools are not statically linked - often `glibc
+<https://www.gnu.org/software/libc/>`_ or
+`musl <https://www.musl-libc.org/>`_.
+
+For this tutorial we will build a BusyBox + musl system:
+
+.. code:: yaml
+
+ kind: stack
+ description: The image contents
+ depends:
+ - contents/busybox.bst
+
+A keen eye may notice that this does not include a ``musl.bst``
+dependency - this is because the busybox element itself is set to
+run-depend on musl, which we use later to stage sysroot content, but
+not the base system.
+
+For the specifics of the included elements, refer to the accompanying
+project repository.
+
+An initramfs
+++++++++++++
+
+Now that we have defined the basic sysroot we can also set up an
+`initramfs <https://en.wikipedia.org/wiki/Initial_ramdisk>`_ - we do
+this now, because we have defined the most basic root file system that
+will be booted into (for the sake of brevity we will not set up any
+kernel modules, otherwise these should be built first and included in
+the initramfs).
+
+For our initramfs we will want an ``init`` and ``shutdown`` script,
+and a copy of the sysroot created previously. We start with an
+initramfs-scripts element:
+
+.. literalinclude:: image/elements/image/initramfs/initramfs-scripts.bst
+ :caption: elements/image/initramfs/initramfs-scripts.bst
+ :language: yaml
+ :linenos:
+
+This will simply place the ``init`` and ``shutdown`` scripts located
+in ``files/initramfs-scripts`` in ``/sbin``, where they can later be
+found and executed.
+
+We then define our initramfs as the intersection between our
+initramfs-scripts and sysroot content:
+
+.. literalinclude:: image/elements/image/initramfs/initramfs.bst
+ :caption: elements/image/initramfs/initramfs.bst
+ :language: yaml
+ :linenos:
+
+Finally we create an element that produces the cpio archive and
+compress it using gzip:
+
+.. literalinclude:: image/elements/image/initramfs/initramfs-gz.bst
+ :caption: elements/image/initramfs/initramfs-gz.bst
+ :language: yaml
+ :linenos:
+
+A Linux kernel
+++++++++++++++
+
+Now that our final environment is set up, we create the Linux kernel
+that will drive it. Setup for this is a little less intricate since it
+only involves building a single project:
+
+
+.. literalinclude:: image/elements/image/linux.bst
+ :caption: elements/image/linux.bst
+ :language: yaml
+ :linenos:
+ :lines: -16
+
+.. literalinclude:: image/elements/image/linux.bst
+ :caption: elements/image/linux.bst (continued)
+ :language: yaml
+ :lineno-start: 272
+ :linenos:
+ :lines: 272-
+
+The main complexity in compiling a Linux kernel is its configuration;
+the 'correct' settings depend a lot on the project. The remaining
+configuration should be quite portable to other builds, however, and
+simply deals with placing files in the correct locations.
+
+Project-specific elements
++++++++++++++++++++++++++
+
+Finally, our project-specific files should be included. For a real
+project, this may be an installer, 'rescue' applications such as
+parted, distribution-specific files or similar.
+
+In our case, we will include a ``hello`` script that simply prints
+``Hello World!``, as is tradition:
+
+.. literalinclude:: image/elements/contents/hello.bst
+ :caption: elements/contents/hello.bst
+ :language: yaml
+ :linenos:
+
+We also update the ``contents.bst`` file to include our project
+target:
+
+.. literalinclude:: image/elements/contents.bst
+ :caption: elements/contents.bst
+ :language: yaml
+ :linenos:
+
+While our ``hello`` element run-depends on busybox, our contents
+*must* include a working set of coreutils - we make this explicit by
+also depending on busybox.
+
+Creating the image
+~~~~~~~~~~~~~~~~~~
+
+Now that all image content is defined, we can create the elements that
+actually build the image. The x86image plugin requires two elements:
+
+- A base system that contains the tools to create an image
+- An element that contains the system we want to create an image of
+
+We already have ``base.bst``, which conveniently contains all tools we
+need (we could have used a separate base system to create the image),
+but we still need to create a system element.
+
+For the system element, we simply collect the image content elements
+and their runtime dependencies:
+
+.. literalinclude:: image/elements/image/system.bst
+ :caption: elements/image/system.bst
+ :language: yaml
+ :linenos:
+
+We can now define our image element - we start by depending on the
+above elements:
+
+.. literalinclude:: image/elements/image-x86_64.bst
+ :caption: elements/image-x86_64.bst
+ :language: yaml
+ :linenos:
+ :lines: -12
+
+We then set a few parameters to suit our system:
+
+.. literalinclude:: image/elements/image-x86_64.bst
+ :caption: elements/image-x86_64.bst (continued)
+ :language: yaml
+ :lineno-start: 16
+ :linenos:
+ :lines: 16-31
+
+The correct values for these parameters will depend on the specific
+image created, but for this project the following values were used:
+
+boot-size
+ The size of ``/boot`` as created by ``image/system.bst`` - the
+ system can be inspected using ``bst checkout``.
+
+rootfs-size
+ The size of ``/`` as created by ``image/system.bst``.
+
+sector-size
+ The default size of 512 should work in most cases, your
+ requirements may differ.
+
+swap-size
+ The desired size for the swap partition.
+
+kernel-args
+ The kernel arguments - the image plugin will by default create the
+ following ``/etc/fstab``:
+
+ .. code::
+
+ /dev/sda2 / ext4 defaults,rw,noatime 0 1
+ /dev/sda1 /boot vfat defaults 0 2
+ /dev/sda3 none swap defaults 0 0
+
+ Hence we specify ``root=/dev/sda2`` and ``rootfstype=ext4``.
+
+ ``image/initramfs-scripts.bst`` defines our init script as
+ ``/sbin/init``, hence we set ``init=/sbin/init``.
+
+ Finally, qemu (which we will use to try out this image)
+ requires our console to be on ttyS0, so we specify
+ ``console=ttyS0``.
+
+kernel-name
+ The default name of the kernel name as created by
+ ``image/linux.bst`` is ``vmlinuz-4.14.3``, and since this is easier
+ than renaming it we specify that value.
+
+The final configuration specifies which dependencies to use as the
+base/system elements, and creates a script to launch our image using
+qemu:
+
+.. literalinclude:: image/elements/image-x86_64.bst
+ :caption: elements/image-x86_64.bst (continued)
+ :language: yaml
+ :lineno-start: 32
+ :linenos:
+ :lines: 32-
+
+Building the image
+~~~~~~~~~~~~~~~~~~
+
+We have now defined everything required to build a basic Linux
+image. With bst and the bst-external plugin repository installed, we
+can now build and boot our image.
+
+We first run ``bst track --deps all image-x86_64.bst`` to determine
+references for all sources used to build this project. We then run
+``bst build image-x86_64.bst`` to build and finally ``bst checkout
+image-x86_64.bst image`` to retrieve our finalized image.
+
+To test the result, simply run ``cd image/ && ./run-in-qemu.sh``
+(perhaps as root), and the image should boot.