Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Tweaked the docs a little bit.

git-svn-id: http://mkrf.rubyforge.org/svn/trunk@36 6e48df83-f314-0410-b1e7-e69642b30866
  • Loading branch information...
commit fa0c1f5ba1c0616204ea9bf3456b6448729669e5 1 parent a6cdf76
johnmg authored
Showing with 37 additions and 22 deletions.
  1. +22 −15 README
  2. +15 −7 lib/mkrf/generator.rb
View
37 README
@@ -1,37 +1,44 @@
= mkrf -- making C extensions for Ruby a bit easier
-<tt>mkrf</tt> is intended to replace <tt>mkmf</tt>, a library for building
-Makefiles to build C extensions to Ruby. Its major goals are easy code reuse of
-its <tt>Availability</tt> class and simple, well documented, use of the
-<tt>Generator</tt> class for Rakefile generation for extensions.
+<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.
+
+Major goals of mkrf are
+* 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 (usually <tt>extconf.rb</tt>) and then runs it, which
-generates a <tt>Rakefile</tt>.
+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.
In general, <tt>extconf.rb</tt> should be placed in the root directory of the
-extension and it expects by default that files to be compiled have a <tt>.c</tt>
-extension and are in the <tt>lib/</tt> directory.
+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.
-The most basic usage looks like this, with the name of the library to be linked
-as the first argument to <tt>Mkrf::Generator.new</tt>:
+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')
-Extra arguments may be passed to the generator in a block:
+Extra arguments may be passed to the Rakefile generator in a block:
- Mkrf::Generator.new('libtrivial) do |g|
+ Mkrf::Generator.new('libtrivial') do |g|
g.logger.level = Logger::WARN
g.include_library('z')
end
-If the extension does not follow the source in <tt>lib/</tt> / <tt>.c</tt>
-extension convention, it may be overridden in the constructor:
+Another example:
- Mkrf::Generator.new('libxml', '*.c') do |g|
+ Mkrf::Generator.new('libxml') do |g|
g.include_library('socket','socket')
g.include_header('libxml/xmlversion.h',
'/opt/include/libxml2',
View
22 lib/mkrf/generator.rb
@@ -6,9 +6,15 @@
module Mkrf
# +Generator+ is concerned with taking configuration for an extension
- # and writing a +Rakefile+ to the local filesystem to build the extension.
+ # and writing a +Rakefile+ to the local filesystem which will later be
+ # used to build the extension.
+ #
+ # You will typically only create one +Generator+ per <tt>extconf.rb</tt>
+ # file, which in turn will generate a Rakefile for building one extension
+ # module.
#
# = Usage
+ #
# In the most basic usage, +Generator+ simply takes the name of the library
# to compile:
#
@@ -18,7 +24,7 @@ module Mkrf
# Configuration of the build can be passed to the +Generator+ constructor
# as a block:
#
- # Mkrf::Generator.new('libxml', 'my_extensions_dir/*.c') do |g|
+ # Mkrf::Generator.new('libxml') do |g|
# g.include_library('socket','socket')
# g.include_header('libxml/xmlversion.h',
# '/opt/include/libxml2',
@@ -35,26 +41,28 @@ class Generator
attr_accessor :additional_code
# You may append to these attributes directly in your Generator.new block,
- # for example: <tt>g.object_files << ' ../common/foo.o ../common/bar.so -lmystuff'</tt> or
+ # for example: <tt>g.object << ' ../common/foo.o ../common/bar.so -lmystuff'</tt> or
# <tt>g.cflags << ' -ansi -Wall'</tt>
#
# Note the extra space at the beginning of those strings.
attr_accessor :cflags
- # objects is for adding additional linked object files. Source objects will still be automatic.
+ # +objects+ is for adding _additional_ object files to the link-edit command -- outside
+ # of the ones that correspond to the source files.
attr_accessor :objects
- # Your system-specific linker command to build a shared library.
+ # Any additional options you'd like appended to your system-specific linker command
+ # (which is used to build the shared library).
attr_accessor :ldshared
- # Create a new generator which will write a new +Rakefile+ to the local
+ # Create a +Generator+ object which writes a Rakefile to the current directory of the local
# filesystem.
#
# Params:
# * +extension_name+ -- the name of the extension
- # * +source_patterns+ -- an array of patterns describing source files to be compiled, ["*.c"] by default
+ # * +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']}"
Please sign in to comment.
Something went wrong with that request. Please try again.