[gnome-builder] doc: add section on run handlers

[Christian Hergert <chergert src gnome org>]

commit e96cee610c4e92ef0ed7aab9222e0c2a046d111e
Author: Christian Hergert <chergert redhat com>
Date:   Wed Sep 6 20:47:30 2017 -0700

    doc: add section on run handlers

 doc/plugins/running.rst |   91 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 91 insertions(+), 0 deletions(-)
---
diff --git a/doc/plugins/running.rst b/doc/plugins/running.rst
index ceb4913..f51678c 100644
--- a/doc/plugins/running.rst
+++ b/doc/plugins/running.rst
@@ -2,3 +2,94 @@
 Extending the Run Manager
 #########################
 
+Running projects is managed by the ``Ide.RunManager``.
+You can provide special "run handlers" to alter how the applications are executed.
+
+For example, the Sysprof-based profiler uses a custom run handler to ensure that the profiler can monitor 
the process.
+Additionally, Builder's GDB debugger backend will alter the arguments so that GDB is used to launch the 
program.
+
+Generally, hooking into the run manager involves adding a menu entry to the "Run Button" and a callback to 
process the launch request.
+
+Let's take a look at a practical example using the Valgrind plugin.
+
+.. code-block:: xml
+   :caption: Embed file as a resource matching /org/gnome/Builder/plugins/$module_name/gtk/menus.ui
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <interface>
+     <menu id="run-menu">
+       <section id="run-menu-section">
+         <item>
+           <attribute name="id">valgrind-run-handler</attribute>
+           <attribute name="after">default-run-handler</attribute>
+           <attribute name="action">run-manager.run-with-handler</attribute>
+           <attribute name="target">valgrind</attribute>
+           <attribute name="label" translatable="yes">Run with Valgrind</attribute>
+           <attribute name="verb-icon-name">system-run-symbolic</attribute>
+           <attribute name="accel">&lt;Control&gt;F10</attribute>
+         </item>
+       </section>
+     </menu>
+   </interface>
+
+Now register a run handler to handle the launch request.
+
+.. code-block:: python3
+
+   from gi.repository import Ide
+   from gi.repository import GLib
+   from gi.repository import GObject
+
+   _ = Ide.gettext
+
+   class ValgrindWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
+       workbench = None
+       has_handler = False
+
+       def do_load(self, workbench):
+           self.workbench = workbench
+
+           build_manager = self.workbench.get_context().get_build_manager()
+           build_manager.connect('notify::pipeline', self.notify_pipeline)
+           self.notify_pipeline(build_manager, None)
+
+       def notify_pipeline(self, build_manager, pspec):
+           run_manager = self.workbench.get_context().get_run_manager()
+
+           # When the pipeline changes, we need to check to see if we can find
+           # valgrind inside the runtime environment.
+           pipeline = build_manager.get_pipeline()
+           if pipeline:
+               runtime = pipeline.get_configuration().get_runtime()
+               if runtime and runtime.contains_program_in_path('valgrind'):
+                   if not self.has_handler:
+                       run_manager.add_handler('valgrind', _('Run with Valgrind'), 'system-run-symbolic', 
'<primary>F10', self.valgrind_handler)
+                       self.has_handler = True
+                   return
+
+           if self.has_handler:
+               run_manager.remove_handler('valgrind')
+
+       def do_unload(self, workbench):
+           if self.has_handler:
+               run_manager = self.workbench.get_context().get_run_manager()
+               run_manager.remove_handler('valgrind')
+           self.workbench = None
+
+       def valgrind_handler(self, run_manager, runner):
+           # We want to run with valgrind --log-fd=N so that we get the valgrind
+           # output redirected to our temp file. Then when the process exits, we
+           # we will open the temp file in the builder editor.
+           source_fd, name = GLib.file_open_tmp('gnome-builder-valgrind-XXXXXX.txt')
+           map_fd = runner.take_fd(source_fd, -1)
+           runner.prepend_argv('--track-origins=yes')
+           runner.prepend_argv('--log-fd='+str(map_fd))
+           runner.prepend_argv('valgrind')
+           runner.connect('exited', self.runner_exited, name)
+
+       def runner_exited(self, runner, name):
+           # If we weren't unloaded in the meantime, we can open the file using
+           # the "editor" hint to ensure the editor opens the file.
+           if self.workbench:
+               uri = Ide.Uri.new('file://'+name, 0)
+               self.workbench.open_uri_async(uri, 'editor', 0, None, None, None)