source: general/sysutils/upower.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY upower-download-http "https://gitlab.freedesktop.org/upower/upower/-/archive/v&upower-version;/upower-v&upower-version;.tar.bz2">
  <!ENTITY upower-download-ftp  " ">
  <!ENTITY upower-md5sum        "2399845217a9c6e4510f66033fcd7cf6">
  <!ENTITY upower-size          "140 KB">
  <!ENTITY upower-buildsize     "5.5 MB (add 2.6 MB for tests)">
  <!ENTITY upower-time          "less than 0.1 SBU (add 0.6 SBU for tests)">
]>

<sect1 id="upower" xreflabel="UPower-&upower-version;">
  <?dbhtml filename="upower.html"?>


  <title>UPower-&upower-version;</title>

  <indexterm zone="upower">
    <primary sortas="a-UPower">UPower</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to UPower</title>

    <para>
      The <application>UPower</application> package provides an interface for
      enumerating power devices, listening to device events and querying history
      and statistics. Any application or service on the system can access the
      org.freedesktop.UPower service via the system message bus.
    </para>

    &lfs121_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&upower-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&upower-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &upower-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &upower-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &upower-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &upower-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">UPower Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libgudev"/> and
      <xref linkend="libusb"/>
    </para>

    <bridgehead renderas="sect4">Optional (Required if building GNOME)</bridgehead>
    <para role="optional">
      &gobject-introspection;
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gtk-doc"/>,
      <xref linkend="libxslt"/>,
      <xref linkend="docbook-xsl"/>,
      <xref linkend="pygobject3"/>,
      <xref linkend="python-dbusmock"/>,
      <xref linkend="umockdev"/> (for part of the test suite), and
      <ulink url="https://libimobiledevice.org/">libimobiledevice</ulink>
    </para>

  </sect2>

  <sect2 role="kernel" id="upower-kernel" revision="systemd">
    <!-- With UPower-0.9.11's hardening of the systemd unit file,
         User Namespace Support (CONFIG_USER_NS) is now required. Without this,
         you will get "ERROR 213/USER" out of a 'systemctl start upower'. -->
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration and recompile the
      kernel if necessary:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="upower-systemd-kernel.xml"/>

    <indexterm zone="upower upower-kernel">
      <primary sortas="d-upower">upower</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of UPower</title>

    <para>
      Install <application>UPower</application> by running the following
      commands:
    </para>

<screen revision="sysv"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup ..                  \
      --prefix=/usr             \
      --buildtype=release       \
      -Dgtk-doc=false           \
      -Dman=false               \
      -Dsystemdsystemunitdir=no \
      -Dudevrulesdir=/usr/lib/udev/rules.d &amp;&amp;
ninja</userinput></screen>

<screen revision="systemd"><userinput>mkdir build                         &amp;&amp;
cd    build                         &amp;&amp;
meson setup ..            \
      --prefix=/usr       \
      --buildtype=release \
      -Dgtk-doc=false     \
      -Dman=false         &amp;&amp;
ninja</userinput></screen>

    <!-- On my system with LANG=zh_CN.UTF-8, one test attempted to compare
         Chinese error message with English references and failed.
         LC_ALL=C fixes the problem.  -->
    <!-- Headphone hotplug (bluetooth and AUX) was tested and seems to work
         okay even with the test faliures. Maybe it's wants headphones plugged
         in during the test? Regardless, it can be safely ignored. -->
    <!-- On a 32-bit machine, the following test failure can be observed:
         ======================================================================
         FAIL: test_battery_energy_charge_mixed (__main__.Tests.test_battery_energy_charge_mixed)
         battery which reports both current charge and energy

         self.assertEqual(self.get_dbus_dev_property(bat0_up, 'Percentage'), 40.0)
         AssertionError: 40.00000000000001 != 40.0

         This is known upstream as https://gitlab.freedesktop.org/upower/upower/-/issues/251
         Not sure if this is an actual problem, but it seems to start and work
         properly -renodr

         test_bluetooth_le_device: upstream MR !207  -xry111 -->

    <!-- On my system all 68 tests passed for v1.90.4.  
         Did not check on a 32-bit system. - bdubbs -->

    <para>
      To test the results, issue: <command>LC_ALL=C ninja test</command>.  The
      test suite should be run from a local GUI session started with
      dbus-launch. On 32-bit machines, one test will fail due to rounding
      errors: <filename>Tests.test_battery_energy_charge_mixed</filename>. On
      some systems, two tests relating to the headphone hotplug feature are
      known to fail. Those can be safely ignored since the functionality still
      works.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <parameter>-Dgtk-doc=false</parameter>: Prevents building the
      documentation. Remove this if you have <application>GTK-Doc</application>
      installed and wish to build the documentation.
    </para>

    <para>
      <parameter>-Dman=false</parameter>: Prevents building the
      manual pages. Remove this if you have <xref linkend='libxslt'/> and
      <xref linkend='docbook-xsl'/> installed and wish to build the manual
      pages.
    </para>

    <para revision="sysv">
      <parameter>-Dsystemdsystemunitdir=no</parameter>: Removes
      the dependency on <application>systemd</application>.
    </para>

    <para revision="sysv">
      <parameter>-Dudevrulesdir=/usr/lib/udev/rules.d</parameter>: Tells
      the build system where to install <application>udev</application>
      rules because the information is missing in
      <filename>/usr/lib/pkgconfig/libudev.pc</filename>
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program<!--
See below... <phrase revision="systemd">s</phrase>--></segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          upower
<!-- <phrase revision="systemd"> and upowerd</phrase>
Upowerd should not be listed, as it is in /usr/libexec, and is not supposed
to be run by a user. Furthermore, upowerd is also in sysv, and there is no
reason so single out systemd here. -->
        </seg>
        <seg>
          libupower-glib.so
        </seg>
        <seg>
          /etc/UPower,
          /usr/include/libupower-glib, and
          /var/lib/upower
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="upower-prog">
        <term><command>upower</command></term>
        <listitem>
          <para>
            is the <application>UPower</application> command line tool
          </para>
          <indexterm zone="upower upower-prog">
            <primary sortas="b-upower">upower</primary>
          </indexterm>
        </listitem>
      </varlistentry>
<!-- See above
      <varlistentry id="upowerd" revision="systemd">
        <term><command>upowerd</command></term>
        <listitem>
          <para>
            is the <application>UPower</application> Daemon. It provides the
            org.freedesktop.UPower service on the system message bus.
          </para>
          <indexterm zone="upower upowerd">
            <primary sortas="b-upowerd">upowerd</primary>
          </indexterm>
        </listitem>
      </varlistentry>-->

      <varlistentry id="libupower-glib">
        <term><filename class="libraryfile">libupower-glib.so</filename></term>
        <listitem>
          <para>
            contains the <application>UPower</application> API functions
          </para>
          <indexterm zone="upower libupower-glib">
            <primary sortas="c-libupower-glib">libupower-glib.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>