6 ms·
The V8 team's anti-documentation culture is kind of problematic. As a compiler author targeting JS, it's been consistently difficult to figure out what kind of
by kevingadd 13y ago
The V8 team's anti-documentation culture is kind of problematic. As a compiler author targeting JS, it's been consistently difficult to figure out what kind of patterns V8 optimizes for, what patterns cause problems, and what the hell is going on inside their runtime. The rapid pace of changes to V8 - both new feature additions and system overhauls - means that if you're maintaining a complex project that interacts with V8, you're going to have a really hard time.
They barely document their engine internals or debugging tools, things change randomly making the existing documentation incorrect, and they frequently break the user-facing development tools like Chrome's JS debugger.
The only good things I can really say are that when V8 works, it works marvelously, and that if you can somehow track down a V8 developer they're usually incredibly helpful. Regardless, having to head over to the Google campus and buy a dev coffee isn't a scalable solution to these kinds of problems.
I've basically given up on delivering good performance in V8 as a result. The cost is too high. If I see obvious bottlenecks in their profiler (when it works at all), I tune them, but that's about it. I wasted a handful of weeks digging around in debug builds looking at bailout log entries and trying to decipher their IR using the broken log viewer they recommend, and the net result was that my code ended up faster for a few weeks until V8 changed again. Not worth it.
P.S. When I say 'anti-documentation culture', I mean it. V8 devs have personally told me they dislike documenting certain aspects of V8 and its internals because they fear that end-users and developers will rely on those internals. They lean towards occasional blog posts and Google IO presentation videos to pick up the slack.
- fridek 13y agoTo be fair - I've never seen such docs for SpiderMonkey. I may have just failed at finding them though. Keeping up-to date documentation of compiler is a horrible job. I think it's good enough that V8 may be built as standalone binary with really extraordinary debug options and tools. At the same time, I'd love to see more talks like http://www.youtube.com/watch?v=FrufJFBSoQY http://www.youtube.com/watch?v=FrufJFBSoQY There are also guys who write about V8 from time to time (http://mrale.ph/ http://mrale.ph/ http://floitsch.blogspot.com/ http://floitsch.blogspot.com/ http://wingolog.org/tags/v8 http://wingolog.org/tags/v8) but this is needle-in-a-haystack type of learning.
- kevingadd 13y agoSpiderMonkey isn't a shining city on a hill in this case, certainly. In my experience though the docs that are there are easier to understand, the log messages are more verbose and understandable, and the developers are easier to get help from. I think this is all just a result of the fact that Mozilla relies more on community involvement to get stuff done, so they have to be a bit more dev-friendly. The same dislike of documenting performance details and internals exists on the SM team, though. Standalone binaries with debug options like d8 and spidermonkey js.exe are great for narrowly-scoped tuning and microbenchmarks, but in the real world your app runs in the browser and you end up having to debug and profile it there. That's where the whole picture falls apart (and where Spidermonkey's tools are dramatically better). Mozilla ships two different performance analysis tools for in-browser JS that give you extremely detailed, precise performance information (JIT Inspector and SPS). They're more stable than Chrome's tools on average as well. You can literally get the browser to dump the native assembly it produced when JITting a given function. I haven't done any perf tuning in a while, so this page is probably out of date, but I've made a point of documenting the stuff I discover about each engine, and linking to sources where possible: https://github.com/sq/JSIL/wiki/JavaScript-Performance-For-Madmen https://github.com/sq/JSIL/wiki/JavaScript-Performance-For-M...
- mraleph 13y ago> You can literally get the browser to dump the native assembly it produced when JITting a given function. You can literally get Chrome to dump native assembly it produces when JITting a given function. You just need to build Chromium yourself, because disassembler is not built into it. It's a dead bloat I guess for 99% of people, even for JS VM engineer disassembly is the last resort. You can get compiler IR from any Chrome build and people do get it. And usually it means that VM itself should be fixed. People should not need to care about IR or (worse) disassembly. If your code is reasonable it should just work reasonably fast. File bugs if it does not, instead of tuning, which can break as soon as V8 moves left or right.
- kevingadd 13y agoTo be more precise, the Firefox addon that does this lets you select a specific function and view the assembly on demand, instead of getting a multi-gigabyte IR/assembly dump from a debug build of the browser. That's what makes it useful. I agree that in general users should not need to care about IR or disassembly. Unfortunately, I'm not sure we'll ever end up in that world.
- jamesaguilar 13y ago> V8 devs have personally told me they dislike documenting certain aspects of V8 and its internals because they fear that end-users and developers will rely on those internals. This doesn't strike me as too egregious, personally. I can understand library maintainers taking any steps necessary to prevent people from relying on fluid internals. If anything, this suggests (to me) that the interface might not be rich enough to accomplish what people want. But it isn't a sin to keep documentation of internals private.
- kevingadd 13y agoBy itself there's nothing wrong with it, it just contributes (along with the other problems) to it being very difficult to interact with V8 as a whole.
- harlowja 13y agoI would say in an opensource project like V8 it is a sin. You don't build a community around V8 by doing this. You build a company owned project (of which the company is throwing code over a wall).
- lttlrck 13y ago"V8 devs have personally told me they dislike documenting certain aspects of V8 and its internals because they fear that end-users and developers will rely on those internals." Shamefully in this instance the problem is changes to the public embedders API... so we shouldn't rely on it? Why did they create the API?
- cromwellian 13y agoSometimes later, an API design is found to conflict with design changes that need to be done, that wasn't known at API design time. Sometimes you have to deprecate. I work on GWT. GWT has, since 2008 at least, relied on certain low level details of the NPAPI in browsers for implementing its Development Mode. Both Chrome and Firefox break this API consistently, in fact, Firefox breaks it on every single release. Eventually NPAPI will go away, because it was designed in a bygone era of Flash plugins. Unfortunately, it's not being replaced with anything that solves our use case, nor does PPAPI solve it. I really feel for the author of v8-juice, but it's more important that the browser vendors drive performance and security forward, and given how tightly integrated JS is with the browser, you would have to expect that radical design changes in internals are eventually going to break low level APIs, even if they are public.
- sgbeal 13y agoFWIW, i agree completely that v8 has to serve its primary target, and there was never any illusion that that wasn't Chrome. i'm not mad about them for that. i'm just frustrated at giving up something i put literally thousands of hours into creating, tweaking, and documenting. :/ It is my sincere hope that someone will pick it up and port it.
- arthurdenture 13y agoI'm curious -- why doesn't Super Dev Mode meet your needs?
- bradleyjg 13y agoSuper Dev Mode doesn't work with GWT RPC. Plus as neat a technology as source maps is, and as slick as the browser dev environments are getting, for non-js languages they still aren't equivalent to a full fledged IDE like eclipse.
- iancarroll 13y ago> Regardless, having to head over to the Google campus and buy a dev coffee I thought coffee was free over there ;)
- mraleph 13y ago[disclaimer: I worked on V8] I must say that public facing API is well documented right in the header files. Each class and majority of important functions have long comments[1]. So claiming that V8 has an anti-documenation culture is incorrect. Next I would like to note that V8 is surely open to patches that improve documentation of public V8 interfaces. I don't remember a lot of those patches flying in though. Finally, documenting internals is completely different from documenting API. I don't think it is feasible to maintain such documentation. Internals exist only to rely on them in an extreme cases and in such extreme cases reaching to V8 developers directly or reading the source code is the only way to get correct and what is more important up to date information given how things are constantly in flux. [1] https://code.google.com/p/v8/source/browse/trunk/include/v8.h?r=16177 https://code.google.com/p/v8/source/browse/trunk/include/v8....
- kevingadd 13y agoI apologize if you got the impression I was claiming you don't document your public-facing APIs. I'm talking about V8 as a system; intended behaviors and recommended usage patterns and strategies, documentation of downsides and weaknesses and such. The debug-related parts of the 'public' (? not sure if they're actually public) API were very poorly documented when last I checked, though - some of the debug flags you can pass to d8 were only documented in old obscure blog posts.
- ahomescu1 13y agoThe problem with documenting internals is that it becomes a contract. Developers then start relying on those documented behaviors, and it later becomes much more difficult to change them. It's bad enough as is with developers relying on undocumented behavior, see the troubles Wine (and Microsoft as well) with applications that touch Windows internals.
- harlowja 13y agoIsn't it the right thing to do though? Open source should not be about hiding behaviors behind undocumented code. Open source is about documenting it so that others can learn and jump in and help. It seems totally non-open if this is how V8 is developed.
- AshleysBrain 13y agoIsn't asm.js moving towards standardising a dialect of Javascript that definitely will be optimised well by VMs? Seems like a possible solution to struggling to figure out what V8 does and doesn't optimise well.
- kevingadd 13y agoIf asm.js eventually evolves to support a large enough subset of applications, it does 'solve' this. But it only solves it for people like me who are writing compilers; people trying to write high-performance JS by hand are left out in the cold.
- mraleph 13y agoExcept that right now you are limited to arithmetic and typed array manipulation. Subset like that is predictable because it is taking away all moving dynamic parts. You become free from questions like "where should I put methods? on prototype or on object itself?" not because you have an answer now, but because you can't have objects, prototypes and methods :-) [well you can but you have to emulate them with typed arrays and virtual dispatch tables, it is likely be slower than "native" JS method dispatch].
- ahoge 13y ago>I wasted a handful of weeks digging around in debug builds looking at bailout log entries and trying to decipher their IR using the broken log viewer they recommend, and the net result was that my code ended up faster for a few weeks until V8 changed again. You have the same problem with any other modern JavaScript VM. There is always lots of magic and some heuristics which can easily break. As a result, performance is hard to predict. For what it's worth, Dart fixed that. Predictable performance was one of its main goals/constrains.