INSTALL.md

   1 Installation
   2 ============
   3
   4 **jack_mixer** uses [meson] and optionally a Python [PEP-517]-compliant build
   5 system for building, installation and packaging.
   6
   7
   8 ## Requirements
   9
  10 Build requirements:
  11
  12  * GCC (version 9.x or 10.x recommended)
  13  * meson >= 0.54.0[<sup>1</sup>](#1)
  14  * [ninja]
  15  * Python headers
  16  * [JACK] headers
  17  * glib2 headers
  18  * gettext
  19  * [Cython] (optional, required if building from a Git checkout)
  20  * [docutils] (optional, `rst2man` required if building from a Git checkout)
  21
  22 Runtime requirements:
  23
  24  * Python >= 3.6
  25  * [Pygobject]
  26  * [pycairo]
  27  * JACK library and server
  28
  29 Optional run-time dependencies:
  30
  31 * [pyxdg] (for saving your preferences, strongly recommended)
  32 * [NSM] (for NSM session management support)
  33
  34 The run-time Python dependencies are checked by meson when setting up the
  35 build directory. To disable this, use the `-Dcheck-py-modules=false` option to
  36 `meson setup.`
  37
  38 <a class="anchor" id="1"></a>
  39
  40 <sup>1</sup> *meson 0.53.0 also works if you use `ninja compile` and
  41 `ninja install` instead of  `meson compile` and `meson install`.*
  42
  43
  44 ## Building
  45
  46 Building with meson always happens in a special build directory. Set up the
  47 build in the `builddir` sub-directory and configure the build with:
  48
  49 ```console
  50 meson setup builddir --prefix=/usr --buildtype=release
  51 ```
  52
  53 Then build the software with:
  54
  55 ```console
  56 meson compile -C builddir
  57 ```
  58
  59 **Note:** *For building **jack_mixer** from source on **debian / Ubuntu**
  60 derrived Linux distributions, please refer to this [wiki page]. If possible,
  61 use your distribution's package manager to install **jack_mixer**.*
  62
  63
  64 ## Installation
  65
  66 ```console
  67 [sudo] meson install -C builddir
  68 ```
  69
  70 **Note for packagers**: to install all files under a destination directory
  71 other than the filesystem root, set the `DESTDIR` environment variable for
  72 `meson install`.
  73
  74 For example:
  75
  76 ```console
  77 DESTDIR="/tmp/jack_mixer-install-root" meson install -C builddir
  78 ```
  79
  80
  81 ## Build options
  82
  83 There are several project-specific [options] to configure the build and the
  84 resulting installation. To see all supported options (including [standard
  85 meson options]) and their possible values run:
  86
  87 ```console
  88 meson configure
  89 ```
  90
  91 If you have already set up the build directory, you can append its name
  92 to see the current values of all options for this build configuration.
  93
  94 To change an option, pass the build directory and `-Doption=value` to
  95 `meson setup` or `meson configure`. For example:
  96
  97 ```console
  98 meson configure builddir -Dgui=disabled
  99 ```
 100
 101
 102 ## Building a Python wheel (for maintainers)
 103
 104 1. Make sure you have Python 3, `git` and [pip] installed and your internet
 105    connection is online.
 106 2. Run the following command to build a binary wheel:
 107
 108 ```console
 109 pip wheel .
 110 ```
 111
 112 This will automatically download the required build tools, e.g. Cython, meson,
 113 ninja, the Python `wheel` package etc. (see the [pyproject.toml] file for
 114 details), build the software with meson and then package it into a wheel, which
 115 will be placed in the project's root directory.
 116
 117 The wheel can be installed with `pip install jack_mixer-*.whl`.
 118
 119
 120 [docutils]: https://pypi.org/project/docutils/
 121 [Cython]: https://cython.org/
 122 [JACK]: https://jackaudio.org/
 123 [meson]: https://mesonbuild.com/
 124 [ninja]: https://ninja-build.org/
 125 [NSM]: https://new-session-manager.jackaudio.org/
 126 [options]: https://mesonbuild.com/Build-options.html
 127 [pip]: https://pypi.org/project/pip/
 128 [pycairo]: https://pypi.org/project/pycairo/
 129 [PyGObject]: https://pypi.org/project/PyGObject/
 130 [pyxdg]: https://freedesktop.org/wiki/Software/pyxdg/
 131 [PEP-517]: https://www.python.org/dev/peps/pep-0517/
 132 [pyproject.toml]: ./pyproject.toml
 133 [standard meson options]: https://mesonbuild.com/Builtin-options.html
 134 [wiki page]: https://github.com/jack-mixer/jack_mixer/wiki/Installing-on-debian---Ubuntu