{"id":16987384,"url":"https://github.com/mchalupa/wldbg","last_synced_at":"2025-03-22T15:30:51.478Z","repository":{"id":19465861,"uuid":"22710637","full_name":"mchalupa/wldbg","owner":"mchalupa","description":"Capture and debug/modify Wayland connections","archived":false,"fork":false,"pushed_at":"2023-10-31T16:46:42.000Z","size":443,"stargazers_count":41,"open_issues_count":20,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-18T13:15:21.693Z","etag":null,"topics":["wayland","wayland-protocol"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mchalupa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-07T06:13:19.000Z","updated_at":"2025-02-18T09:20:29.000Z","dependencies_parsed_at":"2024-10-28T13:23:27.387Z","dependency_job_id":"f2453bc9-7889-4cff-a186-84863fc0b05e","html_url":"https://github.com/mchalupa/wldbg","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalupa%2Fwldbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalupa%2Fwldbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalupa%2Fwldbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mchalupa%2Fwldbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mchalupa","download_url":"https://codeload.github.com/mchalupa/wldbg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244978450,"owners_count":20541858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wayland","wayland-protocol"],"created_at":"2024-10-14T02:49:19.544Z","updated_at":"2025-03-22T15:30:51.064Z","avatar_url":"https://github.com/mchalupa.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"###  What is wldbg?\n\nWldbg is a tool that allows you to debug or modify events in\nWayland connections. It works on the man-in-the-middle basis.\nWhen a Wayland client is run under wldbg, every message to or\nfrom the client is handed out to a pipeline of passes that can\nprocess the message. Passes are simple-to-write plugins.\nWldbg has also an interactive gdb-like mode.\n\n### What is a pass?\n\nThe passes in wldbg are inspired by LLVM passes.\nA pass is a plugin that defines two functions - one for\nmessages going from the client to the server and the another for\nmessages from server to the client.\nIt can analyze or arbitriraly modify the message and\nthen pass the message to the next pass (or stop the whole pipeline)\nand so on..\n\n### Using passes\n\nRun wldbg with passes is very easy, just type on command-line:\n\n```\n  $ wldbg pass1 ARGUMENTS, pass2 ARGUMENTS -- wayland-client\n```\n\npass1 and pass2 are names of the passes without .so extension\n(i. e. dump.so ~~\u003e dump)\n\nIf you do not know what passes are available, use:\n\n```\n  $ wldbg list\n```\n\nTo get better understanding how it works, there's an example pass\nin `passes/example.c`. This pass is also compiled by default, so\nyou can try it out as follows:\n\n```\n  $ wldbg example -- wayland_client\n```\n\n### Using the interactive mode\n\nTo run wldbg in the interactive mode, just do:\n\n```\n  $ wldbg -i wayland-client\n```\n\nIf everything goes well, you'll see:\n\n```\n  Stopped on the first message\n  C: wl_display@1.get_registry(new id wl_registry@2)\n  (wldbg)\n```\n\nwldbg is now waiting for your input. By typing 'c' or 'continue', the program\nwill continue running. Other usefull commands are:\n\n```\n'help'                    -- show help message\n'help COMMAND'            -- show help to COMMAND\n'b' or 'break'            -- stop running on specified messages\n    b id 10                   --\u003e stop on messages with id 10\n    b re REGEXP               --\u003e stop on any message matching regexp)\n'i' or 'info'             -- show information about running state\n    i b(reakpoints)           --\u003e info about breakpoints\n    i objects                 --\u003e info about objects\n    i proc                    --\u003e info about process\n'autocmd'                 -- run command after messages of intereset\n    autocmd add RE CMD        --\u003e run CMD on every message matching RE\n    autocmd add '' i o        --\u003e display info about objects after every message\n'h' or 'hide              -- hide specified messages matching REGEXP, e. g.:\n    h wl_pointer.*            --\u003e hide everything for/from wl_pointer\n    h wl_display@.*done       --\u003e hide done messages from wl_display\n'so' or 'showonly'        -- show only messages matching REGEXP\n    so wl_display.*done       --\u003e show only wl_display.done event\n's' or 'send'             -- send message to client/server (in wire format)\n'e' or 'edit'             -- edit message that we stopped at\n'q' or 'quit'             -- exit wldbg\n```\n\nWhen wldbg is run with -g (-objinfo) option, it gathers information about objects.\nUser then can just type:\n\n```\n(wldbg) i o ID\n```\n\nwhere ID is the id of the object of interest and wldbg will dump information\nit gathered about it. NOTE: this is new and incomplete feature. At this\nmoment wldbg gathers information about xdg_surface, wl_surface and wl_buffer objects.\n\nCtrl-C interrupts the program and prompts user for input.\n\n### Using server mode\n\nWldbg can run in the server mode in which every new connection is redirected to wldbg and\nonly then to the Wayland compositor. Upon the first connection, the user is prompted for an action,\nevery other connection is then connected automatically without stopping.\nThe server mode is interactive, so everything that works in the interactive mode,\nworks in the server mode too. To start wldbg in the server mode, use the -s switch:\n\n```\n$ wldbg -s\nListening for incoming connections...\n```\n\nwhen client connects, you'll see something like:\n\n```\nStopped on the first message\n[weston-terminal: 7874] C: wl_display@1.get_registry(new id wl_registry@2)\n```\n\nAfter another client is connected, the messages from both are just interleaved:\n\n```\n[weston-terminal |7874] S: wl_pointer@3.motion(2739198098, 197.000000, 142.000000)\n[weston-terminal |7874] S: wl_pointer@3.frame()\n[weston-dnd      |7930] S: wl_buffer@38.release()\n[weston-dnd      |7930] S: wl_pointer@3.leave(166, wl_surface@14)\n[weston-dnd      |7930] S: wl_pointer@3.frame()\n[weston-terminal |7874] C: wl_surface@10.attach(wl_buffer@17, 0, 0)\n[weston-terminal |7874] C: wl_surface@10.damage(0, 0, 9, 16)\n[weston-terminal |7874] C: wl_surface@10.commit()\n```\n\nServer mode is handy, for example, for debugging the interaction between two clients,\nlike two weston-dnd instances dragging and dropping between them.\n\n----------------------\n\nAn active development of Wldbg stopped some years ago, but it still should work.\nThere are features missing and probably some bugs, but the features described above\nshould mostly work.\n\nAuthor: Marek Chalupa \u003cmchqwerty@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchalupa%2Fwldbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmchalupa%2Fwldbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmchalupa%2Fwldbg/lists"}