<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>

<section id="environment-setup">

  <para>
    This section provides information on how to configure a proper environment for
    building Grilo, as well building and running Grilo based programs.
  </para>

  <section id="building-grilo-detailed">
    <title>Building Grilo </title>

    <section id="building-grilo-sources-install">
      <title>Building and installing Grilo</title>

      <para>
        You can check the basics of how to build and install Grilo from the
        source code repositories in the
        <link linkend="quick-start">Quick start guide</link>.
      </para>
    </section>

    <section id="compilation-options">
      <title>Compilation options</title>
      <para>
        This is a reference of the most useful compilation switches available:
      </para>
      <itemizedlist>
        <listitem>
          --enable-gtk-doc: Build documentation
          tutorials and API reference. Check doc/ directory for
          the generated documentation. Only in grilo core.
        </listitem>
        <listitem>
          --enable-debug: Build with debug information.
        </listitem>
        <listitem>
          --enable-uninstalled: Prepare for uninstalled use. Only
          in grilo-plugins.
        </listitem>
      </itemizedlist>
      
      <para>
        For more options please run './configure --help'.
      </para>
    </section>
  </section>

  <section id="compiling-grilo-programs-detailed">
    <title>Compiling Grilo based programs</title>
    
    <para>
      You can check how to compile Grilo based apps
      by checking the
      <link linkend="quick-start">Quick start guide</link>.
    </para>
  </section>

  <section id="running-grilo-programs-detailed">
    <title>Running Grilo based programs</title>
    
    <para>
      If you have installed the Grilo libraries in your system
      make sure they have been installed in a path that is
      included in the dynamic linker search path, otherwise
      export the environment variable LD_LIBRARY_PATH to
      include them, for example:
    </para>

  <programlisting>
$ export LD_LIBRARY_PATH=/usr/local/lib
  </programlisting>


    <para>
      For plugins to be visible to application they must be
      stored in the default plugin search path. This should be
      the case if you are not running Grilo in uninstalled form.
      If you are running Grilo uninstalled, or for some reason
      you have plugins available in directories other than
      the default plugin path, export the GRL_PLUGIN_PATH to
      point to the list of directories containing Grilo plugins,
      for example:
    </para>
    
    <programlisting>
$ export GRL_PLUGIN_PATH=/usr/local/lib/grilo-0.3
    </programlisting>

  </section>

  <section id="debugging-with-grilo">
    <title>Debugging with Grilo</title>

    <para>
      If you want to debug Grilo itself, make sure you have built it with
      --enable-debug (both the framework and the plugins).
    </para>

    <para>
      You can also control logging by setting the environment variable GRL_DEBUG.
      Here are some examples:
    </para>

    <programlisting>
# Disable logging for all modules
$ export GRL_DEBUG=*:-

# Enable full logging for all modules
$ export GRL_DEBUG=*:*

# Enable logging of messages of level WARNING or higher  for all modules
$ export GRL_DEBUG=*:warning

# Enable logging of messages of level INFO or higher for all modules
$ export GRL_DEBUG=*:info

# Enable full logging for the plugin registry module
$ export GRL_DEBUG=registry:*

# Enable full logging for the plugin registry module
# and WARNING or higher for the Youtube plugin
$ export GRL_DEBUG=registry:*,youtube:warning
    </programlisting>

    <para>
      Programs can also control logging programatically. See the
      <link linkend="grilo-grl-log">GrlLog</link> API reference for details.
    </para>

    <para>
      Plugins can be ranked. Ranks can be used to sort plugins
      by rank and also in case of conflict when two plugins offer the same
      feature, to decide on the one to use. By default, all the plugins
      have the same rank (0). Higher ranks give plugins more relevance /
      priority.
    </para>

    <para>
      Ranks can be controlled with the environment variable GRL_PLUGIN_RANKS.
      Here is one example:
    </para>

    <programlisting>
# Set the rank of the Youtube plugin to 5 and the Bookmarks plugin to -4
$ export GRL_PLUGIN_RANKS=youtube:5,bookmarks:-4
    </programlisting>

    <para>
      Some plugins extend their plugin name with login specific identifiers.
      To match these plugins the ranks environment variable allows for simple
      glob pattern matching with the '?' and '*' wildcards. This can of course
      also be used in other situations.
      Here is one example:
    </para>

    <programlisting>
# Set the rank of all coverart plugins to 2, but the Last.FM
# coverart plugin whether logged in or not to 5.
# Note that order is important here: the ranks are interpreted from
# right to left.
$ export GRL_PLUGIN_RANKS=grl-lastfm-cover*:5,*cover*:2
    </programlisting>

  </section>
</section>
