As an epic bout of yak shaving draws to a close, Searchfox's pre-alpha
diagramming functionality can now be enabled from the Searchfox settings
page at https://searchfox.org/mozilla-central/pages/settings.html under
a (misnamed) alpha quality gate.
There are a lot of significant caveats. I'm announcing what's available
now because it could unfortunately take quite some time to get
diagramming to the alpha quality bar and I think this functionality
could be useful in a sanity-preserving way to a number of people in the
meantime.
The very large caveats:
- There is no screen reader support at this time and this functionality
otherwise does not meet Searchfox's accessibility bar. The diagrams
that are produced are SVG which have a useless accessibility tree and
the nodes are not in the tab order. I've filed
https://bugzilla.mozilla.org/show_bug.cgi?id=1810696 with my current
thoughts on how I might implement a first class screen reader experience
that I think could broadly improve accessibility as it would not depend
on the visual encoding of the information or require random access x,y
mouse positioning with clicking on the graph. Providing an accessible
experience is a top priority for me (but this all is largely
nights/weekends/PTO stuff, unfortunately).
- Although the functionality is not C++ specific, only the C++ language
analysis has the required fidelity right now. This could easily work
for our Rust or JS code, including supporting call graphs across
language boundaries. (Searchfox already understands XPIDL enough to do
the JS/C++ glue; it needs some help for the Rust bindings still.)
- All the graphs will have a default traversal depth of 4 by default.
You need to change the query string if you want more or less depth. You
can make the depth limit as high as you want but Searchfox will get
bored after 256 nodes. Searchfox finds high fan-out nodes gauche and
will refuse to traverse those edges, but will claim it's something to do
with a local limit of some kind. In general
https://bugzilla.mozilla.org/show_bug.cgi?id=1773165 will improve things
so we can stop at subsystem boundaries automatically and otherwise have
helpful heuristics.
- You're going to need to scroll to the right a lot, because that's
where the interesting part of graphs hang out.
- The graph only knows what Searchfox knows. Searchfox has some gaps in
its understanding of template related things.
https://www.visophyte.org/blog/2022/11/10/andrews-searchfox-roadmap-2022/
has some more details about things like that.
- Even though it looks like you can only select the text on the graph
nodes, they actually will pop up your normal Searchfox context menu when
you click on them. But as a side-effect you can copy and paste
identifiers, which is nice.
- Actually, that's not your normal Searchfox context menu. Part of the
yak shaving was overhauling things as part of
https://bugzilla.mozilla.org/show_bug.cgi?id=1776522 so now the context
menu has a lot more understanding of what's going on with IDL and also
cares about declarations, so you may notice that if you click on symbols
in .ipdl and .idl files you may get some much more precise context menu
options. This will also now enable us to do the thing where we can link
to the Telemetry website and the Crash-stats website and just all kinds
of websites. You'll be accidentally ordering pizzas with random
toppings from the atom table, it'll be great.
- Searchfox just cares about references to functions, it's not hung up
on whether you actually call the function. It similarly is not
impressed by your lambas and will pretend that they don't exist. In
general this works out fine because if you reference a function in a
function, you're probably setting things up to call that function.
- Searchfox does not yet understand indirect function call idioms like
that when you create and dispatch a runnable class that you're causing
its "Run" method to be asynchronously invoked in the future. (It does
understand that IPC Send/Recv calls are paired though and it will try
and ignore the IPC infrastructure underpinning how your Recv method gets
called, although it can get tricked by some cross-platform signature
variations at the current time.)
https://bugzilla.mozilla.org/show_bug.cgi?id=1776522 tracks dealing with
this at a high level too, although Searchfox will need some help with a
manual knowledge-base or annotating classes with some doxygen markup or
something to figure out what's going on with some indirect calling patterns.
Notes that aren't caveats:
- When diagramming is enabled, it will show up as the last item(s) in
the context menu.
- You can diagram fields. The first set of nodes are all the functions
that reference that field. Then all the nodes beyond that are the
functions that reference/call those functions.
- The "query" endpoint server that powers the graphing is its own
process. If I somehow, inconceivably, left an unwrap() in there, this
process could fall over and it won't come back until the server rotates
every ~12 hours. The good news is that this will not take down any
release quality searchfox functionality.
- This will probably work on Searchfox's webkit index
https://searchfox.org/wubkat/source/ when that updates.
Andrew
--
You received this message because you are subscribed to the Google Groups
"[email protected]" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/a/mozilla.org/d/msgid/dev-platform/a7e9c3aa-635a-6cf9-6f11-1b5f83b370fb%40asutherland.org.
