NetDesk 1.5.0 — source release
This commit is contained in:
NetDesk committed
commit
228c492a5c
227 files changed
+80714
No files matched your search
@@ -0,0 +1,189 @@
|
||||
# NetDesk — Linux build & packaging
|
||||
|
||||
Build the native `netdesk-viewer` for Linux and bundle the two distributions
|
||||
**NetDesk by Akronlogic** ships on Linux:
|
||||
|
||||
| Edition | Artifact | Install? |
|
||||
|--------------|-----------------------------------|----------------------------------------|
|
||||
| **AppImage** | `NetDesk-<ver>-x86_64.AppImage` | No — `chmod +x` and run anywhere |
|
||||
| **.deb** | `netdesk_<ver>_amd64.deb` | Yes — `apt install ./…` (launcher + icon) |
|
||||
|
||||
Both are produced by [`packaging/build-linux.sh`](../packaging/build-linux.sh).
|
||||
Everything it writes lands in **`packaging/dist/linux/`** (git-ignored). This is
|
||||
the Linux counterpart of the Windows [`packaging/README.md`](../packaging/README.md).
|
||||
|
||||
> This target must be **built on Linux** (x86_64). The viewer links the system
|
||||
> FFmpeg/VAAPI libraries for the Linux hardware-decode path
|
||||
> (`core/src/decode_vaapi.rs`), which are not present when cross-building from
|
||||
> Windows or macOS.
|
||||
|
||||
---
|
||||
|
||||
## 1. Build dependencies
|
||||
|
||||
The Linux decode backend pulls in FFmpeg through the `ffmpeg-next` crate, whose
|
||||
build script (`ffmpeg-sys-next`) locates `libav*` with **pkg-config** and
|
||||
generates bindings with **libclang**. The GUI (eframe/egui on winit + glow)
|
||||
needs OpenGL at runtime. Install the toolchain + dev libraries first.
|
||||
|
||||
### Debian / Ubuntu
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y build-essential clang pkg-config nasm \
|
||||
libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \
|
||||
libavfilter-dev libavdevice-dev libswresample-dev \
|
||||
libva-dev \
|
||||
libgl1-mesa-dev
|
||||
```
|
||||
|
||||
- `build-essential` → the C/C++ linker (`cc`/`g++`) Rust and `openh264-sys2` need.
|
||||
- `clang` → libclang for `ffmpeg-sys-next`'s bindgen.
|
||||
- `pkg-config` → locates the FFmpeg and VAAPI libraries.
|
||||
- `nasm` → assembler for the bundled `openh264` software-decode fallback.
|
||||
- `libav*-dev` → FFmpeg ≥ 4 development libraries (the full set matches the
|
||||
default features of `ffmpeg-next`).
|
||||
- `libva-dev` → VAAPI headers for the hardware-decode path.
|
||||
- `libgl1-mesa-dev` → OpenGL for the glow renderer.
|
||||
|
||||
### Fedora (FFmpeg dev libs come from RPM Fusion)
|
||||
|
||||
```bash
|
||||
sudo dnf install -y gcc gcc-c++ clang pkgconf-pkg-config nasm \
|
||||
ffmpeg-devel libva-devel mesa-libGL-devel
|
||||
```
|
||||
|
||||
### Optional — native file-picker
|
||||
|
||||
The viewer's **File transfer → Upload…** button uses `rfd`, which is compiled
|
||||
with **no Linux backend** in `viewer/Cargo.toml` (`default-features = false`).
|
||||
The build and the app run fine without it, but the picker is a no-op on Linux
|
||||
until `rfd` is given a backend feature:
|
||||
|
||||
- **GTK 3** backend → add `features = ["gtk3"]` to `rfd`, then install
|
||||
`libgtk-3-dev` (build) / `libgtk-3-0` (runtime).
|
||||
- **XDG portal** backend (no GTK) → add `features = ["xdg-portal", "tokio"]`;
|
||||
needs a running `xdg-desktop-portal` at runtime, nothing extra at build.
|
||||
|
||||
This is the only reason `libgtk` is ever involved on Linux — it is **not**
|
||||
required to build or run NetDesk as shipped.
|
||||
|
||||
---
|
||||
|
||||
## 2. The one command
|
||||
|
||||
```bash
|
||||
export PATH="$HOME/.cargo/bin:$PATH" # ensure cargo/rustup are reachable
|
||||
packaging/build-linux.sh
|
||||
```
|
||||
|
||||
That runs `cargo build --release -p netdesk-viewer`
|
||||
(target `x86_64-unknown-linux-gnu`) and then produces **both** the `.deb` and
|
||||
the AppImage in `packaging/dist/linux/`:
|
||||
|
||||
```
|
||||
packaging/dist/linux/
|
||||
├── netdesk_0.1.0_amd64.deb ← dpkg package (launcher + hicolor icons)
|
||||
├── NetDesk-0.1.0-x86_64.AppImage ← portable single file
|
||||
├── com.akronlogic.netdesk.desktop (generated launcher, shared by both)
|
||||
├── AppDir/ (AppImage staging)
|
||||
└── deb/ (.deb staging tree)
|
||||
```
|
||||
|
||||
> The underlying build command on its own:
|
||||
> ```bash
|
||||
> cargo build --release -p netdesk-viewer --target x86_64-unknown-linux-gnu
|
||||
> ```
|
||||
|
||||
### Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|-----------------------|----------------------------------------------------|
|
||||
| `--skip-build` | reuse an existing `target/.../release/netdesk-viewer` |
|
||||
| `--no-appimage` | build the `.deb` only |
|
||||
| `--no-deb` | build the AppImage only |
|
||||
| `--target <triple>` | override the Rust target (default `x86_64-unknown-linux-gnu`) |
|
||||
| `LINUXDEPLOY=/path` | env: use a local `linuxdeploy` instead of downloading it |
|
||||
|
||||
The AppImage step downloads **linuxdeploy** once (cached in
|
||||
`packaging/dist/.tools/`) and runs it with `APPIMAGE_EXTRACT_AND_RUN=1`, so it
|
||||
works in containers/CI without FUSE. linuxdeploy `ldd`-scans the binary and
|
||||
bundles its shared libraries (`libavcodec`, `libavutil`, `libswscale`, …) into
|
||||
the AppImage; `libGL`, `libX11`/`xcb`, Wayland and `libva` are intentionally
|
||||
**not** bundled — they are `dlopen()`ed and must come from the host graphics
|
||||
stack. The `.deb` instead declares those as package `Depends:`.
|
||||
|
||||
---
|
||||
|
||||
## 3. VAAPI hardware-decode note
|
||||
|
||||
NetDesk hardware-decodes the host's H.264 stream on Linux through
|
||||
**VAAPI via FFmpeg/libavcodec** (`core/src/decode_vaapi.rs`): it opens the
|
||||
libavcodec H.264 decoder with a VAAPI `hw_device_ctx` on the default DRI render
|
||||
node (`/dev/dri/renderD128`), decodes on the GPU, pulls the surface to system
|
||||
memory (NV12), crops to the true display size, and swscales to the packed RGB8
|
||||
`Frame` the viewer paints — see [`cross-platform-decode.md`](cross-platform-decode.md)
|
||||
for the full backend matrix.
|
||||
|
||||
**Hardware decode is optional at runtime.** `best_decoder()` tries VAAPI first
|
||||
and **falls back to the openh264 software decoder** if no usable VAAPI device is
|
||||
present, so headless / GPU-less boxes still work. VAAPI is a build dependency
|
||||
(the libraries must link) but not a runtime requirement.
|
||||
|
||||
To get the hardware path at runtime on the target machine:
|
||||
|
||||
1. **Install a VAAPI driver** (the `.deb` lists these as `Recommends`):
|
||||
- Intel (Broadwell+): `intel-media-va-driver` (iHD)
|
||||
- Intel (older): `i965-va-driver`
|
||||
- AMD / others (Mesa): `mesa-va-drivers` (radeonsi)
|
||||
2. **Verify it:** `vainfo` should list an `H264` decode profile (e.g.
|
||||
`VAProfileH264High : VAEntrypointVLD`). Install `vainfo` from `libva-utils`.
|
||||
3. **Render-node access:** the user must be able to read
|
||||
`/dev/dri/renderD128` — typically by membership of the `render` (or `video`)
|
||||
group.
|
||||
4. **Driver override (if needed):** `export LIBVA_DRIVER_NAME=iHD` (or `i965`,
|
||||
`radeonsi`) when autodetection picks the wrong driver.
|
||||
|
||||
Confirm which path is live from the viewer's log:
|
||||
|
||||
```
|
||||
decode: VAAPI H.264 (FFmpeg hardware) ← hardware path selected
|
||||
VAAPI init failed (...); using openh264 ... ← fell back to software
|
||||
```
|
||||
|
||||
If it fell back, check `vainfo`, the `/dev/dri/renderD128` permissions, and
|
||||
`LIBVA_DRIVER_NAME`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Troubleshooting
|
||||
|
||||
- **`libavcodec` not found via pkg-config / bindgen errors** — the FFmpeg dev
|
||||
libraries or `clang` are missing. Re-run the install command in §1. For FFmpeg
|
||||
in a non-standard prefix, set `PKG_CONFIG_PATH`.
|
||||
- **`openh264` build fails for want of an assembler** — install `nasm`.
|
||||
- **AppImage not produced** (linuxdeploy download/FUSE error) — the script warns
|
||||
and still writes the `.deb`. Supply a local tool with `LINUXDEPLOY=/path`, or
|
||||
run with `--no-appimage`. `APPIMAGE_EXTRACT_AND_RUN=1` is already exported for
|
||||
FUSE-less hosts.
|
||||
- **`.deb` won't install — unmet FFmpeg dependency** — soname package names
|
||||
differ per release; the control file lists `libavcodec60 | 59 | 58 | ffmpeg`
|
||||
(and likewise for `libavutil`/`libswscale`). On an unusual release, installing
|
||||
the distro `ffmpeg` package satisfies the catch-all.
|
||||
- **Wrong window/taskbar icon on GNOME/Wayland** — the launcher file name and
|
||||
its `Icon=` key both use the app-id `com.akronlogic.netdesk`, matching the
|
||||
viewer's `with_app_id(...)`; for the `.deb`, `gtk-update-icon-cache` runs in
|
||||
`postinst`. Log out/in if the shell cached the old icon.
|
||||
|
||||
---
|
||||
|
||||
## 5. Test
|
||||
|
||||
```bash
|
||||
vainfo # confirm a VAAPI driver + H264 profile (optional)
|
||||
cargo test -p netdesk-core # core decode/transport tests
|
||||
./packaging/dist/linux/NetDesk-*.AppImage # smoke-test the viewer
|
||||
```
|
||||
|
||||
Smoke-test end to end against a live host; the log line
|
||||
`decode: VAAPI H.264 (FFmpeg hardware)` confirms the hardware path was selected.
|
||||
Reference in new issue
Block a user