Merge wiki debugging information into RTD

doc/dev/debugging.rst

@@ -1,16 +1,71 @@
 
+.. _debugging:
 
-Debugging tips
-==============
+Debugging Exaile
+================
 
-TODO: developing with exaile
+.. contents::
+
+
+Development Environment Setup
+-----------------------------
+
+Linux:
+
+OSX:
+
+Windows:
+
+TODO
+
+
+Editor: Atom
+~~~~~~~~~~~~
+
+I've found recent versions of Github's Atom editor to be very useful for Python
+development, I recommend installing the ``autocomplete-python`` and
+``linter-pyflakes`` packages.
+
+Editor: Eclipse + pydev
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Pydev can be a bit tricky to set up correctly.
+
+* Ensure you add the correct python interpreter in the project settings
+* Add the root of the repository as a source directory
+
+
+What's an easy way to test stuff without wrecking my actual collection?
+-----------------------------------------------------------------------
+
+If you use the ``--all-data-dir`` option to Exaile, it will store all data
+for that execution of Exaile in that directory (collections, playlists, logs)::
+    
+    ./exaile --all-data-dir=tmp
+
+Debugging options for Exaile
+----------------------------
+
+See ``--help`` for more details, but there are a few useful options:
+
+* ``--debug`` - Shows debug log messages
+* ``--eventdebug`` - Enable debugging of xl.event. Generates lots of output
+* ``--eventdebug-full`` - Enable debugging of xl.event. Generates LOTS of output
+* ``--threaddebug`` - Adds the thread name to logging messages
+
+Where can I find log files?
+---------------------------
+
+On Linux/OSX:
+
+* ```~/.cache/exaile/logs/``, old files have a .1, .2, … name suffix
+* ``~/.local/share/exaile/logs/`` for Exaile 3.x releases
+
+TODO: Windows
 
-* Setup pydev properly
-    * Add glib, gtk,pygst,gst,gobject to builtins
-    * Add correct source directory
 
-GST issues
-----------
+GStreamer Debugging Techniques
+------------------------------
 
 When tracking down GST issues, a useful thing to do is the following::
 
@@ -22,10 +77,10 @@ When tracking down GST issues, a useful thing to do is the following::
 `GST_DEBUG_NO_COLOR=1` is good if you're running exaile inside of pydev on eclipse.
 
 Additional help about GStreamer debugging variables can be found at 
-http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-checklist-debug.html
+https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gst-running.html
 
 GST Bin Visualization
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 This is pretty cool, shows you the entire GST pipeline::
 
@@ -38,3 +93,59 @@ Then if you run exaile like so::
 It will dump a dot file that you can turn into an image::
 
     dot -Tpng -oimage.png graph_lowlevel.dot
+
+Using GDB to diagnose issues
+----------------------------
+
+GDB can be used to diagnose segfaults and other issues. To run GDB:
+
+.. code-block:: bash
+
+    gdb --args python2 exaile.py --startgui <other arguments here>
+
+Refer to the `Python Documentation <https://wiki.python.org/moin/DebuggingWithGdb>`_,
+but especially useful here are:
+
+* ``(gdb) py-bt`` is similar to ``(gdb) bt``, but it lists the python stack instead
+* ``(gdb) info threads``
+
+Tips for debugging issues related to Gtk+ or GLib
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Refer to the `Gtk+ <https://developer.gnome.org/gtk3/stable/gtk-running.html>`_
+and `GLib <https://developer.gnome.org/glib/stable/glib-running.html>`_
+debugging documentation.
+
+Enable diagnostic warnings on Fedora
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Fedora stable you might want to set the ``G_ENABLE_DIAGNOSTIC`` environment
+variable to test this since Glib warnings are disabled by default on Fedora. See
+`this commit <http://pkgs.fedoraproject.org/cgit/glib2.git/commit/?h=f22&id=bdab866334343601ca6b92e23029b4bd78ca6de6>`_.
+
+Eliminating Gtk-WARNING
+~~~~~~~~~~~~~~~~~~~~~~~
+
+1. run gdb with ``G_DEBUG=fatal-warnings gdb --args python2 exaile --startgui``
+2. run exaile from gdb with ``run``
+3. do whatever causes `Gtk-WARNING`. This will lead to a crash in exaile.
+4. debug this crash with gdb
+
+**WARNING**: On Linux, this will freeze your X server if the crash happens in a
+menu. This is due to `X grabbing all input on open menus <https://tronche.com/gui/x/xlib/input/pointer-grabbing.html>`_.
+When gdb stops exaile inside a menu it can't leave the input grab.
+
+Prevent X server from freezing your Desktop when debugging exaile
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some recommend starting exaile on another X server or on a Wayland backend. One
+way to workaround this is to run exaile on a nested X server inside weston:
+
+1. install weston
+2. run ``weston --modules=xwayland.so`` (note: from now on all your Gtk+ 3.x applications will try to start inside weston due to preferring Wayland over X)
+3. inside weston, run ``env | grep DISPLAY`` to figure out which X11 display to start exaile on
+4. before running gdb, add ``GDK_BACKEND=x11` and `DISPLAY=:1`` (or whatever you got the step before) to its environment
+
+To make Gtk+ 3.x applications not run inside weston but use your current X11
+desktop session, run them with ``GDK_BACKEND=x11`` environment variable set.
+