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 10, 2024
1 parent 5d1c456 commit a7a1c4a
Show file tree
Hide file tree
Showing 4 changed files with 235 additions and 214 deletions.
217 changes: 4 additions & 213 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,9 @@
# NAME

*powerkit* - Desktop independent power manager for Linux

# SYNOPSIS

powerkit *`[--config]`* *`[--set-brightness-up]`* *`[--set-brightness-down]`* *`[--sleep]`* *`[--hibernate]`* *`[--lock]`*

# DESCRIPTION
# powerkit

Desktop independent power manager for use with alternative X11 desktop environments and window managers on Linux.

![Screenshot of the powerkit configuration](screenshot.png)

* Implements *``org.freedesktop.ScreenSaver``* service
* Implements *``org.freedesktop.PowerManagement.Inhibit``* service
* Automatic actions on lid, idle and low battery
Expand All @@ -24,207 +18,4 @@ Desktop independent power manager for use with alternative X11 desktop environme
* Screen backlight support
* Notification support (can use *``org.freedesktop.Notifications``* if available)

# USAGE

powerkit should be started during the X11 user session. Consult the documentation for your desktop environment or window manager for launching startup applications.

* In *Fluxbox* add *``powerkit &``* to the *``~/.fluxbox/startup``* file
* In *Openbox* add *``powerkit &``* to the *``~/.config/openbox/autostart``* file.

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

## CONFIGURATION

Settings are available directly from the system tray icon or run *``powerkit --config``*. You should also be able to lauch the powerkit settings from your desktop application menu (if available).

## SCREEN SAVER

powerkit implements a basic screen saver to handle screen blanking, poweroff and locking feature.

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.

powerkit also supports the following commands that can be used for global shortcuts, scripts etc:

*`powerkit --set-brightness-up`*
: Set default display brightness up.

*`powerkit --set-brightness-down`*
: Set default display brightness down.

On Fluxbox you can add the commands to the *`~/.fluxbox/keys`* file:

```
XF86MonBrightnessUp :Exec powerkit --set-brightness-up
XF86MonBrightnessDown :Exec powerkit --set-brightness-down
```

## HIBERNATE

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 or window manager.

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

# FAQ

## How does an application inhibit the screen saver?

The preferred way to inhibit the screen saver from an application is to use the *org.freedesktop.ScreenSaver* specification. Any application that uses *org.freedesktop.ScreenSaver* will work with powerkit.

Popular applications that uses this feature is Mozilla Firefox, Google Chrome, VideoLAN VLC and many more.

## How does an application inhibit suspend actions?

The preferred way to inhibit suspend actions from an application is to use the *org.freedesktop.PowerManagement* specification. Any application that uses *org.freedesktop.PowerManagement* will work with powerkit.

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

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

Chrome 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:

```
export DESKTOP_SESSION=xfce
export XDG_CURRENT_DESKTOP=xfce
```

## Mozilla Firefox does not inhibit the power manager during audio playback and/or downloading!?

This is an issue with Firefox (missing feature). Use a different browser or open a request on the Firefox issue tracker.

Firefox should inhibit the power manager during audio playback (regardless of video) and during download (active queue). Currently Firefox only inhibit the screen saver during video playback. Chrome/Chromium does this correctly.

# REQUIREMENTS

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/)*
* *[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

First make sure you have the required dependencies installed, then review the most common build options:

* *``CMAKE_INSTALL_PREFIX=</usr/local>``* - Install target. *``/usr``* recommended.
* *``CMAKE_BUILD_TYPE=<Release/Debug>``* - Build type. *``Release``* recommended

Now configure powerkit with CMake and build:

```
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
make -j4
```

All you need is the *``powerkit``* binary located in the build directory, you can run it from any location.

## Install

Use regular *``make install``* with optional *``DESTDIR``*:

```
make DESTDIR=<package_directory> install
```

or make a native package:

```
cpack -G DEB
```
```
cpack -G RPM
```

# CHANGELOG

## 2.0.0 (TBA)

* Recommended locker is ``xsecurelock``
* Added support for "modern" logind
* Removed support for ConsoleKit
* Removed support for XScreenSaver
* Added basic screen saver
* Easier to use (minimal/no setup)
* New UI
* Major code changes

# OPTIONS

*``--config``*
: Launch configuration.

*`--set-brightness-up`*
: Set default display brightness up.

*`--set-brightness-down`*
: Set default display brightness down.

*`--sleep`*
: Suspend computer now. Can be combined with *`--hibernate`* for suspend then hibernate after X amount of time.

*`--hibernate`*
: Hibernate computer now. Can be combined with *`--sleep`* for suspend then hibernate after X amount of time.

*`--lock`*
: Lock screen.

# FILES

*``~/.config/powerkit/powerkit.conf``*
: Per user configuration file.

# SEE ALSO

**``xsecurelock``**(1), **``UPower``**(7), **``systemd-logind``**(8)

# BUGS

See **https://github.com/rodlie/powerkit/issues**.

# COPYRIGHT

```
Copyright (c) Ole-André Rodlie <https://github.com/rodlie>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```
See [documentation](powerkit.md) (`man powerkit`) for more information.
2 changes: 1 addition & 1 deletion docs/build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,6 @@ VERSION=`cat ${CWD}/CMakeLists.txt | sed '/powerkit VERSION/!d;s/)//' | awk '{pr
echo "% POWERKIT(1) Version ${VERSION} | PowerKit Documentation" > ${CWD}/tmp.md
echo "% Ole-André Rodlie" >> ${CWD}/tmp.md
echo "% ${MONTH} ${YEAR}" >> ${CWD}/tmp.md
cat ${CWD}/docs/README.md >> ${CWD}/tmp.md
cat ${CWD}/docs/powerkit.md >> ${CWD}/tmp.md
${PANDOC} ${CWD}/tmp.md -s -t man > ${CWD}/docs/powerkit.1
rm ${CWD}/tmp.md
Loading

0 comments on commit a7a1c4a

Please sign in to comment.