mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-11-25 06:47:19 +00:00
[doc] Rerganize content into install and build pages
This commit is contained in:
Jonathan Rubenstein
Geoffrey McRae
parent
6da04655f0
commit
86c7cfe589
236
doc/build.rst
Normal file
236
doc/build.rst
Normal file
@ -0,0 +1,236 @@
|
||||
.. _building:
|
||||
|
||||
Building
|
||||
########
|
||||
|
||||
The following instructions will help you build Looking Glass for yourself
|
||||
from source code. Before you attempt to do this, you should have a basic
|
||||
understanding of how to use the shell.
|
||||
|
||||
.. _download_source:
|
||||
|
||||
Downloading
|
||||
-----------
|
||||
|
||||
Either visit the Looking Glass website's `Download
|
||||
Page <https://looking-glass.io/downloads>`_, or pull the lastest **bleeding-edge
|
||||
version** with ``git``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone --recursive https://github.com/gnif/LookingGlass.git
|
||||
|
||||
.. warning::
|
||||
|
||||
Please only clone from Git if you're a developer, and know what you're
|
||||
doing. Looking Glass requires git submodules that must be setup and updated
|
||||
when building. Source code downloads from the website come bundled with the
|
||||
necessary submodules.
|
||||
|
||||
.. note::
|
||||
|
||||
When using the latest bleeding-edge client version,
|
||||
you *MUST* download and install the corresponding host application.
|
||||
|
||||
.. _build_client_section:
|
||||
|
||||
Client
|
||||
------
|
||||
|
||||
.. _installing_build_dependencies:
|
||||
|
||||
Installing Build Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
These required libraries and tools should be installed first.
|
||||
|
||||
.. _client_dependencies:
|
||||
|
||||
Required Dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
- cmake
|
||||
- gcc \| clang
|
||||
- fonts-freefont-ttf
|
||||
- libegl-dev
|
||||
- libgl-dev
|
||||
- libfontconfig1-dev
|
||||
- libgmp-dev
|
||||
- libsdl2-dev
|
||||
- libsdl2-ttf-dev
|
||||
- libspice-protocol-dev
|
||||
- make
|
||||
- nettle-dev
|
||||
- pkg-config
|
||||
|
||||
.. _may_be_disabled:
|
||||
|
||||
May be disabled
|
||||
<<<<<<<<<<<<<<<
|
||||
|
||||
These dependencies are required by default, but may be omitted if their
|
||||
feature is disabled when running :ref:`cmake <client_building>`.
|
||||
|
||||
- Disable with ``cmake -DENABLE_BACKTRACE=no``
|
||||
|
||||
- binutils-dev
|
||||
|
||||
- Disable with ``cmake -DENABLE_X11=no``
|
||||
|
||||
- libx11-dev
|
||||
- libxfixes-dev
|
||||
- libxi-dev
|
||||
- libxss-dev
|
||||
|
||||
- Disable with ``cmake -DENABLE_WAYLAND=no``
|
||||
|
||||
- libwayland-bin
|
||||
- libwayland-dev
|
||||
- wayland-protocols
|
||||
|
||||
You can fetch these dependencies on Debian systems with the following command:
|
||||
|
||||
``apt-get install binutils-dev cmake fonts-freefont-ttf libfontconfig1-dev
|
||||
libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libx11-dev nettle-dev
|
||||
wayland-protocols``
|
||||
|
||||
|
||||
.. _client_building:
|
||||
|
||||
Building
|
||||
~~~~~~~~
|
||||
|
||||
If you've downloaded the source code as a zip file, simply unzip and cd into the
|
||||
new directory. If you've cloned the repo with ``git``, then ``cd`` into the
|
||||
'LookingGlass' directory.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir client/build
|
||||
cd client/build
|
||||
cmake ../
|
||||
make
|
||||
|
||||
Should this all go well, you will build the **looking-glass-client**.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`Installing the Client <client_install>`
|
||||
|
||||
.. note::
|
||||
|
||||
The most common compile error is related to backtrace support. This can be
|
||||
disabled by adding the following option to the cmake command:
|
||||
**-DENABLE_BACKTRACE=0**, however, if you disable this and need support for a
|
||||
crash please be sure to use gdb to obtain a backtrace manually or there is
|
||||
nothing that can be done to help you.
|
||||
|
||||
.. _host_building:
|
||||
|
||||
Host
|
||||
----
|
||||
|
||||
These instructions help you build the host yourself from the :ref:`downloaded
|
||||
source code <download_source>`.
|
||||
|
||||
.. warning::
|
||||
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.
|
||||
|
||||
.. _host_win_on_win:
|
||||
|
||||
For Windows on Windows
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Download and install msys2 x86_64 from
|
||||
`http://www.msys2.org/ <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. Checkout the project
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone https://github.com/gnif/LookingGlass.git
|
||||
|
||||
5. Configure the project and build it
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir LookingGlass/host/build
|
||||
cd LookingGlass/host/build
|
||||
cmake -G "MSYS Makefiles" ..
|
||||
make
|
||||
|
||||
.. _host_linux_on_linux:
|
||||
|
||||
For Linux on Linux
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make a ``host/build`` direstory, then run ``cmake``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd host
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
|
||||
.. _host_win_cross_on_linux:
|
||||
|
||||
For Windows cross compiling on Linux
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Like :ref:`host_linux_on_linux`, but specifying the mingw64 toolchain in cmake
|
||||
for building.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd host
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake ..
|
||||
make
|
||||
|
||||
.. _host_build_installer:
|
||||
|
||||
Building the Windows installer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. :ref:`Build <host_win_cross_on_linux>` the host for 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 <host_install>`
|
||||
@ -24,6 +24,9 @@ author = 'Geoffrey McRae and the Looking Glass team'
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = 'B4'
|
||||
|
||||
rst_prolog = """
|
||||
.. |license| replace:: GPLv2
|
||||
"""
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
|
||||
103
doc/faq.rst
103
doc/faq.rst
@ -150,8 +150,7 @@ Another popular solution is to use
|
||||
pipes audio through the network. A guide for setting up scream is available on
|
||||
the wiki: https://looking-glass.io/wiki/Using_Scream_over_LAN
|
||||
|
||||
|
||||
|
||||
.. _faq_win:
|
||||
|
||||
Windows
|
||||
-------
|
||||
@ -171,3 +170,103 @@ The screen stops updating when left idle for a time
|
||||
|
||||
Windows is likely turning off the display to save power, you can prevent
|
||||
this by adjusting the \`Power Options\` in the control panel.
|
||||
|
||||
.. _faq_host:
|
||||
|
||||
Host
|
||||
----
|
||||
|
||||
Where is the log?
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The log file for the host application is located at::
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host.txt
|
||||
|
||||
You can also find out where the file is by right clicking on the tray
|
||||
icon and selecting "Log File Location".
|
||||
|
||||
The log file for the looking glass service is located at::
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt
|
||||
|
||||
This is useful for troubleshooting errors related to the host
|
||||
application not starting.
|
||||
|
||||
High priority capture using DXGI and Secure Desktop (UAC) capture support
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default Windows gives priority to the foreground application for any
|
||||
GPU work which causes issues with capture if the foreground application
|
||||
is consuming 100% of the available GPU resources. The looking glass host
|
||||
application is able to increase the kernel GPU thread to realtime
|
||||
priority which fixes this, but in order to do so it must run as the
|
||||
``SYSTEM`` user account. To do this, Looking Glass needs to run as a
|
||||
service. This can be accomplished by either using the NSIS installer
|
||||
which will do this for you, or you can use the following command to
|
||||
Install the service manually:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe InstallService
|
||||
|
||||
To remove the service use the following command:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe UninstallService
|
||||
|
||||
This will also enable the host application to capture the secure desktop
|
||||
which includes things like the lock screen and UAC prompts.
|
||||
|
||||
.. _faq_host_admin_privs:
|
||||
|
||||
Why does the host require Administrator privileges?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is intentional for several reasons.
|
||||
|
||||
1. NvFBC requires a system wide hook to correctly obtain the cursor
|
||||
position as NVIDIA decided to not provide this as part of the cursor
|
||||
updates.
|
||||
2. NvFBC requires administrator level access to enable the interface in
|
||||
the first place. (WIP)
|
||||
3. DXGI performance can be improved if we have this. (WIP)
|
||||
|
||||
NvFBC (NVIDIA Frame Buffer Capture)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Why can't I compile NvFBC support into the host?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You must download and install the NVidia Capture SDK. Please note that
|
||||
by doing so you will be agreeing to NVIDIA's SDK License agreement.
|
||||
|
||||
*-Geoff*
|
||||
|
||||
.. _a_note_about_ivshmem_and_scream_audio:
|
||||
|
||||
Why doesn't Looking Glass work with Scream over IVSHMEM?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. warning::
|
||||
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
|
||||
to use the same device.
|
||||
|
||||
Please do not use the IVSHMEM plugin for Scream.
|
||||
To fix this issue, use the default network transfer method.
|
||||
The IVSHMEM method induces additional latency that is built into its
|
||||
implementation. When using VirtIO for a network device the VM is already using
|
||||
a highly optimized memory copy anyway so there is no need to make another one.
|
||||
|
||||
If you insist on using IVSHMEM for Scream—despite its inferiority to the
|
||||
default network implementation—the Windows Host Application can be told
|
||||
what device to use. Create a ``looking-glass-host.ini`` file in the same
|
||||
directory as the looking-glass-host.exe file. In it, you can use the
|
||||
``os:shmDevice`` option like so:
|
||||
|
||||
.. code:: INI
|
||||
|
||||
[os]
|
||||
shmDevice=1
|
||||
|
||||
|
||||
160
doc/host.rst
160
doc/host.rst
@ -1,160 +0,0 @@
|
||||
Looking Glass Host
|
||||
##################
|
||||
|
||||
.. _host_building:
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
For Windows on Windows
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. Download and install msys2 x86_64 from
|
||||
`http://www.msys2.org/ <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. Checkout the project
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone https://github.com/gnif/LookingGlass.git
|
||||
|
||||
5. Configure the project and build it
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir LookingGlass/host/build
|
||||
cd LookingGlass/host/build
|
||||
cmake -G "MSYS Makefiles" ..
|
||||
make
|
||||
|
||||
.. _host_linux_on_linux:
|
||||
|
||||
For Linux on Linux
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Make a ``host/build`` direstory, then run ``cmake``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd host
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
|
||||
.. _host_win_cross_on_linux:
|
||||
|
||||
For Windows cross compiling on Linux
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Like :ref:`host_linux_on_linux`, but specifying the mingw64 toolchain in cmake
|
||||
for building.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd host
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw64.cmake ..
|
||||
make
|
||||
|
||||
Building the Windows installer
|
||||
------------------------------
|
||||
|
||||
1. :ref:`Build <host_win_cross_on_linux>` the host for 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``
|
||||
|
||||
Questions and Answers
|
||||
---------------------
|
||||
|
||||
Where is the log?
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The log file for the host application is located at::
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host.txt
|
||||
|
||||
You can also find out where the file is by right clicking on the tray
|
||||
icon and selecting "Log File Location".
|
||||
|
||||
The log file for the looking glass service is located at::
|
||||
|
||||
%ProgramData%\Looking Glass (host)\looking-glass-host-service.txt
|
||||
|
||||
This is useful for troubleshooting errors related to the host
|
||||
application not starting.
|
||||
|
||||
High priority capture using DXGI and Secure Desktop (UAC) capture support
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default Windows gives priority to the foreground application for any
|
||||
GPU work which causes issues with capture if the foreground application
|
||||
is consuming 100% of the available GPU resources. The looking glass host
|
||||
application is able to increase the kernel GPU thread to realtime
|
||||
priority which fixes this, but in order to do so it must run as the
|
||||
``SYSTEM`` user account. To do this, Looking Glass needs to run as a
|
||||
service. This can be accomplished by either using the NSIS installer
|
||||
which will do this for you, or you can use the following command to
|
||||
Install the service manually:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe InstallService
|
||||
|
||||
To remove the service use the following command:
|
||||
|
||||
::
|
||||
|
||||
looking-glass-host.exe UninstallService
|
||||
|
||||
This will also enable the host application to capture the secure desktop
|
||||
which includes things like the lock screen and UAC prompts.
|
||||
|
||||
Why does this version require Administrator privileges?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is intentional for several reasons.
|
||||
|
||||
1. NvFBC requires a system wide hook to correctly obtain the cursor
|
||||
position as NVIDIA decided to not provide this as part of the cursor
|
||||
updates.
|
||||
2. NvFBC requires administrator level access to enable the interface in
|
||||
the first place. (WIP)
|
||||
3. DXGI performance can be improved if we have this. (WIP)
|
||||
|
||||
NvFBC (NVIDIA Frame Buffer Capture)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Why can't I compile NvFBC support into the host?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You must download and install the NVidia Capture SDK. Please note that
|
||||
by doing so you will be agreeing to NVIDIA's SDK License agreement.
|
||||
|
||||
*-Geoff*
|
||||
|
||||
@ -11,6 +11,7 @@ systems for legacy programs that require high-performance graphics.
|
||||
:maxdepth: 2
|
||||
|
||||
install
|
||||
build
|
||||
troubleshooting
|
||||
obs
|
||||
module
|
||||
|
||||
309
doc/install.rst
309
doc/install.rst
@ -1,130 +1,23 @@
|
||||
.. _installing:
|
||||
|
||||
Installation
|
||||
############
|
||||
|
||||
.. _looking_glass_client:
|
||||
.. _client_install:
|
||||
|
||||
Looking Glass Client
|
||||
--------------------
|
||||
Client
|
||||
------
|
||||
|
||||
This guide will step you through building the looking glass client from
|
||||
source, before you attempt to do this you should have a basic
|
||||
understanding of how to use the shell.
|
||||
The Looking Glass Client recieves frames from the :ref:`host_install` to
|
||||
display on your screen. It also handles input, and can optionally share the
|
||||
system clipboard with your guest OS through Spice.
|
||||
|
||||
.. _building_the_application:
|
||||
First you must build the client from source code, see :ref:`building`.
|
||||
|
||||
Building the Application
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
After this, you may move the client into a directory in your path, some may
|
||||
allow ``~/.local/bin``, or run it directly from the build directory.
|
||||
|
||||
.. _installing_build_dependencies:
|
||||
|
||||
Installing Build Dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These required libraries and tools should be installed first.
|
||||
|
||||
.. _required_dependencies:
|
||||
|
||||
Required Dependencies
|
||||
'''''''''''''''''''''
|
||||
|
||||
- cmake
|
||||
- gcc \| clang
|
||||
- fonts-freefont-ttf
|
||||
- libegl-dev
|
||||
- libgl-dev
|
||||
- libfontconfig1-dev
|
||||
- libgmp-dev
|
||||
- libsdl2-dev
|
||||
- libsdl2-ttf-dev
|
||||
- libspice-protocol-dev
|
||||
- make
|
||||
- nettle-dev
|
||||
- pkg-config
|
||||
|
||||
.. _may_be_disabled:
|
||||
|
||||
May be disabled
|
||||
<<<<<<<<<<<<<<<
|
||||
|
||||
These dependencies are required by default, but may be omitted if their
|
||||
feature is disabled when running :ref:`cmake <client_building>`.
|
||||
|
||||
- Disable with ``cmake -DENABLE_BACKTRACE=no``
|
||||
|
||||
- binutils-dev
|
||||
|
||||
- Disable with ``cmake -DENABLE_X11=no``
|
||||
|
||||
- libx11-dev
|
||||
- libxfixes-dev
|
||||
- libxi-dev
|
||||
- libxss-dev
|
||||
|
||||
- Disable with ``cmake -DENABLE_WAYLAND=no``
|
||||
|
||||
- libwayland-bin
|
||||
- libwayland-dev
|
||||
- wayland-protocols
|
||||
|
||||
You can fetch these dependencies on Debian systems with the following command:
|
||||
|
||||
``apt-get install binutils-dev cmake fonts-freefont-ttf libfontconfig1-dev
|
||||
libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libx11-dev nettle-dev
|
||||
wayland-protocols``
|
||||
|
||||
Downloading
|
||||
^^^^^^^^^^^
|
||||
|
||||
Either visit the Looking Glass website's `Download
|
||||
Page <https://looking-glass.io/downloads>`_, or pull the lastest **bleeding-edge
|
||||
version** with ``git``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
git clone --recursive https://github.com/gnif/LookingGlass.git
|
||||
|
||||
.. warning::
|
||||
|
||||
Please only clone from Git if you're a developer, and know what you're
|
||||
doing. Looking Glass requires git submodules that must be setup and updated
|
||||
when building. Source code downloads from the website come bundled with the
|
||||
necessary submodules.
|
||||
|
||||
.. note::
|
||||
|
||||
When using the latest bleeding-edge client version,
|
||||
you *MUST* download and install the corresponding host application.
|
||||
|
||||
.. _client_building:
|
||||
|
||||
Building
|
||||
^^^^^^^^
|
||||
|
||||
If you've downloaded the source code as a zip file, simply unzip and cd into the
|
||||
new directory. If you've cloned the repo with ``git``, then ``cd`` into the
|
||||
'LookingGlass' directory.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir client/build
|
||||
cd client/build
|
||||
cmake ../
|
||||
make
|
||||
|
||||
.. note::
|
||||
|
||||
The most common compile error is related to backtrace support. This can be
|
||||
disabled by adding the following option to the cmake command:
|
||||
**-DENABLE_BACKTRACE=0**, however, if you disable this and need support for a
|
||||
crash please be sure to use gdb to obtain a backtrace manually or there is
|
||||
nothing that can be done to help you.
|
||||
|
||||
Should this all go well, you will build the **looking-glass-client**.
|
||||
Before you run the client, you will first need
|
||||
to configure either libvirt, or QEMU (whichever you prefer) then set
|
||||
up the **looking-glass-host** service in your VM.
|
||||
|
||||
.. _libvirt_configuration:
|
||||
.. _client_libvirt_configuration:
|
||||
|
||||
libvirt Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -149,9 +42,9 @@ your virtual machine.
|
||||
</shmem>
|
||||
|
||||
The memory size (show as 32 in the example above) may need to be
|
||||
adjusted as per the :ref:`Determining Memory <determining_memory>` section.
|
||||
adjusted as per the :ref:`Determining Memory <client_determining_memory>` section.
|
||||
|
||||
.. _spice_server:
|
||||
.. _client_spice_server:
|
||||
|
||||
Spice Server
|
||||
^^^^^^^^^^^^
|
||||
@ -179,6 +72,8 @@ along with clipboard sync support, make sure you have a
|
||||
If you want clipboard synchronization please see
|
||||
:ref:`how_to_enable_clipboard_synchronization_via_spice`
|
||||
|
||||
.. _client_apparmor:
|
||||
|
||||
AppArmor
|
||||
^^^^^^^^
|
||||
|
||||
@ -189,7 +84,7 @@ can be done by adding the following to
|
||||
|
||||
``/dev/shm/looking-glass rw,``
|
||||
|
||||
.. _qemu_commands:
|
||||
.. _client_qemu_commands:
|
||||
|
||||
Qemu Commands
|
||||
~~~~~~~~~~~~~
|
||||
@ -205,9 +100,9 @@ the ``bus`` parameter to suit your particular configuration:
|
||||
-object memory-backend-file,id=ivshmem,share=on,mem-path=/dev/shm/looking-glass,size=32M
|
||||
|
||||
The memory size (shown as 32M in the example above) may need to be
|
||||
adjusted as per :ref:`Determining Memory <determining_memory>` section.
|
||||
adjusted as per :ref:`Determining Memory <client_determining_memory>` section.
|
||||
|
||||
.. _determining_memory:
|
||||
.. _client_determining_memory:
|
||||
|
||||
Determining Memory
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
@ -228,7 +123,7 @@ For example, for a resolution of 1920x1080 (1080p):
|
||||
You must round this value up to the nearest power of two, which for the
|
||||
provided example is 32MB.
|
||||
|
||||
.. _shared_memory_file_permissions:
|
||||
.. _client_shmfile_permissions:
|
||||
|
||||
Shared Memory File Permissions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -251,94 +146,6 @@ with the following::
|
||||
Change ``UID`` to the user name you will run Looking Glass with, usually your
|
||||
own.
|
||||
|
||||
.. _looking_glass_service_windows:
|
||||
|
||||
Looking Glass Service (Windows)
|
||||
-------------------------------
|
||||
|
||||
You must first run the Windows VM with the changes noted above in either
|
||||
the :ref:`libvirt_configuration` or :ref:`qemu_commands` sections.
|
||||
|
||||
.. _installing_the_ivshmem_driver:
|
||||
|
||||
Installing the IVSHMEM Driver
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Windows will not prompt for a driver for the IVSHMEM device, instead, it
|
||||
will use a default null (do nothing) driver for the device. To install
|
||||
the IVSHMEM driver you will need to go into the device manager and
|
||||
update the driver for the device "PCI standard RAM Controller" under the
|
||||
"System Devices" node.
|
||||
|
||||
A signed Windows 10 driver can be obtained from Red Hat for this device
|
||||
from the below address:
|
||||
|
||||
https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/
|
||||
|
||||
Please note that you must obtain version 0.1.161 or later.
|
||||
|
||||
If you encounter warnings or errors about driver signatures, ensure secure boot
|
||||
is turned off in the bios/uefi settings of your virtual machine.
|
||||
|
||||
.. _a_note_about_ivshmem_and_scream_audio:
|
||||
|
||||
A note about IVSHMEM and Scream Audio
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. warning::
|
||||
Using IVSHMEM with Scream may interfere with Looking Glass, as they may try
|
||||
to use the same device.
|
||||
|
||||
Please do not use the IVSHMEM plugin for Scream.
|
||||
Use the default network transfer method. The IVSHMEM method induces
|
||||
additional latency that is built into its implementation. When using
|
||||
VirtIO for a network device the VM is already using a highly optimized
|
||||
memory copy anyway so there is no need to make another one.
|
||||
|
||||
If you insist on using IVSHMEM for Scream—despite its inferiority to the
|
||||
default network implementation—the Windows Host Application can be told
|
||||
what device to use. Create a ``looking-glass-host.ini`` file in the same
|
||||
directory as the looking-glass-host.exe file. In it, you can use the
|
||||
``os:shmDevice`` option like so:
|
||||
|
||||
.. code:: INI
|
||||
|
||||
[os]
|
||||
shmDevice=1
|
||||
|
||||
.. _using_the_windows_host_application:
|
||||
|
||||
Using the Windows Host Application
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Start by downloading the correct version for your release from
|
||||
https://looking-glass.io/downloads. You can either choose between
|
||||
**Official Releases**, which are stable; or **Release Candidates**, new versions
|
||||
about to be stable, but haven't passed validation.
|
||||
|
||||
.. note::
|
||||
If your **looking-glass-client** was created by building from the **master
|
||||
branch** you have to pick the **Bleeding Edge** version.
|
||||
|
||||
Next, extract the zip archive using the commit hash for the password.
|
||||
Then, run the ``looking-glass-host-setup.exe`` installer and install the host.
|
||||
By default, the installer will install a service that
|
||||
automatically starts the host application at boot. The installer can
|
||||
also be installed in silent mode with the ``/S`` switch. You can find other
|
||||
command line options with the ``/h`` switch.
|
||||
|
||||
The windows host application captures the windows desktop and stuffs the
|
||||
frames into the shared memory via the shared memory virtual device,
|
||||
without this Looking Glass will not function. It is critical that the
|
||||
version of the host application matches the version of the client
|
||||
application, as differing versions can be, and usually are,
|
||||
incompatible.
|
||||
|
||||
.. note::
|
||||
As of 2020-10-23, Microsoft Defender is known to mark the
|
||||
Looking-Glass host executable as a virus and in some cases will
|
||||
automatically delete the file.
|
||||
|
||||
.. _client_usage:
|
||||
|
||||
Usage
|
||||
@ -607,3 +414,79 @@ The following is a complete list of options accepted by this application
|
||||
+=====================+=======+=======+=======================+
|
||||
| wayland:warpSupport | | yes | Enable cursor warping |
|
||||
+---------------------+-------+-------+-----------------------+
|
||||
|
||||
.. _host_install:
|
||||
|
||||
Host
|
||||
----
|
||||
|
||||
The Looking Glass Host captures frames from the guest OS using a capture API,
|
||||
and sends these frames to the :ref:`client_install`, be it on the host OS
|
||||
(hypervisor) or another Virtual Machine, through a low-latency transfer
|
||||
protocol over shared memory.
|
||||
|
||||
You can get the host program in two ways:
|
||||
|
||||
- Download a pre-built binary from https://looking-glass.io/downloads
|
||||
(**recommended**)
|
||||
|
||||
- Download the source code as described in :ref:`building`, then
|
||||
:ref:`build the host <host_building>`.
|
||||
|
||||
.. _host_install_windows:
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
To begin, you must first run the Windows VM with the changes noted above in
|
||||
either the :ref:`client_libvirt_configuration` or :ref:`client_qemu_commands`
|
||||
sections.
|
||||
|
||||
.. _installing_the_ivshmem_driver:
|
||||
|
||||
Installing the IVSHMEM Driver
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Windows will not prompt for a driver for the IVSHMEM device, instead, it
|
||||
will use a default null (do nothing) driver for the device. To install
|
||||
the IVSHMEM driver you will need to go into the device manager and
|
||||
update the driver for the device "PCI standard RAM Controller" under the
|
||||
"System Devices" node.
|
||||
|
||||
A signed Windows 10 driver can be obtained from Red Hat for this device
|
||||
from the below address:
|
||||
|
||||
https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/
|
||||
|
||||
Please note that you must obtain version 0.1.161 or later.
|
||||
|
||||
If you encounter warnings or errors about driver signatures, ensure secure boot
|
||||
is turned off in the bios/uefi settings of your virtual machine.
|
||||
|
||||
.. _host_install_service:
|
||||
|
||||
Installing the Looking Glass Service
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After installing your IVSHMEM driver, we can now install the Looking Glass Host
|
||||
onto our Windows Virtual Machine.
|
||||
|
||||
1. First, run ``looking-glass-host-setup.exe`` as an administrator
|
||||
(:ref:`Why? <faq_host_admin_privs>`)
|
||||
2. You will be greeted by an intro screen. Press ``Next`` to continue.
|
||||
3. You are presented with the |license| license. Please read and agree to the
|
||||
license by pressing ``Agree``.
|
||||
4. You can change the install path if you wish, otherwise press ``Next`` to
|
||||
continue.
|
||||
5. You may enable or disable options on this screen to configure the
|
||||
installation. The default values are recommended for most users.
|
||||
Press ``Install`` to begin installation.
|
||||
6. After a few moments, installation will complete, and you will have a
|
||||
running instance of Looking Glass. If you experience failures, you can
|
||||
see them in the install log appearing in the middle of the window.
|
||||
7. Press ``Close`` to exit the installer.
|
||||
|
||||
Command line users can run ``looking-glass-host-setup.exe /S`` to execute a
|
||||
silent install with default options selected. Further configuration from the
|
||||
command line can be done with flags. You can list all available flags by
|
||||
running ``looking-glass-host-setup.exe /?``.
|
||||
|
||||
@ -14,7 +14,7 @@ Build Instructions
|
||||
|
||||
The OBS plugin is included in the main source tree of Looking Glass. The
|
||||
building process is very similar to the
|
||||
:ref:`client's <looking_glass_client>`.
|
||||
:ref:`client's <build_client_section>`.
|
||||
|
||||
Dependencies
|
||||
^^^^^^^^^^^^
|
||||
|
||||
@ -64,18 +64,3 @@ Initially, we were using interrupts in early designs however it became
|
||||
clear that the performance, especially for high update rate mice was
|
||||
extremely poor. This may have improved in recent QEMU versions and
|
||||
perhaps should be re-evaluated at some point.
|
||||
|
||||
.. _how_do_i_build_the_host:
|
||||
|
||||
How do I build the looking-glass-host?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It is not recommended to build the looking-glass-host program, and instead
|
||||
download it from the `website <https://looking-glass.io/downloads/>`_. However,
|
||||
if you know what you're doing, you can follow the
|
||||
:doc:`build instructions <host>`.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
host
|
||||
|
||||
Loading…
Reference in New Issue
Block a user