doc/examples/strict-mode: Adding a user guide for using non-strict build plans

13 files changed, 193 insertions, 0 deletions

diff --git a/doc/examples/strict-mode/elements/base.bst b/doc/examples/strict-mode/elements/base.bst
new file mode 100644
index 000000000..1b85a9e8c
--- /dev/null
+++ b/doc/examples/strict-mode/elements/base.bst
@@ -0,0 +1,5 @@
+kind: stack
+description: Base stack
+
+depends:
+- base/alpine.bst
diff --git a/doc/examples/strict-mode/elements/base/alpine.bst b/doc/examples/strict-mode/elements/base/alpine.bst
new file mode 100644
index 000000000..433f4773a
--- /dev/null
+++ b/doc/examples/strict-mode/elements/base/alpine.bst
@@ -0,0 +1,17 @@
+kind: import
+description: |
+
+    Alpine Linux base runtime
+
+sources:
+- kind: tar
+  url: alpine:integration-tests-base.v1.x86_64.tar.xz
+  ref: 3eb559250ba82b64a68d86d0636a6b127aa5f6d25d3601a79f79214dc9703639
+
+#
+# Run ldconfig in the libdir before running anything
+#
+public:
+  bst:
+    integration-commands:
+    - ldconfig "%{libdir}"
diff --git a/doc/examples/strict-mode/elements/hello-dynamic.bst b/doc/examples/strict-mode/elements/hello-dynamic.bst
new file mode 100644
index 000000000..8025a1ed3
--- /dev/null
+++ b/doc/examples/strict-mode/elements/hello-dynamic.bst
@@ -0,0 +1,22 @@
+kind: manual
+description: |
+
+  The dynamically linked hello application
+
+# Depend on the hello library
+depends:
+- libhello.bst
+
+# Stage the files/hello directory for building
+sources:
+  - kind: local
+    path: files/hello
+
+# Now configure the commands to run
+config:
+
+  build-commands:
+  - make -f Makefile.dynamic PREFIX="%{prefix}"
+
+  install-commands:
+  - make -f Makefile.dynamic -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
diff --git a/doc/examples/strict-mode/elements/hello-static.bst b/doc/examples/strict-mode/elements/hello-static.bst
new file mode 100644
index 000000000..63806d184
--- /dev/null
+++ b/doc/examples/strict-mode/elements/hello-static.bst
@@ -0,0 +1,24 @@
+kind: manual
+description: |
+
+  The statically linked hello application
+
+# Depend on the hello library with the strict option
+#
+depends:
+- filename: libhello.bst
+  strict: true
+
+# Stage the files/hello directory for building
+sources:
+  - kind: local
+    path: files/hello
+
+# Now configure the commands to run
+config:
+
+  build-commands:
+  - make -f Makefile.static PREFIX="%{prefix}"
+
+  install-commands:
+  - make -f Makefile.static -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
diff --git a/doc/examples/strict-mode/elements/libhello.bst b/doc/examples/strict-mode/elements/libhello.bst
new file mode 100644
index 000000000..53496c84c
--- /dev/null
+++ b/doc/examples/strict-mode/elements/libhello.bst
@@ -0,0 +1,22 @@
+kind: manual
+description: |
+
+  The libhello library
+
+# Depend on the base system
+depends:
+- base.bst
+
+# Stage the files/libhello directory for building
+sources:
+  - kind: local
+    path: files/libhello
+
+# Now configure the commands to run
+config:
+
+  build-commands:
+  - make PREFIX="%{prefix}"
+
+  install-commands:
+  - make -j1 PREFIX="%{prefix}" DESTDIR="%{install-root}" install
diff --git a/doc/examples/strict-mode/files/hello/Makefile.dynamic b/doc/examples/strict-mode/files/hello/Makefile.dynamic
new file mode 100644
index 000000000..52b0f72cd
--- /dev/null
+++ b/doc/examples/strict-mode/files/hello/Makefile.dynamic
@@ -0,0 +1,12 @@
+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install: all
+	install -d ${DESTDIR}${PREFIX}/bin
+	install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+	$(CC) -Wall -o $@ $< -lhello
diff --git a/doc/examples/strict-mode/files/hello/Makefile.static b/doc/examples/strict-mode/files/hello/Makefile.static
new file mode 100644
index 000000000..87fb51206
--- /dev/null
+++ b/doc/examples/strict-mode/files/hello/Makefile.static
@@ -0,0 +1,12 @@
+# Sample makefile for hello.c
+#
+.PHONY: all install
+
+all: hello
+
+install: all
+	install -d ${DESTDIR}${PREFIX}/bin
+	install -m 755 hello ${DESTDIR}${PREFIX}/bin
+
+hello: hello.c
+	$(CC) -Wall -o $@ $< /usr/lib/libhello.a
diff --git a/doc/examples/strict-mode/files/hello/hello.c b/doc/examples/strict-mode/files/hello/hello.c
new file mode 100644
index 000000000..83e762c29
--- /dev/null
+++ b/doc/examples/strict-mode/files/hello/hello.c
@@ -0,0 +1,20 @@
+/*
+ * hello.c - Simple hello program
+ */
+#include <stdio.h>
+#include <libhello.h>
+
+int main(int argc, char *argv[])
+{
+  const char *person = NULL;
+
+  if (argc > 1)
+    person = argv[1];
+
+  if (person)
+    hello(person);
+  else
+    hello("stranger");
+
+  return 0;
+}
diff --git a/doc/examples/strict-mode/files/libhello/Makefile b/doc/examples/strict-mode/files/libhello/Makefile
new file mode 100644
index 000000000..cdc20a30a
--- /dev/null
+++ b/doc/examples/strict-mode/files/libhello/Makefile
@@ -0,0 +1,21 @@
+# Sample makefile for hello library
+#
+.PHONY: all install
+
+all: libhello.so libhello.a
+
+install: all
+	install -d ${DESTDIR}${PREFIX}/lib
+	install -d ${DESTDIR}${PREFIX}/include
+	install -m 644 libhello.so ${DESTDIR}${PREFIX}/lib
+	install -m 644 libhello.a ${DESTDIR}${PREFIX}/lib
+	install -m 644 libhello.h ${DESTDIR}${PREFIX}/include
+
+%.o: %.c %.h
+	$(CC) -c $< -o $@ -Wall
+
+libhello.a: libhello.o
+	$(AR) rcs $@ $^
+
+libhello.so: libhello.o
+	$(CC) -shared -o $@ $<
diff --git a/doc/examples/strict-mode/files/libhello/libhello.c b/doc/examples/strict-mode/files/libhello/libhello.c
new file mode 100644
index 000000000..7d0eca340
--- /dev/null
+++ b/doc/examples/strict-mode/files/libhello/libhello.c
@@ -0,0 +1,9 @@
+/*
+ * libhello.c - The hello library
+ */
+#include <stdio.h>
+
+void hello(const char *person)
+{
+  printf("Good morning %s\n", person);
+}
diff --git a/doc/examples/strict-mode/files/libhello/libhello.h b/doc/examples/strict-mode/files/libhello/libhello.h
new file mode 100644
index 000000000..f714f3659
--- /dev/null
+++ b/doc/examples/strict-mode/files/libhello/libhello.h
@@ -0,0 +1,8 @@
+/*
+ * libhello.h - The hello library
+ */
+
+/*
+ * A function to say hello to @person
+ */
+void hello(const char *person);
diff --git a/doc/examples/strict-mode/project.conf b/doc/examples/strict-mode/project.conf
new file mode 100644
index 000000000..ac73434c8
--- /dev/null
+++ b/doc/examples/strict-mode/project.conf
@@ -0,0 +1,12 @@
+# Unique project name
+name: strict-mode
+
+# Required BuildStream format version
+format-version: 18
+
+# Subdirectory where elements are stored
+element-path: elements
+
+# Define an alias for our alpine tarball
+aliases:
+  alpine: https://bst-integration-test-images.ams3.cdn.digitaloceanspaces.com/
diff --git a/doc/examples/strict-mode/update.patch b/doc/examples/strict-mode/update.patch
new file mode 100644
index 000000000..070b2422e
--- /dev/null
+++ b/doc/examples/strict-mode/update.patch
@@ -0,0 +1,9 @@
+--- libhello.c
++++ libhello.c
+@@ -5,5 +5,5 @@
+ 
+ void hello(const char *person)
+ {
+-  printf("Hello %s\n", person);
++  printf("Good morning %s\n", person);
+ }