Include comment in generated code

[adetaylor]

Feature request: include a comment in generated code to say "generated using autocxx version XYZ from input XYZ" or similar.

[anforowicz]

It might be worth adding a "@" character in there - rustfmt and other tools might be able to recognize @generated in the first few lines and treat the file in a special way. For example see https://rust-lang.github.io/rustfmt/?version=v1.4.38&search=#format_generated_files

[bsilver8192]

I would appreciate if the comment is deterministic (ideally by default, at least with a flag). Version and path are fine, but it's tempting to add a timestamp in a comment like that which I would like a way to avoid.

Bazel caching works a lot better with deterministic code generators. If the generated source file changes, then Bazel doesn't know enough to avoid recompiling it (and everything which #includes the header), and then relinking all the binaries that use it, and then rerunning all the tests that change (sometimes that last one is saved because the binary doesn't include the comment so it ends up identical, but sometimes the comment makes its way into debug info). I have dealt with patching tools, digging around to find flags, and sometimes resorting to running sed afterwards to remove timestamps in similar comments from other tools.

Also, I haven't checked if the output is deterministic already. I'll do that eventually, just asking to not add problems here.

[dmgolembiowski]

I was wondering if we're looking for something like a macro to generate a #[doc = include_ver!(#thing)] tag at each of the relevant Rust codegen spots.

#[doc(hidden)]
#[macro_export]
macro_rules! include_ver {
    ($input:path) => {
        format!("// @generated using autocxx version {}.{}.{}{} for {}",
            env!("CARGO_PKG_VERSION_MAJOR"),
            env!("CARGO_PKG_VERSION_MINOR"),
            env!("CARGO_PKG_VERSION_PATCH"),
            option_env!("CARGO_PKG_VERSION_PRE").unwrap_or(""),
            stringify!($path));
    }
}

Does this roughly cover the need?

[adetaylor]

It's probably simpler than that. No need for a macro. Code in autocxd_engine/src/conversion/codegen_{rs|cpp} literally already writes these files to disk, so it should be a small change to include equivalent comments in that file-writing code's output, with no macro (hopefully!) required though I may be missing something!