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