{"id":13591342,"url":"https://github.com/sharkdp/dbg-macro","last_synced_at":"2025-05-13T23:07:15.623Z","repository":{"id":37396878,"uuid":"192787774","full_name":"sharkdp/dbg-macro","owner":"sharkdp","description":"A dbg(…) macro for C++","archived":false,"fork":false,"pushed_at":"2025-03-01T19:28:08.000Z","size":178,"stargazers_count":3124,"open_issues_count":10,"forks_count":259,"subscribers_count":51,"default_branch":"master","last_synced_at":"2025-04-30T14:16:00.655Z","etag":null,"topics":["cpp","debugging","macro","pretty-printing"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sharkdp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sharkdp"}},"created_at":"2019-06-19T18:53:47.000Z","updated_at":"2025-04-30T09:08:48.000Z","dependencies_parsed_at":"2024-05-01T23:11:40.466Z","dependency_job_id":"cad90f3b-2924-42e0-9aba-2c2865bd35de","html_url":"https://github.com/sharkdp/dbg-macro","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharkdp%2Fdbg-macro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharkdp%2Fdbg-macro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharkdp%2Fdbg-macro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharkdp%2Fdbg-macro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sharkdp","download_url":"https://codeload.github.com/sharkdp/dbg-macro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254041151,"owners_count":22004677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","debugging","macro","pretty-printing"],"created_at":"2024-08-01T16:00:56.338Z","updated_at":"2025-05-13T23:07:10.611Z","avatar_url":"https://github.com/sharkdp.png","language":"C++","readme":"# `dbg(…)`\n\n[![Build status](https://github.com/sharkdp/dbg-macro/workflows/CI/badge.svg)](https://github.com/sharkdp/dbg-macro/actions) [![Try it online](https://img.shields.io/badge/try-online-f34b7d.svg)](https://godbolt.org/z/Yj13Kaxfh) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](dbg.h)\n\n*A macro for `printf`-style debugging fans.*\n\nDebuggers are great. But sometimes you just don't have the time or patience to set\nup everything correctly and just want a quick way to inspect some values at runtime.\n\nThis projects provides a [single header file](dbg.h) with a `dbg(…)`\nmacro that can be used in all circumstances where you would typically write\n`printf(\"…\", …)` or `std::cout \u003c\u003c …`. But it comes with a few extras.\n\n## Examples\n\n``` c++\n#include \u003cdbg.h\u003e\n#include \u003ccstdint\u003e\n#include \u003cvector\u003e\n\n// You can use \"dbg(..)\" in expressions:\nint32_t factorial(int32_t n) {\n  if (dbg(n \u003c= 1)) {\n    return dbg(1);\n  } else {\n    return dbg(n * factorial(n - 1));\n  }\n}\n\nint32_t main() {\n  std::string message = \"hello\";\n  dbg(message);  // [example.cpp:15 (main)] message = \"hello\" (std::string)\n\n  const int32_t a = 2;\n  const int32_t b = dbg(3 * a) + 1;  // [example.cpp:18 (main)] 3 * a = 6 (int32_t)\n\n  std::vector\u003cint32_t\u003e numbers{b, 13, 42};\n  dbg(numbers);  // [example.cpp:21 (main)] numbers = {7, 13, 42} (std::vector\u003cint32_t\u003e)\n\n  dbg(\"this line is executed\");  // [example.cpp:23 (main)] this line is executed\n\n  factorial(4);\n\n  return 0;\n}\n```\n\nThe code above produces this output ([try it yourself](https://repl.it/@sharkdp/dbg-macro-demo)):\n\n![dbg(…) macro output](https://i.imgur.com/NVTzGRk.png)\n\n## Features\n\n * Easy to read, colorized output (colors auto-disable when the output is not an interactive terminal)\n * Prints file name, line number, function name and the original expression\n * Adds type information for the printed-out value\n * Specialized pretty-printers for containers, pointers, string literals, enums, `std::optional`, etc.\n * Can be used inside expressions (passing through the original value)\n * The `dbg.h` header issues a compiler warning when included (so you don't forget to remove it).\n * Compatible and tested with C++11, C++14 and C++17.\n\n## Installation\n\nTo make this practical, the `dbg.h` header should be readily available from all kinds of different\nplaces and in all kinds of environments. The quick \u0026 dirty way is to actually copy the header file\nto `/usr/local/include` or to clone the repository and symlink `dbg.h` to `/usr/local/include/dbg.h`.\n``` bash\ngit clone https://github.com/sharkdp/dbg-macro\nsudo ln -s $(readlink -f dbg-macro/dbg.h) /usr/local/include/dbg.h\n```\nIf you don't want to make untracked changes to your filesystem, check below if there is a package for\nyour operating system or package manager.\n\n### On Arch Linux\n\nYou can install [`dbg-macro` from the AUR](https://aur.archlinux.org/packages/dbg-macro/):\n``` bash\nyay -S dbg-macro\n```\n\n### With vcpkg\n\nYou can install the [`dbg-macro` port](https://github.com/microsoft/vcpkg/tree/master/ports/dbg-macro) via:\n``` bash\nvcpkg install dbg-macro\n```\n\n### With cmake\n\n`CMakeLists.txt`\n```cmake\ncmake_minimum_required(VERSION 3.11) # FetchContent added in cmake 3.11\nproject(app) # name of executable\n\nset(CMAKE_CXX_STANDARD 17)\n\n# dbg-macro\ninclude(FetchContent)\n\nFetchContent_Declare(dbg_macro GIT_REPOSITORY https://github.com/sharkdp/dbg-macro)\nFetchContent_MakeAvailable(dbg_macro)\n\nadd_executable(${PROJECT_NAME} main.cpp) # your source files goes here\ntarget_link_libraries(${PROJECT_NAME} PRIVATE dbg_macro) # make dbg.h available\n```\n\n`main.cpp`\n```cpp\n#include \u003cdbg.h\u003e\n\nint main() {\n  dbg(42, \"hello world\", false);\n  return 0;\n}\n```\n\n## Configuration\n\n* Set the `DBG_MACRO_DISABLE` flag to disable the `dbg(…)` macro (i.e. to make it a no-op).\n* Set the `DBG_MACRO_NO_WARNING` flag to disable the *\"'dbg.h' header is included in your code base\"* warnings.\n* Set the `DBG_MACRO_FORCE_COLOR` flag to force colored output and skip tty checks.\n\n## Advanced features\n\n### Multiple arguments\n\nYou can pass multiple arguments to the `dbg(…)` macro. This will output all expressions on a single line.\n``` c++\ndbg(42, \"hello world\", false);\n```\n\nNote that you have to wrap \"unprotected commas\" in parentheses:\n```c++\ndbg(\"a vector:\", (std::vector\u003cint\u003e{2, 3, 4}));\n```\n\nIf you want to output expressions each on its own line write `dbg(x); dbg(y); dbg(z);` instead of `dbg(x, y, z)`.\n\n### Hexadecimal, octal and binary format\n\nIf you want to format integers in hexadecimal, octal or binary representation, you can\nsimply wrap them in `dbg::hex(…)`, `dbg::oct(…)` or `dbg::bin(…)`:\n```c++\nconst uint32_t secret = 12648430;\ndbg(dbg::hex(secret));\n```\n\n### Printing type names\n\n`dbg(…)` already prints the type for each value in parenthesis (see screenshot above). But\nsometimes you just want to print a type (maybe because you don't have a value for that type).\nIn this case, you can use the `dbg::type\u003cT\u003e()` helper to pretty-print a given type `T`.\nFor example:\n```c++\ntemplate \u003ctypename T\u003e\nvoid my_function_template() {\n  using MyDependentType = typename std::remove_reference\u003cT\u003e::type\u0026\u0026;\n  dbg(dbg::type\u003cMyDependentType\u003e());\n}\n```\n\n### Print the current time\n\nTo print a timestamp, you can use the `dbg::time()` helper:\n```c++\ndbg(dbg::time());\n```\n\n### Customization\n\nIf you want `dbg(…)` to work for your custom datatype, you can simply overload `operator\u003c\u003c` for\n`std::ostream\u0026`:\n```c++\nstd::ostream\u0026 operator\u003c\u003c(std::ostream\u0026 out, const user_defined_type\u0026 v) {\n  out \u003c\u003c \"…\";\n  return out;\n}\n```\n\nIf you want to modify the type name that is printed by `dbg(…)`, you can add a custom\n`get_type_name` overload:\n```c++\n// Customization point for type information\nnamespace dbg {\n    std::string get_type_name(type_tag\u003cbool\u003e) {\n        return \"truth value\";\n    }\n}\n```\n\n## Development\n\nIf you want to contribute to `dbg-macro`, here is how you can build the tests and demos:\n\nMake sure that the submodule(s) are up to date:\n```bash\ngit submodule update --init\n```\n\nThen, use the typical `cmake` workflow. Usage of `-DCMAKE_CXX_STANDARD=17` is optional,\nbut recommended in order to have the largest set of features enabled:\n```bash\nmkdir build\ncd build\ncmake .. -DCMAKE_CXX_STANDARD=17\nmake\n```\n\nTo run the tests, simply call:\n```bash\nmake test\n```\nYou can find the unit tests in `tests/basic.cpp`.\n\n## Acknowledgement\n\nThis project is inspired by Rusts [`dbg!(…)` macro](https://doc.rust-lang.org/std/macro.dbg.html).\n","funding_links":["https://github.com/sponsors/sharkdp"],"categories":["Debug","C++","Debugging"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharkdp%2Fdbg-macro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsharkdp%2Fdbg-macro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharkdp%2Fdbg-macro/lists"}