Skip to content

larskanis/ffi

 
 

Description

Ruby-FFI is a gem for programmatically loading dynamically-linked native libraries, binding functions within them, and calling those functions from Ruby code. Moreover, a Ruby-FFI extension works without changes on CRuby (MRI), JRuby, Rubinius and TruffleRuby. Discover why you should write your next extension using Ruby-FFI.

Features

  • Intuitive DSL
  • Supports all C native types
  • C structs (also nested), enums and global variables
  • Callbacks from C to Ruby
  • Automatic garbage collection of native memory

Synopsis

require 'ffi'

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

MyLib.puts 'Hello, World using libc!'

For less minimalistic and more examples you may look at:

Requirements

When installing the gem on CRuby (MRI), you will need:

  • A C compiler (e.g., Xcode on macOS, gcc or clang on everything else) Optionally (speeds up installation):
  • The libffi library and development headers - this is commonly in the libffi-dev or libffi-devel packages

The ffi gem comes with a builtin libffi version, which is used, when the system libffi library is not available or too old. Use of the system libffi can be enforced by:

gem install ffi -- --enable-system-libffi        # to install the gem manually
bundle config build.ffi --enable-system-libffi   # for bundle install

or prevented by --disable-system-libffi.

On Linux systems running with PaX (Gentoo, Alpine, etc.), FFI may trigger mprotect errors. You may need to disable mprotect for ruby (paxctl -m [/path/to/ruby]) for the time being until a solution is found.

On FreeBSD systems pkgconf must be installed for the gem to be able to compile using clang. Install either via packages pkg install pkgconf or from ports via devel/pkgconf.

On JRuby and TruffleRuby, there are no requirements to install the FFI gem, and require 'ffi' works even without installing the gem (i.e., the gem is preinstalled on these implementations).

Installation

From rubygems:

[sudo] gem install ffi

or from the git repository on github:

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

License

The ffi library is covered by the BSD license, also see the LICENSE file. The specs are covered by the same license as ruby/spec, the MIT license.

Credits

The following people have submitted code, bug reports, or otherwise contributed to the success of this project:

About

Ruby FFI

Resources

License

BSD-3-Clause and 2 other licenses found

Licenses found

BSD-3-Clause
LICENSE
Unknown
COPYING
MIT
LICENSE.SPECS

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Ruby 50.0%
  • C 47.0%
  • Makefile 2.1%
  • Other 0.9%