mirror of
https://github.com/librespot-org/librespot.git
synced 2024-12-18 17:11:53 +00:00
94d174c33d
* discovery: use opaque error type for DnsSdError This helps to decouple discovery and core by not leaking implementation details of the zeroconf backend into Error conversion impls in core. * discovery: map all MDNS/DNS-SD errors to DiscoveryError::DnsSdError previously, libmdns errors would use a generic conversion from std::io::Error to core::Error * discovery: use an opaque type for the handle to the DNS-SD service * discovery: make features additive i.e. add with-libmdns instead of using not(with-dns-sd). The logic is such that enabling with-dns-sd in addition to the default with-libmdns will still end up using dns-sd, as before. If only with-libmdns is enabled, that will be the default. If none of the features is enabled, attempting to build a `Discovery` will yield an error. * discovery: add --zeroconf-backend CLI flag * discovery: Add minimal Avahi zeroconf backend * bump MSRV to 1.75 required by zbus >= 4 * discovery: ensure that server and dns-sd backend shutdown gracefully Previously, on drop the the shutdown_tx/close_tx, it wasn't guaranteed the corresponding tasks would continue to be polled until they actually completed their shutdown. Since dns_sd::Service is not Send and non-async, and because libmdns is non-async, put them on their own threads. * discovery: use a shared channel for server and zeroconf status messages * discovery: add Avahi reconnection logic This deals gracefully with the case where the Avahi daemon is restarted or not running initially. * discovery: allow running when compiled without zeroconf backend... ...but exit with an error if there's no way to authenticate * better error messages for invalid options with no short flag
121 lines
5.4 KiB
Markdown
121 lines
5.4 KiB
Markdown
# Compiling
|
||
|
||
## Setup
|
||
|
||
In order to compile librespot, you will first need to set up a suitable Rust build environment, with the necessary dependencies installed. You will need to have a C compiler, Rust, and the development libraries for the audio backend(s) you want installed. These instructions will walk you through setting up a simple build environment.
|
||
|
||
### Install Rust
|
||
The easiest, and recommended way to get Rust is to use [rustup](https://rustup.rs). Once that’s installed, Rust's standard tools should be set up and ready to use.
|
||
|
||
#### Additional Rust tools - `rustfmt`
|
||
To ensure a consistent codebase, we utilise [`rustfmt`](https://github.com/rust-lang/rustfmt) and [`clippy`](https://github.com/rust-lang/rust-clippy), which are installed by default with `rustup` these days, else they can be installed manually with:
|
||
```bash
|
||
rustup component add rustfmt
|
||
rustup component add clippy
|
||
```
|
||
Using `cargo fmt` and `cargo clippy` is not optional, as our CI checks against this repo's rules.
|
||
|
||
### General dependencies
|
||
Along with Rust, you will also require a C compiler.
|
||
|
||
On Debian/Ubuntu, install with:
|
||
```shell
|
||
sudo apt-get install build-essential
|
||
|
||
```
|
||
On Fedora systems, install with:
|
||
```shell
|
||
sudo dnf install gcc
|
||
```
|
||
### Audio library dependencies
|
||
Depending on the chosen backend, specific development libraries are required.
|
||
|
||
*_Note this is an non-exhaustive list, open a PR to add to it!_*
|
||
|
||
| Audio backend | Debian/Ubuntu | Fedora | macOS |
|
||
|--------------------|------------------------------|-----------------------------------|-------------|
|
||
|Rodio (default) | `libasound2-dev` | `alsa-lib-devel` | |
|
||
|ALSA | `libasound2-dev, pkg-config` | `alsa-lib-devel` | |
|
||
|GStreamer | `gstreamer1.0-plugins-base libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-good libgstreamer-plugins-good1.0-dev` | `gstreamer1 gstreamer1-devel gstreamer1-plugins-base-devel gstreamer1-plugins-good` | `gstreamer gst-devtools gst-plugins-base gst-plugins-good` |
|
||
|PortAudio | `portaudio19-dev` | `portaudio-devel` | `portaudio` |
|
||
|PulseAudio | `libpulse-dev` | `pulseaudio-libs-devel` | |
|
||
|JACK | `libjack-dev` | `jack-audio-connection-kit-devel` | `jack` |
|
||
|JACK over Rodio | `libjack-dev` | `jack-audio-connection-kit-devel` | `jack` |
|
||
|SDL | `libsdl2-dev` | `SDL2-devel` | `sdl2` |
|
||
|Pipe & subprocess | - | - | - |
|
||
|
||
###### For example, to build an ALSA based backend, you would need to run the following to install the required dependencies:
|
||
|
||
On Debian/Ubuntu:
|
||
```shell
|
||
sudo apt-get install libasound2-dev pkg-config
|
||
|
||
```
|
||
On Fedora systems:
|
||
```shell
|
||
sudo dnf install alsa-lib-devel
|
||
```
|
||
|
||
### Zeroconf library dependencies
|
||
Depending on the chosen backend, specific development libraries are required.
|
||
|
||
*_Note this is an non-exhaustive list, open a PR to add to it!_*
|
||
|
||
| Zeroconf backend | Debian/Ubuntu | Fedora | macOS |
|
||
|--------------------|------------------------------|-----------------------------------|-------------|
|
||
|avahi | | | |
|
||
|dns_sd | `libavahi-compat-libdnssd-dev pkg-config` | `avahi-compat-libdns_sd-devel` | |
|
||
|libmdns (default) | | | |
|
||
|
||
### Getting the Source
|
||
|
||
The recommended method is to first fork the repo, so that you have a copy that you have read/write access to. After that, it’s a simple case of cloning your fork.
|
||
|
||
```bash
|
||
git clone git@github.com:YOUR_USERNAME/librespot.git
|
||
```
|
||
|
||
## Compiling & Running
|
||
|
||
Once your build environment is setup, compiling the code is pretty simple.
|
||
|
||
### Compiling
|
||
|
||
To build a ```debug``` build with the default backend, from the project root run:
|
||
|
||
```bash
|
||
cargo build
|
||
```
|
||
|
||
And for ```release```:
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
You will most likely want to build debug builds when developing, as they compile faster, and more verbose, and as the name suggests, are for the purposes of debugging. When submitting a bug report, it is recommended to use a debug build to capture stack traces.
|
||
|
||
There are also a number of compiler feature flags that you can add, in the event that you want to have certain additional features also compiled. The list of these is available on the [wiki](https://github.com/librespot-org/librespot/wiki/Compiling#addition-features).
|
||
|
||
By default, librespot compiles with the ```rodio-backend``` feature. To compile without default features, you can run with:
|
||
|
||
```bash
|
||
cargo build --no-default-features
|
||
```
|
||
|
||
Similarly, to build with the ALSA backend:
|
||
```bash
|
||
cargo build --no-default-features --features "alsa-backend"
|
||
```
|
||
|
||
### Running
|
||
|
||
Assuming you just compiled a ```debug``` build, you can run librespot with the following command:
|
||
|
||
```bash
|
||
./target/debug/librespot
|
||
```
|
||
|
||
There are various runtime options, documented in the wiki, and visible by running librespot with the ```-h``` argument.
|
||
|
||
Note that debug builds may cause buffer underruns and choppy audio when dithering is enabled (which it is by default). You can disable dithering with ```--dither none```.
|