RomanNum3ral
/
Solaar
mirror of https://github.com/pwr-Solaar/Solaar.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: improve installation document

This commit is contained in:
Peter F. Patel-Schneider 2020-05-09 09:09:54 -04:00
parent 574aee0cc7
commit 354c914bd2
1 changed files with 34 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/installation.md
View File

@ -6,17 +6,26 @@ layout: page
# Manual installation
### Requirements
## Downloading
You should have a reasonably new kernel (4.0+), with kernel modules `hid-logitech-dj`
Clone solaar from GitHub via `git clone https://github.com/pwr-Solaar/Solaar.git`
## Requirements for running Solaar
Installing Solaar from a repository should have set up all these requirements
so in this situation you should be able to skip this section.
Solaar needs a reasonably new kernel (5.0+ should work fine), with kernel modules `hid-logitech-dj`
and `hid-logitech-hidpp` loaded. Also, the `udev` package must be installed
and the daemon running. If you have a recent Linux distribution (2017+), you are
and its daemon running. If you have a recent Linux distribution, you are
most likely good to go.
Solaar requires Python 3.2+
and the `python3-pyudev` package.
To run the GUI, solaar also requires Gtk3, and its GObject
Introspection bindings. The Debian/Ubuntu package names are
introspection bindings.
The Debian/Ubuntu packages that need to be installed are
`python3-gi` and `gir1.2-gtk-3.0`;
in Fedora you need `gtk3` and `python3-gobject`;
if you're using another
@ -32,21 +41,6 @@ available, you can also use `gir1.2-appindicator3-0.1` if necessary (e.g.,
for Unity in Ubuntu).
### Downloading
Clone solaar from GitHub via `git clone https://github.com/pwr-Solaar/Solaar.git`
### Running from the Download Directories
To access the USB devices you may need to run solaar as super user.
Go to the solaar directory and `sudo bin/solaar` for the GUI
or `sudo bin/solaar <command> <arguments>` for the CLI.
If you are running a security-enhanced Linux (RedHat or Fedora)
you may have to turn off enforcing mode.
### Installing Solaar's udev Rule
Solaar needs to write to the receiver's HID device.
@ -62,17 +56,28 @@ For this rule to set up the correct permissions for your receiver
you will then need to either physically remove the receiver and
re-insert it or reboot your computer.
Then solaar can be run without using sudo.
## Running from the Download Directories
If Solaar's udev rule is installed,
you can just go to the solaar directory and run `bin/solaar` for the GUI
or `bin/solaar <command> <arguments>` for the CLI.
Otherwise you will need to run Solaar as root via
and `sudo bin/solaar` for the GUI
or `sudo bin/solaar <command> <arguments>` for the CLI.
### Installing Solaar
## Installing Solaar
Python programs are usually installed using [pip][pip].
The pip instructions for solaar are in `setup.py`, the standard place to put such instructions.
To install solaar for yourself only run `pip install --user .` from the solaar directory.
This tells pip to install into your `.local` directory. You can then run solaar as
`~/.local/bin/solaar`.
This tells pip to install into your `.local` directory, but does not install Solaar's udev rule.
(See above for installing the udev rule.)
You can then run solaar as `sudo ~/.local/bin/solaar` (or just `~/.local/bin/solaar`
if the udev rule has been installed).
Installing python programs to system directories using pip is generally frowned on both
because this runs arbitrary code as root and because this can override existing python libraries
@ -85,17 +90,17 @@ Then solaar can be run as /usr/local/bin/solaar.
[pip]: https://en.wikipedia.org/wiki/Pip_(package_manager)
## Running Solaar at Startup
### Running Solaar at Startup
Solaar is run automatically at user login via the desktop file
`/etc/xdg/autostart/solaar.desktop`.
Solaar is run automatically at user login using a desktop file,
which may have been installed at `/etc/xdg/autostart/solaar.desktop`.
If you manually install Solaar you may need to modify this automatic starting of Solaar.
If you install Solaar yourself you may need to create or modify this file.
### Using PyPI
## Using PyPI
As an alternative to downloading and installing you can install a recent release
(but not the current git version) of Solaar from PyPI.
(but not the current github version) of Solaar from PyPI.
Just run `pip install --user solaar` or `sudo pip install solaar`.
The `--user` install will not install the Solaar udev rule or the Solaar autostart file.