v0.2 (Done)

[matthewmueller]

Goals

1. The tests are a lot faster
2. The codebase is simpler to contribute to
3. Bud starts up faster

Deliverable

• Branch protection turned on for main branch because the test suite runs in under 5 minutes.
• There's been a livestream walking people through the codebase.

Tasks

graph BT
classDef done fill:green,color:white,stroke:green;
classDef wip fill:yellow,stroke:yellow;
classDef x fill:red,stroke:red,color:white;
1(Refactor Compiler):::done
2(Add parsing tests):::x
3(Rework E2E tests):::done
4(Protect main branch):::done
5(Write compiler tests):::done
6(Reduce flakiness in CI):::done
7(Improve CI caching):::done
1-->4
2-->4
3-->4
5-->4
6-->4
7-->4

Loading

[matthewmueller]

Update on Refactor Compiler:

Right now the compiler architecture is a bit complex and hard to understand. There's two high-level steps:

1. Generate a project CLI of Go code into the ./bud/.cli directory and build ./bud/.cli/main.go to ./bud/cli.
2. Use the project CLI (aka ./bud/cli) to generate an app of Go code into the ./bud/.app directory, then build ./bud/.app/main.go to ./bud/app and finally boot your web application by calling ./bud/app.

Executing bud run looks like the following visually:

sequenceDiagram
autonumber
bud->>./bud/.cli/...: generate ./bud/.cli packages
bud->>./bud/cli: go build ./bud/.cli/main.go
bud->>./bud/cli: execute ./bud/cli run
./bud/cli ->> ./bud/.app/...: generate ./bud/.app packages
./bud/cli ->> ./bud/app: go build ./bud/.app/main.go
./bud/cli ->> ./bud/app: execute ./bud/app
Note over ./bud/app: Ready to serve requests!

Loading

(Let me know if the diagram above doesn't make sense to you.)

The reason for this double binary is that we want to be able to support:

• Custom generators: you should be able to write your own code generator (e.g. generate a graphql server) that hooks into bud run and bud build. Ideally your custom generators shouldn't be treated any differently than the code generators that ship with bud.
• Custom transforms: Want to convert markdown to HTML? The framework should support these kinds of extensions in a way that it hooks into the existing view generators.
• Wrapping core commands: It would be nice to be able to wrap core commands like bud run so you can maintain the same shared vocabulary with your teammates, but these commands can be tailored to your team unique processes (e.g. run tests before running bud build).

I don't know what to call this process (pre-generate, expand?), but it's similar to expanding macros. Developers can define code that's run during the build step.

One other stretch goal I'm keeping in mind is a way to eventually define your own expanding macros. We currently have generator, transform and command, but I could see developers wanting to bring their own macros.

Additionally, while not confirmed, I sense that custom commands (e.g. random scripts) could bloat the application binary, so having them separated out could be useful. There might be downsides I'm not considering though.

The downside with the complexity above is:

• Slows down the tests considerably: Writing fast tests with code generation and go builds is quite difficult.
• Harder to contribute because:
  • The compiler is spread out between internal/bud (for building the project cli) and runtime/bud (for building the app).
  • The generators are also spread out too. Macros are in internal/generator, while application generators are in runtime/generator. This was originally to avoid exposing too much as public API.
• Slows down boot time: building two binaries takes a minimum of 300ms on my machine. Fortunately, there's good caching with internal/imhash to avoid repeatedly running go build for many cases. The code generators themselves take around ~70ms with lots of low-hanging fruit to speed this up.

I was hoping that Go plugins would be the answer to the double binary complexity, where you generate bud/.cli then load it into bud. While I got a prototype working, it felt underwhelming:

• Still can't co-locate generator and compiler packages because running go build from ./bud/.cli/main.go has the same internal/ restrictions as a normal build. Honestly, this restriction is a good call from the Go team, just limits my options here.
• It felt less flexible than code generating the project CLI. I could hardcode into bud {run,build} the ability to load commands from command/, transforms from transform/, etc. but then there's no possibility for developers to define their own macros in the future.
• It only saves about 14ms on boot time, the difference between dynamically loading a plugin and spawning an executable.
• I needed to replace xxhash with something that didn't use assembly because -buildmode=plugin had assembly conflicts. This makes me fear hard future issues due to Go plugin's lack of love.

So for now, I think I'm going to hit pause on the compiler refactor. Why fix what's not broken? What I'm going to do instead is focus efforts to improve the existing compiler with more tests.

I'm also planning to co-locate the compiler and the generators together and add a note that these packages are subject to change and you really shouldn't import these packages directly. Hopefully this reduces the jumping around you need to do with the current directory structure and makes it slightly easier to explain to contributors.

In the future, I could also see the pre-generation be a discrete step that runs and exits on boot, rather than a long-running process. The reason I went with long-running process is so that ./bud/cli can cache the ./bud/.app files it generates during live-reload in memory. I'm not really taking advantage of this yet because code generation between file changes is fast enough right now.

If you have any ideas on how to improve any of this, please share your thoughts!

[matthewmueller]

After this refactor, we're no longer generating a cli, just the app. This app is now generated to bud/internal/app instead of bud/.app. The built binary still lives in bud/app.

[matthewmueller]

I wanted to share a quick update on this. As you know, I've been trying to simplify the design of the framework described above to make it easier to understand, easier to contribute to, more performant and better tested.

A large refactor is happening in this PR: #133. Sorry this is taking longer than I would have liked, but it's chugging along and I'm quite happy with the results. I wanted to get this abstraction right before moving on to focus on the code generators. Nothing should really change externally.

• All generators and generator runtimes will be located in a new framework/ directory. This will lead to much less file hoping.
• Removed the generated cli, now we just generate an app. We were carrying too much complexity forward without actually exposing any value. I realized there's more solutions than I originally thought to the custom generator, transform, command problems that we'll focus on when the time comes.
• Took more care in how the bud and app interact with each other. Consolidated hot reload, the v8 client/server and dom file serving into a single dev client/server that's run internally during bud run. I realized all these needs could just be communication between the bud <-> app processes, so it make sense to consolidate and make it into a single internal protocol.
• Started using golden files to test state and generated code changes. These tests are much faster to run than the E2E tests, and they're still able to catch many errors. It's also nice to see the generated state and code for various test setups to get ideas on what can be optimized.
• Moved bud/.app to bud/internal/app. This allows us to get rid of the bud/imports.go file.

All-in-all, this is going to be a great simplification for the framework and get us in a good place to focus on features for the next few releases!

[matthewmueller]

v0.2.0 is out now so we're closing this one down!