fix up documentation and bump version number

diff --git a/dist.ini b/dist.ini
index 38844d018ab0107031c7bea5318321b03590a346..b52cf0a9ed169986bcb9f1c8d2b224afd443be41 100644 (file)
--- a/dist.ini
+++ b/dist.ini
@@ -1,6 +1,6 @@
 
 name = Alien-ZMQ
-version = 0.03
+version = 0.04
 author = Charles McGarvey <ccm@cpan.org>
 license = Perl_5
 copyright_holder = Charles McGarvey

diff --git a/examples/Makefile.PL b/examples/Makefile.PL
new file mode 100644 (file)
index 0000000..63991a2
--- /dev/null
+++ b/examples/Makefile.PL
@@ -0,0 +1,10 @@
+use ExtUtils::MakeMaker;
+use Alien::ZMQ;
+
+WriteMakefile(
+    NAME         => 'My::Module',
+    VERSION_FROM => 'lib/My/Module.pm',
+    INC          => Alien::ZMQ::cflags,
+    LIBS         => Alien::ZMQ::libs,
+    # add more params
+);

diff --git a/lib/Alien/ZMQ.pm b/lib/Alien/ZMQ.pm
index 099edccae644a0d240e87bcac0b27fdab6018c7e..0ef21e8325da247fed67ba84d544d44e02ca6e23 100644 (file)
--- a/lib/Alien/ZMQ.pm
+++ b/lib/Alien/ZMQ.pm
@@ -9,15 +9,25 @@ 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, zeromq 3.2.2 is installed in a shared directory.  In short,
-modules that need libzmq can depend on this module to make sure that it is
-available.
+it is not found, B<libzmq 3.2.2> 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.
 
 =head1 SYNOPSIS
 
     use Alien::ZMQ;
-
-    my $version = Alien::ZMQ::lib_version;
+    use version;
+    
+    my $version = version->parse(Alien::ZMQ::lib_version);
+    my $lib_dir = Alien::ZMQ::lib_dir;
+    
+    print "zeromq $version is installed at $lib_dir\n";
 
 =head1 OPTIONS
 
@@ -27,35 +37,54 @@ These options to F<Build.PL> affect the installation of this module.
 
 =item --zmq-skip-probe
 
-By default, zeromq is not compiled and installed if it is detected to already
-be on the system.  Use this to skip those checks and always install zeromq.
+By default, libzmq is not compiled and installed if it is detected to already
+be on the system.  Use this to skip those checks and always install libzmq.
 
-=item --zmq-config=...
+=item --zmq-cflags=FLAGS
 
-Pass extra flags to zeromq's F<configure> script.  You may want to consider
-passing either C<--with-pgm> or C<--with-system-pgm> if you need support for
-PGM; this is not enabled by default because it is not supported by every
-system.
+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:
+
+    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.
 
-=item --zmq-libs=...
+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>
+environment variable.  Of course, this method requires that you have the
+L<pkg-config(1)> program installed.  Here's an example:
+
+    perl Build.PL
+    PKG_CONFIG_PATH=/opt/zeromq/lib/pkgconfig ./Build
+
+=item --zmq-libs=FLAGS
 
 Pass extra flags to the linker when probing for an existing installation of
-zeromq.  In particular, if your F<libzmq.so> file is installed to a special
-location, you may pass flags such as C<-L/opt/libzmq2/lib -lzmq>.
+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.
 
-=item --zmq-cflags=...
+=item --zmq-config=FLAGS
 
-Pass extra flags to the compiler when probing for an existing installation of
-zeromq.  These flags will not be used when actually compiling zeromq from
-source.  For that, just use the C<CFLAGS> environment variable.
+Pass extra flags to the libzmq F<configure> script.  You may want to consider
+passing either C<--with-pgm> or C<--with-system-pgm> if you need support for
+PGM; this is not enabled by default because it is not supported by every
+system.
 
 =back
 
 =head1 CAVEATS
 
-Probing is only done upon installation, so if you are using a system-installed
-version of libzmq and you uninstall or upgrade it, you will also need to
-reinstall this module.
+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>.
 
 =head1 BUGS
 
@@ -80,8 +109,8 @@ modules, including L<Alien::GMP> and L<Alien::Tidyp>.
 
 =method inc_version
 
-Get the version number of libzmq as a dotted version string according to the
-F<zmq.h> header file.
+Get the version number of libzmq as a v-string (version string), according to
+the F<zmq.h> header file.
 
 =cut
 
@@ -89,8 +118,8 @@ sub inc_version { }
 
 =method lib_version
 
-Get the version number of libzmq as a dotted version string according to the
-F<libzmq.so> file.
+Get the version number of libzmq as a v-string (version string), according to
+the F<libzmq.so> file.
 
 =cut
 
@@ -115,7 +144,7 @@ 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 C<inc_dir>.
+is a shortcut for constructing a C<-I> flag using L</inc_dir>.
 
 =cut
 
@@ -126,7 +155,15 @@ sub cflags {
 =method libs
 
 Get the linker flags required to link a program against libzmq.  This is
-a shortcut for constructing a C<-L> flag using C<lib_dir>, plus C<-lzmq>.
+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:
+
+    my $mylibs = 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.
 
 =cut