Skip to content

Add-on packaging – Manifests revisited and wiki

I’ve been spending some time working on the new wiki for the Add-on Packaging Spec. Here it is.

At the moment I’m writing the complete manifest file specification, basically copying and adapting the current specifications for install manifests and chrome manifests. I’m pretty much done with the former, and will be adding the latter probably tomorrow.

After receiving lots of feedback regarding the manifest format, I agreed to take the manifest file the XML way. I followed JJ Barton’s suggestion of using HTML instead of a custom XML format, which leads to a very simple and familiar manifest format, with some very nice visualization options. This is the first time I’ve used the :before pseudo-class and the CSS content property, and I must say that they blew me away, limited as the latter is. Cool stuff.

If you want to discuss the pros and cons of the HTML manifest format, please fire away in the comments. I will be adding more content to the wiki as the project progresses.

{ 15 } Comments

  1. Mossop | 2010/05/25 at 9:59 PM | Permalink

    I’m really not sure what you see as the benefits of using what you call HTML for this in favour of custom XML tags.

    I can see some basic editor support except that by requiring valid XML you’ll probably find that many editors will generate files that aren’t valid. Even when handwriting I’ve seen developers be very frustrated when they have to close all their tags that they are used to the browser just handling.

    Familiarity is a nice thing but I don’t understand how you get that by using HTML tags for purposes which they weren’t intended. I understand how to write a document in HTML because the tags make sense. Without looking at your spec I couldn’t guess what tag I’d use for an add-on ID.

    I really think it would make more sense to get a better consensus on what format the manifest should be before diving into the project, that way the outcome of the project could actually be a landable patch rather than just a set of lessons learnt and a load of extra work that could have already been done.

  2. Benjamin Smedberg | 2010/05/25 at 11:44 PM | Permalink

    I still don’t understand why you need a new manifest. Each addon already has a manifest. The extension JAR file has an internal directory structure which we can easily query. Why can’t we just use the existing manifests directly, instead of repackaging the data into yet another new format?

  3. Daniel Glazman | 2010/05/26 at 1:29 AM | Permalink

    Being an heavy user of install.rdf and chrome manifests, I have two sort of comments based on not only my personal experience but also the experience of all my customers and the engineers I trained on moz. Some comments are related to the formats, the others are related to the features.

    1. install.rdf is ultra-painful. To paraphrase Cato, “RDF delenda est”, honestly. This is the kind of magic people just _hate_ when I am giving a course to engineers about Mozilla’s underlying specs. I want to see install.rdf die and replaced by something more readable, with no namespaces, no magic, something that is trivially parseable and manageable, something trivially notepadable, something trivially generated by an online generator. In that sense, JSON or a **dead simple** new xml dialect is ten times more preferable than RDF. I have the gut feeling JSON is better than yet another xml dialect. I am totally opposed to xhtml here: an xhtml microformat is conceptually nice, but practically useless and even possibly painful because of the learning curve and the variability of such manifests; editability in an xhtml editor is pointless, IMHO.
    The fact a tool like McCoy completely shakes an install.rdf when it signs it – and I perfectly understand it’s perfectly valid to do it – is very badly received by some addons authors who don’t masterize install.rdf’s and RDF’s magic.
    I hope JSON can contain JS comments à la /* … */ ?

    2. chrome.manifest and jar.mn also have their magic. The latter require declaration of all registered files while the former can hold directory declarations. Declarations of resource:// URLs are an alien in these files and most people get it wrong at least once. The presence of “classic/1.0″ in skin registrations is not understood by the people I am training. I recommend a merge between chrome.manifest and jar.mn under one name only with serious cleanup and the ability to declare only dirs in both addons and app chrome registration.
    On a more positive note, creating and editing a chrome manifest is ten times easier than creating and editing install.rdf. XML dialects are not always the best choice for notepadability and maintainability.

    3. I am not sure I want to merge again install.rdf and chrome registrations. We went from that long ago and that was a good move.

    4. flags in chrome manifests are often not understood ; this is probably more related to a lack of easily found documentation than a flaw in the format itself, but still it’s interesting to note that many addon authors don’t get them.

    5. visualizing and styling manifests is a neat idea, but I think it’s not worth the learning curve of a new microformat. If manifests are kept dead simple and trivially parseable and readable, it’s a non-issue and JS will handle that in just a few lines of code anyone could write.

  4. jorge | 2010/05/26 at 11:55 AM | Permalink

    @Mossop:
    There’s no file format you can come up with where everything is so straightforward that you don’t need a reference. I mention in the parsing section that what will really matter is the element ids, and the parser will be flexible with tag names.
    Coding for GSOC began yesterday. As I mentioned in the introductory post, this all materialized rather quickly, and I didn’t have the time to ask for proper consensus. I also think that changing the file format is not that difficult a change once the project is done. Nobody was working on this, or even planning on working on this as far as I know, so I think anything this project produces will be a gain over the current state of affairs.

    @Benjamin Smedberg:
    The objective of the project is to simplify add-on development by creating a new manifest format and making the internal layout of add-on packages more flexible. Little is left of it if the new manifest was discarded.

    @Daniel Glazman:
    1. What do you mean about variability? Why do you think the learning curve would be worse than with a custom XML format?
    JSON parsers don’t support /* … */. Supremely stupid, I know.
    2. Covering manifest files inside the application is outside of the scope of this project.
    3. Can you explain the reasons for the separation? Anything that would concern add-on developers?
    4. They’re well documented at MDC, but finding this doc can be very difficult, I agree. It’s probably poor naming of the doc. https://developer.mozilla.org/en/Chrome_Registration#Manifest_Flags

    @Everyone: thanks for the input. I think changing the manifest format and the parser won’t be too difficult even after the project is done, specially considering most of us now agree that the file should be some form of XML. What matters to me most is that the general idea makes sense, and that the new format can cover everything the current one does. The project is already underway, so I’ll be more conservative about spec modifications from now on. Thanks again, and let’s keep the conversation going :)

  5. Ms2ger | 2010/06/01 at 9:56 AM | Permalink

    “The manifest file is laid out as HTML in order to facilitate the work for developers. However, there’s no need to use an HTML parser to process the file, since it will only be used to extract data out of it.”

    That’s ridiculous. If you’re going to use HTML (for which I haven’t seen any good arguments), you’ll need an HTML parser. If you’re going to require XML, it makes a lot more sense to use a custom format, with elements that actually makes sense for an add-on manifest.

  6. jorge | 2010/06/01 at 10:03 AM | Permalink

    Ms2ger: Care to provide any reasons behind your arguments?

  7. mawrya | 2010/06/01 at 11:59 AM | Permalink

    I agree with the choice for XML. I’m not so sure about XHTML. The benefits cited are “simple”, “familiar” and “very nice visualization options”. Wouldn’t custom XML would be more simple?

    chrome/packagingspec/locale/en-US/
    en-US

    is not as simple as

    The benefit of being “familiar” I can understand. But it’s only the HTML tag names that are familiar. Authors still have to learn the specific HTML layout: put p tags inside li tags and those p tags need to have class attributes with specific values, etc. I would happily trade familiar tag names for custom XML tags that describe the content concisely and semantically (the p tags in the XHTML do not contain paragraphs).

    The final benefit of providing visualization options is nice. I like it. But this could easily be achieved with a custom XML format and a CSS file as well, right?

    Whatever you decide, congratulations, and keep up the good work!

  8. mawrya | 2010/06/01 at 12:01 PM | Permalink

    Opps. I looks like this comment system does not like to display markup. Are there some specific escaping rules one needs to follow to do so?

  9. jorge | 2010/06/01 at 12:05 PM | Permalink

    I think you need to use HTML entities, like &lt; to get a <.
    I can understand what you meant in your previous comment, though. Thank you for your feedback and support!

  10. sys | 2010/06/03 at 3:40 AM | Permalink

    I have a preference for xml format (replace brackets by < ) :
    [ol id="target-applications"]
    [li]
    [p class="application-id"]{ec8030f7-c20a-464f-9b0e-13a3a9e97384}[/p]
    [p class="min-version"]3.6[/p]
    [p class="max-version"]4.0.*[/p]
    [/li]
    [li]
    [p class="application-id"]{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}[/p]
    [p class="min-version"]2.1[/p]
    [p class="max-version"]2.1.*[/p]
    [/li]
    [/ol]

    [target-applications]
    [target-application]
    [id]{ec8030f7-c20a-464f-9b0e-13a3a9e97384}[/id]
    [min-version]3.6[/min-version]
    [max-version]4.0.*[/max-version]
    [/target-application]
    [target-application]
    [id]{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}[/id]
    [min-version]2.1[/min-version]
    [max-version]2.1.*[/max-version]
    [/target-application]
    [/target-applications]

    In my opinion the second format is the best :
    * It’s more compact and simple to read in a text view.
    * You have no more element dtd to know : the learning curve is the same.
    * You can use css for preview in same manner as the html format.
    * It’s an xml formal format, it’s easy to validate (dtd, relax ng…), it can be important for ide tools.
    * It’s more simple for ide tools to build and parse xml files than html files.

    (sorry for my awfull english)

  11. sys | 2010/06/03 at 3:42 AM | Permalink

    Sorry my comment is not easy to read : space indent and CR are loosed…

  12. mawrya | 2010/06/03 at 7:09 PM | Permalink

    @sys

    Not bad. Though I would recommend putting “non-extensible” data values in attributes. It’s easier to read, makes for smaller files, and that’s what attributes are for. More like this:

    [target-applications]
     [!-- Firefox --]
     [application id="{ec8030f7-c20a-464f-9b0e-13a3a9e97384}"]
      [versions min="3.6" max="4.0.*"/]
     [/application]
    [/target-applications]

    And I think Jorge is really proposing an xhtml format, not html, so no need to worry about parsing and validating issues.

  13. sys | 2010/06/05 at 2:49 AM | Permalink

    I’m agree with attributes benefits. But it’s more difficult to render with pure CSS. XSLT is then probably necessary. In my opinion, adding an XSL is a good solution, but I’m not sure that everyone like xsl…

  14. Mithgol the Webmaster | 2010/06/09 at 1:29 AM | Permalink

    Seriously, you should stay in awe about the delightful simplicity of chrome manifests and create a new format as easy to write and to edit.

    For example, you start with the following horrible bloat:

    «?xml version=”1.0″?»
    «RDF xmlns=”http://www.w3.org/1999/02/22-rdf-syntax-ns#”
      xmlns:em=”http://www.mozilla.org/2004/em-rdf#”»
      «Description about=”urn:mozilla:install-manifest”»
        «em:id»helloworld@xulschool.com«/em:id»
        «em:name»XUL School Hello World«/em:name»
        «em:description»Welcome to XUL School!«/em:description»
        «em:version»0.1«/em:version»
        «em:creator»Appcoast«/em:creator»
        «em:homepageURL»https://developer.mozilla.org/en/XUL_School«/em:homepageURL»
        «em:type»2«/em:type»
        «em:targetApplication»
          «Description»
            «em:id»{ec8030f7-c20a-464f-9b0e-13a3a9e97384}«/em:id»
            «em:minVersion»3.0«/em:minVersion»
            «em:maxVersion»3.6.*«/em:maxVersion»
          «/Description»
        «/em:targetApplication»
      «/Description»
    «/RDF»

    and you may get the following bright future:

    # This is a comment.
    extid    helloworld@xulschool.com # This also is a comment.
    extname  XUL School Hello World
    extdesc  Welcome to XUL School!
    extver   0.1 # White spaces of all kinds (even nbsp) would be stripped before and after the keyword
    creator  Appcoast
    homepage https://developer.mozilla.org/en/XUL_School
    target   {ec8030f7-c20a-464f-9b0e-13a3a9e97384} 3.0-3.6.*, 3.7a5pre # Firefox
    # Note: here Firefox 3.7a4 users will not get automatic updates to this experimental version,
    # presumably targetet for stable and nightlies only (not for alpha versions).

    No XML / XHTML / HTML will ever be easier.

  15. Mithgol the Webmaster | 2010/06/09 at 1:59 AM | Permalink

    Adblock Plus is kinda reference example here, so please have an example of Adblock Plus RDF manifest converted to that flat format:

    extid       {d10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d}
    extver      1.2
    extname     Adblock Plus
    extdesc     Ads were yesterday!
    creator     Wladimir Palant
    homepage    http://adblockplus.org/
    contributor Rob Brown
    contributor Nickolay Ponomarev
    contributor Fabrice Desré

    # Note [em:name]Adblock Plus[/em:name] is not repeated in locales below: should be inherited

    [ar] extdesc الإعلانات أصبحت من الأمس!
    [bg] extdesc Рекламите бяха вчера!
    [ca] extdesc Els anuncis eren ahir
    [cs] extdesc A reklamy jsou minulostí!
    [da] extdesc Reklamer er fortid!
    [de] extdesc Werbung war gestern!
    [el] extdesc Αφήστε τις διαφημίσεις στο χθες!
    [en-GB] extdesc Ads were yesterday!
    [en-US] extdesc Ads were yesterday!
    [es-AR] extdesc ¡La publicidad es cosa del pasado!
    [es-ES] extdesc La publicidad es cosa del ayer
    [fi] extdesc Mainokset ovat menneisyyttä!
    [fr] extdesc Les publicités, c’est du passé !
    [fy-NL] extdesc Fan no ôf gjin reklames mear!
    [gl] extdesc Os anuncios son cousa do pasado!
    [he] extdesc הפרסומות שייכות לעבר!
    [hr] extdesc Oglasi su prošlost!
    [hu] extdesc A reklám a múlté!
    [hy-AM] extdesc Գովազդները երեկ էին!
    [id] extdesc Iklan telah berlalu!
    [is] extdesc Auglýsingar eru hluti af fortíðinni!
    [it] extdesc Permette di dire ‘no’ alla pubblicità presente nelle pagine web!
    [ja] extdesc 広告は過去の遺物です!
    [kk-KZ] extdesc Жарнамаға жол жоқ!
    [ko] extdesc 광고, 이제 안녕!
    [mn] extdesc Сурталчилгаа бол өчигдөр байлаа!
    [ms-MY] extdesc Iklan semalam!
    [nl] extdesc Reclames behoren tot het verleden!
    [pl] extdesc Powiedz NIE! reklamom
    [pt-BR] extdesc Propaganda indesejada é coisa do passado!
    [pt-PT] extdesc Publicidade… já era!
    [ro] extdesc Elimină publicitatea din paginile web.
    [ru] extdesc Скажи «нет» рекламе!
    [sk] extdesc Reklamy sú minulosťou!
    [sl] extdesc Oglasi so preteklost!
    [sr] extdesc Рекламе су прошлост!
    [sv-SE] extdesc Säg farväl till all reklam! Med Adblock Plus kan du välja att filtrera bort all reklam – reklam som tar både tid och kapacitet att ladda ner…
    [th] extdesc ลาก่อนพวกโฆษณา!
    [tr] extdesc Reklamlar geçmişte kaldı!
    [uk] extdesc Скажи «НІ» рекламі! # Note: lowercase «ні» would resemble English «hi» less :-)
    [vi] extdesc Quảng cáo đã là dĩ vãng!
    [zh-CN] extdesc 广告已成往事!
    [zh-TW] extdesc 廣告已成過去式!

    translator Ahmet Serkan Tıratacı
    translator Dagobert_78
    translator Hrvoje Majer
    translator Jakub Tománek
    translator Joni Heinonen
    translator Jose Sun
    translator Ján Kendi (Jacen)
    translator KNTRO
    translator Ken
    translator Kristján Bjarni Guðmundsson
    translator Leonid
    translator Leszek(teo)Życzkowski
    translator Luana Di Muzio
    translator Manuel Meixide
    translator Mark Tyndall
    translator Martin Srebotnjak
    translator Mikes Kaszmán István
    translator Nguyễn Mạnh Hùng
    translator Premier
    translator Raul Pimentel
    translator Schuzak
    translator SiiiE
    translator Urko
    translator Wim Benes
    translator Wladimir Palant
    translator blackdire
    translator catcat
    translator el_libre http://www.catmidia.cat
    translator jojaba
    translator kapetance
    translator markh
    translator maybee
    translator pirlouy
    translator pitdicker
    translator rookie
    translator sushizang
    translator Бауржан Муфтахидинов
    translator Владимир Палант
    translator ДакСРБИЈА
    translator Ивайло Йовчев (s0urce)
    translator Тимофій Бабич
    translator Էդուարդ Բաբայան (edo248)
    translator مؤيد مارديني

    # Front End Integration Hooks (used by Extension Manager)
    icon    chrome://adblockplus/skin/adblockplus.png
    about   chrome://adblockplus/content/ui/about.xul
    options chrome://adblockplus/content/ui/settings.xul

    # Target Application this extension can install into,
    # with minimum and maximum supported versions.

    # FireFox
    target {ec8030f7-c20a-464f-9b0e-13a3a9e97384} 3.0.12 – 3.7a5pre
    # Note: dash in «3.0.12 – 3.7a5pre» should probably be space-separated,
    #       not to be confused with «3.0.12-» → «3.0.12-3» → «3.0.12-3.7» → …
    # This is an amendment to my previous «Appcoast» mock-up manifest logic.

    # SeaMonkey
    target {92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a} 2.0 – 2.1a1pre

    # Thunderbird
    target {3550f703-e582-4d05-9a08-453d09bdfdc6} 3.0 – 3.2a1pre

    # Songbird
    target songbird@songbirdnest.com 1.4.0 – 1.8.0a

    # Midbrowser
    target {aa5ca914-c309-495d-91cf-3141bbb04115} 0.2 – 0.3

    # eMusic Remote
    # Currently not supported – based on Gecko 1.8.1
    # target dlm@emusic.com 1.0 – 1.0.0.*

    # Conkeror
    target {a79fe89b-6662-4ff4-8e88-09950ad4dfde} 0.1 – 100.0
    # Conkeror developers will take care of UI integration themselves

    # Prism
    target prism@developer.mozilla.org 1.0b1 – 1.0.*

    # Fennec
    target {a23983c0-fd0e-11dc-95ff-0800200c9a66} 1.0 – 1.1.*

{ 1 } Trackback

  1. Xulforge Blog | 2011/03/16 at 7:24 PM | Permalink

    [...] Add-on packaging – Manifests revisited and wiki [...]

Post a Comment

Your email is never published nor shared. Required fields are marked *