From 9497022e7a0a56676c33c7d8f948e6b723826355 Mon Sep 17 00:00:00 2001 From: Quantum Date: Wed, 12 Aug 2026 03:13:16 -0400 Subject: [PATCH] [doc] move all legacy host information into a dedicated section It's just distracting to have legacy host application information interleaved with the other stuff when it's deprecated. --- doc/build.rst | 131 ------------------------------------------- doc/build_host.rst | 130 ++++++++++++++++++++++++++++++++++++++++++ doc/host_usage.rst | 4 +- doc/index.rst | 2 + doc/install.rst | 1 - doc/install_host.rst | 1 + doc/legacy_host.rst | 47 ++++++++++++++++ doc/overview.rst | 3 + doc/requirements.rst | 16 ------ 9 files changed, 185 insertions(+), 150 deletions(-) create mode 100644 doc/build_host.rst create mode 100644 doc/legacy_host.rst diff --git a/doc/build.rst b/doc/build.rst index 21ad68eb..ccf12a5c 100644 --- a/doc/build.rst +++ b/doc/build.rst @@ -225,134 +225,3 @@ it directly from the build directory: If you disable this and need support for a crash, use ``gdb`` to obtain a backtrace manually. - -.. _host_building: - -Legacy Host Application build ------------------------------ - -.. warning:: - - The Host Application is a legacy server application. New installations should - use the prebuilt :doc:`Looking Glass IDD `. These build - instructions are retained for the complete matching B7 stack described in - :ref:`legacy_host_policy`. - -.. note:: - - `Host` in this context refers to the `Looking Glass (LG) host server application`, - to which the LG client connects to, it thus does not refer to the `host OS`! - - A common setup is to have a `host OS` running a `guest VM`. In such a setup - the `client application` runs on the `host OS`; and the `host application` - on the `guest VM`. - - The term `Host application` was chosen over `Guest application`, because LG - can be run in a VM to VM configuration, in which case both Host Application and - Client Application are run inside VM Guests. - -These instructions help you build the host yourself from the -:ref:`downloaded source code `. - -.. warning:: - :name: dont-build-the-host - - Building the host from source code is not recommended for most purposes, - and should only be attempted by users who are prepared to handle issues - on their own. Please download the pre-built binary installers from - https://looking-glass.io/downloads for stability, and increased support. - - .. note:: - - The pre-built binaries also include NvFBC support built in, which is - only available to current Nvidia SDK license holders, and cannot - be enabled when building the host without also having a license. - - (`link <#dont-build-the-host>`_) - -.. _host_win_on_win: - -For Windows on Windows -~~~~~~~~~~~~~~~~~~~~~~ - -1. Download and install msys2 x86_64 from - `http://www.msys2.org/ `__ following the setup - instructions provided - -2. Run the MSYS2 shell - -3. Download build dependencies with pacman - -.. code:: bash - - pacman -Fy - pacman -Sy git make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake - -4. Change directory to the source tree with ``cd`` - -5. Configure the project and build it - -.. code:: bash - - mkdir host/build - cd host/build - cmake -G "MSYS Makefiles" .. - make - -.. _host_linux_on_linux: - -For Linux on Linux -~~~~~~~~~~~~~~~~~~ - -Make a ``host/build`` directory, then run ``cmake`` - -.. code:: bash - - mkdir host/build - cd host/build - cmake .. - make - -.. _host_win_cross_on_linux: - -For Windows cross compiling on Linux -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Like :ref:`host_linux_on_linux`, but using the mingw64 toolchain to -cross-compile a Windows ``.exe`` file. - -.. code:: bash - - mkdir host/build - cd host/build - cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake .. - make - -.. _host_build_installer: - -Building the Windows installer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. :ref:`Build ` the host on Linux. - -2. Install ``nsis`` - -.. code:: bash - - apt-get install nsis - -3. Use ``makensis`` to build the installer. - -.. code:: bash - - cd host/build/platform/Windows - makensis installer.nsi - -.. _host_questions: - -This will build ``looking-glass-host-setup.exe`` under -``host/build/platform/Windows/looking-glass-host-setup.exe`` - -.. seealso:: - - :ref:`Installing the Host ` diff --git a/doc/build_host.rst b/doc/build_host.rst new file mode 100644 index 00000000..60a7ed2b --- /dev/null +++ b/doc/build_host.rst @@ -0,0 +1,130 @@ +.. _host_building: + +Legacy Host Application build +############################# + +.. warning:: + + The Host Application is a legacy server application. New installations should + use the prebuilt :doc:`Looking Glass IDD `. These build + instructions are retained for the complete matching B7 stack described in + :ref:`legacy_host_policy`. + +.. note:: + + `Host` in this context refers to the `Looking Glass (LG) host server application`, + to which the LG client connects to, it thus does not refer to the `host OS`! + + A common setup is to have a `host OS` running a `guest VM`. In such a setup + the `client application` runs on the `host OS`; and the `host application` + on the `guest VM`. + + The term `Host application` was chosen over `Guest application`, because LG + can be run in a VM to VM configuration, in which case both Host Application and + Client Application are run inside VM Guests. + +These instructions help you build the host yourself from the +:ref:`downloaded source code `. + +.. warning:: + :name: dont-build-the-host + + Building the host from source code is not recommended for most purposes, + and should only be attempted by users who are prepared to handle issues + on their own. Please download the pre-built binary installers from + https://looking-glass.io/downloads for stability, and increased support. + + .. note:: + + The pre-built binaries also include NvFBC support built in, which is + only available to current Nvidia SDK license holders, and cannot + be enabled when building the host without also having a license. + + (`link <#dont-build-the-host>`_) + +.. _host_win_on_win: + +For Windows on Windows +~~~~~~~~~~~~~~~~~~~~~~ + +1. Download and install msys2 x86_64 from + `http://www.msys2.org/ `__ following the setup + instructions provided + +2. Run the MSYS2 shell + +3. Download build dependencies with pacman + +.. code:: bash + + pacman -Fy + pacman -Sy git make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake + +4. Change directory to the source tree with ``cd`` + +5. Configure the project and build it + +.. code:: bash + + mkdir host/build + cd host/build + cmake -G "MSYS Makefiles" .. + make + +.. _host_linux_on_linux: + +For Linux on Linux +~~~~~~~~~~~~~~~~~~ + +Make a ``host/build`` directory, then run ``cmake`` + +.. code:: bash + + mkdir host/build + cd host/build + cmake .. + make + +.. _host_win_cross_on_linux: + +For Windows cross compiling on Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Like :ref:`host_linux_on_linux`, but using the mingw64 toolchain to +cross-compile a Windows ``.exe`` file. + +.. code:: bash + + mkdir host/build + cd host/build + cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake .. + make + +.. _host_build_installer: + +Building the Windows installer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. :ref:`Build ` the host on Linux. + +2. Install ``nsis`` + +.. code:: bash + + apt-get install nsis + +3. Use ``makensis`` to build the installer. + +.. code:: bash + + cd host/build/platform/Windows + makensis installer.nsi + +.. _host_questions: + +This will build ``looking-glass-host-setup.exe`` under +``host/build/platform/Windows/looking-glass-host-setup.exe`` + +.. seealso:: + + :ref:`Installing the Host ` diff --git a/doc/host_usage.rst b/doc/host_usage.rst index bb83fe89..f6d0ca21 100644 --- a/doc/host_usage.rst +++ b/doc/host_usage.rst @@ -1,7 +1,7 @@ .. _host_usage: -Legacy Host configuration -######################### +Legacy Host Application configuration +##################################### .. warning:: diff --git a/doc/index.rst b/doc/index.rst index 836a61e1..7cacda8c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -21,6 +21,8 @@ input. obs faq + legacy_host + .. toctree:: :hidden: diff --git a/doc/install.rst b/doc/install.rst index 980e50a6..630ba368 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -15,4 +15,3 @@ do not install both Windows servers. install_libvirt install_idd install_client - install_host diff --git a/doc/install_host.rst b/doc/install_host.rst index 22f7fab3..a92b9180 100644 --- a/doc/install_host.rst +++ b/doc/install_host.rst @@ -97,3 +97,4 @@ Legacy configuration :maxdepth: 1 host_usage + build_host diff --git a/doc/legacy_host.rst b/doc/legacy_host.rst new file mode 100644 index 00000000..307e098a --- /dev/null +++ b/doc/legacy_host.rst @@ -0,0 +1,47 @@ +.. _legacy_host: + +Legacy Host Application +####################### + +.. warning:: + + The Host Application is a legacy server application. New installations should + use the prebuilt :doc:`Looking Glass IDD `. These build + instructions are retained for the complete matching B7 stack described in + :ref:`legacy_host_policy`. + +.. note:: + + `Host` in this context refers to the `Looking Glass (LG) host server application`, + to which the LG client connects to, it thus does not refer to the `host OS`! + + A common setup is to have a `host OS` running a `guest VM`. In such a setup + the `client application` runs on the `host OS`; and the `host application` + on the `guest VM`. + + The term `Host application` was chosen over `Guest application`, because LG + can be run in a VM to VM configuration, in which case both Host Application and + Client Application are run inside VM Guests. + +The Windows Host Application is no longer the recommended server implementation. +It is missing many of the features available in the Looking Glass IDD, such as: + +* No additional video capture overhead; +* Usage without a monitor or dummy plug connected; +* Automatically resizing the guest to fit the client application viewport; +* HDR support; or +* Usage in virtual machines without GPU acceleration. + +B7 is the last recommended version of the legacy host application for users who +require its non-capture mouse input workflow. Use the complete matching B7 stack +for that workflow rather than mixing B7 and current components. + +The documentation is included here for completeness. + + +.. toctree:: + :maxdepth: 1 + + Installation + Configuration + Building from source diff --git a/doc/overview.rst b/doc/overview.rst index b8c01a4b..518c15d4 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -78,3 +78,6 @@ If your workflow specifically requires non-capture mouse input with the Host Application, B7 is the last recommended release. Use the matching B7 client, Host Application and B7 documentation together; do not mix B7 components with current releases. + +Download the complete B7 release from https://looking-glass.io/downloads and see +the :ref:`legacy_host` section. diff --git a/doc/requirements.rst b/doc/requirements.rst index 03166162..100cdc7e 100644 --- a/doc/requirements.rst +++ b/doc/requirements.rst @@ -93,19 +93,3 @@ continues to use its SDR-compatible path when those interfaces are unavailable. Native HDR presentation on Linux requires the EGL renderer, Wayland ``color-management-v1`` support in the compositor, and an HDR-capable output. When native HDR is unavailable, the client can map HDR content to SDR. - -Legacy Host compatibility -------------------------- - -The Windows Host Application is no longer the recommended server implementation. -It is missing many of the features available in the Looking Glass IDD, such as: - -* Lack of video capture overhead; -* Usage without a monitor or dummy plug connected; -* Automatically resizing the guest to fit the client application viewport; -* HDR support; or -* Usage in virtual machines without GPU acceleration. - -B7 is the last recommended version of the legacy host application for users who -require its non-capture mouse input workflow. Use the complete matching B7 stack -for that workflow rather than mixing B7 and current components.