diff --git a/docs/README.md b/docs/README.md index 4e514bdb8..0942f1fe2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,7 @@ Install Crystal and get it running. Introductory courses for beginners and advanced learners. * [Basics](tutorials/basics/README.md) +* [Debugging](tutorials/debugging/README.md)
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 62dd28f32..a8bda07a1 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -143,3 +143,6 @@ * [Strings](tutorials/basics/40_strings.md) * [Control Flow](tutorials/basics/50_control_flow.md) * [Methods](tutorials/basics/60_methods.md) + * [Debugging](tutorials/debugging/README.md) + * [Debuggers](tutorials/debugging/10_debuggers.md) + * [Caveats](tutorials/debugging/20_caveats.md) diff --git a/docs/tutorials/debugging/10_debuggers.md b/docs/tutorials/debugging/10_debuggers.md new file mode 100644 index 000000000..9af27cea7 --- /dev/null +++ b/docs/tutorials/debugging/10_debuggers.md @@ -0,0 +1,6 @@ +# Debuggers + +## Tools + +* [GDB](https://www.sourceware.org/gdb/) +* [LLDB](https://lldb.llvm.org/) diff --git a/docs/tutorials/debugging/20_caveats.md b/docs/tutorials/debugging/20_caveats.md new file mode 100644 index 000000000..f8f1b9b68 --- /dev/null +++ b/docs/tutorials/debugging/20_caveats.md @@ -0,0 +1,19 @@ +# Caveats + +## Segmentation Fault During GC Initialization + +It is generally safe to ignore `SIGSEGV` during startup of a Crystal program. This is intended behavior; see the [Debugging](https://hboehm.info/gc/debugging.html) documentation of Crystal's [GC library](https://hboehm.info/gc/). + +### Mitigation + +Automatically ignore this segmentation fault with breakpoints: + + + +#### LLDB + + +``` +breakpoint set -n main -G true -o true -C 'process handle -s false -n false SIGSEGV SIGBUS' +breakpoint set -n __crystal_main -G true -o true -C 'process handle -s true -n true SIGSEGV SIGBUS' +``` diff --git a/docs/tutorials/debugging/README.md b/docs/tutorials/debugging/README.md new file mode 100644 index 000000000..4b6a5591a --- /dev/null +++ b/docs/tutorials/debugging/README.md @@ -0,0 +1,8 @@ +# Debugging + +This course targets experienced Crystal programmers and discusses common tools and methods to debug your Crystal code. + +Contents: + +* [Debuggers](10_debuggers.md) – Introduction to common debugging tools compatible with Crystal +* [Caveats](20_caveats.md) – Gotchas and limitations when debugging Crystal code \ No newline at end of file