From 1536597d09e88a6d0892536d729206258a1955dc Mon Sep 17 00:00:00 2001 From: Haowei Hsu Date: Mon, 27 Jul 2026 16:19:25 +0800 Subject: [PATCH] Fix all undefined label warnings in cross-references - Add `ref-signing` label to signatures.rst - Add `ref-fuse` label to fuse.rst - Add `ref-apprun` label to software-overview.rst before AppRun section - Fix `appstream-support` -> `ref-appstream` (label already exists) - Fix `relocatable-apps` / `ref-relocatablility` -> `ref-binaries-no-abs-paths` - Fix `ref-signing-appimages` / `ref-signatures` -> `ref-signing` - Replace `ref-temporary-mountpoint` ref with plain text (not a standalone topic) - Replace `ref-libappimage` refs with GitHub external link (no dedicated page) --- source/introduction/software-overview.rst | 6 ++++-- source/packaging-guide/from-source/native-binaries.rst | 4 ++-- source/packaging-guide/optional/index.rst | 2 +- source/packaging-guide/optional/signatures.rst | 2 ++ source/reference/architecture.rst | 2 +- source/reference/desktop-integration.rst | 2 +- source/user-guide/run-appimages.rst | 2 +- source/user-guide/troubleshooting/fuse.rst | 1 + 8 files changed, 13 insertions(+), 8 deletions(-) diff --git a/source/introduction/software-overview.rst b/source/introduction/software-overview.rst index 2977257..bef6370 100644 --- a/source/introduction/software-overview.rst +++ b/source/introduction/software-overview.rst @@ -40,17 +40,19 @@ appimagetool appimagetool is the easiest way to create AppImages from existing directories on the system, the so-called :ref:`AppDirs `. It creates the AppImage by embedding the :ref:`runtime `, and creating and appending the filesystem image. -appimagetool implements all optional features, like for instance `update information `__, :ref:`signing `, and some linting options to make sure the information in the AppImage is valid (for instance, it can validate :ref:`AppStream files `). +appimagetool implements all optional features, like for instance `update information `__, :ref:`signing `, and some linting options to make sure the information in the AppImage is valid (for instance, it can validate :ref:`AppStream files `). **Download:** You can get it as an AppImage from https://github.com/AppImage/appimagetool/releases/continuous. +.. _ref-apprun: + AppRun ^^^^^^ Every AppImage's AppDir must contain a file called :code:`AppRun`, providing the "entry point". When running the AppImage, the :ref:`runtime ` executes the :code:`AppRun` file within the :ref:`AppDir `. -:code:`AppRun` doesn't necessarily have to be a regular file. If the application is :ref:`relocatable `, it can just be a symlink to the main binary. Tools like :ref:`ref-linuxdeploy` can turn applications into relocatable applications, and therefore create such a symlink. +:code:`AppRun` doesn't necessarily have to be a regular file. If the application is :ref:`relocatable `, it can just be a symlink to the main binary. Tools like :ref:`ref-linuxdeploy` can turn applications into relocatable applications, and therefore create such a symlink. In some cases, though, when an existing application must not be altered (e.g., when the license prohibits any modifications) or tools like linuxdeploy cannot be used, AppImageKit's :code:`AppRun.c` can be used. :code:`AppRun.c` attempts to make programs load bundled shared libraries instead of system ones by manipulating environment variable. Furthermore, it attempts to prevent warnings users might encounter that are coming from the fact the :ref:`AppDir ` is mounted read-only. diff --git a/source/packaging-guide/from-source/native-binaries.rst b/source/packaging-guide/from-source/native-binaries.rst index ccedda1..543b0ef 100644 --- a/source/packaging-guide/from-source/native-binaries.rst +++ b/source/packaging-guide/from-source/native-binaries.rst @@ -170,7 +170,7 @@ Luckily, linuxdeploy supports such a workflow as well. It provides functionaliti Please consult the applications' documentation (e.g., homepage or man pages) to see what kinds of resources must be put into the AppImage. This can involve some trial-and-error, as you need to :ref:`test your AppImages on different systems ` to find possible errors. .. warning:: - In order to be packaged as AppImages, applications must load the resources relative to their main binary, and not from a hardcoded path (usually ``/usr/...``). This is called :ref:`relocatability `. + In order to be packaged as AppImages, applications must load the resources relative to their main binary, and not from a hardcoded path (usually ``/usr/...``). This is called :ref:`relocatability `. If your app doesn't load resources from the AppImage, but e.g., shows errors it couldn't find resources, it is most likely not relocatable. In this case, you must ask the author of the application to make it relocatable. Many modern frameworks such as Qt even provide functionality to implement this easily. In some cases, there's also flags you can specify when building from source to make applications relocatable. @@ -201,7 +201,7 @@ Minimal example: As most plugins, linuxdeploy-plugin-appimage provides some environment variables to enable additional functionality, such as: ``SIGN=1`` - Sign AppImage. See :ref:`ref-signing-appimages` for more information. + Sign AppImage. See :ref:`ref-signing` for more information. ``UPDATE_INFORMATION=zsync|...`` Add update information to the AppImage, and generate a ``.zsync`` file. diff --git a/source/packaging-guide/optional/index.rst b/source/packaging-guide/optional/index.rst index 76d0ba8..cfb4e7f 100644 --- a/source/packaging-guide/optional/index.rst +++ b/source/packaging-guide/optional/index.rst @@ -3,7 +3,7 @@ Optional Resources and Features If you have followed our packaging guide to this point: congratulations! You should have a working AppImage by now. -However, the produced AppImage can be improved further. We provide some additional features such as :ref:`binary delta updating ` and a standardized and verifiable :ref:`signature mechanism `. +However, the produced AppImage can be improved further. We provide some additional features such as :ref:`binary delta updating ` and a standardized and verifiable :ref:`signature mechanism `. Also, you can add optional resources such as :ref:`AppStream metadata ` to allow tools which work with AppImages such as :ref:`AppImageHub ` to display additional information about your AppImage. diff --git a/source/packaging-guide/optional/signatures.rst b/source/packaging-guide/optional/signatures.rst index 28764f4..3a4f4ba 100644 --- a/source/packaging-guide/optional/signatures.rst +++ b/source/packaging-guide/optional/signatures.rst @@ -1,3 +1,5 @@ +.. _ref-signing: + Signing AppImages ================= diff --git a/source/reference/architecture.rst b/source/reference/architecture.rst index 10809c5..158964a 100644 --- a/source/reference/architecture.rst +++ b/source/reference/architecture.rst @@ -21,7 +21,7 @@ An AppImage consists of two parts: a *runtime* and a *file system image*. For th AppImage file structure. Copyright © `@TheAssassin `__ 2019. Licensed under CC-By-SA Intl 4.0. -What happens when an AppImage is run is that the operating system runs the AppImage as an executable. The runtime, the executable part, tries to mount the file system image using :ref:`FUSE `. If that succeeds, the :ref:`AppDir ` is available in a :ref:`temporary mountpoint `, and can be used like a read-only directory. +What happens when an AppImage is run is that the operating system runs the AppImage as an executable. The runtime, the executable part, tries to mount the file system image using :ref:`FUSE `. If that succeeds, the :ref:`AppDir ` is available in a temporary mountpoint, and can be used like a read-only directory. The runtime continues by calling the AppDir's "entrypoint" :ref:`AppRun ` using the operating system facilities. There are no checks performed by the runtime, the operating system is simply tasked with the execution of ``/AppRun``. This provides a lot of flexibility, as AppRun can be an arbitrary executable, a script with a shebang_, or even a simple symlink to another executable within the AppDir. The file must be executable. diff --git a/source/reference/desktop-integration.rst b/source/reference/desktop-integration.rst index 1f5076b..8d25fdb 100644 --- a/source/reference/desktop-integration.rst +++ b/source/reference/desktop-integration.rst @@ -40,7 +40,7 @@ X-AppImage-Arch **Examples:** :code:`x86_64`, :code:`i386` -:ref:`appimagetool ` and :ref:`libappimage ` currently make use mostly of :code:`X-AppImage-Version`. +:ref:`appimagetool ` and `libappimage `__ currently make use mostly of :code:`X-AppImage-Version`. .. seealso:: diff --git a/source/user-guide/run-appimages.rst b/source/user-guide/run-appimages.rst index 3a5a54f..3b9a7b4 100644 --- a/source/user-guide/run-appimages.rst +++ b/source/user-guide/run-appimages.rst @@ -102,7 +102,7 @@ AppImages are standalone bundles, and do not need to be *installed*. However, so appimaged ********* -`appimaged `__ is a daemon that monitors the system and integrates AppImages. It monitors a predefined set of directories on the user's system searching for AppImages, and integrates them into the system using :ref:`libappimage `. +`appimaged `__ is a daemon that monitors the system and integrates AppImages. It monitors a predefined set of directories on the user's system searching for AppImages, and integrates them into the system using `libappimage `__. .. seealso:: More information on appimaged can be found in :ref:`appimaged`. diff --git a/source/user-guide/troubleshooting/fuse.rst b/source/user-guide/troubleshooting/fuse.rst index 0a705f0..534b3e0 100644 --- a/source/user-guide/troubleshooting/fuse.rst +++ b/source/user-guide/troubleshooting/fuse.rst @@ -1,3 +1,4 @@ +.. _ref-fuse: .. _ref-ug-troubleshooting-fuse: I get some errors related to something called "FUSE"