From: Charles McGarvey Date: Sun, 20 Jan 2013 04:13:45 +0000 (-0700) Subject: fix up documentation and bump version number X-Git-Tag: v0.04^0 X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=7837ede3e4d33f9a8dc8b74538544088aeb62d71;p=chaz%2Fp5-Alien-ZMQ fix up documentation and bump version number --- diff --git a/dist.ini b/dist.ini index 38844d0..b52cf0a 100644 --- a/dist.ini +++ b/dist.ini @@ -1,6 +1,6 @@ name = Alien-ZMQ -version = 0.03 +version = 0.04 author = Charles McGarvey license = Perl_5 copyright_holder = Charles McGarvey diff --git a/examples/Makefile.PL b/examples/Makefile.PL new file mode 100644 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 099edcc..0ef21e8 100644 --- 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 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. In particular, I'm still pondering on +how S should be handled. Currently, if S is found on +the system, L will use it, but there is no way to install +S with L. I'm not sure what the most useful behavior +with regards to S 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 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 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, 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, 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 flag instead. -=item --zmq-libs=... +A better alternative to using L and L is to help +the L command find your libzmq using the C +environment variable. Of course, this method requires that you have the +L 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 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, to help the probing +function locate your libzmq installation if it is installed in an unexpected +place. Like L, 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 environment variable. +Pass extra flags to the libzmq F 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. =head1 BUGS @@ -80,8 +109,8 @@ modules, including L and L. =method inc_version -Get the version number of libzmq as a dotted version string according to the -F header file. +Get the version number of libzmq as a v-string (version string), according to +the F 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 file. +Get the version number of libzmq as a v-string (version string), according to +the F 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. +is a shortcut for constructing a C<-I> flag using L. =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, plus C<-lzmq>. +a shortcut for constructing a C<-L> flag using L, 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