switch distribution to zeromq-3.2.3; bump version

[chaz/p5-Alien-ZMQ] / lib / Alien / ZMQ.pm

diff --git a/lib/Alien/ZMQ.pm b/lib/Alien/ZMQ.pm
index f31ad8a942ee57ca7dcffacf6e02cf176d57d9e2..4660cfb2dd7c2c326053e85263eedf9263d2d679 100644 (file)
--- a/lib/Alien/ZMQ.pm
+++ b/lib/Alien/ZMQ.pm
@@ -1,5 +1,5 @@
 package Alien::ZMQ;
-# ABSTRACT: detect and/or install zeromq
+# ABSTRACT: find and install libzmq, the core zeromq library
 
 use warnings;
 use strict;
@@ -9,15 +9,9 @@ use String::ShellQuote qw/shell_quote/;
 =head1 DESCRIPTION
 
 Upon installation, the target system is probed for the presence of libzmq.  If
-it is not found, B<libzmq 3.2.2> is installed in a shared directory.  In
+it is not found, B<libzmq 3.2.3> is installed in a shared directory.  In
 short, modules that need libzmq can depend on this module to make sure that it
-is available.
-
-This module is still B<EXPERIMENTAL>.  In particular, I'm still pondering on
-how S<libzmq-2.x> should be handled.  Currently, if S<libzmq-2.x> is found on
-the system, L<Alien::ZMQ> will use it, but there is no way to install
-S<libzmq-2.x> with L<Alien::ZMQ>.  I'm not sure what the most useful behavior
-with regards to S<libzmq-2.x> is, so please talk to me if you have any ideas.
+is available, or use it independently as a way to install zeromq.
 
 =head1 SYNOPSIS
 
@@ -44,21 +38,21 @@ be on the system.  Use this to skip those checks and always install libzmq.
 
 Pass extra flags to the compiler when probing for an existing installation of
 libzmq.  You can use this, along with L</--zmq-libs>, to help the probing
-function locate your libzmq installation if it is installed in an unexpected
-place.  For example, if your libzmq is installed at F</opt/zeromq>, you can do
-something like this:
+function locate libzmq if it is installed in an unexpected place.  For
+example, if your libzmq is installed at F</opt/zeromq>, you can do something
+like this:
 
-    perl ./Build.PL --zmq-cflags="-I/opt/zeromq/include" \
-                    --zmq-libs="-L/opt/zeromq/lib -lzmq"
+    perl Build.PL --zmq-cflags="-I/opt/zeromq/include" \
+                  --zmq-libs="-L/opt/zeromq/lib -lzmq"
 
 These flags are only used by the probing function to locate libzmq; they will
 not be used when compiling libzmq from source (if it needs to be).  To affect
 the compiling of libzmq, using the L</--zmq-config> flag instead.
 
 A better alternative to using L</--zmq-cflags> and L</--zmq-libs> is to help
-the L<pkg-config(1)> command find your libzmq using the C<PKG_CONFIG_PATH>
+the L<pkg-config> program find your libzmq by using the C<PKG_CONFIG_PATH>
 environment variable.  Of course, this method requires that you have the
-L<pkg-config(1)> program installed.  Here's an example:
+L<pkg-config> program installed.  Here's an example:
 
     perl Build.PL
     PKG_CONFIG_PATH=/opt/zeromq/lib/pkgconfig ./Build
@@ -67,9 +61,9 @@ L<pkg-config(1)> program installed.  Here's an example:
 
 Pass extra flags to the linker when probing for an existing installation of
 libzmq.  You can use this, along with L</--zmq-cflags>, to help the probing
-function locate your libzmq installation if it is installed in an unexpected
-place.  Like L</--zmq-cflags>, these flags are only used by the probing
-function to locate libzmq.
+function locate libzmq if it is installed in an unexpected place.  Like
+L</--zmq-cflags>, these flags are only used by the probing function to locate
+libzmq.
 
 =item --zmq-config
 
@@ -86,9 +80,14 @@ Probing is only done during the installation of this module, so if you are
 using a system-installed version of libzmq and you uninstall or upgrade it,
 you will also need to reinstall L<Alien::ZMQ>.
 
+If S<libzmq-2.x> is found on the system, L<Alien::ZMQ> will use it.  There are
+a few incompatibilities between S<libzmq-2.x> and S<libzmq-3.x>, so your
+program may want to use the L</lib_version> method to check which version of
+libzmq is installed.
+
 =head1 BUGS
 
-Windows is not yet supported.  Patches are welcome.
+MSWin32 is not yet supported, but cygwin works.
 
 =head1 SEE ALSO
 
@@ -144,31 +143,44 @@ sub lib_dir { }
 =method cflags
 
 Get the C compiler flags required to compile a program that uses libzmq.  This
-is a shortcut for constructing a C<-I> flag using L</inc_dir>.
+is a shortcut for constructing a C<-I> flag using L</inc_dir>.  In scalar
+context, the flags are quoted using L<String::ShellQuote> and returned as
+a single string.
 
 =cut
 
 sub cflags {
-    "-I" . shell_quote(inc_dir);
+    if (wantarray) {
+        "-I" . inc_dir;
+    } else {
+        "-I" . shell_quote(inc_dir);
+    }
 }
 
 =method libs
 
 Get the linker flags required to link a program against libzmq.  This is
-a shortcut for constructing a C<-L> flag using L</lib_dir>, plus C<-lzmq>.  On
-some platforms, you may also want to add the library path to your executable
-or library as a runtime path; this can be done by passing C<-rpath> to the
-linker.  Something like this could work:
+a shortcut for constructing a C<-L> flag using L</lib_dir>, plus C<-lzmq>.  In
+scalar context, the flags are quoted using L<String::ShellQuote> and returned
+as a single string.
+
+On some platforms, you may also want to add the library path to your
+executable or library as a runtime path; this is usually done by passing
+C<-rpath> to the linker.  Something like this could work:
 
-    my $mylibs = Alien::ZMQ::libs . " -Wl,-rpath=" . Alien::ZMQ::lib_dir;
+    my @flags = (Alien::ZMQ::libs, "-Wl,-rpath=" . Alien::ZMQ::lib_dir);
 
 This will allow your program to find libzmq, even if it is installed in
-a non-standard location, but this isn't necessary on some platforms.
+a non-standard location, but some systems don't have this C<RPATH> mechanism.
 
 =cut
 
 sub libs {
-    "-L" . shell_quote(lib_dir) . " -lzmq";
+    if (wantarray) {
+        "-L" . lib_dir, "-lzmq";
+    } else {
+        "-L" . shell_quote(lib_dir) . " -lzmq";
+    }
 }
 
 1;