{"id":21707795,"url":"https://github.com/flightaware/tclgdb","last_synced_at":"2025-03-20T17:22:25.841Z","repository":{"id":66872758,"uuid":"94104455","full_name":"flightaware/tclgdb","owner":"flightaware","description":"Use gdb breakpoints for Tcl source with Tcl_CreateTrace","archived":false,"fork":false,"pushed_at":"2018-10-24T23:00:56.000Z","size":76,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":20,"default_branch":"master","last_synced_at":"2023-04-18T10:34:09.966Z","etag":null,"topics":["gdb","tcl-internals"],"latest_commit_sha":null,"homepage":null,"language":"M4","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flightaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2017-06-12T14:18:31.000Z","updated_at":"2023-04-18T10:34:09.966Z","dependencies_parsed_at":"2023-02-23T10:46:10.660Z","dependency_job_id":null,"html_url":"https://github.com/flightaware/tclgdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flightaware%2Ftclgdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flightaware%2Ftclgdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flightaware%2Ftclgdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flightaware%2Ftclgdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flightaware","download_url":"https://codeload.github.com/flightaware/tclgdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244657084,"owners_count":20488714,"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":["gdb","tcl-internals"],"created_at":"2024-11-25T22:19:17.692Z","updated_at":"2025-03-20T17:22:25.821Z","avatar_url":"https://github.com/flightaware.png","language":"M4","funding_links":[],"categories":[],"sub_categories":[],"readme":"tclgdb - helpers for using gdb and tcl together for debugging\n===\n\ntclgdb is a Tcl cmdtrace handler in C.  This allows one to set a breakpoint on\ntclgdb_cmdstep and step the Tcl interpreter while in gdb.\n\n[How to install](INSTALL.md)\n\nUsing with truss or strace\n----------------\nAdd the command trace to your TCL program and start it. This will have the overhead of the Tclx cmdtrace. Your program will be slower.\n```\npackage require tclgdb\n::tclgdb::tclgdb\n```\nInside your TCL process the trace is writing to file descriptor -1.  That is an intentional error.  But we can get the trace data out of the running\nprocess with ```truss``` on BSD or ```strace``` on Linux.\n\nYou only need the ```write(-1,``` trace from the truss.  An example looks like this:\n\n```\n0.000078469 write(-1,\"15: @@ proc=my_scan,pLn=0,path=unknown @@ incr count\",67) ERR#9 'Bad file descriptor'\n0.000199850 write(-1,\"15: @@ proc=my_scan,pLn=0,path=unknown @@ compile_user $trigger(user_id)\",111) ERR#9 'Bad file descriptor'\n0.000271614 write(-1,\"16: @@ proc=compile_user,pLn=0,path=unknown @@ if {[info exists ::cache($userID)]} {\\n\\t\\treturn $::cache($userID)\\n\\t}\",152) ERR#9 'Bad file descriptor'\n```\n\nFor truss you should add \"-d\" for timestamps. Also add \"-s \u003cN\u003e\" to expand the reported arguments. Note that truss writes on stderr not stdout.\n```\ntruss -d -s 500 -p \u003cpid\u003e 2\u003etruss.out\n```\nYou can control-C the truss when you think that you have collected enough data.\n\nOnce you have generated the truss output, then you can convert that file into a viewable heatmap or interactive viewer.\nSee [viewing with traceevent](traceevent/README.md).  Or you can simply use the output from truss.\n\ngdb debugger Usage\n------------------\n```\npackage require tclgdb\n\n::tclgdb::tclgdb\n```\nThen in gdb set a breakpoint on tclgdb_cmdstep.\n\nExample\n-------\n```\n$ gdb /usr/local/bin/tclsh8.6\nGNU gdb 6.1.1 [FreeBSD]\nCopyright 2004 Free Software Foundation, Inc.\nGDB is free software, covered by the GNU General Public License, and you are\nwelcome to change it and/or distribute copies of it under certain conditions.\nType \"show copying\" to see the conditions.\nThere is absolutely no warranty for GDB.  Type \"show warranty\" for details.\nThis GDB was configured as \"amd64-marcel-freebsd\"...\n(gdb) break tclgdb_cmdstep\nFunction \"tclgdb_cmdstep\" not defined.\nMake breakpoint pending on future shared library load? (y or [n]) y\nBreakpoint 1 (tclgdb_cmdstep) pending.\n(gdb) run tests/simple.tcl\nStarting program: /usr/local/bin/tclsh8.6 tests/simple.tcl\n[New LWP 100889]\n[New Thread 802006400 (LWP 100889/tclsh8.6)]\nBreakpoint 2 at 0x8018856b0: file ./generic/tclgdb.c, line 39.\nPending breakpoint \"tclgdb_cmdstep\" resolved\n[Switching to Thread 802006400 (LWP 100889/tclsh8.6)]\n\nBreakpoint 2, tclgdb_cmdstep (clientData=0x801a85f80, interp=0x802031010, level=1, command=0x80203e460 \"while {1} {\\n\\tafter 500\\n    set val1 0\\n\\tset done $val1\\n}\", \n    cmdProc=0x800a4ab20 \u003cTclInvokeObjectCommand\u003e, cmdClientData=0x802031a10, argc=3, argv=0x80203e4a0) at ./generic/tclgdb.c:39\n39\t\tstrncpy(buffer, s, sizeof(buffer)-1);\n(gdb) p command\n$1 = 0x80203e460 \"while {1} {\\n\\tafter 500\\n    set val1 0\\n\\tset done $val1\\n}\"\n(gdb) cont\nContinuing.\n\nBreakpoint 2, tclgdb_cmdstep (clientData=0x801a85f80, interp=0x802031010, level=2, command=0x80203e4f0 \"after 500\", cmdProc=0x800a4ab20 \u003cTclInvokeObjectCommand\u003e, \n    cmdClientData=0x802031d10, argc=2, argv=0x80203e510) at ./generic/tclgdb.c:39\n39\t\tstrncpy(buffer, s, sizeof(buffer)-1);\n(gdb) p command\n$2 = 0x80203e4f0 \"after 500\"\n(gdb) cont\nContinuing.\n\nBreakpoint 2, tclgdb_cmdstep (clientData=0x801a85f80, interp=0x802031010, level=2, command=0x80203e4f0 \"set val1 0\", cmdProc=0x800a4ab20 \u003cTclInvokeObjectCommand\u003e, \n    cmdClientData=0x802026710, argc=3, argv=0x80203e510) at ./generic/tclgdb.c:39\n39\t\tstrncpy(buffer, s, sizeof(buffer)-1);\n(gdb) p command\n$3 = 0x80203e4f0 \"set val1 0\"\n(gdb) cont\nContinuing.\n\nBreakpoint 2, tclgdb_cmdstep (clientData=0x801a85f80, interp=0x802031010, level=2, command=0x80203e4f0 \"set done $val1\", cmdProc=0x800a4ab20 \u003cTclInvokeObjectCommand\u003e, \n    cmdClientData=0x802026710, argc=3, argv=0x80203e510) at ./generic/tclgdb.c:39\n39\t\tstrncpy(buffer, s, sizeof(buffer)-1);\n(gdb) p command\n$4 = 0x80203e4f0 \"set done $val1\"\n```\n\nFuture Work\n--------\nOne goal will be to incorporate the Unicorn engine, http://www.unicorn-engine.org.  With Unicorn's virtual machine we can run diagnostic Tcl without affecting the Tcl interpreter.\nFor example, if you call ```print Tcl_GetString(argv[2])``` then one may cause a Tcl alloc or string creation in the representation.\nUsing the Unicorn interpreter, we can call Tcl interpreter code without changing the debug target.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflightaware%2Ftclgdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflightaware%2Ftclgdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflightaware%2Ftclgdb/lists"}