Stream: rustdoc

Topic: cargo-callgraph


view this post on Zulip Robin Moussu (Feb 15 2021 at 18:03):

Hello! Some of you may know may know that I worked last November on a tool whose goal was to extract the callgraph relations between all functions in a given crate: cargo-callgraph. Its input is a tcx, and its output is currently a graph in textual format (so you can pipe the output in graphviz, and get an image). Since it works in a very similar way to rustdoc, the easiest way for me to create a main() in which I have a tcx was to fork rustc, remove everything but librustdoc, then call the entry point to my own code from the main() of librustdoc (and change it to be a binary). Since I’m re-using internals part of rustc (just like rustdoc), I’m expecting to stay forever in nightly, and have to update some things once in a while. But, by forking librustdoc instead of just creating a main() from scratch means that I made my like more complicated than needed by increasing the coupling between the parts that move and my code (all of rustdoc + the part of rustc that I really use). In order to keep the maintenance easy to do, I will have to either:

What should be the best path forward? @Joshua Nelson any input?

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:06):

I think this is a personal decision honestly - do you want your code to be part of rustdoc? I'm certainly interested in showing this somehow, maybe as another mode like --show-coverage

view this post on Zulip Robin Moussu (Feb 15 2021 at 18:09):

Do I want it? That would be really sweet, at the same time I’m not sure the performances will be good enough for real creates (I don’t want to exceed 1mn even for very big project, but that can definitively be too much for rustdoc).

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:10):

I mean rustdoc already has terrible performance lol, I wouldn't dismiss it out just because of that

view this post on Zulip Robin Moussu (Feb 15 2021 at 18:10):

Said otherwise, if I dissociate myself completely from rustdoc, what should I keep in mind to be easy to be integrated later?

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:11):

I don't really understand the question I guess? It will be a ton of work no matter what if you change the fork too much

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:12):

It would be simplest if you had a pass, the same way intra-doc links work, so you can just slot it in later. But I don't know how feasible that is, especially since rustdoc has lots of weird caching that doesn't go through queries

view this post on Zulip Robin Moussu (Feb 15 2021 at 18:20):

Currently my code is completely isolated in a new file (extract_dependencies.rs) with only two public function (and a few public types). As I said, it need a tcx as input, which mean that I modified a bit core.rs to call my code. Finally I removed some stuff from core.rs and lib.rs to make the analysis faster (rustdoc does some useless work for my usecase), as well as enabling a few more nightly features in lib.rs.

I wasn’t expecting any difficulty to rebase my work, but since December rustdoc has a new internal dependency (rustdoc-json-types), and modified quite a bit both lib.rs and core.rs.

view this post on Zulip Robin Moussu (Feb 15 2021 at 18:22):

I know that you gave me some stuff to read about what is a pass, but I totally forgot what this is. Is it something which is in tcx.sess.time("build_call_graph", || { my_code() }) or not at all?

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:39):

I mean a Pass: https://github.com/rust-lang/rust/blob/d1206f950ffb76c76e1b74a19ae33c2b7d949454/src/librustdoc/core.rs#L622

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:40):

I wasn’t expecting any difficulty to rebase my work, but since December rustdoc has a new internal dependency (rustdoc-json-types), and modified quite a bit both lib.rs and core.rs.

I wouldn't expect the new dependency to be a big deal, but yeah since then there's a tcx passed to the render backend which required a lot of restructuring

view this post on Zulip Joshua Nelson (Feb 15 2021 at 18:40):

it might be easiest to just discard your changes to core.rs and lib.rs and add extract_dependencies as a pass without trying to change the framework too much

view this post on Zulip Robin Moussu (Feb 15 2021 at 18:50):

That’s probably a better idea. I will try that.

view this post on Zulip Robin Moussu (Feb 15 2021 at 19:26):

As far as I can tell, I should add a new pass, then activate it by adding it to rustdoc::Options::manual_passes, but I can’t find how to set passes from the command lines.

view this post on Zulip Robin Moussu (Feb 15 2021 at 19:31):

ah maybe it’s because the option exists for rustdoc, but not for cargo doc

view this post on Zulip Joshua Nelson (Feb 15 2021 at 19:38):

You can pass flags to rustdoc with cargo rustdoc -- --some-flag

view this post on Zulip GuillaumeGomez (Feb 15 2021 at 22:54):

I think we should propose it to the rest of the team. I personally think it's a bit too much out of context to be put in rustdoc. Also: it'd require maintenance and a whole test suite, which seems like a lot. Keeping it out of rustdoc seems better in my opinion. @Joshua Nelson seems to think otherwise though, which is why I think we should bring it up to the team.

view this post on Zulip Noah Lev (Feb 16 2021 at 04:32):

Yeah, I agree with Guillaume. This seems like a really great project, but aside from implementation it doesn't have much in common with rustdoc. Perhaps in the future it could be integrated into Cargo (of course, if the Cargo team were okay with it), much like what happened with cargo-tree.

view this post on Zulip Poliorcetics (Feb 16 2021 at 11:57):

It could be integrated to rustc instead of cargo, it seems like a useful capability for anyone compiling rust, not just using cargo

view this post on Zulip Robin Moussu (Feb 16 2021 at 18:09):

but aside from implementation it doesn't have much in common with rustdoc

Currently it doesn’t, but in the future, it could have a soft-link. Given that it’s a graph of function, it makes a lot of sense to create a direct link to the function documentation.

view this post on Zulip GuillaumeGomez (Feb 16 2021 at 18:20):

But it doesn't need to be in rustdoc code base to do so.

view this post on Zulip Robin Moussu (Feb 16 2021 at 19:06):

That’s absolutely right. As long as it’s easy to craft the html link to the pages, I’m fine.

view this post on Zulip GuillaumeGomez (Feb 16 2021 at 19:20):

There are multiple ways to do so, just depends which one you prefer. :)


Last updated: Oct 21 2021 at 20:47 UTC