Haxe Macro book

Hej all !
I try to improve my understanding of macros in Haxe. I write macros since 2011, I’m not a specialist but I success to do almost all I want and have a quite good understanding of the basis but I still need to understand some details and how does it work on the background.
For example I would like to detail a bit more this picture, show where exactly occur the different macro contexts (initialization, builds, expressions) and also where exactly occur the callbacks like onTypeNotFound, onAfterTyping, onGenerate, onAfterGenerate, vhere does macro “loop” when creating a new Type that need pass the typer and so on, show on every contexts what can we interract with ( set metas, manipulate fileds…), which kind of exprs and types can we manipulate in order to modify that or that.
I’m also sometimes confused when I deal with exprs and typedExprs, for example when I need to get type of an expr inside a build macro, and return it back (getTypedExpr( typeExpr ) ) I know some things are resolved like usings,imports, getter/setters… but it’s complicated I don’t really know i it’s better to send it to expression macros and deal all in typed mode or can I mix the both ? What is the process inside when doing such a thing please ?
Can some people that know very well macros and how does it work in the background explain me (us ?) a bit more please ? Maybe if we can represent that on this scheme but more detailed or another one ? I don’t know…

Thank you very much for your reading,


Hej all !

Macro is one of the most powerful thing in Haxe compiler, especially the way they work, that I think, is new in the programming langage history.

And while there are yet some awesome libraries, and some brilliant people that digged deep into macro, I think especially about Juraj - @back2dos (but there are many other people, I won’t list them all here, they will recognize themselves…), I personnaly, and I am not the only one I hope :sob:, can’t understand some things for years and I use macros a bit blindly in some cases.

Most of time it works fine like that, but sometimes when I go deeper I encouter mistakes that I can’t resolve because I really lack of knowledge.

I lack of knowledge in some programming paradigms, that’s true, I’ve learned programming by myself and I learn things everyday and love that, but I also lack of knowledge on Haxe macros because of the lack of the knowledge about compiler concepts, the way things run “under the hood”.
Some things the way the parser/typer works, the way the types are build, the resolution of cyclical redundancy (I write about cyclic redundancy because today I’ve encouter that but there are many other things…)

Maybe it would be a good idea to make a pot, to pay someone that has enough time and knowledge to write a more detailed book about Haxe macros ? Not only “basic” and impressive examples like in the haxe cook-book, but something specially dedicated to macros and compiler work and features, since once again, it’s one of the most powerfull feature in Haxe.

(Or maybe people uderstand things quite well and I’m like the only one with these lacks, so maybe there is someone I could pay in order to give me some lessons about things I described upper (and by the way someone patient that could support my bad english and my lack of comprehension :rofl: ) ?

Thanks for reading me,


If anyone feels up to the task of authoring such a book, I’d be glad to help. Personally, I can’t take on such a project because I have very little experience even just reading books on technical subjects, and absolutely none writing them. But if someone else takes the initiative, I will help where I can :wink:


Once all the Tink docs are finished you mean? :wink:

I’d be happy to pledge a coffee or a beer’s worth of euros every now and again to any project that expands the haxe documentation, especially if it opens doors to the dark arts like macros.

1 Like

You mean the code is not self-documenting? :stuck_out_tongue_winking_eye:


I’d also be happy to help on authoring such a book.

I have experience in writing macros, and have much more experience in writing long documents describing very high level technical concepts. I have also read a lot of books and journals doing the same thing. Perhaps I could guide on structure, etc…

Unfortunately, I don’t think I can divide my time between such a big undertaking like writing a book and everything else, otherwise I would be offering to do it myself (plus I would want to dig much deeper into syntax trees and macros before I even start)

1 Like

I created a little “snippets project” where I will “record” all my experience using macros GitHub - filt3rek/Snippets, especially building macros : Snippets/haxe_build_macro_order.md at main · filt3rek/Snippets · GitHub

I’ll do it bit by bit and try to organize that when maybe it will shows a kind of logical plan.

It’s like a reminder for me and some people can surely find it “basic” or stupid but If it can help people to progress in macros until we get more documentation or the famous book, it’s ok.

If some advanced people look at this and see mistakes, please correct it if you can so It won’t spread mistakes all over the web, it’s not the goal :sweat_smile:


BTW, I’ve just seen these interesting videos, I didn’t know such videos exist… :

While the samples are basic, Juraj tells exactly what I wanted to hear and what messed me a lot about macros : All this stuff about AST (where macros can transform AST) and Typed AST where macro can just kind of analyze it and how and why it’s dangerous to try to “reinject” Typed AST back into the untyped AST (all things I’ve passed long time to do in fact :rofl: …)

People sometimes have warned me about that but since I missed some important things about macros, I misunderstood the documentation, I obstinated in some cases.

The evil for me is for example ̀Context.getTypedExpr`: it permits to get back an untyped expr from a typed one. For people like me documentation should contain giant warning “Using at your own risks” because I’m kind of trisomic : it’s permit ? Let’s go use it ! :rofl:

Another important and confusing point for me is the things about many macros running at the same time, mess in the building types, and in these videos Juraj says just that about circular redundacies for example…
In this case, I would prefer compiler (eval in this case I think) going into an infinite loop than silently giving me an unbuild yet type with empty fields for example… I will better know how to deal with that.

Before, I’ve seen Haxe macros like something with strong guards (as the Haxe compiler is), which alerts you If you do something “stupid”, but now I see haxe macros like whole “untyped” tool : It permit doing almost all what you want but at your own risks, there is absolutely no guards !

Well a lot of time and energy spent for nothing, because of some little but important things that I didn’t understood by the documentation but these videos give me answers, thanks a lot for that !


Recently I’ve been thinking about writing this very “book” exactly and here I find a fresh thread on that topic :slight_smile:

I feel that macros are one of the most satisfying parts of Haxe and learning to use them was mostly experimentation, asking Simn, or transferring ideas from other places. The manual and API docs could be improved for sure but there is a lot of content that fits neither, nor does it fit the “snippet” format of the cookbook.

Let’s do it!


This would be super useful for me as I am just getting into Macros. I don’t really have the experience though. Wish you all luck!