https://github.com/greymattergames/unbug Skip to content Navigation Menu Toggle navigation Sign in * Product + GitHub Copilot Write better code with AI + Security Find and fix vulnerabilities + Actions Automate any workflow + Codespaces Instant dev environments + Issues Plan and track work + Code Review Manage code changes + Discussions Collaborate outside of code + Code Search Find more, search less Explore + All features + Documentation + GitHub Skills + Blog * Solutions By company size + Enterprises + Small and medium teams + Startups By use case + DevSecOps + DevOps + CI/CD + View all use cases By industry + Healthcare + Financial services + Manufacturing + Government + View all industries View all solutions * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} greymattergames / unbug Public * Notifications You must be signed in to change notification settings * Fork 1 * Star 87 A crate to programmatically invoke debugging breakpoints with helping macros docs.rs/unbug License Apache-2.0, MIT licenses found Licenses found Apache-2.0 LICENSE-APACHE MIT LICENSE-MIT 87 stars 1 fork Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Projects * Security * Insights greymattergames/unbug main BranchesTags [ ] Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 28 Commits .vscode .vscode assets assets examples/basic examples/basic src src .editorconfig .editorconfig .gitignore .gitignore Cargo.lock Cargo.lock Cargo.toml Cargo.toml LICENSE-APACHE LICENSE-APACHE LICENSE-MIT LICENSE-MIT README.md README.md rust-toolchain.toml rust-toolchain.toml View all files Repository files navigation * README * Apache-2.0 license * MIT license Unbug logo Unbug A crate to programmatically invoke debugging breakpoints with helping macros. These macros are designed to help developers catch errors during debugging sessions that would otherwise be a panic (which may not be desirable in certain contexts) or simply a log message (which may go unnoticed). This crate's internals are disabled by default, there are shims provided so breakpoints will not be compiled outside of a debugging context. This means that the macros in this crate can be used freely throughout your code without having to conditionally compile them out yourself. NOTICE You must use the enable feature of this crate (deactivated by default) to activate the breakpoints. This crate cannot detect the presence of a debugger. BREAKPOINTS REQUIRE NIGHTLY RUST BREAKPOINTS REQUIRE ENABLING THE EXPERIMENTAL core_intrinsics FEATURE Additonally, debugging may not land on the macro statements themselves. This can have the consequence that the debgger may pause on an internal module. To avoid this, return or continue immediately following a macro invocation. Alternatively, use your debugger's "step-out" feature until you reenter the scope of your code. Error messages are logged when used in conjuction with Tracing Examples VSCode debugging example // trigger the debugger unbug::breakpoint!(); for i in 0..5 { // ensure! will only trigger the debugger once // when the expression argument is false unbug::ensure!(false); unbug::ensure!(false, "Ensure can take an optional log message"); unbug::ensure!(false, "{}", i); // ensure_always! will trigger the debugger every time // when the expression argument is false unbug::ensure_always!(i % 2 == 0); // Use the tracing_subscriber crate to log error messages // from the fail! and fail_always! macros. tracing_subscriber::fmt::init(); // fail! pauses and logs an error message // will also only trigger once unbug::fail!("fail! will continue to log in non-debug builds"); if i < 3 { // fail! and fail_always! can be formatted just like error! // from the Tracing crate unbug::fail!("{}", i); } let Some(_out_var) = some_option else { unbug::fail_always!("fail_always! will trigger every time"); }; } Usage Prepare your environment for debugging Rust. If you are using VSCode you will need the Rust Analyzer and Code LLDB (Linux/Mac) or the C/C++ (Windows) extensions. See Microsoft's Documentation on Rust Debugging in VSCode. 1. Enable Nightly Rust: You can set a workspace toolchain override by adding a rust-toolchain.toml file at the root of your project with the following contents: [toolchain] channel = "nightly" OR you can set cargo to default to nightly globally: rustup install nightly rustup default nightly 2. Create a debug feature in your project that will only be active in the context of a debugger, i.e. not enabled by default. Cargo.toml: [features] default = [] my_debug_feature = [ "unbug/enable" ] 3. enable the core_intrinsics feature in the root of your crate (src/ main.rs or src/lib.rs) src/main.rs: #![cfg_attr( // this configuration will conditionally activate core_intrinsics // only when in a dev build and your debug feature is active all( debug_assertions, feature = "my_debug_feature", ), feature(core_intrinsics), // Optionally allow internal_features to suppress the warning allow(internal_features), )] 4. Pass your feature flag to cargo during your debug build. Sample VSCode .vscode/launch.json with LLDB (Linux/Mac): { "version": "0.2.0", "configurations": [ { "type": "lldb", "request": "launch", "name": "LLDB Debug (nightly)", "cargo": { "args": [ "build", "--bin=my_project", "--package=my_project", "--features=my_debug_feature" ], "filter": { "name": "my_project", "kind": "bin" } }, "args": [], "cwd": "${workspaceFolder}", "env": { "CARGO_MANIFEST_DIR": "${workspaceFolder}" } } ] } Sample VSCode .vscode/launch.json with msvc (Windows): { "version": "0.2.0", "configurations": [ { "name": "Windows debug (nightly)", "type": "cppvsdbg", "request": "launch", "program": "${workspaceRoot}/target/debug/unbug_basic_example.exe", "stopAtEntry": false, "cwd": "${workspaceRoot}", "preLaunchTask": "win_build_debug" } ] } and complimentary .vscode/tasks.json { "version": "2.0.0", "tasks": [ { "type": "cargo", "command": "build", "args": [ "--bin=my_project", "--package=my_project", "--features=my_debug_feature" ], "problemMatcher": [ "$rustc" ], "group": { "kind": "build", "isDefault": true }, "label": "win_build_debug" } ] } 5. Select the debug launch configuration for your platform and start debugging In VSCode, open the "Run and Debug" panel from the left sidebar. launch configurations can be now found in the dropdown menu next to the green "Start Debugging" button. License Unbug is free and open source. All code in this repository is dual-licensed under either: * MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT) * Apache License, Version 2.0 (LICENSE-APACHE or http:// www.apache.org/licenses/LICENSE-2.0) at your option. About A crate to programmatically invoke debugging breakpoints with helping macros docs.rs/unbug Topics rust debugging Resources Readme License Apache-2.0, MIT licenses found Licenses found Apache-2.0 LICENSE-APACHE MIT LICENSE-MIT Activity Custom properties Stars 87 stars Watchers 1 watching Forks 1 fork Report repository Releases 1 0.2 Latest Nov 20, 2024 Packages 0 No packages published Contributors 2 * @BrainBacon BrainBacon Brian Jesse * @girtonman girtonman Languages * Rust 100.0% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.