libMmkDebugStack

A cross-platform library for simple callstack tracing with C89 and C++03 public APIs.

Requires a C++11 compiler to build.

Possible Use Cases

Fancy assertion or logging macros
Automatic tracing for bug database submission (JIRA, Sentry.IO, etc.)
Stack traces for leaked allocations or refcounting

Compatability

Tested OS	Compiler	SDK	Unwind Impl	Symbols Impl
Windows 7	VS2015 u1		DbgHelp	DbgHelp
Android 5.0	GCC 4.9	nVidia Codeworks 1R4	libunwind	Custom elf/dwarf parser
Android 5.0	Clang 3.6	Microsoft's Android SDK	__builtin_return_address	Custom elf/dwarf parser
Ubuntu 16.10	Clang 3.8.1		None (noop/fallback)	None
Ubuntu 16.10	GCC 6.2.0		None (noop/fallback)	None

Other C++11 capable platforms/compilers should at least be able to use the Fallback implementation, feel free to file an issue if they don't!

Example

#include <mmk/debug/stack.h> // mmkDebugStackCurrentThread etc.
#include <stdio.h>           // printf
#include <string.h>

#define NO_INLINE   ZMMK_DEBUG_STACK_NO_INLINE // Note: ZMMK_* isn't part of the public API

const char* nameOnly(const char* filename) {
	if (const char* bs = strrchr(filename, '\\')) return bs+1;
	if (const char* fs = strrchr(filename, '/'))  return fs+1;
	return filename;
}

#define TRACE() (void)(printf("Trace:\n"),   mmk::debug::stackCurrentThread(mmkDebugStackResolveAll, 0, 25, \
    [](const mmk::debug::stackFunction& f) {                                                                \
        printf("    %s(%d): %s @ %p\n", nameOnly(f.file), f.line, f.name, f.address);                       \
        return true; /* continue trace */                                                                   \
    }, MMK_DEBUG_STACK_HINT()),   printf("\n\n\n"),   0)

NO_INLINE void test_trace() { TRACE(); }
template < size_t N > struct recursive { NO_INLINE static void test_trace() { recursive<N-1>::test_trace(); } };
template <>        struct recursive<0> { NO_INLINE static void test_trace() { ::test_trace(); } };

int main()
{
	recursive<10>::test_trace();
}

Resulting Debug|x86 Console:

Trace:
    main.cpp(19): test_trace @ 013B2C76
    main.cpp(21): recursive<0>::test_trace @ 013B2C03
    main.cpp(20): recursive<1>::test_trace @ 013B28E3
    main.cpp(20): recursive<2>::test_trace @ 013B2933
    main.cpp(20): recursive<3>::test_trace @ 013B2983
    main.cpp(20): recursive<4>::test_trace @ 013B29D3
    main.cpp(20): recursive<5>::test_trace @ 013B2A23
    main.cpp(20): recursive<6>::test_trace @ 013B2A73
    main.cpp(20): recursive<7>::test_trace @ 013B2AC3
    main.cpp(20): recursive<8>::test_trace @ 013B2B13
    main.cpp(20): recursive<9>::test_trace @ 013B2B63
    main.cpp(20): recursive<10>::test_trace @ 013B2BB3
    main.cpp(26): main @ 013B2DB3
    exe_common.inl(74): invoke_main @ 013B6B4E
    exe_common.inl(264): __scrt_common_main_seh @ 013B699A
    exe_common.inl(309): __scrt_common_main @ 013B682D
    exe_main.cpp(17): mainCRTStartup @ 013B6B68
    <unknown>(0): BaseThreadInitThunk @ 76F3336A
    <unknown>(0): RtlInitializeExceptionChain @ 77C39902
    <unknown>(0): RtlInitializeExceptionChain @ 77C398D5

More examples:

mmkDebugStackTest (c++)
mmkNvidiaCodeworksTest (java, c++)
mmkAndroidTest (java, c++)

Installation

NuGet

Add libMmkDebugStack to your project via nuget. Done!

From Source (on Windows development machine)

Clone the repository
Use libMmkDebugStack.sln to build libMmkDebugStack.lib in the configurations/platforms of your choice.
Add HAS_MMK_DEBUG_STACK to your preprocessor definitions.
Add libMmkDebugStack\include\ to your #include paths.
Targeting Windows:
- Add build\native\lib\$(PlatformTarget)\$(PlatformToolset)\$(Configuration)\ to your library paths
- Add libMmkDebugStack.lib and DbgHelp.lib to your additional dependencies list.
Targeting Android via the nVidia Codeworks for Android 1R4 SDK:
- Add build\native\lib\$(ArchAbi)\$(ToolchainIdentifier)\$(Configuration)\ to your library paths
- Add MmkDebugStack to your additional dependencies list.
Targeting Android via the Microsoft Android SDK:
- Add build\native\lib\$(Platform)\$(PlatformToolset)\$(Configuration)\ to your library paths
- Add -lMmkDebugStack to your additional dependencies list.

From Source (on Linux development machine)

Clone the repository
Run make
Add -DHAS_MMK_DEBUG_STACK to your CCFLAGS
Add -Lbin/$(compiler)-$(arch)-$(build)-$(language)/ to your LDFLAGS
Add -lMmkDebugStack to your LDFLAGS
Add bin/$(compiler)-$(arch)-$(build)-$(language)/ to your LD_LIBRARY_PATH

TODO

Add option to use separate debugger process for stability / collecting stacks of foreign threads
Backport to C++03 for wider compatability
Properly port to Linux, OS X, iOS
Port to Consoles, Handhelds, etc. (Blocker: Devkit access)
Add Windows CDB backend for possible stability improvements, multi-thread stacks, crash dump analysis, etc.

MaulingMonkey / libMmkDebugStack