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
  14  * [ninja]
  15  * Python headers (`python3-dev`)
  16  * [JACK] headers (`libjack-jackd2-dev` (recommended) or `libjack-dev`)
  17  * glib2 headers (`libglib-2.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 3.6)
  24  * [Pygobject]
  25  * [pycairo]
  26  * `libjack` and JACK server (`jackd2` (recommended) or `jackd`)
  27
  28 Optional run-time dependencies:
  29
  30 * [pyxdg] - For saving your preferences (strongly recommended)
  31 * [NSM] - For NSM session management support
  32
  33
  34 ## Building
  35
  36 Building with meson always happens in a special build directory. Set up the
  37 build in the `builddir` sub-directory and configure the build with:
  38
  39 ```console
  40 meson setup builddir --prefix=/usr --buildtype=release
  41 ```
  42
  43 Then build the software with:
  44
  45 ```console
  46 meson compile -C builddir
  47 ```
  48
  49
  50 ## Installation
  51
  52 ```console
  53 [sudo] meson install -C builddir
  54 ```
  55
  56 **Note for packagers**: to install all files under a destination directory
  57 other than the filesystem root, set the `DESTDIR` environment variable for
  58 `meson install`.
  59
  60 For example:
  61
  62 ```console
  63 DESTDIR="/tmp/jack_mixer-install-root" meson install -C builddir
  64 ```
  65
  66
  67 ## Build options
  68
  69 There are several project-specific [options] to configure the build and the
  70 resulting installation. To see all supported options (including [standard
  71 meson options]) and their possible values run:
  72
  73 ```console
  74 meson configure
  75 ```
  76
  77 If you have already set up the build directory, you can append its name
  78 to see the current values of all options for this build configuration.
  79
  80 To change an option, pass the build directory and `-Doption=value` to
  81 `meson setup` or `meson configure`. For example:
  82
  83 ```console
  84 meson configure builddir -Dgui=disabled
  85 ```
  86
  87
  88 ## Building a Python wheel (for maintainers)
  89
  90 1. Make sure you have Python 3, `git` and [pip] installed:
  91 2. Run the following command to build a binary wheel:
  92
  93 ```console
  94 pip wheel .
  95 ```
  96
  97 This will automatically download the required build tools, e.g. Cython, meson,
  98 ninja, the Python `wheel` package etc. (see the [pyproject.toml] file for
  99 details), build the software with meson and then package it into a wheel, which
 100 will be placed in the project's root directory.
 101
 102 The wheel can be installed with `pip install jack_mixer-*.whl`.
 103
 104
 105 [docutils]: https://pypi.org/project/docutils/
 106 [Cython]: https://cython.org/
 107 [JACK]: https://jackaudio.org/
 108 [meson]: https://mesonbuild.com/
 109 [ninja]: https://ninja-build.org/
 110 [NSM]: https://github.com/linuxaudio/new-session-manager
 111 [options]: https://mesonbuild.com/Build-options.html
 112 [pip]: https://pypi.org/project/pip/
 113 [pycairo]: https://pypi.org/project/pycairo/
 114 [PyGObject]: https://pypi.org/project/PyGObject/
 115 [pyxdg]: https://freedesktop.org/wiki/Software/pyxdg/
 116 [PEP-517]: https://www.python.org/dev/peps/pep-0517/
 117 [pyproject.toml]: ./pyproject.toml
 118 [standard meson options]: https://mesonbuild.com/Builtin-options.html