{"id":19269481,"url":"https://github.com/status-im/nim-libbacktrace","last_synced_at":"2025-10-07T19:21:17.286Z","repository":{"id":37821059,"uuid":"228731803","full_name":"status-im/nim-libbacktrace","owner":"status-im","description":"Nim wrapper for libbacktrace","archived":false,"fork":false,"pushed_at":"2025-06-15T15:00:39.000Z","size":1443,"stargazers_count":21,"open_issues_count":3,"forks_count":4,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-06-26T08:46:54.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/status-im.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHEv2","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":"2019-12-18T01:24:21.000Z","updated_at":"2025-06-03T16:28:09.000Z","dependencies_parsed_at":"2024-03-03T01:25:15.904Z","dependency_job_id":"95296ac2-6b4a-4f0d-afcd-b6175afd31c0","html_url":"https://github.com/status-im/nim-libbacktrace","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/status-im/nim-libbacktrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/status-im%2Fnim-libbacktrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/status-im%2Fnim-libbacktrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/status-im%2Fnim-libbacktrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/status-im%2Fnim-libbacktrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/status-im","download_url":"https://codeload.github.com/status-im/nim-libbacktrace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/status-im%2Fnim-libbacktrace/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263166454,"owners_count":23424161,"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":[],"created_at":"2024-11-09T20:19:59.550Z","updated_at":"2025-10-07T19:21:17.178Z","avatar_url":"https://github.com/status-im.png","language":"C","readme":"# All the backtrace, none of the overhead\n\n![Github action](https://github.com/status-im/nim-libbacktrace/workflows/CI/badge.svg)\n[![License: Apache](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)\n\nNim's default stack tracing functionality comes with significant\noverhead, by adding `nimln_()`, `nimfr_()` calls all over the place. The\nproblem is being discussed upstream in [this GitHub\nissue](https://github.com/nim-lang/Nim/issues/12702).\n\nIn practice, you can get as much as 66% improved performance by disabling the\ndefault stack tracing: https://github.com/status-im/nimbus-eth2/pull/3466\n\nThat `popFrame()` at the end of each C function is particularly problematic,\nsince it prevents the C compiler from doing tail-call optimisations.\n\nThis is a lightweight alternative based on libbacktrace, meant to offer the\nsame stack traces without the runtime overhead.\n\nC++ function name demangling is supported using \"\\_\\_cxa\\_demangle()\".\n\n## Building \u0026 Testing\n\nThis project uses Git submodules, so get it with:\n\n```bash\ngit clone https://github.com/status-im/nim-libbacktrace.git\ncd nim-libbacktrace\ngit submodule update --init\n```\n\nYou build the library (or libraries, on macOS) with `make`. You test it with\n`make test`.\n\nNimble is grudgingly supported, so `nimble install` works. (No, we will not\nlet a silly package manager dictate our project's structure. People have the\npower!)\n\n## Supported platforms\n\nTested with GCC and LLVM on Linux, macOS and 64-bit Windows (with Mingw-w64 and\nthe MSYS that comes with \"Git for Windows\").\n\n## Usage\n\nbttest.nim:\n\n```nim\nimport libbacktrace\n\n# presumably in some procedure:\necho getBacktrace()\n\n# Should be the same output as writeStackTrace() - minus the header.\n```\n\nWe need debugging symbols in the binary and we can do without Nim's bloated and\nslow stack trace implementation:\n\n```bash\n# `-f` needed if you've changed nim-libbacktrace\nnim c -r --debugger:native --stacktrace:off bttest.nim\n```\n\nBy default, the Nim compiler passes \"-g3\" to the C compiler, with\n\"--debugger:native\", which almost doubles the resulting binary's size (only on\ndisk, not in memory). If we don't need to use GDB on that binary, we can get\naway with significantly fewer debugging symbols by switching to \"-g1\":\n\n```bash\n# for the C backend\nnim c -d:release --debugger:native --gcc.options.debug:'-g1' somefile.nim\n\n# for the C++ backend\nnim cpp -d:release --debugger:native --gcc.cpp.options.debug:'-g1' somefile.nim\n\n# Clang needs a different argument\nnim c -d:release --cc:clang --debugger:native --clang.options.debug:'-gline-tables-only' somefile.nim\n```\n\nWhen the C compiler inlines some functions, or does tail-call optimisation -\nusually with `-d:release` or `-d:danger` - your stack trace might be incomplete.\n\nIf that's a problem, you can use `--passC:\"-fno-inline -fno-optimize-sibling-calls\"`.\n\n### Two-step backtraces\n\nWhen you store backtraces in re-raised exceptions, you won't need to print them\nmost of the time, so it makes sense to delay the expensive part of debugging\ninfo collection until it's actually needed:\n\n```nim\nlet maxLength: cint = 128\n\n# Unwind the stack and get a seq of program counters - the fast step:\nlet programCounters = getProgramCounters(maxLength)\n\n# Later on, when you need to print these backtraces, get the debugging\n# info - the relatively slow step:\nlet entries = getDebuggingInfo(programCounters, maxLength)\n```\n\nIf you have multiple backtraces - and yo do with a re-raised exception - you\nshould pass subsets of program counters representing complete stack traces to\n`getDebuggingInfo()`, because there's some logic inside it that keeps track of\ncertain inlined functions in order to change the output\n\nYou may get more StackTraceEntry objects than the program counters you passed\nto `getDebuggingInfo()`, when you have inlined functions and the debugging\nformat knows about them (DWARF does).\n\n### Debugging\n\n`export NIM_LIBBACKTRACE_DEBUG=1` to see the trace lines hidden by default.\n\n### Nim compiler support\n\nNim 1.0.6 supports [replacing the default stack tracing mechanism with an\nexternal one](https://github.com/nim-lang/Nim/pull/12922).\n\nThis means you no longer have to call `getBacktrace()` yourself, if you compile\nyour program like this:\n\n`nim c -r --debugger:native --stacktrace:off -d:nimStackTraceOverride --import:libbacktrace foo.nim`\n\nYou can even use libbacktrace in the Nim compiler itself, by building it with:\n\n`./koch boot -d:release --debugger:native -d:nimStackTraceOverride --import:libbacktrace`\n\n(`-d:release` implies `--stacktrace:off`)\n\n## Dependencies\n\nYou need Make and Nim.\n\nThe other dependencies are bundled, for your convenience. We use a [libbacktrace\nfork](https://github.com/status-im/libbacktrace) with macOS support, and dynamically depend on the system's installed unwinder (libunwind / libSystem / libgcc\\_s.so.1).\n\nIf you know better and want to use your system's libbacktrace package instead\nof the bundled one, you can, with `make USE_SYSTEM_LIBS=1` and by passing\n`-d:libbacktraceUseSystemLibs` to the Nim compiler.\n\nIf you don't want to build the C++ wrapper, pass `BUILD_CXX_LIB=0` to Make.\n\nTo get the running binary's path in a cross-platform way, we rely on\n[whereami](https://github.com/gpakosz/whereami).\n\n## License\n\nLicensed and distributed under either of\n\n* MIT license: [LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT\n\nor\n\n* Apache License, Version 2.0, ([LICENSE-APACHEv2](LICENSE-APACHEv2) or http://www.apache.org/licenses/LICENSE-2.0)\n\nat your option. These files may not be copied, modified, or distributed except according to those terms.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatus-im%2Fnim-libbacktrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatus-im%2Fnim-libbacktrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatus-im%2Fnim-libbacktrace/lists"}