Output files cause rebuild loop

[davidrea]

I've installed mdbook and mdbook-plantuml using:

cargo install mdbook
cargo install mdbook-plantuml

And (after installing plantuml on Ubuntu 18.04 via apt install plantuml) added the plantuml preprocessor to my book.toml file:

[preprocessor.plantuml]
plantuml-cmd="plantuml"

Whenever a plantuml diagram is present in one of the book's markdown files, it triggers a rebuild loop in mdbook serve:

2020-04-29 06:18:59 [INFO] (mdbook::cmd::serve): Files changed: ["/path/to/book/src/mdbook-plantuml-img/364fac99-99ec-434b-a480-17677bbdff9f.puml"]
2020-04-29 06:18:59 [INFO] (mdbook::cmd::serve): Building book...
2020-04-29 06:18:59 [INFO] (mdbook::book): Book building has started
2020-04-29 06:19:00 [INFO] (ws::io): Accepted a new tcp connection from [::1]:34134.
2020-04-29 06:19:01 [INFO] (mdbook::book): Running the html backend
2020-04-29 06:19:01 [INFO] (mdbook::cmd::serve): Files changed: ["/path/to/book/src/mdbook-plantuml-img/7ae62db4-f52d-4fe6-97b3-1cdf7c99696d.puml"]
2020-04-29 06:19:01 [INFO] (mdbook::cmd::serve): Building book...
2020-04-29 06:19:01 [INFO] (mdbook::book): Book building has started
2020-04-29 06:19:01 [INFO] (ws::io): Accepted a new tcp connection from [::1]:34140.
2020-04-29 06:19:03 [INFO] (mdbook::book): Running the html backend
2020-04-29 06:19:03 [INFO] (mdbook::cmd::serve): Files changed: ["/path/to/book/src/mdbook-plantuml-img/751fa61e-1564-47fc-96cd-05b9395dad70.puml"]
2020-04-29 06:19:03 [INFO] (mdbook::cmd::serve): Building book...
2020-04-29 06:19:03 [INFO] (mdbook::book): Book building has started
2020-04-29 06:19:03 [INFO] (ws::io): Accepted a new tcp connection from [::1]:34146.
2020-04-29 06:19:04 [INFO] (mdbook::book): Running the html backend
2020-04-29 06:19:04 [INFO] (mdbook::cmd::serve): Files changed: ["/path/to/book/src/mdbook-plantuml-img/c08c92ef-16c5-4acb-a2c7-d79221422f78.puml"]
2020-04-29 06:19:04 [INFO] (mdbook::cmd::serve): Building book...
2020-04-29 06:19:04 [INFO] (mdbook::book): Book building has started
2020-04-29 06:19:05 [INFO] (ws::io): Accepted a new tcp connection from [::1]:34152.
2020-04-29 06:19:06 [INFO] (mdbook::book): Running the html backend

The .puml file just contains the plantuml code from inside the plantuml triple-backtick block. Since mdbook-plantuml is placing this inside the src/ tree, it rebuilds the book continuously.

Have I misconfigured something? I've also tried it using local and remote plantuml server URLs; instead of placing a .puml in mdbook-plantuml-img/, .svg files trigger the rebuild loop.

[niko-dunixi]

I'm seeing this as well. I just found this preprocessor this evening so I don't know how long this behavior has been occurring, but I'm seeing this happen as well. Might become a larger problem as more diagrams get embedded within the book, but only a single puml snippet has already made a noticeable effect on battery.

[niko-dunixi]

Reread the readme in case I was overlooking something simple:

enable-cache: Optional flag to enable caching (defaults to false for now). When enabled, repetitive book generation is significantly faster, because only the changed PlantUML code blocks are regenerated.

Unfortunately, It's reproducible even with caching enabled:

[preprocessor.plantuml]
plantuml-cmd = "plantuml"
enable-cache = true

[hamaluik]

This was annoying me so I wrote a simple replacement: https://crates.io/crates/mdbook-puml

It renders the PlantUML as inline SVG, nothing more, nothing less. Hopefully it will help you guys too.

[niko-dunixi]

Is it bad that I did the same thing? I started with a fork but ended up starting from scratch so I could get my head around how the MDBook authors intended things to work.

I'm not sure yet, but I don't think this pre-processor was entirely at fault for the rebuild loop. I think it's actually triggering an edge-case in mdbook itself. I'm not 100% certain what triggers it, but I noticed that while I was working on my own preprocessor it was doing essentially the same thing, but never completely consistently.

[hamaluik]

Perhaps? Both this and your project actively create new files, which I don't think is intended by MDBook. I have never triggered a rebuild loop with mine, simply because I pipe the plantuml code directly into plantuml's stdin, and read from the stdout and use that to modify the source directly to use inline svg rather than including a file.

[niko-dunixi]

Maybe they didn't intend so, but I've triggered it with the include preprocessor that comes stock with mdbook so I'm thinking the rebuild loop isn't a fault with the preprocessor itself, so much is it's a problem with mdbook or one of its dependencies.

Based on that, @davidrea, I'd recommend closing this issue as a false positive since this behavior really isn't in the purview of mdbook-plantuml. I've opened an issue on mdbook itself that probably will solve the problem with preprocessors triggering the loop. The generated files aren't allowed to be placed in the final book directory. Hopefully resolving that issue will fix this problem?

Also, nice work @hamaluik :) I don't think I'll end up using it since I have ... like 30+ diagrams in many of my chapters and re-rendering all of them from scratch every time I touch the file doesn't really work for my current use-case, but I definitely like the approach you took!

[sytsereitsma]

Sorry people. For some reason I'm not getting emails from github activity. And I've been busy with other things.

I'm aware of the rebuild loop. The problem is that mdBook > v0.31 deletes the output dir after running the preprocessor, which forces me to place the files in the src dir (introduced with mdBook issue #985).

The mdBook .gitignore file does not work as advertised, so I'll create a solution that only overwrites files when they are changed.

I've sent a PR to mdBook addressing this very issue, but this has not been merged sofar. I'll see if I can entice them to merge that PR.

Again, sorry for the neglect.