From 20ebe18d2cd82793fc2467c0ea78628c481fe56c Mon Sep 17 00:00:00 2001
From: zi3m5f <113244000+zi3m5f@users.noreply.github.com>
Date: Wed, 23 Oct 2024 23:02:33 +0200
Subject: [PATCH] nixos/manual: enhance appimage instructions

Following a bug report (#350383) about `appimage-run` missing a
shared library, add instructions to nixos manual.
---
 .../adding-custom-packages.section.md         | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/nixos/doc/manual/configuration/adding-custom-packages.section.md b/nixos/doc/manual/configuration/adding-custom-packages.section.md
index f9a5221d6c93..f2012d9c2462 100644
--- a/nixos/doc/manual/configuration/adding-custom-packages.section.md
+++ b/nixos/doc/manual/configuration/adding-custom-packages.section.md
@@ -90,16 +90,30 @@ Hello, world!
 
 Most pre-built executables will not work on NixOS. There are two notable
 exceptions: flatpaks and AppImages. For flatpaks see the [dedicated
-section](#module-services-flatpak). AppImages will not run "as-is" on NixOS.
-First you need to install `appimage-run`: add to `/etc/nixos/configuration.nix`
+section](#module-services-flatpak). AppImages can run "as-is" on NixOS.
+
+First you need to enable AppImage support: add to `/etc/nixos/configuration.nix`
 
 ```nix
 {
-  environment.systemPackages = [ pkgs.appimage-run ];
+  programs.appimage.enable = true;
+  programs.appimage.binfmt = true;
 }
 ```
 
-Then instead of running the AppImage "as-is", run `appimage-run foo.appimage`.
+Then you can run the AppImage "as-is" or with `appimage-run foo.appimage`.
+
+If there are shared libraries missing add them with
+
+```nix
+{
+  programs.appimage.package = pkgs.appimage-run.override {
+    extraPkgs = pkgs: [
+      # missing libraries here, e.g.: `pkgs.libepoxy`
+    ];
+  }
+}
+```
 
 To make other pre-built executables work on NixOS, you need to package them
 with Nix and special helpers like `autoPatchelfHook` or `buildFHSEnv`. See