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, package `build-essential` on Debian/Ubuntu)
  13  * meson >= 0.54.0[<sup>1</sup>](#1)
  14  * [ninja]
  15  * Python headers (`python3-dev`)
  16  * [JACK] headers (`libjack-jackd2-dev` (recommended) or `libjack-dev`)
  17  * glib2 headers (`libglib2.0-dev`)
  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 (at least version 3.6)
  24  * [Pygobject] (`python3-gi`)
  25  * [pycairo] (`python3-cairo`)
  26  * JACK library (`libjack-jack2-0` or `libjack0`) and server (`jackd2` or `jackd1`)
  27
  28 Optional run-time dependencies:
  29
  30 * [pyxdg] (`python-xdg`) - 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
  59 ## Installation
  60
  61 ```console
  62 [sudo] meson install -C builddir
  63 ```
  64
  65 **Note for packagers**: to install all files under a destination directory
  66 other than the filesystem root, set the `DESTDIR` environment variable for
  67 `meson install`.
  68
  69 For example:
  70
  71 ```console
  72 DESTDIR="/tmp/jack_mixer-install-root" meson install -C builddir
  73 ```
  74
  75
  76 ## Build options
  77
  78 There are several project-specific [options] to configure the build and the
  79 resulting installation. To see all supported options (including [standard
  80 meson options]) and their possible values run:
  81
  82 ```console
  83 meson configure
  84 ```
  85
  86 If you have already set up the build directory, you can append its name
  87 to see the current values of all options for this build configuration.
  88
  89 To change an option, pass the build directory and `-Doption=value` to
  90 `meson setup` or `meson configure`. For example:
  91
  92 ```console
  93 meson configure builddir -Dgui=disabled
  94 ```
  95
  96
  97 ## Building a Python wheel (for maintainers)
  98
  99 1. Make sure you have Python 3, `git` and [pip] installed and your internet
 100    connection is online.
 101 2. Run the following command to build a binary wheel:
 102
 103 ```console
 104 pip wheel .
 105 ```
 106
 107 This will automatically download the required build tools, e.g. Cython, meson,
 108 ninja, the Python `wheel` package etc. (see the [pyproject.toml] file for
 109 details), build the software with meson and then package it into a wheel, which
 110 will be placed in the project's root directory.
 111
 112 The wheel can be installed with `pip install jack_mixer-*.whl`.
 113
 114
 115 [docutils]: https://pypi.org/project/docutils/
 116 [Cython]: https://cython.org/
 117 [JACK]: https://jackaudio.org/
 118 [meson]: https://mesonbuild.com/
 119 [ninja]: https://ninja-build.org/
 120 [NSM]: https://github.com/linuxaudio/new-session-manager
 121 [options]: https://mesonbuild.com/Build-options.html
 122 [pip]: https://pypi.org/project/pip/
 123 [pycairo]: https://pypi.org/project/pycairo/
 124 [PyGObject]: https://pypi.org/project/PyGObject/
 125 [pyxdg]: https://freedesktop.org/wiki/Software/pyxdg/
 126 [PEP-517]: https://www.python.org/dev/peps/pep-0517/
 127 [pyproject.toml]: ./pyproject.toml
 128 [standard meson options]: https://mesonbuild.com/Builtin-options.html