INSTALL.md

   1 Installation
   2 ============
   3
   4 **jack_mixer** uses the [meson] build system for building, installation and
   5 packaging.
   6
   7
   8 ## Requirements
   9
  10 Build requirements:
  11
  12  * GCC (version >= 9.x recommended)
  13  * meson >= 0.64.0
  14  * [ninja]
  15  * Python headers
  16  * [JACK] headers
  17  * glib2 headers
  18  * gettext
  19  * [Cython] (optional, required if building from a Git checkout)
  20  * [docutils] (optional, `rst2man` required if building from a Git checkout)
  21
  22 Runtime requirements:
  23
  24  * Python >= 3.8
  25  * [Pygobject]
  26  * [pycairo]
  27  * JACK library and server
  28
  29 Optional run-time dependencies:
  30
  31 * [appdirs] (for saving your preferences, strongly recommended)
  32 * [NSM] (for NSM session management support)
  33
  34 The run-time Python dependencies are checked by meson when setting up the
  35 build directory. To disable this, use the `-Dcheck-py-modules=false` option to
  36 `meson setup.`
  37
  38
  39 ## Building
  40
  41 Building with meson always happens in a special build directory. Set up the
  42 build in the `builddir` sub-directory and configure the build with:
  43
  44 ```console
  45 meson setup builddir --prefix=/usr --buildtype=release
  46 ```
  47
  48 Then build the software with:
  49
  50 ```console
  51 meson compile -C builddir
  52 ```
  53
  54 **Note:** *For building **jack_mixer** from source on **debian / Ubuntu**
  55 derrived Linux distributions, please refer to this [wiki page]. If possible,
  56 use your distribution's package manager to install **jack_mixer**.*
  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 (only for special needs)
  98
  99 **Note:** Due to limitations of Python's build ecosystem, the wheel packages
 100 built with the instructions given here, will *not* contain any files used
 101 for system desktop integration, e.g. icons and `.desktop' files, nor man pages
 102 or translation files. Using this method to install jack_mixer is thus not
 103 recommended and mainly provided for testing prurposes.
 104
 105 1. Make sure you have Python 3, `git`, [pip] and the Python [build] package
 106    installed and your internet connection is online.
 107 2. Run the following command to build a binary wheel:
 108
 109 ```console
 110 python -m build -w
 111 ```
 112
 113 This will automatically download the required build tools, e.g. Cython, meson,
 114 ninja, the Python `wheel` package etc. (see the [pyproject.toml] file for
 115 details), build the software with meson and then package it into a wheel, which
 116 will be placed in the `dist` directory below the project's root directory.
 117
 118 The wheel can be installed with `python -m pip install dist/jack_mixer-*.whl`.
 119
 120
 121 [docutils]: https://pypi.org/project/docutils/
 122 [build]: https://pypi.org/project/build
 123 [Cython]: https://cython.org/
 124 [JACK]: https://jackaudio.org/
 125 [meson]: https://mesonbuild.com/
 126 [ninja]: https://ninja-build.org/
 127 [NSM]: https://new-session-manager.jackaudio.org/
 128 [options]: https://mesonbuild.com/Build-options.html
 129 [pip]: https://pypi.org/project/pip
 130 [pycairo]: https://pypi.org/project/pycairo/
 131 [PyGObject]: https://pypi.org/project/PyGObject/
 132 [appdirs]: https://pypi.org/project/appdirs/
 133 [PEP-517]: https://www.python.org/dev/peps/pep-0517/
 134 [pyproject.toml]: ./pyproject.toml
 135 [standard meson options]: https://mesonbuild.com/Builtin-options.html
 136 [wiki page]: https://github.com/jack-mixer/jack_mixer/wiki/Installing-on-debian---Ubuntu