.. _plugin_action:

Action plugins
==============

Action plugins control how files should be compiled.

There is a list of plugins shipped with Évariste, but you can also :ref:`write your own <write_action>`.

.. toctree::
   :maxdepth: 1

   action/autocommand
   action/command
   action/make
   action/raw

Which plugin applies to which file?
-----------------------------------

Automatic selection
  Each :class:`action plugin <evariste.plugins.action.Action>` have a :attr:`~evariste.plugins.Plugin.priority` and a :meth:`~evariste.plugins.Plugin.match` method. By default, the plugin used to compile a file is the plugin with the highest priority that matches the file (i.e. ``myplugin.match(file)`` returns ``True``).

Manual selection
  However, user can explicitely choose a plugin for a given file, in an :ref:`evsignore <evsignore>` file:

  .. code-block:: ini
     :caption: Manual selection of an action plugin

     [action]
     plugin = foo

     [action.foo]
     bar = options for plugin foo

Options
-------

Each plugin has its own set of options. However, every action plugin accepts options :ref:`targets` and :ref:`depends`.

.. _targets:

Targets
"""""""

Évariste cannot guess the name of the files that will be produced by an action. Use this option to define the targets, i.e. a space separated list of files that are generated by a given action. This option is :ref:`formatted <format>`.

In the following example, the command produces two files: a `pdf` and a `png`.

.. code-block:: ini
   :caption: Example of the ``targets`` option.

   [action.command]
   targets = {basename}.pdf {basename}.png
   command =
      latex {basename}
      convert {basename}.pdf {basename}.png

.. _depends:

Depends
"""""""

The source files of a compiled one should not appear in the output of Évariste. By default, the file "trigerring" the action is considered the source file, and discarded. But, for instance, if you compile a *tex* files that includes a *png* image, you would like both files to be ignored in the final output. To do so, ``depends`` option is a space separated list of files that the compiled file depends on, and which should be discarded in the final output.

In the following example, the :file:`image.png` file will be ignored in the final output.

.. code-block:: ini
   :caption: Example of the ``depends`` option.

   [action.command]
   depends = image.png
   targets = {basename}.pdf
   command = pdflatex {basename}

Note that the :ref:`command plugin <plugin_action_command>` (and the plugins that inherit from it) accept the experimental, slower :ref:`strace option <plugin_action_command_options>`, which automatically detects the files that the compiled file depends on.