diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..8969a81 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,237 @@ +## Building + +PipeWire uses a build tool called [*Meson*](https://mesonbuild.com) as a basis for its build +process. It's a tool with some resemblance to Autotools and CMake. Meson +again generates build files for a lower level build tool called [*Ninja*](https://ninja-build.org/), +working in about the same level of abstraction as more familiar GNU Make +does. + +Meson uses a user-specified build directory and all files produced by Meson +are in that build directory. This build directory will be called `builddir` +in this document. + +Generate the build files for Ninja: + +``` +$ meson setup builddir +``` + +For distribution-specific build dependencies, please check our +[CI pipeline](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/master/.gitlab-ci.yml) +(search for `FDO_DISTRIBUTION_PACKAGES`). Note that some dependencies are +optional and depend on options passed to meson. + +Once this is done, the next step is to review the build options: + +``` +$ meson configure builddir +``` + +Define the installation prefix: + +``` +$ meson configure builddir -Dprefix=/usr # Default: /usr/local +``` + +PipeWire specific build options are listed in the "Project options" +section. They are defined in `meson_options.txt`. + +Finally, invoke the build: + +``` +$ meson compile -C builddir +``` + +Just to avoid any confusion: `autogen.sh` is a script invoked by *Jhbuild*, +which orchestrates multi-component builds. + +## Running + +If you want to run PipeWire without installing it on your system, there is a +script that you can run. This puts you in an environment in which PipeWire can +be run from the build directory, and ALSA, PulseAudio and JACK applications +will use the PipeWire emulation libraries automatically +in this environment. You can get into this environment with: + +``` +$ ./pw-uninstalled.sh -b builddir +``` + +In most cases you would want to run the default pipewire daemon. Look +below for how to make this daemon start automatically using systemd. +If you want to run pipewire from the build directory, you can do this +by doing: + +``` +cd builddir/ +make run +``` + +This will use the default config file to configure and start the daemon. +The default config will also start `pipewire-media-session`, a default +example media session and `pipewire-pulse`, a PulseAudio compatible server. + +You can also enable more debugging with the `PIPEWIRE_DEBUG` environment +variable like so: + +``` +cd builddir/ +PIPEWIRE_DEBUG="D" make run +``` + +You might have to stop the pipewire service/socket that might have been +started already, with: + +``` +systemctl --user stop pipewire.service \ + pipewire.socket \ + pipewire-media-session.service \ + pipewire-pulse.service \ + pipewire-pulse.socket +``` + +## Installing + +PipeWire comes with quite a bit of libraries and tools, run: + +``` +meson install -C builddir +``` + +to install everything onto the system into the specified prefix. +Depending on the configured installation prefix, the above command +may need to be run with elevated privileges (e.g. with `sudo`). +Some additional steps will have to be performed to integrate +with the distribution as shown below. + +### PipeWire daemon + +A correctly installed PipeWire system should have a pipewire +process, a pipewire-media-session (or alternative) and an (optional) +pipewire-pulse process running. PipeWire is usually started as a +systemd unit using socket activation or as a service. + +Configuration of the PipeWire daemon can be found in +`/usr/share/pipewire/pipewire.conf`. Please refer to the comments in the +config file for more information about the configuration options. + +The daemon is started with: +``` +systemctl --user start pipewire.service pipewire.socket +``` + +If you did not start the media-session in pipewire.conf, you will +also need to start it like this: +``` +systemctl --user start pipewire-media-session.service +``` +To make it start on system startup: +``` +systemctl --user enable pipewire-media-session.service +``` +you can write ```enable --now``` to start service immediately. + +### ALSA plugin + +The ALSA plugin is usually installed in: + +On Fedora: +``` +/usr/lib64/alsa-lib/libasound_module_pcm_pipewire.so +``` +On Ubuntu: +``` +/usr/lib/x86_64-linux-gnu/alsa-lib/libasound_module_pcm_pipewire.so +``` + +There is also a config file installed in: + +``` +/usr/share/alsa/alsa.conf.d/50-pipewire.conf +``` + +The plugin will be picked up by alsa when the following files +are in `/etc/alsa/conf.d/`: + +``` +/etc/alsa/conf.d/50-pipewire.conf -> /usr/share/alsa/alsa.conf.d/50-pipewire.conf +/etc/alsa/conf.d/99-pipewire-default.conf +``` + +With this setup, `aplay -l` should list a pipewire device that can be used as +a regular alsa device for playback and record. + +### JACK emulation + +PipeWire reimplements the 3 libraries that JACK applications use to make +them run on top of PipeWire. + +These libraries are found here: + +``` +/usr/lib64/pipewire-0.3/jack/libjacknet.so -> libjacknet.so.0 +/usr/lib64/pipewire-0.3/jack/libjacknet.so.0 -> libjacknet.so.0.304.0 +/usr/lib64/pipewire-0.3/jack/libjacknet.so.0.304.0 +/usr/lib64/pipewire-0.3/jack/libjackserver.so -> libjackserver.so.0 +/usr/lib64/pipewire-0.3/jack/libjackserver.so.0 -> libjackserver.so.0.304.0 +/usr/lib64/pipewire-0.3/jack/libjackserver.so.0.304.0 +/usr/lib64/pipewire-0.3/jack/libjack.so -> libjack.so.0 +/usr/lib64/pipewire-0.3/jack/libjack.so.0 -> libjack.so.0.304.0 +/usr/lib64/pipewire-0.3/jack/libjack.so.0.304.0 + +``` + +The provided `pw-jack` script uses `LD_LIBRARY_PATH` to set the library +search path to these replacement libraries. This allows you to run +jack apps on both the real JACK server or on PipeWire with the script. + +It is also possible to completely replace the JACK libraries by adding +a file `pipewire-jack-x86_64.conf` to `/etc/ld.so.conf.d/` with +contents like: + +``` +/usr/lib64/pipewire-0.3/jack/ +``` + +Note that when JACK is replaced by PipeWire, the SPA JACK plugin (installed +in `/usr/lib64/spa-0.2/jack/libspa-jack.so`) is not useful anymore and +distributions should make them conflict. + + +### PulseAudio replacement + +PipeWire reimplements the PulseAudio server protocol as a small service +that runs on top of PipeWire. + +The binary is normally placed here: + +``` +/usr/bin/pipewire-pulse +``` + +The server can be started with provided systemd activation files or +from PipeWire itself. (See `/usr/share/pipewire/pipewire.conf`) + +``` +systemctl --user start pipewire-pulse.service pipewire-pulse.socket +``` + +You can also start additional PulseAudio servers listening on other +sockets with the `-a` option. See `pipewire-pulse -h` for more info. + + +## Uninstalling + +To uninstall, run: + +``` +ninja -C builddir uninstall +``` + +Depending on the configured installation prefix, the above command +may need to be run with elevated privileges (e.g. with `sudo`). + +Note that at the time of writing uninstallation only works with the +same build directory that was used for installation. Meson stores the +list of installed files in the build directory, and this list is +necessary for uninstallation to work. |