Merge pull request #1418 from tonytheodore/plugin-docs

Plugin docs and add $(PKG)_PATCHES field
This commit is contained in:
Boris Nagaev 2016-07-05 12:28:05 +04:00 committed by GitHub
commit e126df803b
4 changed files with 155 additions and 19 deletions

View File

@ -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))

View File

@ -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
```
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`.
MXE will:
For details on `*.mk` contents, please consult the contents of this directory
and `src/*.mk`.
- 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'
```
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)))
```
Note the order of inclusion is indeterminate so multiple plugins should not
be chained or attempt to add/modify the same package.

View File

@ -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'