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)