.. _dune_instance_begin:

dune_instance_begin
===================

.. cmake_function:: dune_instance_begin

   .. cmake_brief::

      Prepare for a list of instances.

   .. cmake_param:: FILES
      :multi:
      :argname: file_spec

      List of template files with embedded templates.

   Read the given template files, and extract embedded templates.  Run the
   generator on the remaining file content with the variables currently in
   effect.

   .. note::

      A matching :ref:`dune_instance_end() <dune_instance_end>` is required.
      Since information is communicated through variables in the callers
      scope, :ref:`dune_instance_begin()
      <dune_instance_begin>`/:ref:`dune_instance_end() <dune_instance_end>`
      blocks may not be nested inside the same scope.  Since a function is a
      new scope, it may safely contain a :ref:`dune_instance_begin()
      <dune_instance_begin>`/:ref:`dune_instance_end() <dune_instance_end>`
      block, even if it is itself called from one.


