FindRuby — CMake 4.4.3-dirty Documentation

# FindRuby

Finds Ruby installation and the locations of its include files and libraries:

    find_package(Ruby [<version>] [COMPONENTS <components>...] [...])

Ruby is a general-purpose programming language. This module supports Ruby 2.0 through 4.0. Virtual environments, such as RVM or RBENV, are also supported.

## Components

Added in version 4.3.

This module supports the following components:

`Interpreter`

  The Ruby interpreter executable.

`Development`

  Headers and libraries needed to build Ruby extensions or embed Ruby.

If no components are specified, both `Interpreter` and `Development` are searched for.

## Imported Targets

Added in version 4.3.

This module defines the following `IMPORTED` targets:

`Ruby::Interpreter`

  Ruby interpreter. Target defined if component `Interpreter` is found.

`Ruby::Ruby`

  Ruby library for embedding Ruby in C/C++ applications. Target defined if component `Development` is found.

`Ruby::Module`

  Ruby library for building Ruby extension modules. Target defined if component `Development` is found. Use this target when creating native extensions that will be loaded into Ruby via `require`. On most platforms, extension modules do not link directly to libruby. Includes appropriate symbol visibility settings.

## Result Variables

This module defines the following variables:

`Ruby_FOUND`

  Added in version 3.3.

  Boolean indicating whether (the requested version of) ruby was found.

`Ruby_VERSION`

  The version of ruby which was found, e.g. `3.2.6`.

`Ruby_VERSION_MAJOR`

  Ruby major version.

`Ruby_VERSION_MINOR`

  Ruby minor version.

`Ruby_VERSION_PATCH`

  Ruby patch version.

`Ruby_EXECUTABLE`

  The full path to the ruby binary.

`Ruby_INCLUDE_DIRS`

  Include dirs to be used when using the ruby library.

`Ruby_LIBRARIES`

  Added in version 3.18.

  Libraries needed to use ruby from C.

Changed in version 3.18: Previous versions of CMake used the `RUBY_` prefix for all variables.

## Hints

This module accepts the following variables:

`Ruby_FIND_VIRTUALENV`

  Added in version 3.18.

  This variable defines the handling of virtual environments. It can be left empty or be set to one of the following values:

  - `FIRST`: Virtual Ruby environments are searched for first,

      then the system Ruby installation. This is the default.

  - `ONLY`: Only virtual environments are searched

  - `STANDARD`: Only the system Ruby installation is searched.

  Virtual environments may be provided by:

  `rvm`

    Requires that the `MY_RUBY_HOME` environment is defined.

  `rbenv`

    Requires that `rbenv` is installed in `~/.rbenv/bin` or that the `RBENV_ROOT` environment variable is defined.

## Deprecated Variables

The following variables are provided for backward compatibility:

Deprecated since version 4.0: The following variables are deprecated. See policy `CMP0185`.

`RUBY_FOUND`

  Same as `Ruby_FOUND`.

`RUBY_VERSION`

  Same as `Ruby_VERSION`.

`RUBY_EXECUTABLE`

  Same as `Ruby_EXECUTABLE`.

`RUBY_INCLUDE_DIRS`

  Same as `Ruby_INCLUDE_DIRS`.

`RUBY_INCLUDE_PATH`

  Same as `Ruby_INCLUDE_DIRS`.

`RUBY_LIBRARY`

  Same as `Ruby_LIBRARY`.

## Examples

Finding Ruby and specifying the minimum required version:

    find_package(Ruby 3.2.6 EXACT REQUIRED)
    # or
    find_package(Ruby 3.2)