https://github.com/yazd/backtrace-d

backtrace-d provides a pretty backtrace for D applications running under Linux
https://github.com/yazd/backtrace-d

Last synced: about 1 month ago
JSON representation

backtrace-d provides a pretty backtrace for D applications running under Linux

• Host: GitHub
• URL: https://github.com/yazd/backtrace-d
• Owner: yazd
• License: bsl-1.0
• Created: 2013-11-07T12:14:15.000Z (about 11 years ago)
• Default Branch: master
• Last Pushed: 2018-05-10T13:53:55.000Z (over 6 years ago)
• Last Synced: 2024-07-03T04:07:04.415Z (5 months ago)
• Language: D
• Size: 15.6 KB
• Stars: 40
• Watchers: 4
• Forks: 5
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

• awesome-jordan - backtrace-d - backtrace-d provides a pretty backtrace for D applications running under Linux. (D)

README

        
backtrace-d

===========

backtrace-d is a library that provides a pretty backtrace for D applications

running under Linux. Its usage is very simple, you'll only need to import the

module `backtrace.backtrace` and call `printPrettyTrace`. Also, make sure that

you compile with debug symbols on. On DMD, for example, use the -g flag.

backtrace-d was tested using DMD 2.063.2 and LDC2 0.12.0.

You can also try the experimental `install` call to make backtraces showing on

exceptions beautiful. This works using DMD compiled applications only for now.

Example on using `printPrettyTrace`

-----------------------------------

    import backtrace;

    import std.stdio;

    void main() {

      goToF1();

    }

    void goToF1() {

      goToF2();

    }

    void goToF2(uint i = 0) {

      if (i == 2) {

        printPrettyTrace(stderr); return;

      }

      goToF2(++i);

    }

This will print the following to the standard error:

    Stack trace:

    #1: /path/to/source/app.d line (14) in void app.goToF2(uint)

     (11)

     (12)     void goToF2(uint i = 0) {

     (13)       if (i == 2) {

    >(14)         printPrettyTrace(stderr); return;

     (15)       }

     (16)       goToF2(++i);

     (17)     }

    #2: /path/to/source/app.d line (17) in void app.goToF2(uint)

     (14)         printPrettyTrace(stderr); return;

     (15)       }

     (16)       goToF2(++i);

    >(17)     }

    #3: /path/to/source/app.d line (17) in void app.goToF2(uint)

    #4: /path/to/source/app.d line (10) in void app.goToF1()

    #5: /path/to/source/app.d line (5) in _Dmain

Example on using `install` (DMD only)

-------------------------------------

    static import backtrace;

    import std.stdio;

    void main() {

      backtrace.install(stderr);

      goToF1();

    }

    void goToF1() {

      goToF2();

    }

    void goToF2(uint i = 0) {

      if (i == 2) throw new Exception("Exception thrown");

      goToF2(++i);

    }

This will print the following to the standard error:

    object.Exception@source/app.d(15): Exception thrown

    ----------------

    Stack trace:

    #1: /path/to/source/app.d line (16) in void app.goToF2(uint)

     (13)

     (14) void goToF2(uint i = 0) {

     (15)   if (i == 2) throw new Exception("Exception thrown");

    >(16)   goToF2(++i);

     (17) }

    #2: /path/to/source/app.d line (17) in void app.goToF2(uint)

     (14) void goToF2(uint i = 0) {

     (15)   if (i == 2) throw new Exception("Exception thrown");

     (16)   goToF2(++i);

    >(17) }

    #3: /path/to/source/app.d line (17) in void app.goToF2(uint)

    #4: /path/to/source/app.d line (12) in void app.goToF1()

    #5: /path/to/source/app.d line (7) in _Dmain

    ----------------

You can customize the way the backtrace is printed using the following options:

    PrintOptions options;

    options.detailedForN = 2;        //number of frames to show code for

    options.numberOfLinesBefore = 3; //number of lines of code to show before the specific line

    options.numberOfLinesAfter  = 3; //number of lines of code to show after the specific line

    options.colored = true;          //enable colored output for the backtrace

    options.stopAtDMain = false;     //show stack traces after the entry point of the D code

    printPrettyTrace(stdout, options);

Documentation

-------------

    //prints the backtrace to `output` using the printing `options` provided. Frames to skip is used to

    //skip frames that belong to the internal code of the library. You might need to change this depending

    //on the optimization level of your compiler

    void printPrettyTrace(File output, PrintOptions options = PrintOptions.init, uint framesToSkip = 1)

    //install the runtime trace handler to print the backtraces

    void install(File file, PrintOptions options = PrintOptions.init, uint framesToSkip = 6)

    //returns an array of backtrace addresses

    void*[] getBacktrace()

    //returns an array of symbols provided an array of addresses

    Symbol[] getBacktraceSymbols(const(void*[]) backtrace)

    //returns an array of lines and files corresponding to the addresses provided

    //this uses `addr2line` tool internally

    Trace[] getLineTrace(const(void*[]) backtrace)

Work to do and bugs

-------------------

- Inaccurate address to line resolving.

 - Problem could reside in the debug symbols emitted by the compilers or the code that produces backtrace addresses.

- Integrate the library with `Runtime.traceHandler` (work in progress)

 - Only works under DMD for now.

Feedback and pull requests

--------------------------

Please use Github's issue tracker. I'm also open to pull and feature requests.