plugins/README: expand background and usage

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.