DuneSymlinkOrCopy
=================

Convenience commands to expose files from the source tree inside the build
tree by copying or symlinking them.

.. cmake:command:: dune_add_copy_command

  Add a custom command that copies a source-tree file into the current build
  directory.

  .. code-block:: cmake

    dune_add_copy_command(<filename>)

  ``filename``
    Path to a file relative to the current source directory.

  This command only creates the custom command for the copied output file. It
  does not add a top-level target by itself.

.. cmake:command:: dune_add_copy_target

  Add a custom target that copies a source-tree file into the current build
  directory.

  .. code-block:: cmake

    dune_add_copy_target(<target-name> <filename>)

  ``target-name``
    Name of the custom target to create.

  ``filename``
    Path to a file relative to the current source directory.

  The created target depends on the copied file output created by
  :cmake:command:`dune_add_copy_command()`.

.. cmake:command:: dune_add_copy_dependency

  Add a file copy step as a dependency of an existing target.

  .. code-block:: cmake

    dune_add_copy_dependency(<target> <filename>)

  ``target``
    Existing target that should depend on the copied file.

  ``filename``
    Path to a file relative to the current source directory.

  This command creates an auxiliary copy target and adds it as a dependency of
  ``target``.

.. cmake:command:: dune_symlink_to_source_tree

  Create directory symlinks from the build tree back into the source tree.

  .. code-block:: cmake

    dune_symlink_to_source_tree([NAME <link-name>])

  ``NAME``
    Name of the symlink created in each build directory. The default is
    ``src_dir``.

  Call this from a top-level ``CMakeLists.txt`` to create a symlink in every
  build-tree subdirectory that points to the corresponding source directory. On
  Windows, a warning is issued instead.

.. cmake:variable:: DUNE_SYMLINK_TO_SOURCE_TREE

  If set to ``TRUE``, the functionality of
  :cmake:command:`dune_symlink_to_source_tree()` is enabled globally for a
  module.

.. cmake:variable:: DUNE_SYMLINK_RELATIVE_LINKS

  If set to ``TRUE``, relative symlinks are created instead of absolute ones.

.. cmake:command:: dune_symlink_to_source_files

  Create symlinks, or copies on Windows, for selected source files in the
  current build directory.

  .. code-block:: cmake

    dune_symlink_to_source_files(
      FILES <files>...
      [DESTINATION <relative-path>]
    )

  ``FILES``
    Files relative to the current source directory that should be mirrored into
    the build directory.

  ``DESTINATION``
    Relative destination directory below the current build directory.

  On Windows, copying is used as a fallback because symlink creation is not
  generally available.