Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@rodlie
rodlie committed Feb 4, 2024
1 parent aaa7bf6 commit 69e15aa
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 64 deletions.
45 changes: 21 additions & 24 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,17 @@ powerkit *`[--config]`*

# DESCRIPTION

**NOTE:** powerkit version 2 is under heavy development, it may break at any time!

powerkit is an desktop independent Linux power manager for alternative X11 desktop environments and window managers.

* Implements *[org.freedesktop.ScreenSaver](https://people.freedesktop.org/~hadess/idle-inhibition-spec/re01.html)* service
* Implements *[org.freedesktop.PowerManagement](https://www.freedesktop.org/wiki/Specifications/power-management-spec/)* service
* Implements *``org.freedesktop.ScreenSaver``* service and screen saver
* Implements *``org.freedesktop.PowerManagement.Inhibit``* service
* Automatically suspend on idle
* Automatically lock screen on idle
* Automatically hibernate or shutdown on critical battery
* Inhibit actions if external monitor(s) is connected
* Automatically suspend or shutdown on critical battery
* Inhibit lid action if external monitor connected
* Screen locking support
* Screen backlight support
* RTC wake alarm support
* CPU frequency scaling support
* Thermal support
* Notification support
* RTC wake support
* Notification support (can use *``org.freedesktop.Notifications``* if available)

# USAGE

Expand All @@ -32,7 +27,7 @@ powerkit should be started during the X11 user session. Consult the documentatio
* In *Fluxbox* add *``powerkit &``* to the *``~/.fluxbox/startup``* file
* In *Openbox* add *``powerkit &``* to the *``~/.config/openbox/autostart``* file.

**Do not run powerkit if your desktop environment already has a power manager!**
**Do use powerkit if your desktop environment or window manager already has a power manager or screen saver service running.**

## CONFIGURATION

Expand All @@ -44,21 +39,23 @@ powerkit implements a basic screen saver to handle screen blanking, poweroff and

Locking feature depends on ``xsecurelock``.

You can override the lock command with *``screensaver_lock_cmd=<command>``* in *`~/.config/powerkit/powerkit.conf`*. Note that the command must not contain spaces.

## BACKLIGHT

The current display brightness (on laptops and supported displays) can be adjusted with the mouse wheel on the system tray icon or through the system tray menu.

## HIBERNATE

If hibernate *"just works"* depends on your system, worst case a swap partition (or file) is needed by the kernel to support hibernate, just add *``resume=<swap_partition>``* to the kernel command line in the boot loader.
If hibernate works depends on your system, a swap partition (or file) is needed by the kernel to support hibernate.

***Consult your system documentation regarding hibernation***.

## ICONS

powerkit will use the existing icon theme from the running desktop environment. You should have (a proper version) of Adwaita installed as a fallback.
powerkit will use the existing icon theme from the running desktop environment or window manager.

You can override the icon theme in the *`~/.config/powerkit/powerkit.conf`* file, see *``icon_theme=<theme_name>``*.
You can override the icon theme in the *`~/.config/powerkit/powerkit.conf`* file, use *``icon_theme=<theme_name>``*.

# FAQ

Expand All @@ -74,7 +71,7 @@ The preferred way to inhibit suspend actions from an application is to use the *

Common use cases are audio playback, downloading, rendering and similar.

## Google Chrome/Chromium does not inhibit the screen saver!?
## Google Chrome/Chromium does not inhibit the screen saver or power manager!?

*[Chrome](https://chrome.google.com)* does not use *org.freedesktop.ScreenSaver* or *org.freedesktop.PowerManagement* until it detects a supported desktop environment. Add the following to *``~/.bashrc``* or the *``google-chrome``* launcher if you don't run a supported desktop environment:

Expand All @@ -90,10 +87,9 @@ powerkit requires the following dependencies:
* *[X11](https://www.x.org)*
* *[libXss](https://www.x.org/archive//X11R7.7/doc/man/man3/Xss.3.xhtml)*
* *[libXrandr](https://www.x.org/wiki/libraries/libxrandr/)*
* *[Qt5](https://qt.io)* *(Core/DBus/Gui/Widgets)*
* *[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/)*
* *[logind](https://www.freedesktop.org/wiki/Software/systemd/logind/)*
* *[UPower](https://upower.freedesktop.org/)*
* *[Qt](https://qt.io)* 5.15 *(Core/DBus/Gui/Widgets)*
* *[logind](https://www.freedesktop.org/wiki/Software/systemd/logind/)* *(or compatible service)*
* *[UPower](https://upower.freedesktop.org/)* *(or compatible service)*
* *[xsecurelock](https://github.com/google/xsecurelock)*

# BUILD
Expand All @@ -103,11 +99,12 @@ First make sure you have the required dependencies installed, then review the mo
* *``CMAKE_INSTALL_PREFIX=</usr/local>``* - Install target. *``/usr``* recommended.
* *``CMAKE_BUILD_TYPE=<Release/Debug>``* - Build type. *``Release``* recommended
* *``SERVICE_USER=<root>``* - powerkitd owner, needs write access to /sys. Usually the *``root``* user.
* *``SERVICE_GROUP=<power>``* - Group that can access the powerkitd service, this should be any desktop user that can change screen brightness, CPU performance and RTC wake alarm. Usually the *``power``* group or similar. Consult your system documentation.
* *``SERVICE_GROUP=<power>``* - Group that can access the powerkitd service, this should be any desktop user. Consult your system documentation for the preferred user group.

Now configure powerkit with CMake and build (*example for packaging purposes*).

```
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
cmake -DCMAKE_INSTALL_PREFIX=/usr -DSERVICE_GROUP=plugdev -DCMAKE_BUILD_TYPE=Release ..
make
make DESTDIR=<package> install
```
Expand Down Expand Up @@ -154,9 +151,9 @@ pkg
* Added screen saver in powerkit
* Easier to use (minimal setup)
* New UI
* RTC wake alarm support
* RTC wake alarm support (not used for anything yet)
* Hibernate computer while suspended for X amount of time
* CPU frequency scaling and thermal support
* CPU frequency scaling and thermal support (not used for anything yet)
* Intel PState
* powerkitd
* Service for unprivileged users (needed for CPU/RTC/brightness)
Expand Down
70 changes: 30 additions & 40 deletions share/powerkit.1
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,34 @@
.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "POWERKIT" "1" "January 2024" "Version 2.0.0" "PowerKit Documentation"
.TH "POWERKIT" "1" "February 2024" "Version 2.0.0" "PowerKit Documentation"
.SH NAME
\f[I]powerkit\f[R] - desktop independent Linux power manager
.SH SYNOPSIS
powerkit \f[I]\f[CI][--config]\f[I]\f[R]
.SH DESCRIPTION
\f[B]NOTE:\f[R] powerkit version 2 is under heavy development, it may
break at any time!
.PP
powerkit is an desktop independent Linux power manager for alternative
X11 desktop environments and window managers.
.IP \[bu] 2
Implements
\f[I]org.freedesktop.ScreenSaver (https://people.freedesktop.org/~hadess/idle-inhibition-spec/re01.html)\f[R]
service
Implements \f[I]\f[CI]org.freedesktop.ScreenSaver\f[I]\f[R] service and
screen saver
.IP \[bu] 2
Implements
\f[I]org.freedesktop.PowerManagement (https://www.freedesktop.org/wiki/Specifications/power-management-spec/)\f[R]
Implements \f[I]\f[CI]org.freedesktop.PowerManagement.Inhibit\f[I]\f[R]
service
.IP \[bu] 2
Automatically suspend on idle
.IP \[bu] 2
Automatically lock screen on idle
Automatically suspend or shutdown on critical battery
.IP \[bu] 2
Automatically hibernate or shutdown on critical battery
.IP \[bu] 2
Inhibit actions if external monitor(s) is connected
Inhibit lid action if external monitor connected
.IP \[bu] 2
Screen locking support
.IP \[bu] 2
Screen backlight support
.IP \[bu] 2
RTC wake alarm support
.IP \[bu] 2
CPU frequency scaling support
RTC wake support
.IP \[bu] 2
Thermal support
.IP \[bu] 2
Notification support
Notification support (can use
\f[I]\f[CI]org.freedesktop.Notifications\f[I]\f[R] if available)
.SH USAGE
powerkit should be started during the X11 user session.
Consult the documentation for your desktop environment or window manager
Expand All @@ -50,8 +40,8 @@ In \f[I]Fluxbox\f[R] add \f[I]\f[CI]powerkit &\f[I]\f[R] to the
In \f[I]Openbox\f[R] add \f[I]\f[CI]powerkit &\f[I]\f[R] to the
\f[I]\f[CI]\[ti]/.config/openbox/autostart\f[I]\f[R] file.
.PP
\f[B]Do not run powerkit if your desktop environment already has a power
manager!\f[R]
\f[B]Do use powerkit if your desktop environment or window manager
already has a power manager or screen saver service running.\f[R]
.SS CONFIGURATION
The most common options are available directly from the system tray
icon, for more advanced options open \f[I]\f[CI]Settings\f[I]\f[R] from
Expand All @@ -63,25 +53,27 @@ powerkit implements a basic screen saver to handle screen blanking,
poweroff and locking feature.
.PP
Locking feature depends on \f[CR]xsecurelock\f[R].
.PP
You can override the lock command with
\f[I]\f[CI]screensaver_lock_cmd=<command>\f[I]\f[R] in
\f[I]\f[CI]\[ti]/.config/powerkit/powerkit.conf\f[I]\f[R].
Note that the command must not contain spaces.
.SS BACKLIGHT
The current display brightness (on laptops and supported displays) can
be adjusted with the mouse wheel on the system tray icon or through the
system tray menu.
.SS HIBERNATE
If hibernate \f[I]\[lq]just works\[rq]\f[R] depends on your system,
worst case a swap partition (or file) is needed by the kernel to support
hibernate, just add \f[I]\f[CI]resume=<swap_partition>\f[I]\f[R] to the
kernel command line in the boot loader.
If hibernate works depends on your system, a swap partition (or file) is
needed by the kernel to support hibernate.
.PP
\f[B]\f[BI]Consult your system documentation regarding
hibernation\f[B]\f[R].
.SS ICONS
powerkit will use the existing icon theme from the running desktop
environment.
You should have (a proper version) of Adwaita installed as a fallback.
environment or window manager.
.PP
You can override the icon theme in the
\f[I]\f[CI]\[ti]/.config/powerkit/powerkit.conf\f[I]\f[R] file, see
\f[I]\f[CI]\[ti]/.config/powerkit/powerkit.conf\f[I]\f[R] file, use
\f[I]\f[CI]icon_theme=<theme_name>\f[I]\f[R].
.SH FAQ
.SS How does an application inhibit the screen saver?
Expand All @@ -99,7 +91,7 @@ Any application that uses \f[I]org.freedesktop.PowerManagement\f[R] will
work with powerkit.
.PP
Common use cases are audio playback, downloading, rendering and similar.
.SS Google Chrome/Chromium does not inhibit the screen saver!?
.SS Google Chrome/Chromium does not inhibit the screen saver or power manager!?
\f[I]Chrome (https://chrome.google.com)\f[R] does not use
\f[I]org.freedesktop.ScreenSaver\f[R] or
\f[I]org.freedesktop.PowerManagement\f[R] until it detects a supported
Expand All @@ -121,13 +113,13 @@ powerkit requires the following dependencies:
.IP \[bu] 2
\f[I]libXrandr (https://www.x.org/wiki/libraries/libxrandr/)\f[R]
.IP \[bu] 2
\f[I]Qt5 (https://qt.io)\f[R] \f[I](Core/DBus/Gui/Widgets)\f[R]
.IP \[bu] 2
\f[I]D-Bus (https://www.freedesktop.org/wiki/Software/dbus/)\f[R]
\f[I]Qt (https://qt.io)\f[R] 5.15 \f[I](Core/DBus/Gui/Widgets)\f[R]
.IP \[bu] 2
\f[I]logind (https://www.freedesktop.org/wiki/Software/systemd/logind/)\f[R]
\f[I](or compatible service)\f[R]
.IP \[bu] 2
\f[I]UPower (https://upower.freedesktop.org/)\f[R]
\f[I]UPower (https://upower.freedesktop.org/)\f[R] \f[I](or compatible
service)\f[R]
.IP \[bu] 2
\f[I]xsecurelock (https://github.com/google/xsecurelock)\f[R]
.SH BUILD
Expand All @@ -145,16 +137,14 @@ access to /sys.
Usually the \f[I]\f[CI]root\f[I]\f[R] user.
.IP \[bu] 2
\f[I]\f[CI]SERVICE_GROUP=<power>\f[I]\f[R] - Group that can access the
powerkitd service, this should be any desktop user that can change
screen brightness, CPU performance and RTC wake alarm.
Usually the \f[I]\f[CI]power\f[I]\f[R] group or similar.
Consult your system documentation.
powerkitd service, this should be any desktop user.
Consult your system documentation for the preferred user group.
.PP
Now configure powerkit with CMake and build (\f[I]example for packaging
purposes\f[R]).
.IP
.EX
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
cmake -DCMAKE_INSTALL_PREFIX=/usr -DSERVICE_GROUP=plugdev -DCMAKE_BUILD_TYPE=Release ..
make
make DESTDIR=<package> install
.EE
Expand Down Expand Up @@ -206,13 +196,13 @@ Easier to use (minimal setup)
.IP \[bu] 2
New UI
.IP \[bu] 2
RTC wake alarm support
RTC wake alarm support (not used for anything yet)
.RS 2
.IP \[bu] 2
Hibernate computer while suspended for X amount of time
.RE
.IP \[bu] 2
CPU frequency scaling and thermal support
CPU frequency scaling and thermal support (not used for anything yet)
.RS 2
.IP \[bu] 2
Intel PState
Expand Down

0 comments on commit 69e15aa

Please sign in to comment.