depot/third_party/nixpkgs/nixos/modules/services/x11/desktop-managers/pantheon.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chap-pantheon">
  <title>Pantheon Desktop</title>
  <para>
    Pantheon is the desktop environment created for the elementary OS
    distribution. It is written from scratch in Vala, utilizing GNOME
    technologies with GTK and Granite.
  </para>
  <section xml:id="sec-pantheon-enable">
    <title>Enabling Pantheon</title>
    <para>
      All of Pantheon is working in NixOS and the applications should be
      available, aside from a few
      <link xlink:href="https://github.com/NixOS/nixpkgs/issues/58161">exceptions</link>.
      To enable Pantheon, set
    </para>
    <programlisting>
services.xserver.desktopManager.pantheon.enable = true;
</programlisting>
    <para>
      This automatically enables LightDM and Pantheon’s LightDM greeter.
      If you’d like to disable this, set
    </para>
    <programlisting>
services.xserver.displayManager.lightdm.greeters.pantheon.enable = false;
services.xserver.displayManager.lightdm.enable = false;
</programlisting>
    <para>
      but please be aware using Pantheon without LightDM as a display
      manager will break screenlocking from the UI. The NixOS module for
      Pantheon installs all of Pantheon’s default applications. If you’d
      like to not install Pantheon’s apps, set
    </para>
    <programlisting>
services.pantheon.apps.enable = false;
</programlisting>
    <para>
      You can also use
      <xref linkend="opt-environment.pantheon.excludePackages" /> to
      remove any other app (like <literal>elementary-mail</literal>).
    </para>
  </section>
  <section xml:id="sec-pantheon-wingpanel-switchboard">
    <title>Wingpanel and Switchboard plugins</title>
    <para>
      Wingpanel and Switchboard work differently than they do in other
      distributions, as far as using plugins. You cannot install a
      plugin globally (like with
      <option>environment.systemPackages</option>) to start using it.
      You should instead be using the following options:
    </para>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraWingpanelIndicators" />
        </para>
      </listitem>
      <listitem>
        <para>
          <xref linkend="opt-services.xserver.desktopManager.pantheon.extraSwitchboardPlugs" />
        </para>
      </listitem>
    </itemizedlist>
    <para>
      to configure the programs with plugs or indicators.
    </para>
    <para>
      The difference in NixOS is both these programs are patched to load
      plugins from a directory that is the value of an environment
      variable. All of which is controlled in Nix. If you need to
      configure the particular packages manually you can override the
      packages like:
    </para>
    <programlisting>
wingpanel-with-indicators.override {
  indicators = [
    pkgs.some-special-indicator
  ];
};

switchboard-with-plugs.override {
  plugs = [
    pkgs.some-special-plug
  ];
};
</programlisting>
    <para>
      please note that, like how the NixOS options describe these as
      extra plugins, this would only add to the default plugins included
      with the programs. If for some reason you’d like to configure
      which plugins to use exactly, both packages have an argument for
      this:
    </para>
    <programlisting>
wingpanel-with-indicators.override {
  useDefaultIndicators = false;
  indicators = specialListOfIndicators;
};

switchboard-with-plugs.override {
  useDefaultPlugs = false;
  plugs = specialListOfPlugs;
};
</programlisting>
    <para>
      this could be most useful for testing a particular plug-in in
      isolation.
    </para>
  </section>
  <section xml:id="sec-pantheon-faq">
    <title>FAQ</title>
    <variablelist spacing="compact">
      <varlistentry>
        <term>
          <anchor xml:id="sec-pantheon-faq-messed-up-theme" />I have
          switched from a different desktop and Pantheon’s theming looks
          messed up.
        </term>
        <listitem>
          <para>
            Open Switchboard and go to: Administration → About → Restore
            Default Settings → Restore Settings. This will reset any
            dconf settings to their Pantheon defaults. Note this could
            reset certain GNOME specific preferences if that desktop was
            used prior.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <anchor xml:id="sec-pantheon-faq-gnome-and-pantheon" />I
          cannot enable both GNOME and Pantheon.
        </term>
        <listitem>
          <para>
            This is a known
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/64611">issue</link>
            and there is no known workaround.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <anchor xml:id="sec-pantheon-faq-appcenter" />Does AppCenter
          work, or is it available?
        </term>
        <listitem>
          <para>
            AppCenter has been available since 20.03. Starting from
            21.11, the Flatpak backend should work so you can install
            some Flatpak applications using it. However, due to missing
            appstream metadata, the Packagekit backend does not function
            currently. See this
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/15932">issue</link>.
          </para>
          <para>
            If you are using Pantheon, AppCenter should be installed by
            default if you have
            <link linkend="module-services-flatpak">Flatpak
            support</link> enabled. If you also wish to add the
            <literal>appcenter</literal> Flatpak remote:
          </para>
          <programlisting>
$ flatpak remote-add --if-not-exists appcenter https://flatpak.elementary.io/repo.flatpakrepo
</programlisting>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
</chapter>