`NoBug` provides GLARING! assertions and annotations for rust code. These have different
semantic than the stdlib assertions. The Idea behind `NoBug` is to have active annotations
with semantic meaning.
# Assertions
Normal builds of a programm will `std::process::abort()` when the asserted condition
fails. Only in tests they will panic because the test harness running tests in threads and
catching panics.
Aside from a generic (and discouraged) [`ASSERT!`] macro we provide:
* [`REQUIRE!`] -- checking preconditions
* [`ENSURE!`] -- checking postconditions
Each of those has a correspondending `ASSERT_DBG!`, `REQUIRE_DBG!` and `ENSURE_DBG!`
variants that inserts checks only in debug builds.
Since some programs must not abort on assertion failure we provide a `abort_on_failure`
feature. When this is not enabled then any `DIE!` and any other macro calling it will cause a
compile error in release, non-test builds. One can only use the `*_DBG!` variants of the nobug
macros then.
# Annotations
`NoBug` defines macros to actively annotate code. Actively means that these macros can do
different things in release or debug builds, depending on configuration:
* Be a [`compile_error!()`]
When certain things must be resolved before software is released and deployed.
* Abort the program with a message
When a code path can't make progress because of unfinished code.
* Log a message each time the macro is encountered
Just to nag the programmer
* Log a message once when the macro is encountered for the first time
Less nagging
* Do Nothing
We provide following annotation macros (with the noted defaults):
* [`FIXME!`] -- Bug that must be fixed.
* [`FIXED!`] -- Annotate fixed bugs.
* [`TODO!`] -- Incomplete but required code.
* [`WIP!`] -- Work in progress.
* [`IDEA!`] -- Not required improvement of existing code.
* [`PLANNED!`] -- Potential future planned feature.
# Tool Macros
The above uses some tool macros which may be useful on their own in some cases.
* [`MESSAGE!`] -- Print a message to the user.
* [`DIE!`] -- Abort (or panic). `compile_error!()` when `abort_on_fail` is not enabled.
# Feature Flags
* `abort_on_fail`
This is enabled by default. When not enabled then [`DIE!`] and all macros using it will
cause a compile error in release/non-test builds. This is useful when you want to make
sure that nobug will never abort in release builds. One can only use the `*_DBG!` variants
of the nobug macros in release builds then.
# History
In 2006 I started a C Debug library of the same name
(<https://git.pipapo.org/cehteh/nobug>). This implementation will carry some of its ideas
over to rust.
# Roadmap
Currently we only implemented most basic functionally. In future more features will be added.
* Eventually some of the macros will become proc macros
* Support for invariants on objects (needs proc macros)
* With proc macros we can have some nicer syntax:
```rust,ignore
#[nobug]
fn example(i: i32 where i > 0) -> i32
where
result < 100
{
...
}
```
* Add support for logging and tracing