launch: Make the "launched failed" message more explanatory.

Since this is the most common error seen by people who have
installation problems, buggy qemu, etc, and since no one reads the
FAQ, describe in this error message what resources are available to
debug launch problems.

Cherry picked from commit 840deea12079b05a9f588016af273843d5d6e1b8
and fixed for the stable branch.

2 files changed, 19 insertions, 2 deletions

diff --git a/src/guestfs-internal.h b/src/guestfs-internal.h
index fcdf00a8..0a37618e 100644
--- a/src/guestfs-internal.h
+++ b/src/guestfs-internal.h
@@ -414,6 +414,7 @@ extern void guestfs___call_callbacks_message (guestfs_h *g, uint64_t event, cons
 extern void guestfs___call_callbacks_array (guestfs_h *g, uint64_t event, const uint64_t *array, size_t array_len);
 extern int guestfs___is_file_nocase (guestfs_h *g, const char *);
 extern int guestfs___is_dir_nocase (guestfs_h *g, const char *);
+extern void guestfs___launch_failed_error (guestfs_h *g);
 extern char *guestfs___download_to_tmp (guestfs_h *g, struct inspect_fs *fs, const char *filename, const char *basename, uint64_t max_size);
 extern char *guestfs___case_sensitive_path_silently (guestfs_h *g, const char *);
 extern struct inspect_fs *guestfs___search_for_root (guestfs_h *g, const char *root);
diff --git a/src/launch.c b/src/launch.c
index 54ba4714..74473080 100644
--- a/src/launch.c
+++ b/src/launch.c
@@ -1055,12 +1055,12 @@ launch_appliance (guestfs_h *g)
   free (buf);
 
   if (r == -1) {
-    error (g, _("guestfs_launch failed, see earlier error messages"));
+    guestfs___launch_failed_error (g);
     goto cleanup1;
   }
 
   if (size != GUESTFS_LAUNCH_FLAG) {
-    error (g, _("guestfs_launch failed, see earlier error messages"));
+    guestfs___launch_failed_error (g);
     goto cleanup1;
   }
 
@@ -1214,6 +1214,22 @@ guestfs___launch_send_progress (guestfs_h *g, int perdozen)
   }
 }
 
+/* Since this is the most common error seen by people who have
+ * installation problems, buggy qemu, etc, and since no one reads the
+ * FAQ, describe in this error message what resources are available to
+ * debug launch problems.
+ */
+void
+guestfs___launch_failed_error (guestfs_h *g)
+{
+  if (g->verbose)
+    error (g, _("guestfs_launch failed, see earlier error messages"));
+  else
+    error (g, _("guestfs_launch failed.\n"
+                "See http://libguestfs.org/guestfs-faq.1.html#debugging-libguestfs\n"
+                "and/or run 'libguestfs-test-tool'."));
+}
+
 /* Return the location of the tmpdir (eg. "/tmp") and allow users
  * to override it at runtime using $TMPDIR.
  * http://www.pathname.com/fhs/pub/fhs-2.3.html#TMPTEMPORARYFILES