diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 000000000..1256086b3 --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,4 @@ +{ + // MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines + "MD031": true +} diff --git a/COMPILING.md b/COMPILING.md index 6e25b811c..edf960c72 100644 --- a/COMPILING.md +++ b/COMPILING.md @@ -9,24 +9,30 @@ The easiest, and recommended way to get Rust is to use [rustup](https://rustup.r #### 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. @@ -47,11 +53,14 @@ Depending on the chosen backend, specific development libraries are required. ###### 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 ``` @@ -86,11 +95,13 @@ This is the **default choice** and provides the best compatibility. It integrate **Dependencies:** On Debian/Ubuntu: + ```shell sudo apt-get install libssl-dev pkg-config ``` On Fedora: + ```shell sudo dnf install openssl-devel pkg-config ``` @@ -119,6 +130,7 @@ Uses a Rust-based TLS implementation with certificate authority (CA) verificatio **No additional system dependencies required** - rustls is implemented in Rust (with some assembly for performance-critical cryptographic operations) and doesn't require external libraries like OpenSSL. #### Building with specific TLS backends + ```bash # Default (native-tls) cargo build diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ba24393b..ae8eec269 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,7 @@ Make any changes that you are going to make to the code, but do not commit yet. Unless your changes are negligible, please add an entry in the "Unreleased" section of `CHANGELOG.md`. Refer to [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) for instructions on how this entry should look like. If your changes break the API such that downstream packages that depend on librespot need to update their source to still compile, you should mark your changes as `(breaking)`. Make sure that the code is correctly formatted by running: + ```bash cargo fmt --all ``` @@ -45,6 +46,7 @@ cargo build ``` Once it has built, check for common code mistakes by running: + ```bash cargo clippy ``` diff --git a/README.md b/README.md index d80006bdb..25b6532e9 100644 --- a/README.md +++ b/README.md @@ -40,16 +40,19 @@ We recently switched to using [Rodio](https://github.com/tomaka/rodio) for audio For Linux, you will need to run the additional commands below, depending on your distro. On Debian/Ubuntu, the following command will install these dependencies: + ```shell sudo apt-get install build-essential libasound2-dev ``` On Fedora systems, the following command will install these dependencies: + ```shell sudo dnf install alsa-lib-devel make gcc ``` librespot currently offers the following selection of [audio backends](https://github.com/librespot-org/librespot/wiki/Audio-Backends): + ``` Rodio (default) ALSA @@ -62,9 +65,11 @@ SDL Pipe Subprocess ``` + Please check [COMPILING.md](COMPILING.md) for detailed information on TLS, audio, and discovery backend dependencies, or the [Compiling](https://github.com/librespot-org/librespot/wiki/Compiling#general-dependencies) entry on the wiki for additional backend specific dependencies. Once you've installed the dependencies and cloned this repository you can build *librespot* with the default features using Cargo. + ```shell cargo build --release ``` @@ -80,14 +85,17 @@ librespot is also available via official package system on various operating sys ## Usage A sample program implementing a headless Spotify Connect receiver is provided. Once you've built *librespot*, run it using : + ```shell target/release/librespot --name DEVICENAME ``` The above is a minimal example. Here is a more fully fledged one: + ```shell target/release/librespot -n "Librespot" -b 320 -c ./cache --enable-volume-normalisation --initial-volume 75 --device-type avr ``` + The above command will create a receiver named ```Librespot```, with bitrate set to 320 kbps, initial volume at 75%, with volume normalisation enabled, and the device displayed in the app as an Audio/Video Receiver. A folder named ```cache``` will be created/used in the current directory, and be used to cache audio data and credentials. A full list of runtime options is available [here](https://github.com/librespot-org/librespot/wiki/Options).