ffi 1.0.0 → 1.17.1

data/README.md

@@ -0,0 +1,137 @@
+# Ruby-FFI https://github.com/ffi/ffi/wiki
+
+## 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](https://github.com/ffi/ffi/wiki/why-use-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
+* Usable in Ractor: [How-to-use-FFI-in-Ruby-Ractors](https://github.com/ffi/ffi/wiki/Ractors)
+
+## Synopsis
+
+```ruby
+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:
+
+* the `samples/` folder
+* the examples on the [wiki](https://github.com/ffi/ffi/wiki)
+* the projects using FFI listed on the wiki: https://github.com/ffi/ffi/wiki/projects-using-ffi
+
+## 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](https://en.wikipedia.org/wiki/PaX) (Gentoo, Alpine, etc.), FFI may trigger `mprotect` errors. You may need to disable [mprotect](https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecurity_and_PaX_Configuration_Options#Restrict_mprotect.28.29) 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
+
+From a Gemfile using git or GitHub
+
+    gem 'ffi', github: 'ffi/ffi', submodules: true
+
+or from the git repository on github:
+
+    git clone git://github.com/ffi/ffi.git
+    cd ffi
+    git submodule update --init --recursive
+    bundle install
+    rake install
+
+### Install options:
+
+* `--enable-system-libffi` : Force usage of system libffi
+* `--disable-system-libffi` : Force usage of builtin libffi
+* `--enable-libffi-alloc` : Force closure allocation by libffi
+* `--disable-libffi-alloc` : Force closure allocation by builtin method
+
+## 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](https://github.com/ruby/spec), the MIT license.
+
+## Credits
+
+The following people have submitted code, bug reports, or otherwise contributed to the success of this project:
+
+* Alban Peignier <alban.peignier@free.fr>
+* Aman Gupta <aman@tmm1.net>
+* Andrea Fazzi <andrea.fazzi@alcacoop.it>
+* Andreas Niederl <rico32@gmx.net>
+* Andrew Cholakian <andrew@andrewvc.com>
+* Antonio Terceiro <terceiro@softwarelivre.org>
+* Benoit Daloze <eregontp@gmail.com>
+* Brian Candler <B.Candler@pobox.com>
+* Brian D. Burns <burns180@gmail.com>
+* Bryan Kearney <bkearney@redhat.com>
+* Charlie Savage <cfis@zerista.com>
+* Chikanaga Tomoyuki <nagachika00@gmail.com>
+* Hongli Lai <hongli@phusion.nl>
+* Ian MacLeod <ian@nevir.net>
+* Jake Douglas <jake@shiftedlabs.com>
+* Jean-Dominique Morani <jdmorani@mac.com>
+* Jeremy Hinegardner <jeremy@hinegardner.org>
+* Jesús García Sáez <blaxter@gmail.com>
+* Joe Khoobyar <joe@ankhcraft.com>
+* Jurij Smakov <jurij@wooyd.org>
+* KISHIMOTO, Makoto <ksmakoto@dd.iij4u.or.jp>
+* Kim Burgestrand <kim@burgestrand.se>
+* Lars Kanis <lars@greiz-reinsdorf.de>
+* Luc Heinrich <luc@honk-honk.com>
+* Luis Lavena <luislavena@gmail.com>
+* Matijs van Zuijlen <matijs@matijs.net>
+* Matthew King <automatthew@gmail.com>
+* Mike Dalessio <mike.dalessio@gmail.com>
+* NARUSE, Yui <naruse@airemix.jp>
+* Park Heesob <phasis@gmail.com>
+* Shin Yee <shinyee@speedgocomputing.com>
+* Stephen Bannasch <stephen.bannasch@gmail.com>
+* Suraj N. Kurapati <sunaku@gmail.com>
+* Sylvain Daubert <sylvain.daubert@laposte.net>
+* Victor Costan
+* beoran@gmail.com
+* ctide <christide@christide.com>
+* emboss <Martin.Bosslet@googlemail.com>
+* hobophobe <unusualtears@gmail.com>
+* meh <meh@paranoici.org>
+* postmodern <postmodern.mod3@gmail.com>
+* wycats@gmail.com <wycats@gmail.com>
+* Wayne Meissner <wmeissner@gmail.com>

data/Rakefile

@@ -1,189 +1,206 @@
-require 'rubygems'
 require 'rbconfig'
-
-USE_RAKE_COMPILER = (RUBY_PLATFORM =~ /java/) ? false : true
-if USE_RAKE_COMPILER
-  gem 'rake-compiler', '>=0.6.0'
-  require 'rake/extensiontask'
-  ENV['RUBY_CC_VERSION'] = '1.8.6:1.9.1'
-end
-
 require 'date'
 require 'fileutils'
-require 'rbconfig'
+require 'yaml'
+require 'rspec/core/rake_task'
+require 'rubygems/package_task'
+require 'rake/extensiontask'
+require_relative "lib/ffi/version"
+require_relative "rakelib/ffi_gem_helper"
 
-load 'tasks/setup.rb'
+BUILD_DIR = "build"
+BUILD_EXT_DIR = File.join(BUILD_DIR, "#{RbConfig::CONFIG['arch']}", 'ffi_c', RUBY_VERSION)
 
-LIBEXT = case Config::CONFIG['host_os'].downcase
-  when /darwin/
-    "dylib"
-  when /mswin|mingw/
-    "dll"
-  else
-    Config::CONFIG['DLEXT']
-  end
+gem_spec = Bundler.load_gemspec('ffi.gemspec')
 
-CPU = case Config::CONFIG['host_cpu'].downcase
-  when /i[3456]86/
-    # Darwin always reports i686, even when running in 64bit mode
-    if Config::CONFIG['host_os'] =~ /darwin/ && 0xfee1deadbeef.is_a?(Fixnum)
-      "x86_64"
-    else
-      "i386"
-    end
+RSpec::Core::RakeTask.new(:spec) do |config|
+  config.rspec_opts = YAML.load_file 'spec/spec.opts'
+end
 
-  when /amd64|x86_64/
-    "x86_64"
+desc "Build all packages"
+task :package => %w[ gem:java gem:native ]
+
+CLOBBER.include 'lib/ffi/types.conf'
+CLOBBER.include 'pkg'
+CLOBBER.include 'log'
+
+CLEAN.include 'build'
+CLEAN.include 'conftest.dSYM'
+CLEAN.include 'spec/ffi/fixtures/libtest.{dylib,so,dll}'
+CLEAN.include 'spec/ffi/fixtures/*.o'
+CLEAN.include 'spec/ffi/embed-test/ext/*.{o,def}'
+CLEAN.include 'spec/ffi/embed-test/ext/Makefile'
+CLEAN.include "pkg/ffi-*-*/"
+CLEAN.include 'lib/{2,3}.*'
+
+# clean all shipped files, that are not in git
+CLEAN.include(
+    gem_spec.files -
+    `git --git-dir ext/ffi_c/libffi/.git ls-files -z`.split("\x0").map { |f| File.join("ext/ffi_c/libffi", f) } -
+    `git ls-files -z`.split("\x0")
+)
+
+task :distclean => :clobber
 
-  when /ppc64|powerpc64/
-    "powerpc64"
+desc "Test the extension"
+task :test => [ :spec ]
 
-  when /ppc|powerpc/
-    "powerpc"
 
-  else
-    Config::CONFIG['host_cpu']
+namespace :bench do
+  ITER = ENV['ITER'] ? ENV['ITER'].to_i : 100000
+  bench_files = Dir["bench/bench_*.rb"].sort.reject { |f| f == "bench/bench_helper.rb" }
+  bench_files.each do |bench|
+    task File.basename(bench, ".rb")[6..-1] => :compile do
+      sh %{#{Gem.ruby} #{bench} #{ITER}}
+    end
   end
-
-OS = case Config::CONFIG['host_os'].downcase
-  when /linux/
-    "linux"
-  when /darwin/
-    "darwin"
-  when /freebsd/
-    "freebsd"
-  when /openbsd/
-    "openbsd"
-  when /sunos|solaris/
-    "solaris"
-  when /mswin|mingw/
-    "win32"
-  else
-    Config::CONFIG['host_os'].downcase
+  task :all => :compile do
+    bench_files.each do |bench|
+      sh %{#{Gem.ruby} #{bench}}
+    end
   end
+end
 
-CC=ENV['CC'] || Config::CONFIG['CC'] || "gcc"
-
-GMAKE = Config::CONFIG['host_os'].downcase =~ /bsd|solaris/ ? "gmake" : "make"
-
-LIBTEST = "build/libtest.#{LIBEXT}"
-BUILD_DIR = "build"
-BUILD_EXT_DIR = File.join(BUILD_DIR, "#{Config::CONFIG['arch']}", 'ffi_c', RUBY_VERSION)
-
-# Project general information
-PROJ.name = 'ffi'
-PROJ.authors = 'Wayne Meissner'
-PROJ.email = 'wmeissner@gmail.com'
-PROJ.url = 'http://wiki.github.com/ffi/ffi'
-PROJ.version = '1.0.0'
-PROJ.rubyforge.name = 'ffi'
-PROJ.readme_file = 'README.rdoc'
-
-# Annoucement
-PROJ.ann.paragraphs << 'FEATURES' << 'SYNOPSIS' << 'REQUIREMENTS' << 'DOWNLOAD/INSTALL' << 'CREDITS' << 'LICENSE'
-
-PROJ.ann.email[:from] = 'andrea.fazzi@alcacoop.it'
-PROJ.ann.email[:to] = ['ruby-ffi@googlegroups.com']
-PROJ.ann.email[:server] = 'smtp.gmail.com'
-
-# Gem specifications
-PROJ.gem.need_tar = false
-PROJ.gem.files = %w(History.txt LICENSE README.rdoc Rakefile) + Dir.glob("{ext,gen,lib,spec,tasks}/**/*")
-PROJ.gem.platform = Gem::Platform::RUBY
-
-# Override Mr. Bones autogenerated extensions and force ours in
-PROJ.gem.extras['extensions'] = %w(ext/ffi_c/extconf.rb gen/Rakefile)
+task 'spec:run' => :compile
+task 'spec:specdoc' => :compile
 
-# RDoc
-PROJ.rdoc.exclude << '^ext\/'
-PROJ.rdoc.opts << '-x' << 'ext'
+task :default => :spec
 
-# Ruby
-PROJ.ruby_opts = []
-PROJ.ruby_opts << '-I' << BUILD_EXT_DIR unless RUBY_PLATFORM == "java"
+namespace 'java' do
 
-# RSpec
-PROJ.spec.files.exclude /rbx/
-PROJ.spec.opts << '--color' << '-fs'
+  java_gem_spec = gem_spec.dup.tap do |s|
+    s.files.reject! { |f| File.fnmatch?("ext/*", f) }
+    s.extensions = []
+    s.platform = 'java'
+  end
 
-# Dependencies
+  Gem::PackageTask.new(java_gem_spec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+    pkg.package_dir = 'pkg'
+  end
+end
 
-depend_on 'rake', '>=0.8.7'
+task 'gem:java' => 'java:gem'
+
+FfiGemHelper.install_tasks
+# Register binary gems to be pushed to rubygems.org
+Bundler::GemHelper.instance.cross_platforms = %w[
+  x86-mingw32
+  x64-mingw-ucrt
+  x64-mingw32
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-linux-gnu
+  x86_64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  x86_64-darwin
+  arm64-darwin
+]
+
+if RUBY_ENGINE == 'ruby' || RUBY_ENGINE == 'rbx'
+  require 'rake/extensiontask'
+  Rake::ExtensionTask.new('ffi_c', gem_spec) do |ext|
+    ext.name = 'ffi_c'                                        # indicate the name of the extension.
+    # ext.lib_dir = BUILD_DIR                                 # put binaries into this folder.
+    ext.tmp_dir = BUILD_DIR                                   # temporary folder used during compilation.
+    ext.cross_compile = true                                  # enable cross compilation (requires cross compile toolchain)
+    ext.cross_platform = Bundler::GemHelper.instance.cross_platforms
+    ext.cross_compiling do |spec|
+      spec.files.reject! { |path| File.fnmatch?('ext/*', path) }
+    end
+    # Enable debug info for 'rake compile' but not for 'gem install'
+    ext.config_options << "--enable-debug"
 
-TEST_DEPS = [ LIBTEST ]
-if RUBY_PLATFORM == "java"
-  desc "Run all specs"
-  task :specs => TEST_DEPS do
-    sh %{#{Gem.ruby} -S spec #{Dir["spec/ffi/*_spec.rb"].join(" ")} -fs --color}
-  end
-  desc "Run rubinius specs"
-  task :rbxspecs => TEST_DEPS do
-    sh %{#{Gem.ruby} -S spec #{Dir["spec/ffi/rbx/*_spec.rb"].join(" ")} -fs --color}
   end
 else
-  TEST_DEPS.unshift :compile
-  desc "Run all specs"
-  task :specs => TEST_DEPS do
-    ENV["MRI_FFI"] = "1"
-    sh %{#{Gem.ruby} -Ilib -I#{BUILD_EXT_DIR} -S spec #{Dir["spec/ffi/*_spec.rb"].join(" ")} -fs --color}
-  end
-  desc "Run rubinius specs"
-  task :rbxspecs => TEST_DEPS do
-    ENV["MRI_FFI"] = "1"
-    sh %{#{Gem.ruby} -Ilib -I#{BUILD_EXT_DIR} -S spec #{Dir["spec/ffi/rbx/*_spec.rb"].join(" ")} -fs --color}
+  task :compile do
+    STDERR.puts "Nothing to compile on #{RUBY_ENGINE}"
   end
 end
 
-desc "Build all packages"
-task :package => 'gem:package'
 
-desc "Install the gem locally"
-task :install => 'gem:install'
+namespace "gem" do
+  task 'prepare' do
+    require 'rake_compiler_dock'
+    sh "bundle package --all"
+  end
 
+  Bundler::GemHelper.instance.cross_platforms.each do |plat|
+    desc "Build all native binary gems in parallel"
+    multitask 'native' => plat
+
+    desc "Build the native gem for #{plat}"
+    task plat => ['prepare', 'build'] do
+      RakeCompilerDock.sh <<-EOT, platform: plat
+        sudo apt-get update && sudo apt-get install -y libltdl-dev &&
+        bundle --local &&
+        rake native:#{plat} pkg/#{gem_spec.full_name}-#{plat}.gem MAKE='nice make -j`nproc`' RUBY_CC_VERSION=${RUBY_CC_VERSION/:2.4.0/}
+      EOT
+    end
+  end
+end
 
-desc "Clean all built files"
-task :distclean => :clobber do
-  FileUtils.rm_rf('build')
-  FileUtils.rm_rf(Dir["lib/**/ffi_c.#{Config::CONFIG['DLEXT']}"])
-  FileUtils.rm_rf('lib/1.8')
-  FileUtils.rm_rf('lib/1.9')
-  FileUtils.rm_rf('lib/ffi/types.conf')
-  FileUtils.rm_rf('conftest.dSYM')
-  FileUtils.rm_rf('pkg')
+directory "ext/ffi_c/libffi"
+file "ext/ffi_c/libffi/autogen.sh" => "ext/ffi_c/libffi" do
+  warn "Downloading libffi ..."
+  sh "git submodule update --init --recursive"
 end
+task :libffi => "ext/ffi_c/libffi/autogen.sh"
 
+LIBFFI_GIT_FILES = `git --git-dir ext/ffi_c/libffi/.git ls-files -z`.split("\x0")
 
-desc "Build the native test lib"
-task "build/libtest.#{LIBEXT}" do
-  sh %{#{GMAKE} -f libtest/GNUmakefile CPU=#{CPU} OS=#{OS} }
+# Generate files which are in the gemspec but not in libffi's git repo by running autogen.sh
+gem_spec.files.select do |f|
+  f =~ /ext\/ffi_c\/libffi\/(.*)/ && !LIBFFI_GIT_FILES.include?($1)
+end.each do |f|
+  file f => "ext/ffi_c/libffi/autogen.sh" do
+    chdir "ext/ffi_c/libffi" do
+      sh "sh ./autogen.sh"
+    end
+    touch f
+    if gem_spec.files != Gem::Specification.load('./ffi.gemspec').files
+      warn "gemspec files have changed -> Please restart rake!"
+      exit 1
+    end
+  end
 end
 
+# Make sure we have all gemspec files before packaging
+task :build => gem_spec.files
+task :gem => :build
 
-desc "Build test helper lib"
-task :libtest => "build/libtest.#{LIBEXT}"
-
-desc "Test the extension"
-task :test => [ :specs, :rbxspecs ]
 
+require_relative "lib/ffi/platform"
+types_conf = File.expand_path(File.join(FFI::Platform::CONF_DIR, 'types.conf'))
+logfile = File.join(File.dirname(__FILE__), 'types_log')
 
-namespace :bench do
-  ITER = ENV['ITER'] ? ENV['ITER'].to_i : 100000
-  bench_libs = "-Ilib -I#{BUILD_DIR}" unless RUBY_PLATFORM == "java"
-  bench_files = Dir["bench/bench_*.rb"].reject { |f| f == "bench_helper.rb" }
-  bench_files.each do |bench|
-    task File.basename(bench, ".rb")[6..-1] => TEST_DEPS do
-      sh %{#{Gem.ruby} #{bench_libs} #{bench} #{ITER}}
-    end
+task types_conf do |task|
+  require 'fileutils'
+  require_relative "lib/ffi/tools/types_generator"
+  options = {}
+  FileUtils.mkdir_p(File.dirname(task.name), mode: 0755 )
+  File.open(task.name, File::CREAT|File::TRUNC|File::RDWR, 0644) do |f|
+    f.puts FFI::TypesGenerator.generate(options)
   end
-  task :all => TEST_DEPS do
-    bench_files.each do |bench|
-      sh %{#{Gem.ruby} #{bench_libs} #{bench}}
-    end
+  File.open(logfile, 'w') do |log|
+    log.puts(types_conf)
   end
 end
 
-task 'spec:run' => TEST_DEPS
-task 'spec:specdoc' => TEST_DEPS
+desc "Create or update type information for platform #{FFI::Platform::NAME}"
+task :types_conf => types_conf
 
-task :default => :specs
+begin
+  require 'yard'
 
+  namespace :doc do
+    YARD::Rake::YardocTask.new do |yard|
+    end
+  end
+rescue LoadError
+  warn "[warn] YARD unavailable"
+end