From 8c519ddad0edb6b58f2d4f963aa15ce7b4787977 Mon Sep 17 00:00:00 2001 From: eladyn Date: Fri, 7 Mar 2025 21:53:40 +0100 Subject: [PATCH] docs: mention cross and remove rpi64 workaround --- docs/src/SUMMARY.md | 3 +- docs/src/installation/README.md | 10 +-- docs/src/installation/cross-compilation.md | 68 +++++++++++++++++++ .../cross-compile-using-docker.md | 45 ------------ docs/src/installation/raspberrypi64.md | 30 -------- docs/src/installation/source.md | 2 + 6 files changed, 76 insertions(+), 82 deletions(-) create mode 100644 docs/src/installation/cross-compilation.md delete mode 100644 docs/src/installation/cross-compile-using-docker.md delete mode 100644 docs/src/installation/raspberrypi64.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 04313c8b..3fd9238f 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -4,9 +4,8 @@ - [Installation](./installation/README.md) - [Running as a service](./installation/service.md) - - [Installing on RaspberryPi OS 64-bit](./installation/raspberrypi64.md) - [Building from source](./installation/source.md) - - [Cross-Compile using Docker](./installation/cross-compile-using-docker.md) + - [Cross-Compilation](./installation/cross-compilation.md) - [Configuration](./configuration/README.md) - [Authentication](./configuration/auth.md) - [Audio](./configuration/audio.md) diff --git a/docs/src/installation/README.md b/docs/src/installation/README.md index 4d374dce..f83a6eba 100644 --- a/docs/src/installation/README.md +++ b/docs/src/installation/README.md @@ -1,7 +1,7 @@ # Installation Getting `spotifyd` on your system should be as easy as downloading a binary in most cases. -If you'd like to learn how to compile `spotifyd` yourself, head over to [building from source](./source.md). And if you're running a 64-bit RaspbianOS system, have a look [here](./raspbian64.md). +If you'd like to learn how to compile `spotifyd` yourself, head over to [building from source](./source.md). ## Linux @@ -45,10 +45,10 @@ If you're unsure which version to choose, just go for `default` on desktop syste If you're on Linux, check your platform architecture with `uname -m`: -- `x86_64`: Download one of the `spotifyd-linux-{full,default,slim}.tar.gz` packages. -- `armhf`, `armv7`: Download one of the `spotifyd-linux-armhf-{full,default,slim}.tar.gz` packages. -- `armv6`: Download the `spotifyd-linux-armv6-slim.tar.gz` package. -- `aarch64`: Head over to the [RaspberryPi OS 64-bit installation guide](./raspberrypi64.md). +- `x86_64`: Download one of the `spotifyd-linux-x86_64-{full,default,slim}.tar.gz` packages. +- `armhf`, `armv7`: Download one of the `spotifyd-linux-armv7-{full,default,slim}.tar.gz` packages. +- `aarch64`: Download one of the `spotifyd-linux-aarch64-{full,default,slim}.tar.gz` +- `armv6`: Unfortunately, we no longer support this architecture. If you still need this to work, please open an issue or join the [community matrix channel](https://matrix.to/#/#spotifyd:matrix.org) and we'll try to find a solution. If you're on macOS, download one of the `spotifyd-macos-{full,default,slim}.tar.gz` packages. diff --git a/docs/src/installation/cross-compilation.md b/docs/src/installation/cross-compilation.md new file mode 100644 index 00000000..1ea8f975 --- /dev/null +++ b/docs/src/installation/cross-compilation.md @@ -0,0 +1,68 @@ +# Cross-Compilation + +If you want to run `spotifyd` on lower-power hardware such as a RaspberryPi, but none of our prebuilt binaries suit your needs, you might want to cross-compile `spotifyd` on a more powerful machine and deploy the binary on the target system. + +## Using `cross` + +The easiest way to cross-compile is using the amazing [`cross` project](https://github.com/cross-rs/cross). This way, the build environment comes already pre-configured. +Follow the instructions in their README to install `cross`. + +
+ +In the current latest release of cross (v0.2.5), some targets are too outdated and compilation will fail. Thus, it is currently recommended to install the latest version of `cross` from their git repo instead of a prebuilt binary. + +
+ +Then, you should be able to run `cross build --target `, where target is one of the targets in `rustc --print target-list`. Please also refer to [the general from source guide](./source.md) for additional flags that you might want to append to that command. + +If this was successful, copy the resulting binary from `target//{release,debug}/spotifyd` to the `spotifyd` machine and try running it there. + +If `cross` doesn't support your target, you can try the alternative approach using Docker and QEMU below. + +If compilation of your target isn't working even though `cross` supports it, feel free to open an issue on our GitHub or join the [community matrix channel](https://matrix.to/#/#spotifyd:matrix.org) and ask there. + +## Using Docker and QEMU + +We can also use `docker` to cross compile on every platform and OS that runs `docker` and `qemu`: + +1. Setup a docker [custom builder](https://docs.docker.com/build/building/multi-platform/#create-a-custom-builder) + + ```shell + docker buildx create \ + --name container-builder \ + --driver docker-container \ + --use --bootstrap + ``` + + If you are **not** using Docker-Desktop you might have to install [QEMU](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually) + +2. Create a docker `docker-compose.yml` + + Here we are building a `arm64` binary, so we set `platform: linux/arm64` + + ```yaml + services: + build-container: + image: rust:1-bookworm + platform: linux/arm64 + command: bash -c " + apt-get update && + apt-get install -y \ + libasound2-dev \ + libssl-dev \ + jq \ + pkg-config && + wget -O - https://api.github.com/repos/Spotifyd/spotifyd/tarball/$(\ + curl -SsL https://api.github.com/repos/Spotifyd/spotifyd/releases/latest \ + | jq '.tag_name' -r) \ + | tar xzv -C /spotifyd --strip-components=1 && + cargo build --release && + cp /spotifyd/target/release/spotifyd /build/" + working_dir: /spotifyd + volumes: + - ./:/build + ``` + +3. Run `docker compose up` + + This will copy the build `spotifyd` binary in the current directory. diff --git a/docs/src/installation/cross-compile-using-docker.md b/docs/src/installation/cross-compile-using-docker.md deleted file mode 100644 index 53d480f8..00000000 --- a/docs/src/installation/cross-compile-using-docker.md +++ /dev/null @@ -1,45 +0,0 @@ -# Cross Compilation using Docker - -We can also use `docker` to cross compile on every platform and OS that runs `docker` and `qemu`: - -1. Setup a docker [custom builder](https://docs.docker.com/build/building/multi-platform/#create-a-custom-builder) - - ```shell - docker buildx create \ - --name container-builder \ - --driver docker-container \ - --use --bootstrap - ``` - - If you are **not** using Docker-Desktop you might have to install [QEMU](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually) - -2. Create a docker `docker-compose.yml` - - Here we are building a `arm64` binary, so we set `platform: linux/arm64` - - ```yaml - services: - build-container: - image: rust:1-bookworm - platform: linux/arm64 - command: bash -c " - apt-get update && - apt-get install -y \ - libasound2-dev \ - libssl-dev \ - jq \ - pkg-config && - wget -O - https://api.github.com/repos/Spotifyd/spotifyd/tarball/$(\ - curl -SsL https://api.github.com/repos/Spotifyd/spotifyd/releases/latest \ - | jq '.tag_name' -r) \ - | tar xzv -C /spotifyd --strip-components=1 && - cargo build --release && - cp /spotifyd/target/release/spotifyd /build/" - working_dir: /spotifyd - volumes: - - ./:/build - ``` - -3. Run `docker compose up` - - This will copy the build `spotifyd` binary in the current directory. diff --git a/docs/src/installation/raspberrypi64.md b/docs/src/installation/raspberrypi64.md deleted file mode 100644 index e30deca4..00000000 --- a/docs/src/installation/raspberrypi64.md +++ /dev/null @@ -1,30 +0,0 @@ -# Installation on RaspberryPi OS 64-bit - -Unfortunately, we do not yet provide 64-bit binaries for ARM. -Trying to run them will result in `cannot execute: required file not found`. - -To run spotifyd on a 64-bit Raspberry Pi OS, you have two possiblities. Build the 64-bit binary by yourself or add the 32-bit architecture as an additional architecture to your 64-bit Raspberry Pi OS. - -## Option 1: Building yourself - -To build `spotifyd` yourself, head over to [Building from source](./source.md). Note, however, that building can take a long time, especially on low-power devices like a RaspberryPi. - -## Option 2: Add the 32-bit architecture - -### Adding architecture and dependency packages - -These commands add the architecture and install the required packages for the architecure: - -```bash -dpkg --add-architecture armhf -sudo apt update -sudo apt install libasound2-plugins:armhf -``` - -Now you can go on with the [regular install guide](./), by assuming the `armhf` architecture. - -Downloading other variants than thin like full or default may require further armhf packages to be installed with the command like above: - -```console -sudo apt install packagename:armhf -``` diff --git a/docs/src/installation/source.md b/docs/src/installation/source.md index a29ce955..a3bf09a3 100644 --- a/docs/src/installation/source.md +++ b/docs/src/installation/source.md @@ -1,5 +1,7 @@ # Building from source +The guide below assumes that you're building `spotifyd` on the system that you want to run it on. If you'd instead prefer to cross-compile, head over to [this section](./cross-compilation.md). + You can also compile `spotifyd` yourself, allowing you to tailor it perfectly to your needs or get the latest fixes. `spotifyd` is written in Rust. You can download the toolchain (compiler and package manager) over at [rustup.rs](https://rustup.rs). Follow their instructions to get started. > __Note:__ Please make sure that you compile the package using the most recent `stable` version of Rust available through `rustup`. Some distro versions are quite outdated and might result in compilation errors.