* lib/mkmf.rb (create_makefile): rdoc about srcprefix. a patch from

  Daniel Berger <djberg96 AT gmail.com> in [ruby-core:13378].


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@13896 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 31 insertions, 0 deletions

diff --git a/lib/mkmf.rb b/lib/mkmf.rb
index 51cdd4ee3f..6d1aa35926 100644
--- a/lib/mkmf.rb
+++ b/lib/mkmf.rb
@@ -1265,6 +1265,37 @@ end
 # load the file within a Ruby program later, that directory structure will
 # have to be followed, e.g. "require 'test/foo'".
 #
+# The +srcprefix+ should be used when your source files are not in the same
+# directory as your build script. This will not only eliminate the need for
+# you to manually copy the source files into the same directory as your build
+# script, but it also sets the proper +target_prefix+ in the generated
+# Makefile.
+#
+# Setting the +target_prefix+ will, in turn, install the generated binary in
+# a directory under your Config::CONFIG['sitearchdir'] that mimics your local
+# filesystem when you run 'make install'.
+#
+# For example, given the following file tree:
+#
+#    ext/
+#       extconf.rb
+#       test/
+#          foo.c
+#
+# And given the following code:
+#
+#    create_makefile('test/foo', 'test')
+#
+# That will set the +target_prefix+ in the generated Makefile to 'test'. That,
+# in turn, will create the following file tree when installed via the
+# 'make install' command:
+#
+#    /path/to/ruby/sitearchdir/test/foo.so
+#
+# It is recommended that you use this approach to generate your makefiles,
+# instead of copying files around manually, because some third party
+# libraries may depend on the +target_prefix+ being set properly.
+#
 def create_makefile(target, srcprefix = nil)
   $target = target
   libpath = $DEFLIBPATH|$LIBPATH