  <chapter id="plugin-description-file">
    <title>Plugin description file</title>
	<para>
		Plugin meta-data is a <emphasis>.plugin</emphasis> file that
		contains plugin information. Every plugin should have exactly one
		meta-data file. This file is used by plugin manager to identify the
		plugin and know the details prior to activation. Because there are
		some fields which require translation, a <emphasis>.plugin.in</emphasis>
		file is written instead, from which the <emphasis>.plugin</emphasis>
		file will be derived after necessary translation.
	</para>
	<para>
		Fields used in <emphasis>.plugin.in</emphasis> file are:
		<variablelist>
			<varlistentry><term>Group name</term>
				<listitem>
					<para>
						The first group should
						always be [Anjuta Plugin]. This group contains
						plugin details and will be used by plugin manager.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Location</term>
				<listitem>
					<para>
						Describes where the plugin is located. It is of the
						form <emphasis>libname:classname
						</emphasis>. libname is the shared library name without
						the 'lib' prefix and '.so' suffix.
						<emphasis>classname</emphasis> is the plugin class
						defined in the library.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Interfaces</term>
				<listitem>
					<para>
						Primary interfaces implemented by the plugin.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Interfaces</term>
				<listitem>
					<para>
						Comma separated list
						of all interfaces that this plugin depends on. Plugin
						implementing these interaces will be activated before
						activating this plugin. This field is optional. If
						there is no dependencies, it may not present.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Icon</term>
				<listitem>
					<para>
						Icon file name in .png format.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>_Name</term>
				<listitem>
					<para>
						Translatable plugin name.
						Notice the '_' before the key name. It means the field
						is translatable.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>_Description</term>
				<listitem>
					<para>
						Brief translatable
						description. Notice the '_' before the key name. It
						means the field is translatable.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Language</term>
				<listitem>
					<para>
						Name of loader necessary to load
						the plugin, by default the C	
						plugin loader included in libanjuta
						is used. This name must be equal
						to the value of the key SupportedLanguage
						in the group [Plugin Loader] of the
						loader plugin.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>Dependencies</term>
				<listitem>
					<para>
						Name of other plugins needed by this one.
						These other plugins will be loaded before.
						It can be useful to be sure that
						a menu item has been created.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>UserActivatable</term>
				<listitem>
					<para>
						Set to "no", if the plugin cannot be loaded
						by the user. Such plugins are loaded
						automatically by Anjuta when needed. It is
						the case for plugin providing support for
						some file types by example. By default a plugin can
						be loaded by the user.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry><term>ExcludeFromSession</term>
				<listitem>
					<para>
						Set to "yes", if the plugin is not saved in
						the user session. Such plugin must be
						non user activatable too. This is the case
						for project manager plugin. When activated it
						loads a new session, so it does
						not belong to the first session and should not
						be saved inside. By default all plugins are saved
						in the current user session.
					</para>
				</listitem>
			</varlistentry>

		</variablelist>
		Here is a typical plugin meta-data file
		(anjuta-document-manager.plugin.in):

<programlisting>
[Anjuta Plugin]
Location=anjuta-editor:EditorPlugin
Interfaces=IAnjutaDocumentManager
Dependencies=IAnjutaLauncher,IAnjutaMessageManager
Icon=anjuta-document-manager.png
_Name=Document Manager
_Description=Provides document management capabilities.
</programlisting>

	</para>
	<para>
		In addition to mandatory <emphasis>[Anjuta Plugin]</emphasis> group,
		the	meta-data file can also contain other groups, which a plugin can
		read using
		<link linkend="AnjutaPluginDescription"><type>AnjutaPluginDescription</type></link>
		methods. plugin manager simply ignores
		these additional groups, but plugins can use them on their own.
	</para>
	<para>
		A typical example would be using an extra group (e.g [Supported Mime Types])
		for a anjuta-open-file plugin to identify plugins supporting
		mime-types. It could then activate the correct plugin to open a
		particular file based on its mime-type (in addition to requiring that
		the opener plugin support a generic interface,
		such as <link linkend="IAnjutaStream"><type>IAnjutaStream</type></link>
		or <link linkend="IAnjutaFile"><type>IAnjutaFile</type></link>)
	</para>
	<para>
		To install the meta-data and icon files, add the following code in
		Makefile.am:

<programlisting>
plugin_in_files = anjuta-plugin-name.plugin.in
%.plugin: %.plugin.in $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ; \
	$(INTLTOOL_MERGE) $(top_srcdir)/po $&lt; $@ -d -u \ \
		-c $(top_builddir)/po/.intltool-merge-cache

anjuta_plugindir = $(libdir)/anjuta
anjuta_plugin_DATA = $(plugin_in_files:.plugin.in=.plugin)

plugin_icondir = $(datadir)/pixmaps/anjuta
plugin_icon_DATA = anjuta-plugin-name.png
</programlisting>

		<note>
			<para>
				The $(datadir) variable should exactly match with installed
				Anjuta's datadir. In case it is different, use the command
				"pkg-config --variable=prefix libanjuta" in configure.in
				to determine the installed prefix of Anjuta.
			</para>
		</note>
	</para>
  </chapter>
