diff --git a/docs/README.md b/docs/README.md index d9fc729..4af155f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 @@ -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 @@ -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=``* 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=``* 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=``*. +You can override the icon theme in the *`~/.config/powerkit/powerkit.conf`* file, use *``icon_theme=``*. # FAQ @@ -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: @@ -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 @@ -103,11 +99,12 @@ First make sure you have the required dependencies installed, then review the mo * *``CMAKE_INSTALL_PREFIX=``* - Install target. *``/usr``* recommended. * *``CMAKE_BUILD_TYPE=``* - Build type. *``Release``* recommended * *``SERVICE_USER=``* - powerkitd owner, needs write access to /sys. Usually the *``root``* user. - * *``SERVICE_GROUP=``* - 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=``* - 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= install ``` @@ -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) diff --git a/share/powerkit.1 b/share/powerkit.1 index 1fa3046..82dc813 100644 --- a/share/powerkit.1 +++ b/share/powerkit.1 @@ -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 @@ -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 @@ -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=\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=\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=\f[I]\f[R]. .SH FAQ .SS How does an application inhibit the screen saver? @@ -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 @@ -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 @@ -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=\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= install .EE @@ -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