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:
- 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.
