From 422eab6f0a79172d0391baebe8b4cebd83f663b2 Mon Sep 17 00:00:00 2001 From: Tony Theodore Date: Mon, 4 Jul 2016 19:58:50 +1000 Subject: [PATCH] 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 56b0b8b1..9f8726cb 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.