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