name: include_directories
returns: inc
description: |
  Returns an opaque object which contains the directories (relative to
  the current directory) given in the positional arguments. The result
  can then be passed to the `include_directories:` keyword argument when
  building executables or libraries. You can use the returned object in
  any subdirectory you want, Meson will make the paths work
  automatically.

  Note that this function call itself does not add the directories into
  the search path, since there is no global search path. For something
  like that, see [`add_project_arguments()`](#add_project_arguments).

  See also `implicit_include_directories` parameter of
  [[executable]], which adds current source and build
  directories to include path.

  Each directory given is converted to two include paths: one that is
  relative to the source root and one relative to the build root.

example: |
  For example, with the following source tree layout in
  `/home/user/project.git`:

  `meson.build`:
  ```meson
  project(...)

  subdir('include')
  subdir('src')

  ...
  ```

  `include/meson.build`:
  ```meson
  inc = include_directories('.')

  ...
  ```

  `src/meson.build`:
  ```meson
  sources = [...]

  executable('some-tool', sources,
    include_directories : inc,
    ...)

  ...
  ```

  If the build tree is `/tmp/build-tree`, the following include paths
  will be added to the `executable()` call: `-I/tmp/build-tree/include
  -I/home/user/project.git/include`.

varargs:
  name: includes
  type: str
  description: Include paths to add.

kwargs:
  is_system:
    type: bool
    default: false
    description: |
      If set to `true`, flags the specified directories as system directories.
      This means that
      they will be used with the `-isystem` compiler argument rather than
      `-I` on compilers that support this flag (in practice everything
      except Visual Studio).