derive-deftly 1.0 is released.
derive-deftly is a template-based derive-macro facility for Rust. It has been a great success. Your codebase may benefit from it too!
Rust programmers will appreciate its power, flexibility, and consistency, compared to
macro_rules; and its convenience and simplicity, compared to proc macros.
Programmers coming to Rust from scripting languages will appreciate derive-deftly s convenient automatic code generation, which works as a kind of compile-time introspection.
Rust s two main macro systems
I m often a fan of metaprogramming, including macros. They can help
remove duplication and flab, which are often the enemy of correctness.
Rust has two macro systems. derive-deftly offers much of the power of the more advanced (proc_macros), while beating the simpler one (macro_rules) at its own game for ease of use.
(Side note: Rust has at least three other ways to do metaprogramming: generics;
build.rs; and, multiple module inclusion via
#[path=]. These are beyond the scope of this blog post.)
macro_rules!
macro_rules! aka pattern macros , declarative macros , or sometimes macros by example are the simpler kind of Rust macro.
They involve writing a sort-of-BNF pattern-matcher, and a template which is then expanded with substitutions from the actual input. If your macro wants to accept comma-separated lists, or other simple kinds of input, this is OK. But often we want to emulate a
#[derive(...)] macro: e.g., to define code based on a struct, handling each field. Doing that with macro_rules is very awkward:
macro_rules! s pattern language doesn t have a cooked way to match a data structure, so you have to hand-write a matcher for Rust syntax, in each macro. Writing such a matcher is very hard in the general case, because
macro_rules lacks features for matching important parts of Rust syntax (notably, generics). (If you
really need to, there s a
horrible technique as a workaround.)
And, the invocation syntax for the macro is awkward: you must enclose the whole of the struct in
my_macro! . This makes it hard to apply more than one macro to the same struct, and produces rightward drift.
Enclosing the struct this way means the macro must reproduce its input - so it can have bugs where it mangles the input, perhaps subtly. This also means the reader cannot be sure precisely whether the macro modifies the struct itself. In Rust, the types and data structures are often the key places to go to understand a program, so this is a significant downside.
macro_rules also has various other weird deficiencies too specific to list here.
Overall, compared to (say) the C preprocessor, it s great, but programmers used to the power of Lisp macros, or (say) metaprogramming in Tcl, will quickly become frustrated.
proc macros
Rust s
second macro system is much more advanced. It is a fully general system for processing and rewriting code. The macro s implementation is Rust code, which takes the macro s input as arguments, in the form of
Rust tokens, and returns Rust tokens to be inserted into the actual program.
This approach is more similar to Common Lisp s macros than to most other programming languages macros systems. It is extremely powerful, and is used to implement many very widely used and powerful facilities. In particular, proc macros can be applied to data structures with
#[derive(...)]. The macro receives the data structure, in the form of Rust tokens, and returns the code for the new implementations, functions etc.
This is used very heavily in the standard library for basic features like
#[derive(Debug)] and
Clone, and for important libraries like
serde and
strum.
But, it is a complete pain in the backside to
write and
maintain a proc_macro.
The Rust types and functions you deal with in your macro are very low level. You must manually handle every possible case, with runtime conditions and pattern-matching. Error handling and recovery is so nontrivial there are macro-writing
libraries and even
more macros to help. Unlike a Lisp codewalker, a Rust proc macro must deal with Rust s highly complex syntax. You will probably end up dealing with
syn, which is a complete Rust parsing library, separate from the compiler; syn is capable and comprehensive, but a proc macro must still contain a lot of often-intricate code.
There are build/execution environment problems. The proc_macro code can t live with your application; you have to put the proc macros in a separate cargo package, complicating your build arrangements. The proc macro package environment is weird: you can t test it separately, without
jumping through hoops. Debugging can be awkward. Proper tests can only realistically be done with the help of complex
additional tools, and will involve a pinned version of Nightly Rust.
derive-deftly to the rescue
derive-deftly lets you use a write a
#[derive(...)] macro, driven by a data structure, without wading into any of that stuff.
Your macro definition is a template in a simple syntax, with predefined
$-substitutions for the various parts of the input data structure.
Example
Here s a
real-world example from a personal project:
define_derive_deftly!
export UpdateWorkerReport:
impl $ttype
pub fn update_worker_report(&self, wr: &mut WorkerReport)
$(
$ when fmeta(worker_report)
wr.$fname = Some(self.$fname.clone()).into();
)
#[derive(Debug, Deftly, Clone)]
...
#[derive_deftly(UiMap, UpdateWorkerReport)]
pub struct JobRow
...
#[deftly(worker_report)]
pub status: JobStatus,
pub processing: NoneIsEmpty<ProcessingInfo>,
#[deftly(worker_report)]
pub info: String,
pub duplicate_of: Option<JobId>,
This is a nice example, also, of how using a macro can avoid bugs. Implementing this update by hand without a macro would involve a lot of cut-and-paste. When doing that cut-and-paste it can be very easy to accidentally write bugs where you forget to update some parts of each of the copies:
pub fn update_worker_report(&self, wr: &mut WorkerReport)
wr.status = Some(self.status.clone()).into();
wr.info = Some(self.status.clone()).into();
Spot the mistake? We copy
status to
info. Bugs like this are extremely common, and not always found by the type system. derive-deftly can make it much easier to make them impossible.
Special-purpose derive macros are now worthwhile!
Because of the difficult and cumbersome nature of proc macros, very few projects have site-specific, special-purpose
#[derive(...)] macros.
The
Arti codebase has no bespoke proc macros, across its 240kloc and 86 crates. (We did
fork one upstream proc macro package to add a feature we needed.) I have only
one bespoke, case-specific, proc macro amongst all of my personal Rust projects; it predates derive-deftly.
Since we have started using derive-deftly in Arti, it has become an important tool in our toolbox. We have 37 bespoke derive macros, done with derive-deftly. Of these, 9 are exported for use by downstream crates. (For comparison there are 176 macro_rules macros.)
In my most recent
personal Rust project, I have 22 bespoke derive macros, done with with derive-deftly, and 19 macro_rules macros.
derive-deftly macros are easy and straightforward enough that they can be used as readily as macro_rules macros. Indeed, they are often
clearer than a macro_rules macro.
Stability without stagnation
derive-deftly is already highly capable, and can solve many advanced problems.
It is mature software, well tested, with excellent documentation, comprising both comprehensive
reference material and the
walkthrough-structured user guide.
But declaring it 1.0 doesn t mean that it won t improve further.
Our
ticket tracker has a laundry list of possible features. We ll sometimes be cautious about committing to these, so we ve added a
beta feature flag, for opting in to less-stable features, so that we can prototype things without painting ourselves into a corner. And, we intend to further develop the Guide.
comments
Anarcat recently wrote about Qalculate, and I think I m a convert, even though
I ve only barely scratched the surface.
The thing I almost immediately started using it for is time calculations.
When I started tracking my time, I
quickly found that Timewarrior was good at
keeping all the data I needed, but I often found myself extracting bits of
it and reprocessing it in variously clumsy ways. For example, I often don t
finish a task in one sitting; maybe I take breaks, or I switch back and
forth between a couple of different tasks. The raw output of 
Many years ago I made myself a 
Then a few years ago the cheap cotton had started to get worn, and I
decided I needed to replace it. I found a second choice (and thus
cheaper :) ) version of a 
This time I skipped a few pockets that I had found I didn t use that
much, and I didn t add a hood, which didn t play that well when worn
over a hoodie, but I added some detached sleeves, for additional wind
protection.
This left about 60 cm and some odd pieces of leftover fabric in my
stash, for which I had no plan.
And then February
I did however have a spool of reflector thread made of glass fibre by
Rico Design, which I think was originally sold to be worked into
knitting or crochet projects (it is now discontinued) and I had never
used.
I decided to try and sew a decorative blanket stitch border, a decision
I had reasons to regret, since the thread broke and tangled like crazy,
but in the end it was done, I like how it looks, and it seems pretty
functional. I hope it won t break with time and use, and if it does I ll
either fix it or try to redo with something else.
Of course, the day I finished sewing the reflective border it stopped
raining, so I haven t worn it yet, but I hope I ll be able to, and if it
is an horrible failure I ll make sure to update this post.
For my 
As of today, 
The 
TL;DR
It's difficult to find the right Debian image. We have thousands of
ISO files and cloud images and we support multiple CPU architectures
and several download methods. The directory structure of our main image server
is like a maze, and our web pages for downloading are also confusing.
Most important facts from this blog post
Recently createrepo-c on 
20 years ago, I got my Debian Developer account. I was 18 at the time, it was Shrove Tuesday and - as is customary - I was drunk when I got the email. There was so much that I did not know - which is also why the process took 1.5 years from the time I applied. I mostly only maintained a package or two. I'm still amazed that Christian Perrier and Joerg Jaspert put sufficient trust in me at that time. Nevertheless now feels like a good time for a personal reflection of my involvement in Debian.
After circling a bit to find somewhere suitable (there appear to be construction
works in the park!) I set up my gear in 2C with frost on the ground, called CQ,
spotted and got nothing on either the end fed half wave or the cheap vertical.
As it was too late for 20m, I tried 40 and a bit of 80 using the inbuilt tuner,
but wasn t heard by stations I called or when calling independently.
I packed everything up and lora-doofered my way home, mildly deflated.
After a mild struggle on 2m, I set up the end fed the first hill and got to
work from the old hill fort:
The end fed worked flawlessly. Exactly as promised, switching between 7MHz, 14MHz, 21MHz
and 28MHz without a tuner was perfect, I chased hills on all the bands, and had a
great time. Apart from 40m, where there was absolutely no space due to a
contest. That wasn t such a fun time!
My fingers were bitterly cold, so on went the big gloves for the descent and I
felt like I was warm by the time I made it back to the car.
It worked so well, in fact, I took the 1/4 wave cheap vertical out my bag and
decided to brave it on the next activation.
To get some height for the feedpoint, I wrapped the coax around my winder a
couple of turns and trapped it with the elastic while draping the coax over the
trig. This bought me some more height and I felt clever because of it. Maybe a
pole would be easier?
From here, I worked inter-G on 40m and had a wee pile up, eventually working 15
or so European stations on 20m. Pleased with that!
I had been considering a third hill, but home was the call in the failing light.
Back to the car I walked to find my key didn t have any battery, so out came the
Audi App and I used the Internet of Things to unlock my car. The modern world is
bizarre.
I set up at the cairn and picked up 30 contacts overall, split between 40m and
20m, with some inter-g on 40 and a couple of continental surprises. 20 had
longer skip today, so I saw Spain, Finland, Slovenia, Poland.
On teardown, I managed to snap the top segment of my brand new mast with my
cold, clumsy fingers, but thankfully sotabeams stock replacements. More money at
the problem, again.
Back to the car, no app needed, and homeward bound as the light faded.
At the end of the weekend, I find myself finally over 100 activator points and
over 400 chaser points. Somehow I ve collected more points this year already
than last year, the winter bonuses really do stack up!
This weekend I discovered it s possible to have height maps for nice 3d
maps and contours marked on the map - you just need to download some
additions for the maps. This is a really nice feature, it makes maps more
pretty and more useful when you re in the middle of nowhere.
Since these templates were bound to evolve, the teams providing these template relied on 
creates new project with cookiecutter template
makes modification on their code, including on code provided by template
runs cruft to update template code
discovers a lot of code conflicts (similar to git merge conflicts)
often rolls back cruft update and gives up on template update
Note that code conflicts seen with cruft are similar to git merge conflicts, but harder to resolve because, unlike with a git merge, there s no common ancestor, so 
Quick to deploy which is what I was after. My new 5m of coax with a choke fitted attached to the radio and we were off to the races - A convenient thing of beauty when it s up:
I ve made a single guy with a sotabeams