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:` and `d_import_dirs:` keyword arguments
  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.

warnings:
  - |
    When `is_system : true` is used, the include directory order on the
    command line is **reversed** compared to the order given in the
    arguments: the *last* directory listed has the highest priority
    (it appears first among the `-isystem` flags and is searched first
    by the compiler).  This is the opposite of the default (`is_system :
    false`), where the *first* directory listed has the highest priority.
    This may be changed in future releases, but behavior will not change
    as long as `meson_version` is not changed in `project()`.

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).