SeaMonkey:Suite Directory Layout

This document describes the directory layout to be used within the suite/ directory in the mozilla.org source tree.

Do NOT change this document unless SeaMonkey Council people have agreed with what those edits are telling!
You can add your comments or proposals to the Discussion page instead, we're glad to read your opinion there.

Guidelines

• organize things according to function, not according to "how it's built"
• organize locales in a way that works well for "source L10n" (even if that might not fit with the above rule), i.e. all localizable stuff goes into mozilla/suite/locales/en-US/ directories (other locales will have the same structure of files under l10n/<ab-CD>/suite/ in the future)
• themes are kept in suite/themes/<name>/
• use general descriptive names for the components' directories, not "brand" names ("common" instead of "communicator", "browser" instead of "navigator", "mailnews" instead of "messenger", etc.)

Example

main repository:

mozilla/

• suite/
  • branding/ - stuff used for branding the application (mainly artwork)
  • browser/
  • common/
    • prefs/
  • installer/
  • locales/
    • en-US/
      • chrome/
        • [branding|browser|common|mailnews|...]/
      • installer/
  • mailnews/
  • themes/
    • classic/
      • [browser|common|mailnews|...]/
    • modern/
      • [browser|common|mailnews|...]/

L10n repository:

l10n/

• <ab-CD>/
  • suite/
    • chrome/
      • [branding|browser|common|mailnews|...]/
    • installer/

IRC discussion snippets

[2006-01-17 07:00 PST] - topic: suite/ organization

<KaiRo> bsmedberg: you seemed to have a preety good image in mind when discusssing some "move to suite/" stuff a few months back... now that plans are getting more concrete on our side, can you give us some good rules to follow for the directory structure, so that we are a "good citizen" in your eyes?
<bsmedberg> KaiRo: organize things according to function, not according to "how it's built"
<bsmedberg> KaiRo: so instead of "suite/components" (which is basically meaningless)
<bsmedberg> use suite/printing and suite/ui
<bsmedberg> or something like that
<KaiRo> bsmedberg: with locales being somewhat an exception to that rule, right?
<bsmedberg> yeah
<bsmedberg> KaiRo: same thing for content files... instead of suite/content/*
<bsmedberg> KaiRo: use suite/global
<bsmedberg> (which is what xpfe/ does now, better than toolkit/)
<KaiRo> bsmedberg: suite/branding/content/ or suite/mailnews/content/ is okay, I guess? (so that some src/ or whatever can be placed next to the XUL content/)
<bsmedberg> That's fine if desired, though actually not necessary
<bsmedberg> IMO at least
<KaiRo> bsmedberg: so you'd place the XUL files directly in suite/mailnews/ or suite/browser/?
<bsmedberg> KaiRo: that depends on the size of the directory
<bsmedberg> KaiRo: suite/browser should almost certainly have some internal organization or it will be too large
<bsmedberg> as should suite/mailnews
<bsmedberg> but that organization need not be content/ src/ public/ subfolders
<KaiRo> bsmedberg: I guess so... though the current habit of xpfe to use an extra resources/ hierarchy does sound too much to me (e.g. xpfe/browser/resources/content/ atm)
<bsmedberg> yes, resources/ is too much
<KaiRo> bsmedberg: btw, how do you think we should handle themes? we'll likely will still deliver two themes, should those go inside the function-based dirs or into a suite/themes/ that is structured like themes/ is now? (I guess we should move out of the global themes/ dir as well)
<bsmedberg> KaiRo: I personally think that they ought to live in the function-based directories
<bsmedberg> KaiRo: but many people disagree with me, so you may pick suite/themes if your team thinks that's better
<KaiRo> bsmedberg: ok, we'll discuss that... how would you organize two themes in the function-based dirs? or is the reply just "I wouldn't do two themes"?
<bsmedberg> KaiRo: you have several options -- 1) start bug 305746 right now for suite (probably not the most expedient choice)
<bsmedberg> and then your default (presumably classic) theme would actually be in content/
<bsmedberg> 2) have dir/themes/classic and dir/themes/modern
<bsmedberg> 3) have dir/classic and dir/modern
<bsmedberg> 2) is probably best

[2006-02-06 18:00 PST] - topic: locales/ structure

<KaiRo> gandalf: could you give me some clue about what structure we need for source L10n? we've been discussing if it needs to be suite /locales/ or could be suite/<component>/locales/ as well, and I've been wondering what implications that might have for the dir structure in /l10n repository... could you shed some light on that?
<gandalf> hmm
<gandalf> in your case...
<gandalf> KaiRo: what are the chances that someone will want to build seamonkey without a mail?
<gandalf> or browser?
<gandalf> or chatzilla?
<gandalf> or another component?
<KaiRo> gandalf: well, we want to be able to do that... on the other hand, I'd probably like to ship the same en-US.jar in all cases... chatzilla is in a seperate structure anyways
<gandalf> so, I see no reason to put locales in components
<gandalf> rather use locales as one of the components
<gandalf> so
<gandalf> suite/locales/browser/
<gandalf> erm
<gandalf> suite/locales/en-US/chrome
<KaiRo> suite/locales/en-US/chrome/browser actually :)
<KaiRo> (and others in the same structure, of course)
<gandalf> yes
<KaiRo> I'd just like to know what path change it might have in /l10n if we'd like to use suite/browser/locales/en-US/chrome instead (not that I myself want it, but I have to explain it to the others)
<gandalf> well, if you'd switch to this
<gandalf> it's not a big deal for localizers
<gandalf> they'll just to ./ab-CD/suite/browser/chrome/ instead of ./ab-CD/suite/chrome/browser
<gandalf> but <
gandalf> it would make a pain for you to maintain l10n module code
<gandalf> etc. more locale makefiles
<gandalf> etc.
<KaiRo> gandalf: true... and separate jar.mn files... but some developers would actually like that better
<gandalf> I'm trying to figure out possible cons
<KaiRo> thanks... I for myself still feel better with suite/locales but not everyone is sure of that...
<gandalf> ok
<gandalf> what about strings shared between components?
<gandalf> where those would land?
<KaiRo> gandalf: that might even be spread across multiple directories, most will have the related XUl in suite/common/ though
<gandalf> ah, ok
<gandalf> so suite/common/locales ?
<gandalf> because otherwise, if you'll not build a component, you're dead
<KaiRo> gandalf: our directory structure is defined by http://wiki.mozilla.org/SeaMonkey:Suite_Directory_Layout - but you might note that we don't have concrete stuff there yet for locales
<KaiRo> gandalf: sure, suite/common/locales would exist then... maybe others as well though, as suite/branding/locales or so
<gandalf> In my opinion it's too much splitting
<gandalf> locales is a module
<gandalf> and I'd like to think of it like that
<gandalf> of course if we have optional components that are enough big to have it's own component dir and have a lot of l10n, those should use it's own locales dir
<gandalf> but usually
<gandalf> product/locales is ok
<KaiRo> Id feel better with that as well... OTOH, having all browser files in suite/borwser and all branding stuff in suite/branding has its good things as well
<gandalf> we use flock/locales in Flock
<gandalf> but we're way smaller than Seamonkey
<KaiRo> suite will build multiple locales/ dirs from all over the tree anyways, as we'll have all the core files, editor files, eventually chatzilla/venkman/inspector (what way ever they'll go in the future), possibly calendar - and last not least toolkit, once we'll use it
<KaiRo> (add reporter to the extensions-like crowd) [...]
<KaiRo> gandalf: but to come back, the main argument against suite/<component>/locales/ is that it's more complicated in our original /mozilla tree, right?
<gandalf> yes
<KaiRo> ok, good to know