~nabijaczleweli/febug

anyway, here's user-space debugfs
We've got more than two examples nowadays
environment debugged programs' environment
Fix tweet link

clone

read-only
https://git.sr.ht/~nabijaczleweli/febug
read/write
git@git.sr.ht:~nabijaczleweli/febug

You can also use your local clone with git send-email.

#febug builds.sr.ht badge Licence

anyway, here's user-space debugfs

#Debian manpages

#FreeBSD manpages

#NetBSD manpages

#OpenBSD manpages

#MacOS manpages

#Library rustdoc

#What?

Co-operative (between the program and you) debugging:

# 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

#How?

  1. UNIX-domain SOCK_SEQPACKET (or SOCK_STREAM, if not available) at [/var]/run/febug.sock by default, with a corresponding mount at [/var]/run/febug
  2. Debuggable client connects
  3. When credentials are available, a directory appears, à la procfs
  4. When client wants a variable debugged it sends a febug_message (variable_id, variable_type, signal, and name (see febug-abi.h)) – name gets a file under the directory
  5. On open() of the file, the client is sent an attn_febug_message (variable_id and variable_type) and the write end of a pipe and (if signal wasn't SIGKILL) notified
  6. read()s copy directly from the corresponding end of the pipe – the client must close() it by the time it returns from the signal handler (or, if using some other mechanism, when otherwise done representing)
  7. When the variable goes out of scope, the client sends a stop_febug_message (variable_id) to deregister, disappearing the file
  8. When client hangs up, its directory disappears

Or, perhaps (server is box, program is oval, user is trapezium): graphviz diagram

#Building

For a Linux system: builds.sr.ht status for sid

  • install libfuse3-dev, pkg-config, and mandoc
  • make

For FreeBSD: builds.sr.ht status for latest FreeBSD

  • install gmake, fusefs-libs3, and pkgconf
  • gmake

For NetBSD:

  • install devel/gmake
  • gmake LTO=n

For OpenBSD: builds.sr.ht status for latest OpenBSD

  • install gmake
  • gmake CXX=c++ LTO=n

For the Macintosh:

  • install macFUSE and mandoc
  • make

For other platforms:

  • ports welcome!

To build the Rust crate, its examples, and documentation, install cargo/rust/lang/rust[-bin]/rust and run [g]make rust-build rust-doc, but that is irrelevant to the casual builder.

dot(1) from graphviz is also needed to regenerate the diagram. though that itself is optional.

#(End-user-visible) platform differences

When built for Linux, the default socket path is /run/febug.sock, otherwise it's /var/run/febug.sock.

On OpenBSD and Darwin the processes are authenticated by their effective UID/GID/PID.

Darwin doesn't support SOCK_SEQPACKET, SOCK_STREAM is used instead.

#Running

For a system-wide instance, run febug /run/febug/ & (or /var/run/febug/, or wherever else, as the case may be) as root.

To run a user-local instance, the fusermount3 helper is required, and export FEBUG_SOCKET=/run/user/$(id -u)/febug.sock followed by febug /run/user/$(id -u)/febug/ & should work for programs using libfebug and libfebug++; programs using a different ABI wrapper are encouraged to respect this environment variable as well.

init/ contains systemd units for these two use-cases (though that path has to be set manually in the debugged programs' environment), FreeBSD/NetBSD and OpenBSD rc.d scripts for the global one.

See the files in out/examples/, which sort with sleeps in comparison functions, for how they operate.

#Installation

#From Debian repository

The following line in /etc/apt/sources.list or equivalent:

deb https://debian.nabijaczleweli.xyz sid main

With my PGP key (the two URLs are interchangeable):

wget -O- https://keybase.io/nabijaczleweli/pgp_keys.asc | sudo apt-key add
# or
sudo wget -O/etc/apt/trusted.gpg.d/nabijaczleweli.asc https://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key

Then the usual

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

will work on amd64, x32, and i386.

See the repository README or the source package for more information.

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

And make install under devel/febug will work out-of-box on NetBSD and OpenBSD, but will need pkg install fusefs-libs3 on FreeBSD.

#Reporting bugs

There's the tracker, but also see the list below.

#Contributing

Send a patch inline, as an attachment, or a git link and a ref to pull from to the list (~nabijaczleweli/febug@lists.sr.ht) or me directly. I'm not picky, just please include the repo name in the subject prefix.

#Discussion

Please use the tracker, the list, or Twitter.

#Special thanks

To all who support further development on Patreon, in particular:

  • ThePhD
  • Embark Studios