Ruby-FFI 技术文档

1. 安装指南

1.1 系统要求

在安装 Ruby-FFI 之前，请确保您的系统满足以下要求：

• CRuby (MRI): 需要一个 C 编译器（例如 macOS 上的 Xcode，或其他系统上的 gcc 或 clang）。
• 可选: 为了加快安装速度，您可以安装 libffi 库及其开发头文件。这些通常包含在 libffi-dev 或 libffi-devel 包中。

1.2 安装步骤

1.2.1 通过 RubyGems 安装

[sudo] gem install ffi

1.2.2 通过 Gemfile 安装

如果您使用的是 Gemfile，可以在其中添加以下内容：

gem 'ffi', github: 'ffi/ffi', submodules: true

然后运行：

bundle install

1.2.3 从 GitHub 仓库安装

git clone git://github.com/ffi/ffi.git
cd ffi
git submodule update --init --recursive
bundle install
rake install

1.3 安装选项

• --enable-system-libffi: 强制使用系统 libffi。
• --disable-system-libffi: 强制使用内置 libffi。
• --enable-libffi-alloc: 强制通过 libffi 分配闭包。
• --disable-libffi-alloc: 强制通过内置方法分配闭包。

2. 项目使用说明

2.1 基本用法

Ruby-FFI 允许您通过 Ruby 代码调用动态链接的本地库中的函数。以下是一个简单的示例：

require 'ffi'

module MyLib
  extend FFI::Library
  ffi_lib 'c'
  attach_function :puts, [ :string ], :int
end

MyLib.puts 'Hello, World using libc!'

2.2 更多示例

您可以在项目的 samples/ 文件夹中找到更多示例，或者参考项目的 wiki 页面。

3. 项目 API 使用文档

3.1 FFI::Library 模块

FFI::Library 模块提供了加载和绑定本地库的功能。您可以通过 ffi_lib 方法指定要加载的库，并通过 attach_function 方法绑定库中的函数。

module MyLib
  extend FFI::Library
  ffi_lib 'c'
  attach_function :puts, [ :string ], :int
end

3.2 attach_function 方法

attach_function 方法用于绑定库中的函数。它接受三个参数：

• 函数名（符号或字符串）
• 参数类型列表（数组）
• 返回类型（符号或类）

attach_function :puts, [ :string ], :int

3.3 支持的类型

Ruby-FFI 支持所有 C 原生类型，包括：

• 基本类型：:char, :uchar, :short, :ushort, :int, :uint, :long, :ulong, :float, :double
• 指针类型：:pointer
• 结构体：FFI::Struct
• 枚举：FFI::Enum

4. 项目安装方式

4.1 通过 RubyGems 安装

[sudo] gem install ffi

4.2 通过 Gemfile 安装

gem 'ffi', github: 'ffi/ffi', submodules: true

然后运行：

bundle install

4.3 从 GitHub 仓库安装

git clone git://github.com/ffi/ffi.git
cd ffi
git submodule update --init --recursive
bundle install
rake install

通过以上步骤，您可以成功安装并使用 Ruby-FFI 项目。