What does PackageMaker's "Include root in package" option actually do?

I'm making an installer for an OS X application, but have trouble understanding PackageMaker's UI. My version of PackageMaker is 3.0.4, running along Lion and Xcode 4.1.

One option in particular gets me confused. It's the "Include root in package" checkbox when editing the package's contents. Depending on whether it is checked, some of my package's content开发者_如何学Cs are never installed anywhere.

For example, let's say that my content is a single .app bundle, Confused.app. I want to install it to /Applications (the Destination). What exactly does "Include root in package" mean in this case? If it is left unchecked, the installer does absolutely nothing, as far as I can see.

Is there a better example case that would clarify the option's meaning?

Given the case where the payload (i.e. source item to be installed) is Confused.app (which presumably contains a Contents subfolder with Info.plist, MacOS, Resources, etc inside that), and the install destination is /Applications:

• If you check the "Include root in package" option, it does what you probably expect, namely installs Confused.app into /Applications.
• If you don't check the "Include root in package" option, it installs the contents of Confused.app into /Applications -- i.e. you wind up with a /Applications/Contents folder. This is probably what your test without the option did.

The intended usage with "Include root.." disabled is that you'd create a proxy Applications folder on your build machine, designate that as the payload source, and place the app into that folder. This is more useful if you're installing multiple apps at once, or installing to places other than /Applications (i.e. make a proxy root folder, create Applications and Library/Application Support subfolders, and set the install destination as "/").

Or... (the same answer as above but phrased differently which might make it clearer):

"Include root in package" (IRIP) only applies to directories or things that are directories underneath i.e. application packages and bundles.

When you install a simple file, the IRIP flag is set but greyed out: you have no choice, the named file will be installed at the destination.

When you install a directory, the IRIP flag is not greyed out but editable: - when set: the directory plus its contents are installed at the destination - when clear: only the directory contents are installed at the destination