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