ruby-core

--- nobu@ruby-lang.org wrote:

> Hi,
> 
> At Sun, 9 Jul 2006 03:11:44 +0900,
> Daniel Berger wrote in [ruby-core:08177]:
> > Attached is an rdoc patch for what I believe are
> the
> > most used methods of mkmf.  They include docs for:
> 
> Thank you for the great job.
> 
> > check_sizeof
> 
> I guess checking exact size of a type is less
> necessary in
> common.  Checking trueness of an expression might be
> enough in
> most cases, I guess.
> 
> E.g.:
> 
>   def check_iftrue(expr, headers = nil, &b)
>     checking_for("if #{expr}") do
>       try_static_assert(expr, headers, &b)
>     end
>   end
> 
>   check_iftrue("sizeof(long) == sizeof(void*)")
> 
> than:
> 
>   check_sizeof("void*") == check_sizeof("long")

Probably.  What would it return for a preprocessor
constant, if any?  Well, I leave it up to you.

> 
> > check_sizeof
> > have_library
> > have_struct_member
> > have_type
> 
> And these 4 methods accepts a name or a list for
> headers.

Ok, I've updated the docs to reflect this and modified
the source a tiny bit to use the word 'headers'
instead of 'header' to indicate to programmers that it
can take more than one.

> 
> > Also, I was wondering if we could get the
> have_const
> > method added in, as per Nobu's patch in
> > ruby-core:4426.
> 
> It worked for integral constants only.  Now I guess
> have_macro
> and have_var would do the role instead.  Any idea?

Neither of those work for checking the presence of an
enum typedef member in my experiments.  See
ruby-core:4422.  Perhaps I've made a mistake, though.

What is the purpose of allowing a block to methods
like have_header?  I can see within create_tmpsrc that
it does 'src = yield(src) if block_given?'.  How would
one use a block in practice?  Or is it an artifact of
some sort?

Also, should we tag the methods that aren't meant for
public use with :no-doc: tags?  Or perhaps move all of
these methods into Kernel, and designate private
methods?

Attached is the updated diff.

Regards,

Dan

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com

Attachments (1)

mkmf.diff (8.61 KB, text/x-diff)

--- mkmf.orig	Fri Jun 02 02:16:44 2006
+++ mkmf.rb	Sun Jul 09 11:01:41 2006
@@ -547,6 +547,11 @@
   r
 end
 
+# Returns whether or not +macro+ is defined either in the common header
+# files or within any +headers+ you provide.
+#
+# Any options you pass to +opt+ are passed along to the compiler.
+#
 def have_macro(macro, headers = nil, opt = "", &b)
   m = "#{macro}"
   m << " in #{headers.inspect}" if headers
@@ -555,7 +560,15 @@
   end
 end
 
-def have_library(lib, func = nil, header=nil, &b)
+# Returns whether or not the given entry point +func+ can be found within
+# +lib+.  If +func+ is nil, the 'main()' entry point is used by default.
+# If found, it adds the library to list of libraries to be used when linking
+# your extension.
+#
+# If +headers+ are provided, it will include those header files as the
+# header files it looks in when searching for +func+.
+#
+def have_library(lib, func = nil, headers=nil, &b)
   func = "main" if !func or func.empty?
   lib = with_config(lib+'lib', lib)
   checking_for "#{func}() in #{LIBARG%lib}" do
@@ -563,7 +576,7 @@
       true
     else
       libs = append_library($libs, lib)
-      if try_func(func, libs, header, &b)
+      if try_func(func, libs, headers, &b)
         $libs = libs
         true
       else
@@ -573,6 +586,13 @@
   end
 end
 
+# Returns whether or not the entry point +func+ can be found within the library
+# +lib+ in one of the +paths+ specified, where +paths+ is an array of strings.
+# If +func+ is nil , then the main() function is used as the entry point.
+#
+# If +lib+ is found, then the path it was found on is added to the list of
+# library paths searched and linked against.
+#
 def find_library(lib, func, *paths, &b)
   func = "main" if !func or func.empty?
   lib = with_config(lib+'lib', lib)
@@ -595,6 +615,14 @@
   end
 end
 
+# Returns whether or not the function +func+ can be found in the common
+# header files, or within any +headers+ that you provide.  If found, a
+# macro is passed as a preprocessor constant to the compiler using the
+# function name, in uppercase, prepended with 'HAVE_'.
+#
+# For example, if have_func('foo') returned true, then the HAVE_FOO
+# preprocessor macro would be passed to the compiler.
+#
 def have_func(func, headers = nil, &b)
   checking_for "#{func}()" do
     if try_func(func, $libs, headers, &b)
@@ -606,6 +634,14 @@
   end
 end
 
+# Returns whether or not the variable +var+ can be found in the common
+# header files, or within any +headers+ that you provide.  If found, a
+# macro is passed as a preprocessor constant to the compiler using the
+# variable name, in uppercase, prepended with 'HAVE_'.
+#
+# For example, if have_var('foo') returned true, then the HAVE_FOO
+# preprocessor macro would be passed to the compiler.
+#
 def have_var(var, headers = nil, &b)
   checking_for "#{var}" do
     if try_var(var, headers, &b)
@@ -617,6 +653,13 @@
   end
 end
 
+# Returns whether or not the given +header+ file can be found on your system.
+# If found, a macro is passed as a preprocessor constant to the compiler using
+# the header file name, in uppercase, prepended with 'HAVE_'.
+#
+# For example, if have_header('foo.h') returned true, then the HAVE_FOO_H
+# preprocessor macro would be passed to the compiler.
+#
 def have_header(header, &b)
   checking_for header do
     if try_cpp(cpp_include(header), &b)
@@ -628,6 +671,12 @@
   end
 end
 
+# Instructs mkmf to search for the given +header+ in any of the +paths+
+# provided, and returns whether or not it was found in those paths.
+#
+# If the header is found then the path it was found on is added to the list
+# of included directories that are sent to the compiler (via the -I switch).
+#
 def find_header(header, *paths)
   checking_for header do
     if try_cpp(cpp_include(header))
@@ -647,11 +696,22 @@
   end
 end
 
-def have_struct_member(type, member, header = nil, &b)
+# Returns whether or not the struct of type +type+ contains +member+.  If
+# it does not, or the struct type can't be found, then false is returned.  You
+# may optionally specify additional +headers+ in which to look for the struct
+# (in addition to the common header files).
+#
+# If found, a macro is passed as a preprocessor constant to the compiler using
+# the member name, in uppercase, prepended with 'HAVE_ST_'.
+#
+# For example, if have_struct_member('foo', 'bar') returned true, then the
+# HAVE_ST_BAR preprocessor macro would be passed to the compiler.
+# 
+def have_struct_member(type, member, headers = nil, &b)
   checking_for "#{type}.#{member}" do
     if try_compile(<<"SRC", &b)
 #{COMMON_HEADERS}
-#{cpp_include(header)}
+#{cpp_include(headers)}
 /*top*/
 int main() { return 0; }
 int s = (char *)&((#{type}*)0)->#{member} - (char *)0;
@@ -664,17 +724,30 @@
   end
 end
 
-def have_type(type, header = nil, opt = "", &b)
+# Returns whether or not the static type +type+ is defined.  You may
+# optionally pass additional +headers+ to check against in addition to the
+# common header files.
+#
+# You may also pass additional flags to +opt+ which are then passed along to
+# the compiler.
+#
+# If found, a macro is passed as a preprocessor constant to the compiler using
+# the type name, in uppercase, prepended with 'HAVE_TYPE_'.
+#
+# For example, if have_type('foo') returned true, then the HAVE_TYPE_FOO
+# preprocessor macro would be passed to the compiler.
+#
+def have_type(type, headers = nil, opt = "", &b)
   checking_for type do
-    header = cpp_include(header)
+    headers = cpp_include(headers)
     if try_compile(<<"SRC", opt, &b) or (/\A\w+\z/n =~ type && try_compile(<<"SRC", opt, &b))
 #{COMMON_HEADERS}
-#{header}
+#{headers}
 /*top*/
 static #{type} t;
 SRC
 #{COMMON_HEADERS}
-#{header}
+#{headers}
 /*top*/
 static #{type} *t;
 SRC
@@ -686,13 +759,23 @@
   end
 end
 
-def check_sizeof(type, header = nil, &b)
+# Returns the size of the given +type+.  You may optionally specify additional
+# +headers+ to search in for the +type+.
+#
+# If found, a macro is passed as a preprocessor constant to the compiler using
+# the type name, in uppercase, prepended with 'SIZEOF_', followed by the type
+# name, followed by '=X' where 'X' is the actual size.
+#
+# For example, if check_sizeof('mystruct') returned 12, then the
+# SIZEOF_MYSTRUCT=12 preprocessor macro would be passed to the compiler.
+#
+def check_sizeof(type, headers = nil, &b)
   expr = "sizeof(#{type})"
   m = "checking size of #{type}... "
   message "%s", m
   a = size = nil
   Logging::postpone do
-    if size = try_constant(expr, header, &b)
+    if size = try_constant(expr, headers, &b)
       $defs.push(format("-DSIZEOF_%s=%d", type.upcase.tr_s("^A-Z0-9_", "_"), size))
       a = "#{size}\n"
     else
@@ -847,6 +930,17 @@
   $extconf_h = header
 end
 
+# Sets a +target+ name that the user can then use to configure various 'with'
+# options with on the command line by using that name.  For example, if the
+# target is set to "foo", then the user could use the --with-foo-dir command
+# line option.
+#
+# You may pass along additional 'include' or 'lib' defaults via the +idefault+
+# and +ldefault+ parameters, respectively.
+#
+# Note that dir_config only adds to the list of places to search for libraries
+# and include files.  It does not link the libraries into your application.
+#
 def dir_config(target, idefault=nil, ldefault=nil)
   if dir = with_config(target + "-dir", (idefault unless ldefault))
     defaults = Array === dir ? dir : dir.split(File::PATH_SEPARATOR)
@@ -1021,6 +1115,24 @@
 RULES
 end
 
+# Generates the Makefile for your extension, passing along any options and
+# preprocessor constants that you may have generated through other methods.
+#
+# The +target+ name should correspond the name of the global function name
+# defined within your C extension, minus the 'Init_'.  For example, if your
+# C extension is defined as 'Init_foo', then your target would simply be 'foo'.
+#
+# If any '/' characters are present in the target name, only the last name
+# is interpreted as the target name, and the rest are considered toplevel
+# directory names, and the generated Makefile will be altered accordingly to
+# follow that directory structure.
+#
+# For example, if you pass 'test/foo' as a target name, your extension will
+# be installed under the 'test' directory.  This means that in order to
+# load the file within a Ruby program later, that directory structure will
+# have to be followed, e.g. "require 'test/foo'".
+# 
+#
 def create_makefile(target, srcprefix = nil)
   $target = target
   libpath = $LIBPATH

Thread

Prev Next

In This Thread

Prev Next