Simon Ford / debug

Debug library for instrumentation a.k.a printf debugging

Dependents:   pyrocommander Projektni_zadatak_Analogni_sat ProjetOctopode

You are viewing an older revision! See the latest version

Homepage

Table of Contents

  1. Draft library
  2. Usage

This page explores designing a debug library for instrumentation a.k.a printf debugging.

The aims are to address a few things:

  • Provide functions for instrumentation debugging that are simple and practical
  • Avoid people reinventing the wheel. Without a standard approach to debugging, each projects invents their own DBG, xprintf, dprintf type macros
    • And they are all slightly different, and possibly non-composable/compatible - consistency is good!
  • Provide support for statically selective debugging, such as enabling debug in a module or class (vs. all or nothing)
    • Allow debug to be included as part of library code bases, and only enabled when needed (rather than used during development, then commented out/removed)
    • Eliminate at compile time the calls/message strings of disabled debug, so instrumentation can be left in at zero cost
  • Allow options for dynamic debugging (can be programatically enabled)
  • Use stderr as debug stream, and ensure it can be re-routed to different stream devices

Draft library

Import library
debug - debug.h

00001 /* Copyright (c) 2012 mbed.org, MIT License
00002  *
00003  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00004  * and associated documentation files (the "Software"), to deal in the Software without restriction,
00005  * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00006  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00007  * furnished to do so, subject to the following conditions:
00008  *
00009  * The above copyright notice and this permission notice shall be included in all copies or
00010  * substantial portions of the Software.
00011  *
00012  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00013  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00014  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00015  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00016  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00017  */
00018  
00019 #ifndef DEBUG_H
00020 #define DEBUG_H
00021 
00022 #ifndef NDEBUG
00023 
00024 #include <stdarg.h>
00025 #include <stdio.h>
00026 
00027 static inline void debug(const char *format, ...) {
00028     va_list args;
00029     va_start(args, format);
00030     vfprintf(stderr, format, args);
00031     va_end(args);
00032 }
00033 
00034 static inline void debug(bool condition, const char *format, ...) {
00035     if(condition) {
00036         va_list args;
00037         va_start(args, format);
00038         vfprintf(stderr, format, args);
00039         va_end(args);
00040     }
00041 }
00042 
00043 #else
00044 
00045 static inline void debug(const char *format, ...) {}
00046 static inline void debug(bool condition, const char *format, ...) {}
00047 
00048 #endif
00049 
00050 #endif

Usage

Basic debug

#include "mbed.h"
#include "debug.h"

int main() {    
    debug("Hello debug world");

    int v = 5;
    debug("Hello debug world, v = %d", v);
}

Conditional debug (static)

#include "mbed.h"
#include "debug.h"

#define DEBUG_MAIN 1

int main() {    
    debug(DEBUG_MAIN, "Hello debug world");

    int v = 5;
    debug(DEBUG_MAIN, "Hello debug world, v = %d", v);
}
  • Recommended define format: DEBUG_<module> or DEBUG_<module>_<aspect>

Conditional debug (dynamic)

#include "mbed.h"
#include "debug.h"

int main() {    
    bool debug_main = 0;
    debug(debug_main, "Hello debug world");
    debug_main = 1;
    int v = 5;
    debug(debug_main, "Hello debug world, v = %d", v);

    for(int i=0; i<10; i++) {
        debug(i > 7, "Debug something");
    }
}

Redirecting stderr

#include "mbed.h"
#include "debug.h"

LocalFileSystem local("local");

int main() {    
    freopen("/local/debug.txt", "w", stderr);
    debug("Hello debug file");
    fclose(stderr);
}
All wikipages