BundleUtilities: error if fixup_bundle_item called on non-embedded item

Also, improve the documentation of the fixup_bundle and fixup_bundle_item
functions to clarify that plugin type "libs" need to be copied into
the bundle *before* calling fixup_bundle.

Commit e93a4b4d3421ced7b8c852b76c0dcb427f798df8 changed the way that
the libs parameter to fixup_bundle is interpreted. Before the commit,
the libs were copied into the bundle first and then fixed up. After
the commit, the copy was skipped, assuming the libs were in the bundle
in the first place, and then the fixups occurred as before.

However, before the commit, it was possible to name a lib from outside
the bundle, and have it copied in and then fixed up. Its resolved
embedded name was always inside the bundle before. After, its resolved
embedded name was just the same as its resolved name, which is in its
original location, and not necessarily inside the bundle.

This manifested itself as a problem with the ParaView call to
fixup_bundle and its many plugins. Previously, ParaView had simply
passed in the list of plugin file names as they existed in the build
tree, and left the copying into the bundle up to the fixup_bundle
function. When built with CMake 2.8.3 (the first version to contain
the above named commit) the fixup_bundle call would inadventently
fixup libraries in the build tree, not libraries that were in the
bundle. Furthermore, the plugins would not be in the final bundle.

This points out the fact that the fix for the bugs made by the above
commit was a backwards-incompatible change in behavior.

This commit makes it an error to try to fixup an item that is not
already inside the bundle to make the change in behavior apparent
to folks who were depending on the prior copy-in behavior: now,
they should get an error, and hopefully, reading the new and
improved documentation, should be able to resolve it in their
projects by adding code to install or copy in such libraries prior
to calling fixup_bundle.

Whew.

Modules/BundleUtilities.cmake

@@ -27,6 +27,11 @@
 # drag-n-drop copied to another machine and run on that machine as long as all
 # of the system libraries are compatible.
 #
+# If you pass plugins to fixup_bundle as the libs parameter, you should install
+# them or copy them into the bundle before calling fixup_bundle. The "libs"
+# parameter is a list of libraries that must be fixed up, but that cannot be
+# determined by otool output analysis. (i.e., plugins)
+#
 # Gather all the keys for all the executables and libraries in a bundle, and
 # then, for each key, copy each prerequisite into the bundle. Then fix each one
 # up according to its own list of prerequisites.
@@ -112,6 +117,13 @@
 # _EMBEDDED_ITEM keyed variable for that prerequisite. (Most likely changing to
 # an "@executable_path" style reference.)
 #
+# This function requires that the resolved_embedded_item be "inside" the bundle
+# already. In other words, if you pass plugins to fixup_bundle as the libs
+# parameter, you should install them or copy them into the bundle before
+# calling fixup_bundle. The "libs" parameter is a list of libraries that must
+# be fixed up, but that cannot be determined by otool output analysis. (i.e.,
+# plugins)
+#
 # Also, change the id of the item being fixed up to its own _EMBEDDED_ITEM
 # value.
 #
@@ -527,6 +539,24 @@ function(fixup_bundle_item resolved_embedded_item exepath dirs)
   #
   get_item_key("${resolved_embedded_item}" ikey)
 
+  # Ensure the item is "inside the .app bundle" -- it should not be fixed up if
+  # it is not in the .app bundle... Otherwise, we'll modify files in the build
+  # tree, or in other varied locations around the file system, with our call to
+  # install_name_tool. Make sure that doesn't happen here:
+  #
+  get_dotapp_dir("${exepath}" exe_dotapp_dir)
+  string(LENGTH "${exe_dotapp_dir}/" exe_dotapp_dir_length)
+  string(SUBSTRING "${resolved_embedded_item}" 0 ${exe_dotapp_dir_length} item_substring)
+  if(NOT "${exe_dotapp_dir}/" STREQUAL "${item_substring}")
+    message("  exe_dotapp_dir/='${exe_dotapp_dir}/'")
+    message("  item_substring='${item_substring}'")
+    message("  resolved_embedded_item='${resolved_embedded_item}'")
+    message("")
+    message("Install or copy the item into the bundle before calling fixup_bundle")
+    message("")
+    message(FATAL_ERROR "cannot fixup an item that is not in the bundle...")
+  endif()
+
   set(prereqs "")
   get_prerequisites("${resolved_embedded_item}" prereqs 1 0 "${exepath}" "${dirs}")