企业官网建设流程全解析

• 桌面应用
• 操作系统

本指南基于 docs/manual/install/funtoo.rst 编写，面向使用 Funtoo（Gentoo 衍生发行版）的用户，介绍如何通过 Portage 包管理器安装 Qtile 平铺窗口管理器、安装 GitHub master 开发版，以及如何借助dbus与widget-*系列 USE 标志按需定制安装。读完本文，你将掌握emerge安装 Qtile 的完整流程，理解每个 USE 标志背后对应的 Qtile 组件与第三方依赖，并能根据自身需求裁剪或扩展安装内容。

Funtoo 与 Qtile 的安装方式概览

Funtoo 是 Gentoo 的衍生发行版，与 Gentoo 一样使用 Portage 包管理系统与emerge命令，并采用 USE 标志（USE flags）机制按需编译和启用软件功能。Qtile 是一个用 Python 编写、以 Python 配置的平铺窗口管理器（X11 与 Wayland 双后端），Funtoo 官方软件仓库中已经提供了 Qtile 的 ebuild，因此可以像安装其他系统软件一样直接安装，无需手动从源码编译 Python 包。

在 Funtoo 上安装 Qtile 有两种途径：

其中9999是 Gentoo/Funtoo 生态中"实时（live）软件包"的版本号约定，表示该 ebuild 不基于发布 tarball，而是直接从版本控制系统克隆源码构建。

安装稳定版 Qtile

在 Funtoo 上安装最新稳定版 Qtile 只需一条命令：

emerge -av x11-wm/qtile

命令参数说明：

• -a（--ask）：在真正执行前询问确认，方便你检查 Portage 将要安装的依赖列表；
• -v（--verbose）：输出详细的版本、USE 标志与依赖信息，便于确认安装内容。

执行后 Portage 会自动解析 Qtile 的运行时依赖。Qtile 是纯 Python 平铺窗口管理器，其核心依赖包括cffi、cairocffi与 X11 后端所需的xcffib（参见 pyproject.toml 的dependencies字段），同时需要 libpangocairo 用于在状态栏和弹出窗口中绘制文字，这些依赖细节可参考 docs/manual/install/index.rst 中的 "Core Dependencies" 表格。在 Funtoo 上，这些依赖均由 ebuild 自动处理，无需手动干预。

安装 GitHub 开发版（live ebuild）

如果你希望使用 Qtile master 分支上的最新代码（例如抢先体验新 widget 或后端改进），可以安装开发版。由于 live ebuild 没有稳定版 KEYWORDS，需要先将其加入package.accept_keywords：

echo "x11-wm/qtile-9999 **" >> /etc/portage/package.accept_keywords emerge -av qtile

逐行解释：

1. 第一行命令将x11-wm/qtile-9999 **追加写入/etc/portage/package.accept_keywords（文件不存在时会自动创建，需 root 权限）。其中：
   • x11-wm/qtile-9999精确指定要接受关键词的 live ebuild；
   • **表示在所有架构上无条件接受该包的关键字，因为 live ebuild 通常不会为特定架构标记稳定的 KEYWORDS。
2. 第二行执行安装。此处包名省略了x11-wm/类别前缀，Portage 会自动解析到x11-wm/qtile。

需要注意：live ebuild 每次构建都会从 GitHub 重新拉取 master 分支的最新提交，因此每次emerge -av qtile都可能得到不同的代码版本，适合尝鲜，但不建议在追求稳定性的生产环境使用。后续想切回稳定版时，只需删除package.accept_keywords中对应的那一行，再重新emerge -av x11-wm/qtile即可。

使用 USE 标志定制安装

安装完成后，Qtile 的许多可选功能默认并不启用。Funtoo 的 Qtile ebuild 提供了dbus与一系列widget-*USE 标志，用于按需引入相应组件及其第三方依赖，避免"装一堆用不上的库"。

Funtoo 的 Qtile ebuild 支持的 USE 标志如下：

启用某个 USE 标志的通用写法是在安装命令前临时指定，例如：

USE="widget-wlan widget-mpd" emerge -av x11-wm/qtile

若希望长期生效，可将相应 USE 标志写入/etc/portage/package.use（或 Funtoo 推荐的/etc/portage/package.use/目录下的配置文件），例如：

x11-wm/qtile widget-wlan widget-mpd

dbus：默认开启的基础能力

dbusUSE 标志默认启用，因为 Qtile 的多个核心组件都依赖 D-Bus 通信。从源码可以看到，mpris2widget.py、bluetooth.py、keyboardkbdd.py 以及 helpers/status_notifier/statusnotifier.py 都通过from dbus_fast import ...导入dbus-fast库；同时 docs/manual/install/index.rst 也指出dbus-fast用于通过 D-Bus 发送通知（可选）。因此，dbusUSE 标志只在你知道它具体做什么、并确认自己用不到 D-Bus 相关功能时才建议关闭，一般用户应保持默认开启。

各 widget USE 标志对应的组件与依赖

widget-*系列 USE 标志默认全部禁用，原因是这些 widget 需要额外的第三方依赖，而并非每个用户都会用到它们。下面结合仓库源码说明每个标志背后对应的小部件实现，帮助你判断哪些值得启用。

widget-khal-calendar：Khal 日历小部件

对应 libqtile/widget/khal_calendar.py 中的KhalCalendar类。该小部件在状态栏显示 Khal 日历的下一个日程，并在临近提醒时间时高亮显示。它通过subprocess调用系统khal命令（khal list now <lookahead>d）获取日程，再使用python-dateutil解析时间。启用该 USE 标志意味着你的系统需要安装khal程序。小部件支持remindertime（提前提醒分钟数）、lookahead（向前查询天数）、reminder_color（提醒高亮颜色）等配置。

widget-imap：IMAP 邮件小部件

对应 libqtile/widget/imapwidget.py 中的ImapWidget类。它通过 SSL 连接 IMAP 服务器，报告指定邮箱中未读邮件的数量。密码默认从 Gnome Keyring 读取（依赖keyring库），也可直接在配置中指定password。小部件的user、server、mbox、label、hide_no_unseen等参数需要结合你的邮箱环境配置。

widget-keyboardkbdd：kbdd 键盘布局小部件

对应 libqtile/widget/keyboardkbdd.py 中的KeyboardKbdd类。它用于按窗口切换键盘布局，前提是系统已安装并运行kbdd守护进程（来自ru.gentoo.kbddD-Bus 接口，恰好是 Gentoo 系生态的工具）。小部件通过dbus-fast订阅layoutChanged信号实时更新显示，并支持configured_keyboards（布局列表）与colours（各布局对应的前景色）等配置。

widget-launchbar：图标启动栏小部件

对应 libqtile/widget/launchbar.py 中的LaunchBar类。它显示一排图标，点击后执行对应命令，支持progs列表（软件名/图标路径、命令、注释三元组），甚至可以执行qshell:开头的 Qtile 内部 Python 命令。启用该 USE 标志会引入可选的pyxdg依赖，用于在未显式提供图标路径时按图标主题查找图标。

widget-mpd：MPD 音乐小部件

对应 libqtile/widget/mpd2widget.py 中的Mpd2类。它基于python-mpd2库连接 MPD 音乐播放守护进程，显示当前歌曲、播放状态与播放列表状态，并支持鼠标滚轮切换曲目、单击暂停等交互。可配置host、port、password、status_format、idle_format等参数。

widget-mpris：MPRIS2 媒体播放器小部件

对应 libqtile/widget/mpris2widget.py 中的Mpris2类。它通过dbus-fast监听 D-Bus 会话总线上的 MPRIS2 规范信号，显示当前播放曲目与艺术家信息，支持滚动显示、格式化元数据（如{xesam:title} - {xesam:artist}）以及播放/暂停、上下曲等鼠标控制。poll_interval可开启对播放器的后台轮询。

widget-wlan：WiFi 状态小部件

对应 libqtile/widget/wlan.py 中的Wlan类。它依赖iwlib库读取无线网卡的 ESSID 与信号质量，显示当前连接的 WiFi 名称与信号强度，并支持以太网回退检测（use_ethernet、ethernet_message_format）与自定义format。如果你的环境没有 WiFi 设备，官方建议改用Netwidget（libqtile/widget/net.py）。

启用策略很简单：只启用你实际会用到的小部件。例如只在状态栏显示 WiFi 与音乐信息的用户，可只开widget-wlan与widget-mpd；完全不使用任何上述小部件的用户，可以全部保持禁用，让 Qtile 以最精简的依赖运行。widgets依赖集合的完整组成也可以参考 pyproject.toml 中[project.optional-dependencies]的widgets列表（包含python-mpd2、keyring、psutil、pulsectl等），Funtoo 的 ebuild 将对应的依赖拆成了独立的widget-*USE 标志。

安装后的验证与启动

安装完成后，可以用如下命令确认 Qtile 是否就绪：

qtile --version

启动 Qtile 的常见方式是在登录管理器（如 SDDM、LightDM）中选择 Qtile 会话，或通过~/.xinitrc中追加exec qtile start直接启动（无显示管理器场景）。具体启动方式与 X11/Wayland 双后端的选择可参考 docs/manual/install/index.rst 的 "Starting Qtile" 章节，以及 docs/manual/wayland.rst（Wayland 会话可执行qtile start -b wayland，需确保系统具备 wlroots 等依赖）。

如果启用的小部件在启动后没有正常工作，请优先检查对应的第三方依赖是否已随 USE 标志正确安装，以及外部服务（如khal、kbdd、MPD 服务、D-Bus 会话总线）是否正在运行。

日常维护与常见问题

• 升级稳定版：emerge --sync同步 Portage 仓库后，执行emerge -av x11-wm/qtile即可升级到仓库中的最新稳定版。
• 升级开发版：直接再次执行emerge -av qtile，Portage 会重新拉取 GitHub master 最新提交并重建。
• 切换版本：想从开发版切回稳定版，删除/etc/portage/package.accept_keywords中对应行后重新emerge -av x11-wm/qtile；反之按本文前述步骤添加 9999 行。
• 卸载 Qtile：使用emerge --depclean qtile或emerge -C x11-wm/qtile（后者不检查依赖，需谨慎使用），随后可用revdep-rebuild检查被移除库影响的软件。
• 修改 USE 标志后的重建：修改/etc/portage/package.use后，Portage 需要emerge -av --newuse --deep x11-wm/qtile之类的方式重新评估并重建受影响部分。

关于 Qtile 在 Funtoo 上的更完整安装细节，还可以查阅 Funtoo 官方 Wiki 的 "Package:Qtile" 页面（即原文档末尾引用的 Funtoo Qtile documentation），其中包含针对 Funtoo 特有的关键字与依赖说明。

综上，Funtoo 上安装 Qtile 的核心思路是：用emerge装包，按需添加9999实时版本关键字获取最新代码，再通过dbus与widget-*USE 标志精确控制依赖规模。掌握这套流程后，你便可以在 Funtoo 系统上获得一个既完整又精简的 Qtile 平铺桌面环境。

• 桌面应用
• 操作系统