.. _dune_instance_generate_file:

dune_instance_generate_file
===========================

.. cmake_function:: dune_instance_generate_file

   .. cmake_brief::

      Convenience replacement for ``configure_file()``: enable standard
      substitutions, register files as generated, and flag the same file
      being generated twice.

   .. cmake_param:: TEMPLATE
      :positional:
      :single:
      :required:

      The name of the template file.

   .. cmake_param:: INSTANCE
      :positional:
      :single:
      :required:

      The name of the generated file.  This is assumed relative to
      ``${CMAKE_CURRENT_BINARY_DIR}``.

   Make sure the variables ``TEMPLATE``, ``INSTANCE``, and
   ``BINDIR_INSTANCE`` are set to the parameter values and available for
   substitution.  Also set the variable ``GENERATED_SOURCE`` to a one-line
   message that tells a human reader that this file is generated, and the
   name of the template file it was generated from.  The message also
   includes hints for common editors telling them to switch to read-only
   mode.

   Then generate the file as if by ``configure_file()``.

   If the instance file has been registered as a generated source file
   before, this function generates a fatal error.  This ensures that any
   accidential attempt to generate the same file twice is caught.  As a
   special exception, if the generated content is the same as before, the
   error is silently skipped.


