mkrf 0.1.2 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,16 @@
+= 0.2.0 2/3/07
+* [NEW] Added paths option to has_library?
+* [NEW] Added Generator#abort! for when that critical library just isn't there.
+* [NEW] Added Zed Shaw's rakehelper lib (from rfuzz, with permission).
+* [NEW] Extensions using mkrf can now build properly in RubyGems!
+* [NEW] Extension configurations should now be named mkrf_conf.rb to not conflict with the mkmf settings in RubyGems.
+* [NEW] Added example extensions.
+* [NEW] Add install task to generated Rakefile.
+* [CLEAN-UP] Preprocessor define handling moved to Availability from Generator.
+* [NEW] find_executable method added to Availability.
+* [FIXED] include_header and has_header? now properly set preprocessor defines.
+* [FIXED] Defaults on Generator work again. [44]
+
 = 0.1.2 10/4/06
 * [CLEAN-UP] Removed useless add_source from Generator. We've got a constructor for that. [35]
 * [FIXED] Generator.new defaults to sources in the local directory, so extconfs can (and should) be kept in the same directory as the extension files (PROJ_ROOT/ext) and won't clobber pre-existing Rakefiles. [35]
@@ -19,4 +32,4 @@
 * [FIXED] default source pattern for Generator [17]
 
 = 0.1.0  6/28/06
-* First release.
+* First release.

data/README

@@ -1,30 +1,35 @@
 = mkrf -- making C extensions for Ruby a bit easier
 
-<tt>mkrf</tt> is intended to replace <tt>mkmf</tt> which is a library for building
-Makefiles to build C extensions to Ruby. The major differences between the two is
-that +mkrf+ builds you a Rakefile instead of a Makefile, and also that +mkrf+
-provides an object-oriented interface.
+<tt>mkrf</tt> is a library for generating Rakefiles to build Ruby
+extension modules written in C. It is intended as a replacement for
+<tt>mkrf</tt>. The major difference between the two is that +mkrf+
+builds you a Rakefile instead of a Makefile.
 
-Major goals of mkrf are
+Major goals of mkrf include
 * easy code reuse of its <tt>Availability</tt> class and
 * simple, well documented, use of the <tt>Generator</tt> class.
 
 == Basic Usage
 
-<tt>mkrf</tt> works similarly to <tt>mkmf</tt> in that a user writes an
-extension configuration file (usually named <tt>extconf.rb</tt>) and then runs
-it (<tt>ruby ./extconf.rb</tt>), which generates a <tt>Rakefile</tt> in the
-current directory.
+<tt>mkrf</tt> works similarly to <tt>mkmf</tt> in that a user writes
+an extension configuration file and then runs it, generating a
+<tt>Rakefile</tt> in the current directory.
 
-In general, <tt>extconf.rb</tt> should be placed in the root directory of the 
-extension (ex. <tt>PROJECT_ROOT/ext/<i>name_of_module</i></tt>) and it expects,
-by default, that files to be compiled have a <tt>.c</tt> extension and reside in
-that same directory. If your project contains multiple extension modules, then
-each one would get its own subdirectory under <tt>PROJECT_ROOT/ext/</tt> and
-have its own <tt>extconf.rb</tt> file.
+With mkmf it was customary to name the extension configuration file
+"<tt>extconf.rb</tt>". With mkrf, you should name this file
+"<tt>mkrf_conf.rb</tt>".
 
-The most basic usage looks like the following, where the name of the extension
-module being built is "libtrivial":
+In general, <tt>mkrf_conf.rb</tt> should be placed in the root
+directory of the extension
+(ex. <tt>PROJECT_ROOT/ext/<i>name_of_module</i></tt>) and it expects,
+by default, that files to be compiled have a <tt>.c</tt> extension and
+reside in that same directory. If your project contains multiple
+extension modules, then each one would get its own subdirectory under
+<tt>PROJECT_ROOT/ext/</tt> and each would have its own
+<tt>mkrf_conf.rb</tt> file.
+
+The most basic usage looks like the following, where the name of the
+extension module being built is "libtrivial":
 
   require 'mkrf'
   Mkrf::Generator.new('libtrivial')
@@ -47,16 +52,39 @@ Another example:
   end
 
 
+== Helpers
+
+mkrf also comes with <tt>rakehelper.rb</tt> -- a module which contains
+methods you may want to use in your project's top-level Rakefile. The
+docs on using rakehelper do not exist at the moment, but for the time
+being, have a look at <tt>examples/trivial/Rakefile</tt> to get an
+idea of how they're used.
+
+
 == Credits
 * Jim Weirich for writing Rake
 
+
 == Licence
 mkrf is available under an MIT-style license.
 
 Copyright (c) 2006 Kevin Clark
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -41,7 +41,7 @@ namespace :test do
     BASE_DIR = File.dirname(__FILE__) + '/test/sample_files'
     
     SAMPLE_DIRS = {
-      :trivial => BASE_DIR + '/libtrivial/',
+      :trivial => BASE_DIR + '/libtrivial/ext/',
       :syck => BASE_DIR + '/syck-0.55/ext/ruby/ext/syck/',
       :libxml => BASE_DIR + '/libxml-ruby-0.3.8/ext/xml/'
     }
@@ -103,6 +103,7 @@ spec = Gem::Specification.new do |s|
   s.homepage = "http://glu.ttono.us"
 
   s.has_rdoc = true
+  s.rdoc_options << '--main' << 'README' << '--title' << 'mkrf'
   s.requirements << 'rake'
   s.require_path = 'lib'
   s.autorequire = 'mkrf'

data/lib/mkrf.rb

@@ -1,4 +1,4 @@
 require File.dirname(__FILE__) + '/mkrf/availability'
 require File.dirname(__FILE__) + '/mkrf/generator'
 
-Mkrf::VERSION = "0.1.2"
+Mkrf::VERSION = "0.2.0"

data/lib/mkrf/availability.rb

@@ -16,23 +16,26 @@ module Mkrf
     TEMP_SOURCE_FILE = "temp_source.c"
     TEMP_EXECUTABLE = "temp_executable"
     
-    attr_reader :headers, :loaded_libs, :includes, :logger
+    attr_reader :headers, :loaded_libs, :includes, :logger, :defines
     
     # Create a new Availability instance.
     #
     # Valid keys for the options hash include:
     # * <tt>:loaded_libs</tt> -- libraries to load by default
+    # * <tt>:library_paths</tt> -- libraries paths to include by default
     # * <tt>:headers</tt> -- headers to load by default
     # * <tt>:compiler</tt> -- which compiler to use when determining availability
     # * <tt>:includes</tt> -- directories that should be searched for include files
     def initialize(options = {})
       
       @loaded_libs = (options[:loaded_libs] || Config::CONFIG["LIBS"].gsub('-l', '').split).to_a
+      @library_paths = (options[:library_paths] || "").to_a
       # Not sure what COMMON_HEADERS looks like when populated
       @headers = options[:headers] || [] # Config::CONFIG["COMMON_HEADERS"]
       @compiler = options[:compiler] || Config::CONFIG["CC"]
       @includes = (options[:includes] || DEFAULT_INCLUDES).to_a
       @logger = Logger.new('mkrf.log')
+      @defines = []
     end
     
     # Include a library in the list of available libs. Returns +false+ if the
@@ -41,12 +44,18 @@ module Mkrf
     # Params:
     # * <tt>library</tt> -- the library to be included as a string.
     # * <tt>function</tt> -- a method to base the inclusion of the library on. +main+ by default.
-    def include_library(library, function = "main")
+    # * <tt>paths</tt> -- an optional list of search paths if the library is not found in the default paths.
+    def include_library(library, function = "main", *paths)
+      paths.each do |library_dir|
+        @library_paths << library_dir
+      end
       @loaded_libs << library if has_library?(library, function)
     end
     
     # Include a header in the list of availiable headers. Returns +false+ if the
-    # header is not available. Returns non-false otherwise.
+    # header is not available. Returns non-false otherwise. If the header is
+    # found, the preprocessor constant HAVE_BLAH is defined where BLAH is the name
+    # of the header in uppercase without the file extension.
     #
     # Params:
     # * <tt>header</tt> -- the name of the header to be included as a string.
@@ -61,21 +70,30 @@ module Mkrf
     # Params:
     # * <tt>library</tt> -- the library to be included as a string
     # * <tt>function</tt> -- a method to base the inclusion of the library on. +main+ by default.
-    def has_library?(library, function = "main")
+    # * <tt>paths</tt> -- an optional list of search paths if the library is not found in the default paths
+    def has_library?(library, function = "main", *paths)
       logger.info "Checking for library: #{library}"
       return true if library_already_loaded?(library)
+      # Should this be only found_library? or a specialized version with
+      # path searching?
       found_library?(library, function)
     end
     
     # Returns +true+ if the header is found in the default search path or in
-    # optional paths passed as an argument, +false+ otherwise.
+    # optional paths passed as an argument, +false+ otherwise. If the header is
+    # found, the preprocessor constant HAVE_BLAH is defined where BLAH is the name
+    # of the header in uppercase without the file extension.
     #
     # Params:
     # * <tt>header</tt> -- the header to be searched for
     # * <tt>paths</tt> -- an optional list of search paths if the header is not found in the default paths
     def has_header?(header, *paths)
-      return true if header_already_loaded?(header) || header_can_link?(header) || 
+      if header_already_loaded?(header) || header_can_link?(header) || 
                      header_found_in_paths?(header, paths)
+        defines << format("HAVE_%s", header.tr("a-z./\055", "A-Z___"))
+        return true 
+      end
+      
       logger.warn "Header not found: #{header}"
       return false
     end
@@ -124,11 +142,28 @@ module Mkrf
       @loaded_libs.collect {|l| "-l#{l}"}.join(' ')
     end
     
+    # Returns a string of libraries directories formatted for compilation
+    def library_paths_compile_string
+      @library_paths.collect {|l| "-L#{l}"}.join(' ')
+    end
+
     # Returns a string of include directories formatted for compilation
     def includes_compile_string
       @includes.collect {|i| "-I#{i}"}.join(' ')
     end
     
+    # Takes the name of an executable and an optional set of paths to search.
+    # If no paths are given, the environmental path is used by default.
+    # Returns the absolute path to an executable, or nil if not found.
+    def find_executable(bin, *paths)
+      paths = ENV['PATH'].split(File::PATH_SEPARATOR) if paths.empty?
+      paths.each do |path|
+        file = File.join(path, bin)
+        return file if File.executable?(file)
+      end
+      return nil
+    end
+    
     private
     
     def found_library?(library, function)
@@ -171,6 +206,19 @@ module Mkrf
       return false
     end
     
+#    def library_found_in_paths?(library, paths)
+#      paths.each do |include_path|
+#
+#        if with_libs(include_path) { library_can_link?(header) }
+#          @libspath << include_path
+#          return true
+#        end
+#      end
+#      
+#      return false
+# 
+#    end
+
     def header_found_in_paths?(header, paths)
       paths.each do |include_path|
         if with_includes(include_path) { header_can_link?(header) }
@@ -197,8 +245,11 @@ module Mkrf
     end
     
     def link_command
-      "#{@compiler} -o #{TEMP_EXECUTABLE} #{library_compile_string} " +
-      "#{includes_compile_string} #{TEMP_SOURCE_FILE}"
+      # This current implementation just splats the library_paths in
+      # unconditionally.  Is this problematic?
+      "#{@compiler} -o #{TEMP_EXECUTABLE} #{library_paths_compile_string}" +
+      " #{library_compile_string} #{includes_compile_string}" +
+      " #{TEMP_SOURCE_FILE}"
     end
 
     # Creates a temporary source file with the string passed
@@ -263,4 +314,4 @@ module Mkrf
     end
     
   end
-end
+end

data/lib/mkrf/generator.rb

@@ -32,6 +32,12 @@ module Mkrf
   #                      '/usr/include/libxml2')
   #   end
   #  
+  # It is also possible to specify the library paths in
+  # include_library
+  #   Mkrf::Generator.new('libxml') do |g|
+  #     g.include_library('socket','socket', '/usr/local/lib/libxml')
+  #   end
+  #  
   class Generator
     include Rake
     
@@ -63,15 +69,17 @@ module Mkrf
     # Params:
     # * +extension_name+ -- the name of the extension
     # * +source_patterns+ -- an array of patterns describing source files to be compiled. ["*.c"] is the default.
+    
     def initialize(extension_name, source_patterns = ["*.c"], availability_options = {})
       @sources = source_patterns
       @extension_name = extension_name + ".#{CONFIG['DLEXT']}"
       @available = Mkrf::Availability.new(availability_options)
       @defines = []
+      @cc = CONFIG['CC']
       
-      objects = ''
-      ldshared = CONFIG['LDSHARED']
-      cflags = "#{CONFIG['CCDLFLAGS']} #{CONFIG['CFLAGS']} #{CONFIG['ARCH_FLAG']}"
+      @objects  = ''
+      @ldshared = ''
+      @cflags   = "#{CONFIG['CCDLFLAGS']} #{CONFIG['CFLAGS']} #{CONFIG['ARCH_FLAG']}"
       
       yield self if block_given?
       write_rakefile
@@ -85,13 +93,13 @@ module Mkrf
     # Add a define to the compile string. Example: 
     #
     #   Mkrf::Generator.new('my_library') do |g|    
-    #     g.add_define(HAVE_PTHREADS)
+    #     g.add_define('HAVE_PTHREADS')
     #   end
     #
     # Params:
     # * +defn+ -- string to add to compile time defines
     def add_define(defn)
-      @defines.push(defn)
+      @available.defines << defn
     end
     
     # Include a library in the compile. Returns +false+ if the
@@ -129,22 +137,26 @@ module Mkrf
       @available.logger
     end
     
+    # Logs a fatal error and exits with a non-zero code (defaults to 1)
+    def abort!(str, code = 1)
+      logger.fatal str
+      exit code
+    end
+    
     def write_rakefile(filename = "Rakefile") # :nodoc:
       File.open(filename, "w+") do |f|
         f.puts rakefile_contents
       end
-      @available.logger.info "Rakefile written"
+      logger.info "Rakefile written"
     end
     
     def defines_compile_string # :nodoc:
-      (@defines.collect {|define| "-D#{define}" } +
-      @available.headers.collect { |header|
-        format("-DHAVE_%s", header.tr("a-z./\055", "A-Z___"))
-      }).join(' ')
+      @available.defines.collect {|define| "-D#{define}"}.join(' ')
     end
     
     def rakefile_contents # :nodoc:
       <<-END_RAKEFILE
+# Generated by mkrf
 require 'rake/clean'
 
 CLEAN.include('*.o')
@@ -152,13 +164,13 @@ CLOBBER.include('#{@extension_name}', 'mkrf.log')
 
 SRC = FileList[#{sources.join(',')}]
 OBJ = SRC.ext('o')
-CC = "gcc"
+CC = '#{@cc}'
 
 ADDITIONAL_OBJECTS = '#{objects}'
 
 LDSHARED = "#{CONFIG['LDSHARED']} #{ldshared}"
 
-LIBPATH =  '-L"#{CONFIG['rubylibdir']}"'
+LIBPATH =  "-L#{CONFIG['rubylibdir']} #{@available.library_paths_compile_string}"
 
 INCLUDES = "#{@available.includes_compile_string}"
 
@@ -166,6 +178,8 @@ LIBS = "#{@available.library_compile_string}"
 
 CFLAGS = "#{cflags} #{defines_compile_string}"
 
+RUBYARCHDIR = "\#{ENV["RUBYARCHDIR"]}"
+
 task :default => ['#{@extension_name}']
 
 rule '.o' => '.c' do |t|
@@ -177,6 +191,12 @@ file '#{@extension_name}' => OBJ do
   sh "\#{LDSHARED} \#{LIBPATH} -o #{@extension_name} \#{OBJ} \#{ADDITIONAL_OBJECTS} \#{LIBS}"
 end
 
+desc "Install this extension"
+task :install => '#{@extension_name}' do
+  makedirs "\#{RUBYARCHDIR}"
+  install "#{@extension_name}", "\#{RUBYARCHDIR}"
+end
+
 #{additional_code}
       END_RAKEFILE
     end

data/lib/mkrf/rakehelper.rb

@@ -0,0 +1,123 @@
+# 
+#  Copyright (c) 2005 Zed A. Shaw with portions by Kevin Clark
+#  You can redistribute it and/or modify it under the same terms as Ruby.
+# 
+
+def rake(rakedir)
+  Dir.chdir(rakedir) do
+    sh 'rake'
+  end
+end
+
+
+def mkrf_conf(dir)
+  Dir.chdir(dir) do ruby "mkrf_conf.rb" end
+end
+
+
+def setup_tests
+  Rake::TestTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/test*.rb']
+    t.verbose = true
+  end
+end
+
+
+def setup_clean otherfiles
+  files = ['build/*', '**/*.o', '**/*.so', '**/*.a', 'lib/*-*', '**/*.log'] + otherfiles
+  CLEAN.include(files)
+end
+
+
+def setup_rdoc files
+  Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = 'doc/rdoc'
+    rdoc.options << '--line-numbers'
+    rdoc.rdoc_files.add(files)
+  end
+end
+
+
+def setup_extension(dir, extension)
+  ext = "ext/#{dir}"
+  ext_so = "#{ext}/#{extension}.#{Config::CONFIG['DLEXT']}"
+  ext_files = FileList[
+    "#{ext}/*.c",
+    "#{ext}/*.h",
+    "#{ext}/mkrf_conf.rb",
+    "#{ext}/Rakefile",
+    "lib"
+  ] 
+
+  task "lib" do
+    directory "lib"
+  end
+
+  desc "Builds just the #{extension} extension"
+  task extension.to_sym => ["#{ext}/Rakefile", ext_so ]
+
+  file "#{ext}/Rakefile" => ["#{ext}/mkrf_conf.rb"] do
+    mkrf_conf "#{ext}"
+  end
+
+  file ext_so => ext_files do
+    rake "#{ext}"
+    cp ext_so, "lib"
+  end
+end
+
+
+def base_gem_spec(pkg_name, pkg_version)
+  rm_rf "test/coverage"
+
+  pkg_version = pkg_version
+  pkg_name    = pkg_name
+  pkg_file_name = "#{pkg_name}-#{pkg_version}"
+  Gem::Specification.new do |s|
+    s.name = pkg_name
+    s.version = pkg_version
+    s.platform = Gem::Platform::RUBY
+    s.has_rdoc = true
+    s.extra_rdoc_files = [ "README" ]
+
+    s.files = %w(Rakefile) +
+      Dir.glob("{bin,doc/rdoc,ext,examples}/**/*") + 
+      Dir.glob("tools/*.rb") +
+      Dir.glob(RUBY_PLATFORM !~ /mswin/ ? "lib/**/*.rb" : "lib/**/*")
+
+    s.require_path = "lib"
+    s.bindir = "bin"
+  end
+end
+
+def setup_gem(pkg_name, pkg_version)
+  spec = base_gem_spec(pkg_name, pkg_version)
+  yield spec if block_given?
+
+
+  Rake::GemPackageTask.new(spec) do |p|
+    p.gem_spec = spec
+    p.need_tar = true if RUBY_PLATFORM !~ /mswin/
+  end
+end
+
+def sub_project(project, *targets)
+  targets.each do |target|
+    Dir.chdir "projects/#{project}" do
+      sh %{rake --trace #{target.to_s} }
+    end
+  end
+end
+
+# Conditional require rcov/rcovtask if present
+begin
+  require 'rcov/rcovtask'
+  
+  Rcov::RcovTask.new do |t|
+    t.test_files = FileList['test/test*.rb']
+    t.rcov_opts << "-x /usr"
+    t.output_dir = "test/coverage"
+  end
+rescue Object
+end