Feedback wanted: docs on the ideas behind buck2, AKA "Why use Buck2? — or: from Make to Buck2"

[thoughtpolice]

A few months ago while @zjturner was asking me a bunch of questions about buck2 in private, I decided that the existing documentation didn't really address a very important core group of potential users: anyone who hasn't used Bazel!

---

Just kidding. Actually though, I find most people who don't have requisite background or knowledge of tools like Bazel, Nix, Pants, etc to generally be asking a repeating and recurring question: Why buck2? What does it do? What's the theory of its operation? Why does it exist? Why is it better than what I use?

One way to answer that question is to walk someone through the idea of designing it yourself. Some "battle scars" may be needed to fully appreciate it, but I find this to be fun and in buck2's case, actually easier than expected (when you know what you're looking at).

I decided to take a stab at that and put up a short draft on the whole idea of why buck2 over others, starting from GNU Make and a simple Makefile for C/C++ programs, titled: "Why use Buck2? — or: from Make to Buck2"

https://gist.github.com/thoughtpolice/6fcc0b102e10ac968a22b420b540f607

The funny thing is, this doesn't talk about buck2 yet! It only talks about Make. But it comes from a real place of personal experience since it is the one I (personally) care about the most.

While I was writing it, I realized there really need to be a few core sections, and to relate each one to buck2:

• Theory: While I love Build Systems a la Carte, I think it's going to be difficult to appreciate if you're not able to understand the Haskell psuedocode so easily. Bringing in some of that richness was a goal of this document, because you really need to decompose the problems into individual ones.
  • There is a bit of theory in there now, barfed on the document up front
  • But nothing (yet) to relate it to how buck2 calculates things.
  • It should be moved around.
• Abstraction: This is what the current draft basically has in it, which was bore out from my own personal experience, as you can probably tell.
  • Having a real programming language is a differentiator, and it's hard to appreciate how valuable it can be until you are working on big projects.
  • There are a lot of people who don't like generalized languages for build rules, but experience has taught me there is no other way. You will need to convince them or at least address them.
  • It now needs a part about buck2 and why Starlark, not <random other thing someone likes>.
• Multiple languages. It's really important to have consistent UX across languages and tools! This is another hidden sleeper advantage, IMO.
  • This is another thing you get from abstraction, but important enough in the user facing sense that IMO it should be called out directly.
• Scale. Remote execution and caching. Enough said.
  • There is luckily a billion pieces of evidence about why this is a killer feature, many obvious and some not.
  • Therefore it's last on the list because it has the easiest examples, background, etc to set up.

---

This isn't necessarily intended to be put in the documentation, it could be a totally different document. Or it could not, and it could go on the website and the main documentation. I'm interested in knowing if anyone can make sense of this document and learn anything from it — especially any potential lurkers who are reading this and know who they are!

So, please feel free to let me know if this is useful, if it should go somewhere, if you learned something from it, if you want to see more etc. I think having something like this is pretty important in general, but I'm not sure what scale or ideas it should have. The above is just a rough draft and something I figured it would be good to talk about.

[steveklabnik]

I hate just commenting with "wow, this is great," but like, truly that is all I have to say. Something like this should turn into documentation, or at least a blog post from you, imho.

[thoughtpolice]

Thanks! I still need to write a bunch more, but I hope the general idea for at least what's there is, uh, there. I'm currently a bit busy but hoping to return to this soon-ish, so if you have anything else you'd like to see me talk about, let me know.