Need to document how to deal with gitignore scenario(s)

[pnkfelix]

Tango doesn't actually currently say what work flow is recommended, in terms of whether you should check in the .rs files, the .md files, or both.

• I personally always thought it was cute being able to just check in the .md files, but I am not 100% sure that relying on those alone is robust for crates intended to be used as imported libraries (see e.g. Timestamp issues for upstream crates on http repo #10 for a potential problem here, though that has not been confirmed to my satisfaction).

Anyway, if one does choose to check in only .rs files or only .md files, then usually one will want to have .gitignore set up to ignore the other build products.

However, cargo currently will seed the initial setting for its exclude based on .gitignore (see http://doc.crates.io/manifest.html#the-exclude-and-include-fields-optional ). This means that cargo won't bother rebuilding or even re-running tango in response to the changes to generated files, even though the whole point of tango is to ensure that happens.

Therefore, it is super important that tango document how to deal with this. I have repeatedly run into the issue where I put *.md into the .gitignore and then am confused as to why nothings being rebuilt.

---

(In addition, it is possible, but I have not yet confirmed, that the recent changes for #18 to emit rerun-if-changed will actually sidestep all of this? I don't know what takes precedence if a file listed by rerun-if-changed is also in the exclude directive.)

[Screwtapello]

I've done some experimentation with this myself, and here's what I've learned.

I'm working on a little project with Tango, and I've chosen to check in src/main.md and git-ignore src/main.rs. My build.rs just calls tango::process_root() as suggested in the Tango demo project.

At first, after deleting tango.stamp and src/main.rs cargo failed to build because there were no .rs files in src/ at all, and it didn't know whether to build a binary or a library. Adding a [[bin]] section to Cargo.toml fixed that problem.

After that, when I delete tango.stamp and src/main.rs then run cargo build, the project builds correctly.

If I then modify the .mdfile and re-run cargo build, the .rs is regenerated and the project builds correctly.

On the other hand, if I modify the .rs and re-run cargo build, Tango is not re-run and the change is not propagated back to the .md file. This aligns with what this issue says about Cargo ignoring git-ignored files by default.

However, this issue also talks about the build-script emitting a "rerun-if" directive that could work around this issue. This doesn't appear to be the case; when I run "cargo build -vv" I see the output of the build-script, and it always prints:

emit rerun if: false

...so I guess it's not printing the rerun-if directive at all.

Examining Tango's source-code, it looks like I can ask it to emit the rerun-if directive by modifying my build.rs script:

let mut config = tango::Config::new();
config.emit_rerun_if();
    
tango::process_root_with_config(config)
    .expect("Could not process literate Rust files");

After making that change, modifying either the .md or .rs files causes build.rs to be re-run before building the project.

I'd be happy to write this up as more formal documentation if you could point me to where it should go. Alternatively, perhaps Tango should just be changed to make "emit-rerun-if" mode the default.