From 422eab6f0a79172d0391baebe8b4cebd83f663b2 Mon Sep 17 00:00:00 2001
From: Tony Theodore <tonyt@logyst.com>
Date: Mon, 4 Jul 2016 19:58:50 +1000
Subject: plugins/README: expand background and usage
---
plugins/README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 149 insertions(+), 18 deletions(-)
diff --git a/plugins/README.md b/plugins/README.md
index 56b0b8b..9f8726c 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -1,27 +1,158 @@
### MXE Plugins
-MXE lets you override the way packages are built and installed by offering
-plugins mechanism. This directory contains a collection of example plugins and
-experimental content. Enjoy!
+#### Overview
-*Note: the files here should be considered examples only and are unmaintained.*
+MXE aims to provide a stable toolchain and feature-rich set of libraries to
+be as broadly applicable as possible. Many use cases fall outside this main
+objective and plugins are a way to bridge the gap without official framework
+support.
-##### Rolling your own plugin
+The most common cases include:
-The basic usage is to drop some `*.mk` files in a directory `foo/` and set
-`MXE_PLUGIN_DIRS='foo/'` while invoking `make` like this:
+##### Additional packages
-```console
-MXE_PLUGIN_DIRS=foo/ make libpng
+ - building handy tools to run on host
+ - cross-compiled interpreters and packages
+ - examples of packaging complete builds for projects using MXE
+
+The `apps`, `luarocks`, and `native` directories are generally supported by
+the project, each plugin package should have an identified `$(PKG)_OWNER` as
+a primary contact familiar with the specifics of the plugin.
+
+##### Customisation
+
+ - alternate compiler versions
+ - minimal features/dependencies
+ - building a host toolchain
+
+The `examples` and `gcc*` directories contain some starting points for
+experiments or long-lived customisations. Attempts to do such things with
+`git` branches can lead to an outdated core MXE and using plugins allows a
+nice separation while still keeping all local changes under source control.
+
+These are experimental and will be deprecated over time as framework support
+is added to handle the various forms of customisation.
+
+##### Internal MXE uses
+
+The `native` plugin contains sub-directories with symlinks to a subset of
+packages in the parent directory. These "sub-plugins" are automatically
+activated on certain systems where the standard package-manager versions are
+known to cause issues. These are supported but subject to change or removal
+over time and should not be used directly.
+
+#### Usage
+
+The current implementation is very lightweight and a `plugin` is simply a
+directory containing *.mk files. When a plugin is activated with:
+
+```
+make MXE_PLUGIN_DIRS=/path/to/foo
+```
+
+MXE will:
+
+ - include all core packages
+ - include `/path/to/foo/*.mk`
+ - create a target for each `*.mk` file
+ - create an `all-foo` target
+
+Multiple plugins can be activated on the command line with an escaped
+space-separated list:
+
+```
+make MXE_PLUGIN_DIRS='/path/to/foo /path/to/foo2'
+```
+
+To ensure plugins are activated across multiple invocations of `make`, the
+`MXE_PLUGIN_DIRS` variable must always be specified either on the command line
+or by adding an entry in `settings.mk`
+
+*N.B.* Setting `MXE_PLUGIN_DIRS` via the environment is not guaranteed to
+work in future versions.
+
+For example, if you want to build keepassx from the `apps` plugin with
+a minimal qt run:
+
+```
+make keepassx MXE_PLUGIN_DIRS='plugins/examples/custom-qt-min plugins/apps'
```
-If needed, you can also pass multiple directories by separating them with a
-space: `MXE_PLUGIN_DIRS='foo1/ foo2/'`. A plugin takes effect only if it is
-provided in `MXE_PLUGIN_DIRS`. If you run `make` multiple times, do not
-remove a plugin path from `MXE_PLUGIN_DIRS`, otherwise MXE will rebuild
-without the plugin. For example, if you want to build qbittorrent from
-`apps` plugin with gcc 6 provided by `gcc6` plugin, set `MXE_PLUGIN_DIRS`
-to 'plugins/gcc6 plugins/apps' and then run `make qbittorrent`.
+To build all packages in `luarocks`:
+
+```
+$ make all-luarocks MXE_PLUGIN_DIRS=plugins/luarocks
+```
+
+To **always** use your desired plugin:
+
+```
+echo 'override MXE_PLUGIN_DIRS += /path/to/foo' >> settings.mk
+```
+
+Note that multiple entries in `settings.mk` should not be escaped:
+
+```
+echo 'override MXE_PLUGIN_DIRS += /path/to/foo /path/to/foo2' >> settings.mk
+```
+
+To review which plugins are activated, use the `gmsl-print-*` target:
+
+```
+make gmsl-print-MXE_PLUGIN_DIRS MXE_PLUGIN_DIRS='/foo /bar'
+```
+
+#### Creating plugins
+
+The two main use cases lead to different styles of plugin. The first case of
+additional packages follows normal MXE guidelines and reviewing the contents of
+`src/*.mk`, or the `apps` and `luarocks` plugins should help getting started.
+This type of package will also work with normal MXE features such as updates
+and patches.
+
+The customisation style (override/overlay) can be trickier since any arbitrary
+`make` statements can be used. Most normal variables should be overriden with
+[simply expanded variables](https://www.gnu.org/software/make/manual/html_node/Flavors.html#Flavors)
+i.e. using `:=` instead of `=`. For example, to change a package version:
+
+```make
+PKG := foo
+$(PKG)_VERSION := 1.2.3
+$(PKG)_CHECKSUM := 09c4c85cab...
+```
+
+In this case, the behaviour of `make update-package-foo` may not be able to
+determine the correct file to update with the new version and checksum and
+`make` may not detect that the target should be rebuilt (depending on how
+files are named). This is an on-going work that will be addressed.
+
+To change the set of patches applied:
+
+```make
+foo_PATHCES := /path/to/fisrt.patch /path/to/second.patch
+```
+
+To apply no patches:
+
+```make
+foo_PATHCES :=
+```
+
+To alter dependencies and components:
+
+```make
+qt_DEPS := gcc dbus jpeg libmng libpng openssl tiff zlib
+
+qt_BUILD := \
+ $(subst -accessibility ,-no-accessibility ,\
+ $(subst -qt-sql-,-no-sql-,\
+ $(qt_BUILD)))
+
+qt_BUILD_SHARED := \
+ $(subst -static ,-shared ,\
+ $(subst -no-webkit ,-webkit ,\
+ $(qt_BUILD)))
+```
-For details on `*.mk` contents, please consult the contents of this directory
-and `src/*.mk`.
+Note the order of inclusion is indeterminate so multiple plugins should not
+be chained or attempt to add/modify the same package.
--
cgit v0.12
From f0e9cf6f5db5ff2782b4a98a9e5066f2e65c1295 Mon Sep 17 00:00:00 2001
From: Tony Theodore <tonyt@logyst.com>
Date: Mon, 4 Jul 2016 20:01:48 +1000
Subject: plugins/qt5-deps: move to examples
---
plugins/examples/qt5-deps/overrides.mk | 5 +++++
plugins/qt5-deps/overrides.mk | 5 -----
2 files changed, 5 insertions(+), 5 deletions(-)
create mode 100644 plugins/examples/qt5-deps/overrides.mk
delete mode 100644 plugins/qt5-deps/overrides.mk
diff --git a/plugins/examples/qt5-deps/overrides.mk b/plugins/examples/qt5-deps/overrides.mk
new file mode 100644
index 0000000..c437086
--- /dev/null
+++ b/plugins/examples/qt5-deps/overrides.mk
@@ -0,0 +1,5 @@
+# This file is part of MXE.
+# See index.html for further information.
+
+poppler_DEPS := $(filter-out qt ,$(poppler_DEPS)) qtbase
+openscenegraph_DEPS := $(filter-out qt ,$(openscenegraph_DEPS)) qtbase
diff --git a/plugins/qt5-deps/overrides.mk b/plugins/qt5-deps/overrides.mk
deleted file mode 100644
index c437086..0000000
--- a/plugins/qt5-deps/overrides.mk
+++ /dev/null
@@ -1,5 +0,0 @@
-# This file is part of MXE.
-# See index.html for further information.
-
-poppler_DEPS := $(filter-out qt ,$(poppler_DEPS)) qtbase
-openscenegraph_DEPS := $(filter-out qt ,$(openscenegraph_DEPS)) qtbase
--
cgit v0.12
From a0a3340772dd42ce0c36686aea6debd55513c346 Mon Sep 17 00:00:00 2001
From: Tony Theodore <tonyt@logyst.com>
Date: Tue, 5 Jul 2016 16:23:22 +1000
Subject: Makefile: allow packages to specify a list of zero or more patches
---
Makefile | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/Makefile b/Makefile
index 2edab45..ab61761 100644
--- a/Makefile
+++ b/Makefile
@@ -190,7 +190,11 @@ UNPACK_PKG_ARCHIVE = \
# all files for extension plugins will be considered for outdated checks
PKG_MAKEFILES = $(realpath $(sort $(wildcard $(addsuffix /$(1).mk, $(TOP_DIR)/src $(MXE_PLUGIN_DIRS)))))
PKG_TESTFILES = $(realpath $(sort $(wildcard $(addsuffix /$(1)-test*, $(TOP_DIR)/src $(MXE_PLUGIN_DIRS)))))
-PKG_PATCHES = $(realpath $(sort $(wildcard $(addsuffix /$(1)-[0-9]*.patch, $(TOP_DIR)/src $(MXE_PLUGIN_DIRS)))))
+# allow packages to specify a list of zero or more patches
+PKG_PATCHES = $(if $(findstring undefined,$(origin $(1)_PATCHES)), \
+ $(realpath $(sort $(wildcard $(addsuffix /$(1)-[0-9]*.patch, $(TOP_DIR)/src $(MXE_PLUGIN_DIRS))))) \
+ $(else), \
+ $($(1)_PATCHES))
define PREPARE_PKG_SOURCE
cd '$(2)' && $(call UNPACK_PKG_ARCHIVE,$(1))
--
cgit v0.12
From 5b666dc4792e6ca0c1fe027ecb4098a239ea515e Mon Sep 17 00:00:00 2001
From: Tony Theodore <tonyt@logyst.com>
Date: Tue, 5 Jul 2016 16:24:42 +1000
Subject: custom-qt-min plugin: fix for doc example
---
plugins/examples/custom-qt-min/overrides.mk | 1 +
1 file changed, 1 insertion(+)
diff --git a/plugins/examples/custom-qt-min/overrides.mk b/plugins/examples/custom-qt-min/overrides.mk
index bbb1223..f5e5e3a 100644
--- a/plugins/examples/custom-qt-min/overrides.mk
+++ b/plugins/examples/custom-qt-min/overrides.mk
@@ -75,6 +75,7 @@ define qt_BUILD
$(MAKE) -C '$(1)' -j '$(JOBS)'
rm -rf '$(PREFIX)/$(TARGET)/qt'
$(MAKE) -C '$(1)' -j 1 install
+ ln -sf '$(PREFIX)/$(TARGET)/qt/bin/qmake' '$(PREFIX)/bin/$(TARGET)'-qmake-qt4
mkdir '$(1)/test-qt'
cd '$(1)/test-qt' && '$(PREFIX)/$(TARGET)/qt/bin/qmake' '$(PWD)/$(2).pro'
--
cgit v0.12