.. _dune_instance_add:

dune_instance_add
=================

.. cmake_function:: dune_instance_add

   .. cmake_brief::

      Instantiate a template with the currently set variable values.

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

      List of template file specifications.  These are usually the names of
      template files with the ``.in`` extension removed.  See the ID
      parameter for details.

   .. cmake_param:: ID
      :single:

      Used to build the names of generated files.  Each file specification
      together with this id is given to :ref:`dune_instance_from_id()
      <dune_instance_from_id>` to determine the name of a template file and
      the name of an instance file.  To get unique instance file names this
      ID should usually be a list of variable values joined together by
      ``_``.

      Specifically, each file specification may be of the form
      ``template_file_name:base_instance_file_name``, or it may be a single
      token not containing ``:``.  In the latter case, if that token
      contains a trailing ``.in``, that is removed and the result is the base
      instance file name.  The base instance file name has the ``.in``
      appended again to form the template file name.

      The template file name is used as-is to generate files from.

      The ID is mangled by replacing any runs of non-alphanumeric characters
      with an underscore ``_``, and stripping any resulting underscore from
      the beginning and the end.  The result is inserted before any
      extension into the base instance file name to form the instance file
      name.

   .. cmake_param:: TEMPLATE
      :single:

      Instantiate embedded templates by this name.  Defaults to an empty
      name, matching embedded templates without name.

   Instantiate any embedded templates that match the given template name,
   substituting the current variables values.  Then, generate files
   according the the file specifications in the template, doing
   substitutions as well.


