Lib.rs

› 开发工具
#userspace #debugging #fuse #debugfs #anyway #running #build

no-std febug

anyway, here's user-space debugfs

by наб

5 个版本 (1 个稳定版本)

使用旧的 Rust 2015

1.0.0 2023年11月30日
0.2.1 2023年6月12日
0.1.2 2021年1月31日
0.1.1 2021年1月25日
0.1.0 2021年1月20日

#199 in 开发工具

MIT 许可证

28KB
360 行

febug builds.sr.ht 徽章

anyway, here's user-space debugfs

Debian manpages (PDF)

FreeBSD manpages (PDF)

NetBSD manpages (PDF)

OpenBSD manpages (PDF)

MacOS manpages (PDF)

库 rustdoc

是什么？

协作式调试（程序和您之间）

# systemctl start febug
$ findmnt /run/febug
/run/febug febug  fuse.febug rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other
$ ./out/examples/vector-sort &
[1] 1409
$ LD_LIBRARY_PATH=out ./out/examples/string-qsort &
[2] 1410
$ ls /run/febug/
1409    1410
$ ls -l /run/febug/
dr-xr-x--- 4 nabijaczleweli users 0 Jan 15 19:52 1409
dr-xr-x--- 3 nabijaczleweli users 0 Jan 15 19:52 1410
$ ls /run/febug/1409/
comparisons     cool_data
$ cat /run/febug/1409/*
24
-3 -2 -3 -2 -3 -2 3 -1 -2 -3 0 1 2 3 -1 -2 -3 0 1 2 3 -1 -2 -3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3
$ cat /run/febug/1409/*
45
-3 -2 -3 -2 -3 -2 -3 -2 -2 -3 -3 -2 -1 3 -1 1 0 0 1 2 3 2 -1 3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3
$ grep . /run/febug/*/*
/run/febug/1409/comparisons:71
/run/febug/1409/cool_data:-3 -3 -3 -3 -3 -3 -2 -2 -2 -2 -2 -2 -1 3 -1 1 0 0 1 2 3 2 -1 3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3
/run/febug/1410/cool_data:3012987654ACEFOLJKODNIEMIGHBPPbdWwnfTpXQcreRlVvUSitZQWjRTYUazuqwertyuiopoxyhmYsgkq
$ kill %1
$ ls /run/febug/
1410

如何？

  1. 默认情况下，UNIX 域 SOCK_SEQPACKET（如果不可用，则为 SOCK_STREAM）在 [/var]/run/febug.sock，对应挂载在 [/var]/run/febug
  2. 可调试客户端连接
  3. 当凭证可用时，会出现一个目录，类似于 procfs
  4. 当客户端想要调试变量时，它发送一个 febug_message（variable_id、variable_type、signal 和 name（见 febug-abi.h））- name 在目录下获得一个文件
  5. 在文件的 open() 上，客户端收到一个 attn_febug_message（variable_id 和 variable_type）和一个管道的写入端（如果 signal 不是 SIGKILL），并通知
  6. read() 从管道的对应端直接复制——客户端必须在返回信号处理程序之前（或者如果使用其他机制，在适当表示时）close()它。
  7. 当变量超出作用域时，客户端发送stop_febug_message（variable_id）进行注销，消失文件。
  8. 当客户端挂起时，其目录消失。

或者，也许（服务器是盒子，程序是椭圆形，用户是梯形）：graphviz diagram

构建

对于Linux系统：builds.sr.ht status for sid

  • 安装 libfuse3-dev，pkg-config 和 mandoc
  • make

对于FreeBSD：builds.sr.ht status for latest FreeBSD

  • 安装 gmake，fusefs-libs3 和 pkgconf
  • gmake

对于NetBSD

  • 安装 devel/gmake
  • gmakeLTO=n

对于OpenBSD：builds.sr.ht status for latest OpenBSD

  • 安装 gmake
  • gmakeCXX=c++ LTO=n

对于Macintosh

  • 安装 macFUSE 和 mandoc
  • make

对于其他平台

  • 欢迎贡献端口！

要构建Rust crate及其示例和文档，安装 cargo/rust/lang/rust[-bin]/rust 并运行 [g]make rust-build rust-doc，但对于普通构建者来说这并不重要。

Python包可以通过将 febug.py 复制到 PYTHONPATH 或通过运行 [g]make python-build（需要python3）并在 out/febug.py/dist/ 中安装包来安装。

graphviz的dot(1)也需要重新生成图表，尽管这本身是可选的。

（对最终用户可见）平台差异

对于为Linux构建的情况，默认套接字路径是 /run/febug.sock，否则是 /var/run/febug.sock。

在OpenBSD和Darwin上，进程通过其有效UID/GID/PID进行身份验证。

Darwin不支持SOCK_SEQPACKET，因此使用SOCK_STREAM代替。

运行

对于系统实例，以root身份运行 febug /run/febug/ &（或 /var/run/febug/，或任何其他地方，具体情况而定）。

要运行用户本地的实例，需要使用辅助工具 fusermount3，然后需要执行以下命令以设置环境变量 export FEBUG_SOCKET=/run/user/$(id -u)/febug.sock，接着执行 febug /run/user/$(id -u)/febug/ &。这对于使用 libfebug 和 libfebug++ 的程序应该有效；使用不同 ABI 封装的程序也建议遵守此环境变量。

init/ 包含了这两个用例的系统d 单元（尽管需要在调试程序的配置中手动设置此路径），以及用于全局设置的 FreeBSD/NetBSD 和 OpenBSD rc.d 脚本。

有关它们如何运行的示例，请参阅 out/examples/ 目录中的文件，这些文件在比较函数中包含了睡眠。

安装

从 Debian 仓库

在 /etc/apt/sources.list 或等效文件中添加以下行

deb [signed-by=/etc/apt/keyrings/nabijaczleweli.asc] https://debian.nabijaczleweli.xyz sid main

使用 我的 PGP 密钥（两个 URL 可以互换使用）

sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key
sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://nabijaczleweli.xyz/pgp.txt

（您可能需要在 apt <2.4.0 （<=bullseye）的 /etc/apt/keyrings 中手动创建。）

然后执行常规操作

sudo apt update
sudo apt install febug libfebug0 libfebug-dev libfebug++-dev

将适用于 amd64、x32 和 i386。

有关更多信息，请参阅 仓库 README 或 源代码包。

从 pkgsrc

git clone https://git.sr.ht/~nabijaczleweli/febug-pkgsrc /usr/pkgsrc/devel/febug  # or, indeed, where-ever the pkgsrc root is

在 devel/febug 下执行 make install 将在 NetBSD 和 OpenBSD 上自动工作，但在 FreeBSD 上将需要执行 pkg install fusefs-libs3。

从 tar 包

发布版本的 tar 包由 [email protected] 签署（使用 WKD 提取，但使用以下密钥：7D69 474E 8402 8C5C C0C4 4163 BCFD 0B01 8D26 58F1）。它们被存储在 git notes 中，就像通过 示例程序 一样，因此可以在 refs 列表/tag 页面上作为 .tar.gz.asc 可用。

报告错误

有 跟踪器，但也可以参考下面的列表。

贡献

将补丁以内联形式、附件形式或通过 git 链接发送到 列表（~nabijaczleweli/[email protected]）或直接发送给我。我不会挑剔，但请在主题前缀中包含存储库名称。

讨论

请使用跟踪器、列表或 mastussy（以前是 Twitter）。

特别感谢

感谢所有在 Patreon 上支持进一步开发的人，特别是

  • ThePhD
  • Embark Studios
  • Lars Strojny
  • EvModder

依赖项

~91KB