Package: febug
febuganyway, here's user-space debugfsDebian  manpages(PDF)FreeBSD manpages(PDF)NetBSD  manpages(PDF)OpenBSD manpages(PDF)MacOS   manpages(PDF)Library rustdocWhat?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/
1410How?UNIX-domain SOCK_SEQPACKET (or SOCK_STREAM, if not available) at[/var]/run/febug.sockby default, with a corresponding mount at[/var]/run/febugDebuggable client connectsWhen credentials are available, a directory appears, à la procfsWhen client wants a variable debugged it sends afebug_message(variable_id,variable_type,signal, andname(seefebug-abi.h)) –namegets a file under the directoryOnopen()of the file, the client is sent anattn_febug_message(variable_idandvariable_type) and the write end of a pipe and (ifsignalwasn'tSIGKILL) notifiedread()s copy directly from the corresponding end of the pipe – the clientmustclose()it by the time it returns from the signal handler (or, if using some other mechanism, when otherwise done representing)When the variable goes out of scope, the client sends astop_febug_message(variable_id) to deregister, disappearing the fileWhen client hangs up, its directory disappearsOr, perhaps (server is box, program is oval, user is trapezium):BuildingFor a Linux system:installlibfuse3-dev,pkg-config, andmandocmakeFor FreeBSD:installgmake,fusefs-libs3, andpkgconfgmakeFor NetBSD:installdevel/gmakegmake LTO=nFor OpenBSD:installgmakegmake CXX=c++ LTO=nFor the Macintosh:install macFUSE and mandocmakeFor other platforms:ports welcome!To build the Rust crate, its examples, and documentation, installcargo/rust/lang/rust[-bin]/rustand run[g]make rust-build rust-doc,
but that is irrelevant to the casual builder.The Python package can be installed by either copyingfebug.pyto the PYTHONPATH,
or by running[g]make python-build(this requires python3) and installing packages out ofout/febug.py/dist/.dot(1) from graphviz is also needed to regenerate the diagram. though that itself is optional.(End-user-visible) platform differencesWhen 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.RunningFor a system-wide instance, runfebug /run/febug/ &(or/var/run/febug/, or wherever else, as the case may be) as root.To run a user-local instance, thefusermount3helper is required, andexport FEBUG_SOCKET=/run/user/$(id -u)/febug.sockfollowed byfebug /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 inout/examples/, which sort with sleeps in comparison functions, for how they operate.InstallationFrom Debian repositoryThe following line in/etc/apt/sources.listor equivalent:deb [signed-by=/etc/apt/keyrings/nabijaczleweli.asc] https://debian.nabijaczleweli.xyz sid mainWithmy PGP key(the two URLs are interchangeable):sudowget-O/etc/apt/keyrings/nabijaczleweli.aschttps://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key
sudowget-O/etc/apt/keyrings/nabijaczleweli.aschttps://nabijaczleweli.xyz/pgp.txt(you may need to create /etc/apt/keyrings on apt <2.4.0 (<=bullseye) manually).Then the usualsudoaptupdate
sudoaptinstallfebuglibfebug0libfebug-devlibfebug++-devwill work on amd64, x32, and i386.See therepository READMEorthe source packagefor more information.From pkgsrcgitclonehttps://git.sr.ht/~nabijaczleweli/febug-pkgsrc/usr/pkgsrc/devel/febug# or, indeed, where-ever the pkgsrc root isAndmake installunderdevel/febugwill work out-of-box on NetBSD and OpenBSD, but will needpkg install fusefs-libs3on FreeBSD.From tar-ballRelease tarballs are signed withnabijaczleweli@nabijaczleweli.xyz(pull with WKD, but7D69 474E 8402 8C5C C0C4  4163 BCFD 0B01 8D26 58F1).
аnd stored in git notes as-if viathe example programand are thus available on therefs listing/tag page as .tar.gz.asc.Reporting bugsThere'sthe tracker, but also see the list below.ContributingSend a patch inline, as an attachment, or a git link and a ref to pull from tothe list(~nabijaczleweli/febug@lists.sr.ht) ormedirectly. I'm not picky, just please include the repo name in the subject prefix.DiscussionPlease use the tracker, the list, ormastussy(formerlyTwitter).Special thanksTo all who support further development on Patreon, in particular:ThePhDEmbark StudiosLars StrojnyEvModder