Something went wrong. Try again.
🎥 Command line media player
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158waf build system overview=========================
mpv's new build system is based on waf and it should completely replace thecustom ./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 asthe old one at what it did well (customizability) and fix some of it's majorshortcomings:
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 madethis behaviour very popular among users (and rightly so).
Goal 1+3 were somewhat harder to accomplish as it looks like all of the buildsystems we evaluated (waf included!) had problems with them. For reference wehad proof of concept build systems with waf, CMake and autotools.
What puts waf apart from CMake and autotools, is that projects using it usePython to program their build system. Also while the Waf Book shows reallysimple API usages, you can write your own build system on top of waf that istailored 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. Thisdocument will not go over the standard waf behaviour as that is documented inthe `Waf book <http://docs.waf.googlecode.com/git/book_17/single.html>`_.
All of the configuration process is handled with a declarative approach. Listsof dictionaries define the checks, and some custom Python code traverses theselists 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 bythe users with configure flags (that's the meaning of ``--``). This featuredepends on another feature whose name is ``x11``, and the autodetection checkconsists 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 andspecial characters are replaced with underscores. This happens in``waftools/inflectors.py``.
Mandatory fields:-----------------
``name``: indicates the unique identifier used by the custom dependency codeto refer to a feature. If the unique identifier is prepended with ``--``the build system will also generate options for ``./waf configure`` so thatthe feature can be enabled and disabled.
``desc``: this is the textual representation of the feature used in theinteractions with the users.
``func``: function that will perform the check. These functions are defined in``waftools/checks``. The reusable checks are all functions that returnfunctions. The return functions will then be applied using waf's configurationcontext.
The source code for the reusable checks is a bit convoluted, but it should beeasy to pick up their usage from the ``wscript``. Their signature mirrorsthe semantics of some of the shell functions used in mplayer.
If someone expresses some interest, I will extend this document with officialdocumentation for each check function.
Optional fields---------------
``deps``: list of dependencies of this feature. It is a list of names ofother features as defined in the ``name`` field (minus the eventual leading``--``). All of the dependencies must be satisfied. If they are not the checkwill be skipped without even running ``func``.
``deps_any``: like deps but it is satisfied even if only one of the dependenciesis 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 issatisfied.
``req``: defaults to False. If set to True makes this feature a harddependency of mpv (configuration will fail if autodetection fails). If set toTrue you must also provide ``fmsg``.
``fmsg``: string with the failure message in case a required dependency is notsatisfied.
``os_specific_checks``: this takes a dictionary that has ``os-`` dependenciesas keys (such as ``os-win32``), and by values has another dictionary that ismerged 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`` onlyif the target OS of the build is Windows.
``groups``: groups a dependency with another one. This can be used to disabledall the grouped dependencies with one ``--disable-``. At the moment this isonly 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 listof 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 detectedin the configure step (the ``name`` field described above). If this featurewas 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 andldflags that were generated from the features checks in the configure step.