This directory contains comprehensive guides for debugging and troubleshooting libnd4j, particularly focusing on crashes, hangs, and build-related issues.

Available Documentation

1. Build Debugging Flags (README.md)

Covers the core debugging build flags for libnd4j including:

libnd4j.calltrace for function call tracing
libnd4j.printmath for debugging numerical operations
libnd4j.printindices for array bounds checking
Build configuration examples and usage scenarios

2. Process Hang Troubleshooting (TROUBLESHOOTING_HANGS.md)

Comprehensive guide for debugging hanging Java processes, including:

Using GDB with ptrace and direct process attachment
Valgrind integration with test suite
Address Sanitizer (ASAN) configuration and usage
CUDA Compute Sanitizer for GPU code
Best practices and common issues

3. Preprocessor Debugging (PREPROCESSOR_DEBUGGING.md)

Detailed guide for using the preprocessor debugging capabilities:

Using libnd4j.preprocess flag
Understanding preprocessor output
Debugging macro expansions
Troubleshooting include paths and dependencies
Tips for handling large codebases

Quick Start

For Build Issues:

# Enable all debugging flags
mvn -Dlibnd4j.calltrace=ON -Dlibnd4j.printmath=ON -Dlibnd4j.printindices=ON clean install

For Process Hangs:

# Attach to hanging process
sudo gdb -p <process-id>
thread apply all bt

For Macro Issues:

# Generate preprocessor output
mvn clean install -Dlibnd4j.preprocess=ON

Common Use Cases

Debugging Crashes
- Start with build flags from README.md
- Use generated debug information with GDB
Investigating Hangs
- Follow TROUBLESHOOTING_HANGS.md
- Use appropriate tool based on symptom (GDB, Valgrind, ASAN)
Build/Macro Problems
- Use PREPROCESSOR_DEBUGGING.md
- Examine preprocessor output for issues

Contributing

When adding new troubleshooting documentation:

Create a focused markdown file for the specific topic
Update this README.md with a summary
Include practical examples and command-line instructions
Add cross-references to related documentation