A Ton Of C++ Verification Is Now Factored Out

It may have appeared not much was going on in Revolt development this year. (There certainly has been a gap due to illness, which will cause more gaps.)

But more has happened than meets the eye. A giant chunk of code has been removed completely from the Revolt repository and put into a library called "Needful".

https://needful.metaeducation.com/

Only one file from Needful is required to build Revolt. It's a header file full of mostly no-op macros, and is around 1200 lines...where half of them are comments and blank lines:

needful.h

  • 197 blank lines — 17.1%
  • 357 comment-only lines — 30.9%
  • 600 code-bearing lines — 52.0% (including lines with inline comments)

To make building Revolt easier, needful.h is committed at a version stamp into the Revolt repository. That means people can clone Revolt and build it without hunting down some library dependency.

These macros help document all kinds of things about the intentions behind the code. But since the macros are (mostly) no-ops, they do very little during compilation.

The magic comes from if someone building Revolt chooses to put the needful-enhanced/ project directory into their build tree. This code #undefs the no-op macros and re-#defines them using ridiculously powerful C++ metaprogramming... bringing incredible static analysis to the system.

https://github.com/metaeducation/needful-enhanced

If you choose to build Revolt with this enhanced code alongside your build, it will behave exactly the same...if it compiles! But there are thousands of additional checks that can catch mistakes of all kind and stop the compilation, so you can see what you've done wrong and fix it.

(The continuous integration of course has at least one build using the needful-enhanced tree on all platform configurations.)


Explaining How Great This Is Would Take A Long Time

A not-so-secret subgoal of Revolt has been to prove that being able to build a C project as C++ has tremendous value. I've long been a fan of the language and its outsized role in modern technology. I even ran the Austin C/C++ Meetup, and helped facilitate Bjarne Stroustrup coming to speak to our group.

I've also long fought the tendency of C programmers to believe that they should not learn or understand C++ because it is "too complicated". It exists for a reason and is the favored tool of many of the most important software developers on the planet (or it was the direct influence of the languages they use, such as Rust...which is really a collection of "best practices" that came from Modern C++... whether its creator wanted that to be what it was or not).

But I understand the reason why the culture of Rebol would prefer C for an implementation language over C++. This is the "Amish Programming" that I speak of... to "work with your hands" where you are wielding the basics of your craft, where each line of code you step over (that isn't a function call) does one thing and that is a thing you can comprehend at a level that almost corresponds to a single microprocessor instruction.

(Truthfully, optimization principles of C compilers has removed it quite far from the original "slight abstraction over assembly language" state.)

Working in a C99 codebase where your only abstraction tool is essentially function calls is a hard road. But Revolt stayed true to that hard road, and just designed tools for auditing implicit code updating policies.

You see...the goal of C++ is to help developers be able to change a decision in one place and not have to touch all the scattered places in the code that depended on that decision. Needful doesn't lean on the powers of C++ to "do more" at callsites to avoid having to touch them when a decision changes: Needful uses the powers of C++ to alert you when you didn't do the updates in accordance with the codebase policy.

It's a newer, better C.


The Factorization Is Complete

Originally the abstractions in Needful just grew in the Revolt codebase. They had no test suite of their own... the test was just "did Revolt compile or not". They only covered the cases that I encountered vs. being designed from first principles.

But now that Needful is its own project, it has been hardened and sharpened. And as of last night, Revolt is building against it with no errors on the major platforms...including web:


Needful Gone From Revolt's Repo Is A Better Look

With Needful in its own repository, having it grow and be commented...vetted by great AIs like @claude and @chatgpt... it's gotten scarier-looking to a C programmer. Of course it makes sense if you understand it, but there's a lot of things that look like this:

//=//// OVERLOAD 4: semantic wrapper -> re-wrapped result /////////////////=//
//
// Why it exists: Semantic wrappers (Option, Result) carry meaning beyond the
// raw type--their wrapping is part of the data's contract.  Cast must not
// silently strip them.  Instead, the inner value is cast and re-wrapped in
// the same template: `cast(Stump*, Result(Stub*))` -> `Result(Stump*)`.
// This is essential for patterns like `panic_if_failed(cast(T, result_expr))`
// where the Result wrapper must survive for `%` extraction, and for Option
// where engaged/disengaged state must be preserved.
//
template<
    typename To,
    typename FromWrapperRef,
    typename From = remove_reference_t<FromWrapperRef>,
    typename InnerFrom = needful_unwrapped_type(From),
    typename CastResult = needful_merge_const_t(  // lenient cast
        InnerFrom, To
    ),
    typename ResultType = needful_rewrap_type(From, CastResult)
>
enable_if_t<
    IsRewrappable<From>::value
        and IsWrapperSemantic<From>::value,
    ResultType
>
Hookable_Cast_Helper(const FromWrapperRef& from_wrapper)
{
    using ConstTo = needful_constify_t(To);

    static_assert(
        not is_function_pointer<InnerFrom>::value
        and not is_function_pointer<To>::value,
        "Use f_cast() for function pointer casts"
    );

    const InnerFrom& inner = NEEDFUL_EXTRACT_INNER(InnerFrom, from_wrapper);

  #if NEEDFUL_CAST_CALLS_HOOKS
    using ConstFrom = needful_constify_t(InnerFrom);  // hooks see raw type
    static_assert(
        CastHook<ConstFrom, ConstTo>::legal
        or IsBasePtrOf<ConstFrom, ConstTo>::value
        or IsVoidPtrCast<ConstFrom, ConstTo>::value,
        "cast: source type not accepted for this target type");
    CastHook<ConstFrom, ConstTo>::Validate_Bits(inner);
  #endif

    CastResult cast_inner = needful_mutable_cast_unchecked(  // rewrap
        CastResult,
        needful_c_cast(ConstTo, inner)
    );
    return ResultType{cast_inner};
}

If a C programmer who is used to the source code of something like CPython or Lua opened a codebase like Revolt and saw that, they would run first and ask questions never. I can articulate why it's great to someone who will listen, but it's easier if it just doesn't live in the source tree and is instead considered the source code to some tool you use (like Valgrind or Address Sanitizer).

There's some Needful client code that looks like this which adapts the tooling to the Revolt codebase specifically. But we can factor that out as well, into some kind of ren-c-needful project. Then we might have definitions that look like:

#if NEEDFUL_CPP_ENHANCED && DEBUG_EXTRA_HEART_CHECKS
    #include "ren-c-needful/struct-type.h"  // instead of pages of code here
    typedef TypeStruct Type;
#else
    typedef TypeEnum Type;  // the simple definition, clear for any reader
#endif

Having a separate submodule to deal with versioning independently would make maintenance much tougher. But maybe even just writing the files like this...so all the simple definitions could be seen in a line one after another...would help make a better impression.


Will Anyone Else Use Needful?

They should. I'll maybe see if I can make some outreach. But it's certainly great to have it factored as its own project. And AI has helped immeasurably in terms of documenting and testing...as well as helping fix Revolt when the abstractions were improved, to bring the code into shape with more rigorous definitions.

Thanks @claude and @chatgpt!

1 Like

Meetup Sucks Now. I remember when they got greedy and were floating ideas like charging people to attend meetups vs. just charging the organizer for the Meetup. Then they stopped showing you the people who would be at the meetup so you couldn't even contact the people you met unless you paid.

(This is so much the way of it... provide trivial service that connects people and then think you're owed unlimited money for the trivial service when it's the network effect of your users creating the value, not your terrible software... then break the value and lock out people if they don't pay your ridiculous charge. Charging the organizer for the Meetups themselves is ALL THEY NEED, and it was already too much.)

I don't even want to link the meeting URL because of their loginwall.

https://www.meetup.com/cpp-austin/events/77907002/

Here's what the page says:


Presentation from Bjarne Stroustrup, Inventor of C++!
Hosted by: Brian D. (Brian Dickens)
Group: Austin C++ Meetup Group / CppMsg.com
Date & Time: Wed, Sep 19, 2012, 6:00 PM – 8:45 PM CDT
Location: National Instruments Building C, Austin, TX

Event Overview

  • RSVPs: Closed; organizers aimed to accommodate registered attendees within fire code limits.
  • Important Notice: Attendees were advised to arrive by 6:00 PM because National Instruments security gates closed strictly at 7:00 PM. Bringing a laptop or tablet was also recommended to follow the slides from a distance.

Presentation Details

Bjarne Stroustrup visited Austin to discuss applying C++11 to achieve his vision of "Modern C++". Rather than relying on outdated idioms, tangled abstractions, or messy pointer management, Stroustrup advocated for type-rich interfaces, compact data structures, integrated resource management, and clean algorithmic code.

His talk highlighted C++11 features—such as auto, uniform initialization, type aliases, and type-safe threading—to help developers transition away from 1980s-style coding patterns.

Meeting Agenda

  • 6:00 PM: Networking and Gathering (Early arrival strictly enforced due to security gates)
  • 7:00 PM: Call to Order and Announcements
  • 7:15 PM: Presentation and Q&A
  • 8:45 PM: Meeting Evaluation and Adjournment