get_filename_component
----------------------

Get a specific component of a full filename or path.

.. warning::

  .. deprecated:: 3.20

    This command has been superseded by other CMake commands.

    * To replace ``REALPATH`` : Use :command:`file(REAL_PATH)`
    * To replace ``PROGRAM`` : Use
      :command:`separate_arguments(PROGRAM)`
    * For all other modes: Use :command:`cmake_path`

Synopsis
^^^^^^^^

.. parsed-literal::

  `Path component extraction`_
    get_filename_component(<var> <FilePath> { DIRECTORY | PATH } [CACHE])
    get_filename_component(<var> <FilePath> NAME [CACHE])
    get_filename_component(<var> <FilePath> EXT [CACHE])
    get_filename_component(<var> <FilePath> NAME_WE [CACHE])
    get_filename_component(<var> <FilePath> LAST_EXT [CACHE])
    get_filename_component(<var> <FilePath> NAME_WLE [CACHE])

  `Path resolution`_
    get_filename_component(<var> <FilePath> { ABSOLUTE | REALPATH }
                           [BASE_DIR <dir>] [CACHE])

  `System path lookup`_
    get_filename_component(<var> <CommandString> PROGRAM
                           [PROGRAM_ARGS <args_var>] [CACHE})

.. versionchanged:: 3.4
   Added `Path resolution`_ modes ``ABSOLUTE`` and ``REALPATH``.

.. versionchanged:: 3.14
   Added ``LAST_EXT`` and ``NAME_WLE`` to the
   `Path component extraction`_ modes.

Introduction
^^^^^^^^^^^^

``get_filename_component`` performs transformations on the
provided ``<FilePath>`` or ``<CommandString>`` and stores the results
in ``<var>``. The exact operating mode depends on the third argument.

When paths are returned, they use forward slashes and have no
trailing slashes.

If the optional ``CACHE`` argument is specified, the result variable is
added to the cache.

Path component extraction
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  get_filename_component(<var> <FilePath> <mode> [CACHE])

Using any of the following ``<mode>`` arguments will set ``<var>``
to a component extracted from ``<FilePath>``::

  DIRECTORY = Directory without file name
  NAME      = File name without directory
  EXT       = File name longest extension (.b.c from d/a.b.c)
  NAME_WE   = File name with neither the directory nor the longest extension
  LAST_EXT  = File name last extension (.c from d/a.b.c)
  NAME_WLE  = File name with neither the directory nor the last extension
  PATH      = Deprecated alias for DIRECTORY

.. versionchanged:: 3.14
   Added ``LAST_EXT`` and ``NAME_WLE`` modes.

.. deprecated:: 2.8.11
   The ``PATH`` mode. Use ``DIRECTORY`` instead.


Path resolution
^^^^^^^^^^^^^^^

.. versionadded:: 3.4

.. code-block:: cmake

    get_filename_component(<var> <FilePath> ( ABSOLUTE | REALPATH )
                           [BASE_DIR <dir>] [CACHE])

``<var>`` is set to an absolute path representing ``<FilePath>``.

If the provided ``<FilePath>`` is a relative path, it is evaluated
relative to ``<dir>`` if ``BASE_DIR`` is specified. If no ``BASE_DIR``
argument is supplied, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.

Two modes are supported::

  ABSOLUTE = Full path to file
  REALPATH = Full path to existing file with symlinks resolved

System path lookup
^^^^^^^^^^^^^^^^^^

.. code-block:: cmake

  get_filename_component(<var> <CommandString> PROGRAM
                         [PROGRAM_ARGS <arg_var>] [CACHE])

The program in ``<CommandString>``, which can be a program name, path,
or command line with or without arguments, will be found in the system
search path or left as a full path.

If ``<args_var>`` is supplied following the optional ``PROGRAM_ARGS``
argument, then any command-line arguments present in ``<CommandString>``
will be split from the program name and stored in the variable named
by ``<arg_var>``.  This is used to separate a program name from its
arguments in a command line string.
