mirror of https://github.com/mpv-player/mpv
158 lines
6.5 KiB
ReStructuredText
158 lines
6.5 KiB
ReStructuredText
waf build system overview
|
|
=========================
|
|
|
|
mpv's new build system is based on waf and it should completely replace the
|
|
custom ./configure + Makefile based system inherited from MPlayer.
|
|
|
|
Goals and the choice of waf
|
|
===========================
|
|
|
|
The new system comes with some goals, which can be summed up as: be as good as
|
|
the old one at what it did well (customizability) and fix some of it's major
|
|
shortcomings:
|
|
|
|
1) The build system must be uniform in how it handles any single feature check.
|
|
Repetition and boilerplate have to be avoided.
|
|
|
|
When adding a new feature using the old configure, one had to add a fair
|
|
amount of code to the shell script to do option parsing, detection of the
|
|
feature and declaration of variables for the Makefile to pickup. The worst
|
|
part is this pieces are spread apart in the configure and copy pasted for
|
|
any single case. That brings us to..
|
|
|
|
2) --enable-feature has to be overridden by the user and helps them understand that
|
|
they have libraries missing and should install them for the feature to be
|
|
enabled.
|
|
|
|
3) Must be customizable, hackable, pleasant to the developer eyes and to work
|
|
with in general.
|
|
|
|
4) Must have separate configuration and build steps.
|
|
|
|
Goal 2 comes as a given on pretty much any build system, since autotools made
|
|
this behaviour very popular among users (and rightly so).
|
|
|
|
Goal 1+3 were somewhat harder to accomplish as it looks like all of the build
|
|
systems we evaluated (waf included!) had problems with them. For reference we
|
|
had proof of concept build systems with waf, CMake and autotools.
|
|
|
|
What puts waf apart from CMake and autotools, is that projects using it use
|
|
Python to program their build system. Also while the Waf Book shows really
|
|
simple API usages, you can write your own build system on top of waf that is
|
|
tailored to the project's specific needs.
|
|
|
|
mpv's custom configure step on top of waf
|
|
=========================================
|
|
|
|
To some extents mpv has a custom build system written on top of waf. This
|
|
document will not go over the standard waf behaviour as that is documented in
|
|
the `Waf book <https://waf.io/book/>`_.
|
|
|
|
All of the configuration process is handled with a declarative approach. Lists
|
|
of dictionaries define the checks, and some custom Python code traverses these
|
|
lists and depending on the check definition it calls into the actual waf API.
|
|
|
|
A simple example using pkg-config would be::
|
|
|
|
{
|
|
'name': '--vdpau',
|
|
'desc': 'VDPAU acceleration',
|
|
'deps': [ 'x11' ],
|
|
'func': check_pkg_config('vdpau', '>= 0.2'),
|
|
}
|
|
|
|
This defines a feature called ``vdpau`` which can be enabled or disabled by
|
|
the users with configure flags (that's the meaning of ``--``). This feature
|
|
depends on another feature whose name is ``x11``, and the autodetection check
|
|
consists of running ``pkg-config`` and looking for ``vdpau`` with version
|
|
``>= 0.2``. If the check succeeds a ``#define HAVE_VDPAU 1`` will be added to
|
|
``config.h``, if not ``#define HAVE_VDPAU 0`` will be added.
|
|
|
|
The defines names are automatically prepended with ``HAVE_``, capitalized and
|
|
special characters are replaced with underscores. This happens in
|
|
``waftools/inflectors.py``.
|
|
|
|
Mandatory fields:
|
|
-----------------
|
|
|
|
``name``: indicates the unique identifier used by the custom dependency code
|
|
to refer to a feature. If the unique identifier is prepended with ``--``
|
|
the build system will also generate options for ``./waf configure`` so that
|
|
the feature can be enabled and disabled.
|
|
|
|
``desc``: this is the textual representation of the feature used in the
|
|
interactions with the users.
|
|
|
|
``func``: function that will perform the check. These functions are defined in
|
|
``waftools/checks``. The reusable checks are all functions that return
|
|
functions. The return functions will then be applied using waf's configuration
|
|
context.
|
|
|
|
The source code for the reusable checks is a bit convoluted, but it should be
|
|
easy to pick up their usage from the ``wscript``. Their signature mirrors
|
|
the semantics of some of the shell functions used in mplayer.
|
|
|
|
If someone expresses some interest, I will extend this document with official
|
|
documentation for each check function.
|
|
|
|
Optional fields
|
|
---------------
|
|
|
|
``deps``: list of dependencies of this feature. It is a list of names of
|
|
other features as defined in the ``name`` field (minus the eventual leading
|
|
``--``). All of the dependencies must be satisfied. If they are not the check
|
|
will be skipped without even running ``func``.
|
|
|
|
``deps_any``: like deps but it is satisfied even if only one of the dependencies
|
|
is satisfied. You can think of ``deps`` as a 'and' condition and ``deps_any``
|
|
as a 'or' condition.
|
|
|
|
``deps_neg``: like deps but it is satisfied when none of the dependencies is
|
|
satisfied.
|
|
|
|
``req``: defaults to False. If set to True makes this feature a hard
|
|
dependency of mpv (configuration will fail if autodetection fails). If set to
|
|
True you must also provide ``fmsg``.
|
|
|
|
``fmsg``: string with the failure message in case a required dependency is not
|
|
satisfied.
|
|
|
|
``os_specific_checks``: this takes a dictionary that has ``os-`` dependencies
|
|
as keys (such as ``os-win32``), and by values has another dictionary that is
|
|
merged on top of the current feature definition only for that specific OS.
|
|
For example::
|
|
|
|
{
|
|
'name': '--pthreads',
|
|
'desc': 'POSIX threads',
|
|
'func': check_pthreads,
|
|
'os_specific_checks': {
|
|
'os-win32': {
|
|
'func': check_pthreads_w32_static.
|
|
}
|
|
}
|
|
}
|
|
|
|
will override the value of ``func`` with ``check_pthreads_w32_static`` only
|
|
if the target OS of the build is Windows.
|
|
|
|
``groups``: groups a dependency with another one. This can be used to disabled
|
|
all the grouped dependencies with one ``--disable-``. At the moment this is
|
|
only used for OpenGL backends, where you want to disable them when
|
|
``--disable-gl`` is passed to the configure.
|
|
|
|
mpv's custom build step on top of waf
|
|
=====================================
|
|
|
|
Build step is pretty much vanilla waf. The only difference being that the list
|
|
of source files can contain both strings or tuples. If a tuple is found,
|
|
the second element in the tuple will be used to match the features detected
|
|
in the configure step (the ``name`` field described above). If this feature
|
|
was not enabled during configure, the source file will not be compiled in.
|
|
|
|
All of the custom Python for this is inside the function ``filtered_sources``
|
|
contained in the file ``waftools/dependencies.py``.
|
|
|
|
Also ``dependencies_use`` and ``dependencies_includes`` collect cflags and
|
|
ldflags that were generated from the features checks in the configure step.
|