source: networking/netlibs/geoclue2.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 geoclue2-download-http
  "https://gitlab.freedesktop.org/geoclue/geoclue/-/archive/&geoclue2-version;/geoclue-&geoclue2-version;.tar.bz2">
  <!ENTITY geoclue2-download-ftp  " ">
  <!ENTITY geoclue2-md5sum        "08bacd3b45311ee6c20e4240be7bc348">
  <!ENTITY geoclue2-size          "104 KB">
  <!ENTITY geoclue2-buildsize     "6.9 MB">
  <!ENTITY geoclue2-time          "0.1 SBU">
]>

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


  <title>GeoClue-&geoclue2-version;</title>

  <indexterm zone="geoclue2">
    <primary sortas="a-geoclue">GeoClue</primary>
  </indexterm>

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

    <para>
      <application>GeoClue</application> is a modular geoinformation service
      built on top of the <application>D-Bus</application> messaging system. The
      goal of the <application>GeoClue</application> project is to make creating
      location-aware applications as simple as possible.
    </para>

    &lfs121_checked;

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

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="json-glib"/> and
      <xref linkend="libsoup3"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="avahi"/>,
      <xref linkend="libnotify"/>,
      <xref linkend="ModemManager"/>, and
      <xref linkend="vala"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gtk-doc"/>
    </para>

  </sect2>

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

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

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr       \
            --buildtype=release \
            -Dgtk-doc=false     \
            ..                  &amp;&amp;
ninja</userinput></screen>

    <para>
      This package does not come with a test suite.
    </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>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <option>-D3g-source=false</option>: This switch disables
      the 3G backend. Use it if you have not installed the
      <application>ModemManager</application> package.
    </para>

    <para>
      <option>-Dmodem-gps-source=false</option>: This switch disables
      the modem GPS backend. Use it if you have not installed the
      <application>ModemManager</application> package.
    </para>

    <para>
      <option>-Dcdma-source=false</option>: This switch disables the
      CDMA source backend. Use it if you have not installed the
      <application>ModemManager</application> package.
    </para>

    <para>
      <option>-Dnmea-source=false</option>: This switch disables the
      NMEA source. Use it if you have not installed the
      <application>Avahi</application> package.
    </para>

    <para>
      <option>-Ddemo-agent=false</option>: This switch disables the
      demo. Use it if you have not installed the
      <application>libnotify</application> package.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring GeoClue</title>

    <sect3 id="geoclue2-config">
      <title>Config Files</title>
      <para>
        <filename>/etc/geoclue/conf.d/90-lfs-google.conf</filename>
      </para>

      <indexterm zone="geoclue2 geoclue2-config">
        <primary sortas="etc-geoclue-conf.d-90-lfs-google.conf">/etc/geoclue/conf.d/90-lfs-google.conf</primary>
      </indexterm>
    </sect3>

    <sect3><title>Configuration Information</title>

      <para>
        In March of 2024, Mozilla announced the shutdown of the Mozilla Location
        Service. Geoclue uses this service for determining a user's location
        when requested by other applications. The only supported alternative by
        upstream is to use Google's Geolocation Service.
      </para>

      <para>
        To use Google's Geolocation Service, an API key must be used, and a
        configuration file must be created. <emphasis role="bold">This API key
        is only intended for use with LFS. Please do not use this API key if you
        are building for another distro or distributing binary copies. If you
        need an API key, you can request one at
        <ulink url="https://www.chromium.org/developers/how-tos/api-keys"/>.</emphasis>
      </para>

      <para>
        Create the configuration needed for using Google's Geolocation Service
        as the &root; user:
      </para>

<screen role="root"><userinput>cat &gt;&gt; /etc/geoclue/conf.d/90-lfs-google.conf &lt;&lt; "EOF"
<literal># Begin /etc/geoclue/conf.d/90-lfs-google.conf

# This configuration applies for the WiFi source.
[wifi]

# Set the URL to Google's Geolocation Service.
url=https://www.googleapis.com/geolocation/v1/geolocate?key=AIzaSyDxKL42zsPjbke5O8_rPVpVrLrJ8aeE9rQ

# End /etc/geoclue/conf.d/90-lfs-google.conf</literal>
EOF</userinput></screen>

      <para>
        If you do not wish to request your location from a Geolocation service,
        you can hardcode your location in <filename>/etc/geolocation</filename>
        using the format described in
        <ulink role='man' url='&man;geoclue'>geoclue(5)</ulink>.
      </para>
    </sect3>
  </sect2>

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

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          None
        </seg>
        <seg>
          libgeoclue-2.so
        </seg>
        <seg>
          /etc/geoclue,
          /usr/include/libgeoclue-2.0,
          /usr/libexec/geoclue-2.0, and
          /usr/share/gtk-doc/html/{geoclue,libgeoclue}
        </seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

</sect1>