name: install_subdir
returns: void
description: |
  Installs the entire given subdirectory and its contents from the
  source tree to the location specified by the keyword argument
  `install_dir`.

  *(since 0.45.0, deprecated since 0.60.0)* If the subdirectory does not exist
  in the source tree, an empty directory is created in the specified location.
  A newly created subdirectory may only be created in the keyword argument
  `install_dir`. There are a number of flaws with this method, and it was never
  intentionally designed to work this way, please use [[install_emptydir]]
  instead.

example: |
  For a given directory `foo`:
  ```text
  foo/
    bar/
      file1
    file2
  ```
  `install_subdir('foo', install_dir : 'share', strip_directory : false)` creates
  ```text
  share/
    foo/
      bar/
        file1
      file2
  ```

  `install_subdir('foo', install_dir : 'share', strip_directory : true)` creates
  ```text
  share/
    bar/
      file1
    file2
  ```

  `install_subdir('foo/bar', install_dir : 'share', strip_directory : false)` creates
  ```text
  share/
    bar/
      file1
  ```

  `install_subdir('foo/bar', install_dir : 'share', strip_directory : true)` creates
  ```text
  share/
    file1
  ```

  `install_subdir('new_directory', install_dir : 'share')` creates
  ```text
  share/
    new_directory/
  ```

warnings:
  - the `install_mode` kwarg ignored integer values between 0.59.0 -- 1.1.0.

posargs:
  subdir_name:
    type: str
    description: The sub-directory to install

kwargs:
  install_mode:
    type: array[str | int]
    since: 0.47.0
    description: |
      Specify the file mode in symbolic format
      and optionally the owner/uid and group/gid for the installed files.

      See the `install_mode` kwarg of [[install_data]] for more information.

  install_tag:
    type: str
    since: 0.60.0
    description: |
      A string used by the `meson install --tags` command
      to install only a subset of the files. By default these files have no install
      tag which means they are not being installed when `--tags` argument is specified.

  exclude_files:
    type: array[str]
    description: |
      An array of file names that should not be installed.
      Names are interpreted as paths relative to the `subdir_name` location.

  exclude_directories:
    type: array[str]
    since: 0.47.0
    description: |
      An array of directory names that should not be installed.
      Names are interpreted as paths relative to the `subdir_name` location.

  install_dir:
    type: str
    description: Where to install to.

  strip_directory:
    type: bool
    since: 0.45.0
    default: false
    description: |
      Install directory contents.
      If `strip_directory=true` only the last component of the source path is used.

  follow_symlinks:
    type: bool
    since: 1.3.0
    default: true
    description: |
      If true, dereferences links and copies their target instead.  The default
      value will become false in the future.