<?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 prodname "<productname>Caja-Actions</productname>">
  <!ENTITY caja "<productname>Caja</productname>">
]>

<refentry id="na-compiling" revision="4 Dec 2010">

  <refmeta>
    <refentrytitle>Compiling the Caja-Actions package</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>Caja-Actions</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>Compiling the Caja-Actions Package</refname>
    <refpurpose>
      How to compile Caja-Actions
    </refpurpose>
  </refnamediv>

  <refsect1 id="building">
    <title>Building &prodname; on UNIX</title>

    <para>
      On UNIX, &prodname; uses the standard GNU build system,
      using <ulink url="http://www.gnu.org/software/autoconf/">
      <application>autoconf</application></ulink> for package
      configuration and resolving portability issues,
      <ulink url="http://www.gnu.org/software/automake/">
      <application>automake</application></ulink> for building makefiles
      that comply with the GNU Coding Standards, and
      <ulink url="http://www.gnu.org/software/libtool/">
      <application>libtool</application></ulink> for building shared
      libraries on multiple platforms. The normal sequence for
      compiling and installing the &prodname; package is thus:

      <literallayout>
        <userinput>./configure</userinput>
        <userinput>make</userinput>
        <userinput>make install</userinput>
      </literallayout>
    </para>

    <para>
      The standard options provided by <application>GNU
      autoconf</application> may be passed to the
      <command>configure</command> script.  Please see the
      <ulink url="http://www.gnu.org/software/autoconf/manual/index.html">
      <application>autoconf</application> documentation</ulink> or run
      <command>./configure --help</command> for information about
      the standard options.
    </para>
  </refsect1>

  <refsect1 id="dependencies">
    <title>Dependencies</title>

    <para>
      Before you can compile the &prodname; package, you need to have
      various other tools and libraries installed on your
      system. The two main tools needed during the build process (as
      differentiated from the tools used in when creating &prodname;
      mentioned above such as <application>autoconf</application>)
      are <command>pkg-config</command> and GNU make.
    </para>

    <itemizedlist>
      <listitem>
        <para>
          <ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
          is a tool for tracking the compilation flags needed for
          libraries that are used by the &prodname; package.
          (For each library, a small <literal>.pc</literal> text file is
          installed in a standard location that contains the compilation
          flags needed for that library along with version number
          information.)
        </para>
      </listitem>
      <listitem>
        <para>
          The &prodname; makefiles will mostly work with different versions
          of <command>make</command>. However, there tends to be
          a few incompatibilities, so the &prodname; team recommends
          installing <ulink url="http://www.gnu.org/software/make">GNU
          make</ulink> if you don't already have it on your system
          and using it. (It may be called <command>gmake</command>
          rather than <command>make</command>.)
        </para>
      </listitem>
    </itemizedlist>

    <para>
      &prodname; depends on a number of other libraries.
    </para>

    <itemizedlist>
      <listitem>
        <para>
          <ulink url="http://library.gnome.org/devel/glib/stable/">GLib</ulink>
          and <ulink url="http://www.gtk.org/">Gtk+</ulink> are fondamental
          libraries, both for user interface and for portability and
          internationalization management.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://xmlsoft.org/">libxml2</ulink> is used to
          manage XML imports and exports.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://library.gnome.org/devel/libgtop/stable/">libgtop2</ulink>
          is used to detect and identify running processes as part of the validation
          process of a candidate context.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://www.x.org/">libSM</ulink> and
          <ulink url="http://www.x.org/">libICE</ulink>
          are used as a session management libraries, in order to be sure the session
          will not terminate without at least proposing the user to save his
          modifications.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng">libUUID</ulink>
          is the universally unique ID library used to automatically generate a
          unique identifiant at item creation.
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://www.gnome.org/~ebassi/source/">libunique</ulink>
          is required so that the Caja-Actions Configuration Tool only
          executes one instance.
        </para>
      </listitem>
      <listitem>
        <para>
          And, of course,
          <ulink url="http://projects.gnome.org/caja/">&caja; extension</ulink>
          is required because &prodname; is first a &caja; extension.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1 id="extra-configuration-options">
    <title>Extra Configuration Options</title>

    <para>
      In addition to the normal options, the
      <command>configure</command> script in the &prodname; package
      supports these additional arguments:

      <cmdsynopsis>
        <command>configure</command>
        <group>
          <arg>--with-caja-extdir=DIR</arg>
        </group>
        <group>
          <arg>--with-default-io-provider=na-mateconf|na-desktop</arg>
        </group>
        <group>
          <arg>--enable-html-manuals[=db2html]</arg>
        </group>
        <group>
          <arg>--enable-pdf-manuals[=dblatex]</arg>
        </group>
      </cmdsynopsis>
    </para>

    <formalpara>
      <title><systemitem>--with-caja-extdir=DIR</systemitem></title>
      <para>
        With this option, one may define an alternate directory where
        our &caja; extensions will be stored.
      </para>
      <para>
        This is most commonly useful:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            In development mode, we only have to install symlinks
            from &caja; standard location to our development
            tree once. Then, each new version of our libraries
            will be automatically considered by &caja;.
          </para>
        </listitem>
        <listitem>
          <para>
            When running <command>make distcheck</command>, so that
            compiled libraries do not interfere with installed ones.
          </para>
        </listitem>
        <listitem>
          <para>
            When &caja; is not installed itself in a standard
            location.
          </para>
        </listitem>
      </itemizedlist>
    </formalpara>

    <formalpara>
      <title><systemitem>--with-default-io-provider=na-mateconf|na-desktop</systemitem></title>
      <para>
        As of version 3.0, &prodname; may store menus and actions
        both in MateConf, which is the historical behavior, or as
        <filename>.desktop</filename> files.
      </para>
      <para>
        This option lets the packager define which will be the
        default destination when a new menu or action will be
        created.
      </para>
      <para>
        This defaults to &quot;na-desktop&quot; which is the internal
        identifiant of the I/O provider which manages
        <filename>.desktop</filename> files.
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>--enable-html-manuals[=db2html]</systemitem></title>
      <para>
        This option lets the packager regenerate user's manuals
        from the DocBook sources as HTML documents.
      </para>
      <para>
        All available translations are generated.
      </para>
      <para>
        Building HTML documents from DocBook source can be
        realized through <application>mate-doc-tool</application>
        or <application>db2html</application>.
        &prodname; defaults to use <application>mate-doc-tool</application>
        as the output format better sticks with those of
        <application>Yelp</application>.
      </para>
      <para>
        As this option is always set when running
        <command>make distcheck</command>, the packager can be
        mostly sure that the distributed manuals are up to date,
        and may safely ignore this option.
      </para>
    </formalpara>

    <formalpara>
      <title><systemitem>--enable-pdf-manuals[=dblatex]</systemitem></title>
      <para>
        This option lets the packager regenerate user's manuals
        from the DocBook sources as PDF documents.
      </para>
      <para>
        All available translations are generated.
      </para>
      <para>
        As this option is always set when running
        <command>make distcheck</command>, the packager can be
        mostly sure that the distributed manuals are up to date,
        and may safely ignore this option.
      </para>
    </formalpara>

  </refsect1>

</refentry>
