Re: PSA: New method for registering XPCOM components
On Wed, Feb 6, 2019 at 2:25 PM Kris Maglione wrote: > >* Perhaps a link (or multiple links) to MDN docs we already > >have on XPCOM components - which may provide an introduction as > >to what they are, when and why they’re used, etc. > > I'm not sure this is a good idea. Docs about Gecko internals on > MDN are generally deprecated, and the ones about XPCOM are > obsolete to the point of being useless. +1, just say no to internal docs on MDN. Documentation that we can auto-generate from the source code directly is preferred over standalone docs, although even in the latter case it's much better to have this live alongside the source code so we know which revision of m-c it applies to. In both cases https://firefox-source-docs.mozilla.org/ should always be used for Firefox internals, and MDN only for web standards and standard-ish things like WebExtension APIs. Speaking of auto-generation, could some/all of the code blocks in https://searchfox.org/mozilla-central/rev/e00ea598e52bbb35f8c45abf9c2eade17962bb5e/build/docs/defining-xpcom-components.rst be generated via autodoc from https://searchfox.org/mozilla-central/rev/e00ea598e52bbb35f8c45abf9c2eade17962bb5e/xpcom/components/gen_static_components.py ? I suspect it'd increase the readability of that file and make it easier to modify if those bits were separated into a Python class anyway. Note that I don't have particularly strong feelings about this, if you think it's easier to keep the docs separate and/or don't expect to change it much in the future then that's fine too. > I'm also a bit leery about mentioning old coding styles in docs > like this, since those kinds of mentions tend to stick around > long after everyone has forgotten that style ever really > existed... Agreed, we're still dealing with fall-out from people getting confused about old add-ons documentation and snippets etc. that look official since they are on MDN. An even better example where this causes confusion over internals is https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Observer_Notifications - that would be a great candidate for auto-generating from source code. > >* An example of ‘old style’ vs. ’new style’ xpcom definition, > > perhaps even a ‘good’ vs. ‘bad’ - but there’s a negative > > connotation there, which may not be preferred. > >* A full example (prolly on a second page would be best), which > > showcases the discrete steps to get from zero to hero. Err, I > > mean new component. > > > >I’m suggesting all this extra work, because I think it will > >actually save you a lot in the future; rtfm is a very simple, > >yet powerful response to all the queries you’re gonna get. > > Again, I'm not sure the linked doc is really the best place for > such things, since the doc is meant to be permanent, and it > would get dated fast. > > I can give examples in this thread, if you think it would be > useful. But given that I've already converted (or have pending > patches to convert) pretty much all of our old-style > registrations, it wasn't clear to me that it would. I would like to see examples in this thread. It'll be as easy to link folks to the mailing list archive, and it'll be clearer that it's ephemeral since it's a mailing list from a specific time period. Thanks again for making this change :) ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: PSA: New method for registering XPCOM components
On Wed, Feb 06, 2019 at 11:31:20AM +0100, Michael de Boer wrote: That looks really neat and a nice step forward! I’m a fan of all the things you’re doing, btw ;-) Cheers. * Perhaps a link (or multiple links) to MDN docs we already have on XPCOM components - which may provide an introduction as to what they are, when and why they’re used, etc. I'm not sure this is a good idea. Docs about Gecko internals on MDN are generally deprecated, and the ones about XPCOM are obsolete to the point of being useless. I'm also a bit leery about mentioning old coding styles in docs like this, since those kinds of mentions tend to stick around long after everyone has forgotten that style ever really existed... * An example of ‘old style’ vs. ’new style’ xpcom definition, perhaps even a ‘good’ vs. ‘bad’ - but there’s a negative connotation there, which may not be preferred. * A full example (prolly on a second page would be best), which showcases the discrete steps to get from zero to hero. Err, I mean new component. I’m suggesting all this extra work, because I think it will actually save you a lot in the future; rtfm is a very simple, yet powerful response to all the queries you’re gonna get. Again, I'm not sure the linked doc is really the best place for such things, since the doc is meant to be permanent, and it would get dated fast. I can give examples in this thread, if you think it would be useful. But given that I've already converted (or have pending patches to convert) pretty much all of our old-style registrations, it wasn't clear to me that it would. On 5 Feb 2019, at 22:12, Kris Maglione wrote: As of bug 1478124, the new preferred method for registering XPCOM components is via static manifest files, as documented here: https://firefox-source-docs.mozilla.org/build/buildsystem/defining-xpcom-components.html And, as of bug 1524688, it will be the preferred method of defining JavaScript components as well as native ones. The primary motivation for this change is to decrease the amount of memory (and, to a lesser extent, startup performance) overhead that component registrations consume in content processes, which would not have been acceptable in the post-Fission world. It has the side-benefit, though, of making most registrations much more straightforward, requiring only a single entry, in a single place, for each component. Thank you to all of the reviewers who had to review a lot of very large patches to make this possible, particularly Nathan Froyd, Eric Rahm, and Mike Conley, on whom I dumped most of the biggest chunks. -- Kris Maglione Senior Firefox Add-ons Engineer Mozilla Corporation All great truths begin as blasphemies. --George Bernard Shaw ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: PSA: New method for registering XPCOM components
Thanks so much for doing this! Having static XPCOM component manifests will be awesome both for Fission memory usage, and just general usability of our codebase into the future. On Tue, Feb 5, 2019 at 4:12 PM Kris Maglione wrote: > As of bug 1478124, the new preferred method for registering XPCOM > components > is via static manifest files, as documented here: > > > https://firefox-source-docs.mozilla.org/build/buildsystem/defining-xpcom-components.html > > And, as of bug 1524688, it will be the preferred method of defining > JavaScript components as well as native ones. > > The primary motivation for this change is to decrease the amount of memory > (and, to a lesser extent, startup performance) overhead that component > registrations consume in content processes, which would not have been > acceptable in the post-Fission world. It has the side-benefit, though, of > making most registrations much more straightforward, requiring only a > single > entry, in a single place, for each component. > > > Thank you to all of the reviewers who had to review a lot of very large > patches to make this possible, particularly Nathan Froyd, Eric Rahm, and > Mike Conley, on whom I dumped most of the biggest chunks. > ___ > firefox-dev mailing list > firefox-...@mozilla.org > https://mail.mozilla.org/listinfo/firefox-dev > ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: PSA: New method for registering XPCOM components
Hi Kris, That looks really neat and a nice step forward! I’m a fan of all the things you’re doing, btw ;-) Whilst reading through the docs you pointed at, I was missing a few things, to be honest: * Perhaps a link (or multiple links) to MDN docs we already have on XPCOM components - which may provide an introduction as to what they are, when and why they’re used, etc. * An example of ‘old style’ vs. ’new style’ xpcom definition, perhaps even a ‘good’ vs. ‘bad’ - but there’s a negative connotation there, which may not be preferred. * A full example (prolly on a second page would be best), which showcases the discrete steps to get from zero to hero. Err, I mean new component. I’m suggesting all this extra work, because I think it will actually save you a lot in the future; rtfm is a very simple, yet powerful response to all the queries you’re gonna get. Cheers, Mike. > On 5 Feb 2019, at 22:12, Kris Maglione wrote: > > As of bug 1478124, the new preferred method for registering XPCOM components > is via static manifest files, as documented here: > > https://firefox-source-docs.mozilla.org/build/buildsystem/defining-xpcom-components.html > > And, as of bug 1524688, it will be the preferred method of defining > JavaScript components as well as native ones. > > The primary motivation for this change is to decrease the amount of memory > (and, to a lesser extent, startup performance) overhead that component > registrations consume in content processes, which would not have been > acceptable in the post-Fission world. It has the side-benefit, though, of > making most registrations much more straightforward, requiring only a single > entry, in a single place, for each component. > > > Thank you to all of the reviewers who had to review a lot of very large > patches to make this possible, particularly Nathan Froyd, Eric Rahm, and Mike > Conley, on whom I dumped most of the biggest chunks. > ___ > firefox-dev mailing list > firefox-...@mozilla.org > https://mail.mozilla.org/listinfo/firefox-dev ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
PSA: New method for registering XPCOM components
As of bug 1478124, the new preferred method for registering XPCOM components is via static manifest files, as documented here: https://firefox-source-docs.mozilla.org/build/buildsystem/defining-xpcom-components.html And, as of bug 1524688, it will be the preferred method of defining JavaScript components as well as native ones. The primary motivation for this change is to decrease the amount of memory (and, to a lesser extent, startup performance) overhead that component registrations consume in content processes, which would not have been acceptable in the post-Fission world. It has the side-benefit, though, of making most registrations much more straightforward, requiring only a single entry, in a single place, for each component. Thank you to all of the reviewers who had to review a lot of very large patches to make this possible, particularly Nathan Froyd, Eric Rahm, and Mike Conley, on whom I dumped most of the biggest chunks. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
