From 1a003ebb9778fc481681515ec81544f0876c9521 Mon Sep 17 00:00:00 2001
From: Kaspar Schleiser <kaspar@schleiser.de>
Date: Wed, 16 Mar 2016 12:00:25 +0100
Subject: [PATCH] examples: add example for "make bindist"

---
 examples/bindist/Makefile     | 30 +++++++++++++++++++++++++
 examples/bindist/README.md    | 41 +++++++++++++++++++++++++++++++++++
 examples/bindist/abc/Makefile |  1 +
 examples/bindist/abc/abc.c    | 29 +++++++++++++++++++++++++
 examples/bindist/main.c       | 36 ++++++++++++++++++++++++++++++
 5 files changed, 137 insertions(+)
 create mode 100644 examples/bindist/Makefile
 create mode 100644 examples/bindist/README.md
 create mode 100644 examples/bindist/abc/Makefile
 create mode 100644 examples/bindist/abc/abc.c
 create mode 100644 examples/bindist/main.c

diff --git a/examples/bindist/Makefile b/examples/bindist/Makefile
new file mode 100644
index 000000000..1ff324976
--- /dev/null
+++ b/examples/bindist/Makefile
@@ -0,0 +1,30 @@
+# name of your application
+APPLICATION = bindist
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= native
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../..
+
+# Comment this out to disable code in RIOT that does safety checking
+# which is not needed in a production environment but helps in the
+# development process:
+CFLAGS += -DDEVELHELP
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+# bindist specific stuff:
+#
+# build and use module "abc".
+# use BINARY_DIRS instead of DIRS
+BINARY_DIRS += abc
+USEMODULE += abc
+
+# list of files to include in binary distribution
+# "bin/$(BOARD)/$(APPLICATION).elf" will automatically be added
+DIST_FILES += Makefile
+DIST_FILES += bin/$(BOARD)/abc.a
+
+include $(RIOTBASE)/Makefile.include
diff --git a/examples/bindist/README.md b/examples/bindist/README.md
new file mode 100644
index 000000000..fc214bb69
--- /dev/null
+++ b/examples/bindist/README.md
@@ -0,0 +1,41 @@
+# Introduction
+
+RIOT allows for creating a "binary distribution", which can be used to ship
+proprietary, compiled objects in a way that makes it possible to re-link them
+against a freshly compiled RIOT.
+This "binary distribution" also contains version information and md5 hashes of
+a linked binary, making verification of correctness of a link possible.
+
+This application serves as simple example for "make bindist".
+It consists of an application module (bindist.a) and another example module
+(abc.a).
+
+## Instructions
+
+Calling "make bindist" creates a folder "bindist", which only contains the
+compiled and linked binary, bindist.a, abc.a and Makefiles.
+
+In order to recompile RIOT, adjust "RIOTBASE" in Makefile to point to a RIOT
+source checkout, then call "make check_bindist".
+
+RIOT will be build as usual, but just take the pre-compiled bindist.a and
+abc.a.  Their source is not necessary.  The resulting binary will then be
+compared with te precompiled  "bindist.elf" (using md5sum) and the result gets
+printed.  If the same RIOT source tree and build environment (compiler version,
+etc.) was used, the binaries should match.
+
+Step-by-step:
+
+1. # cd <riot-checkout>/examples/bindist
+2. # make all
+3. # make bindist
+4. # cd bindist
+5. <adjust RIOTBASE variable (../.. -> ../../..)
+6. # make check_bindist
+
+## Needed Makefile changes
+
+In order to enable "make bindist" for your application, several things have to
+be changed in the main application's Makefile.
+
+See this application's Makefile as example.
diff --git a/examples/bindist/abc/Makefile b/examples/bindist/abc/Makefile
new file mode 100644
index 000000000..48422e909
--- /dev/null
+++ b/examples/bindist/abc/Makefile
@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base
diff --git a/examples/bindist/abc/abc.c b/examples/bindist/abc/abc.c
new file mode 100644
index 000000000..6a0552dd3
--- /dev/null
+++ b/examples/bindist/abc/abc.c
@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2016 Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       Binary distribution example code
+ *
+ * This file contains just example code that will end up in a example binary
+ * distribution folder.
+ *
+ * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+void abc(void)
+{
+    printf("abc!\n");
+}
diff --git a/examples/bindist/main.c b/examples/bindist/main.c
new file mode 100644
index 000000000..e3e34de0a
--- /dev/null
+++ b/examples/bindist/main.c
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2016 Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       Binary distribution example
+ *
+ * This application serves as simple example for "make bindist", a makefile
+ * target that can be used to ship proprietary, compiled objects together
+ * with a compiled binary in a way that allows re-linking and makes
+ * verification possible.
+ *
+ * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+extern void abc(void);
+
+int main(void)
+{
+    puts("Hello closed-source!");
+    abc();
+
+    return 0;
+}