Dogcows Code - chaz/p5-Alien-ZMQ/blob - lib/Alien/ZMQ.pm

   1 package Alien::ZMQ;
   2 # ABSTRACT: finding and installing libzmq, the core zeromq library
   3
   4 use warnings;
   5 use strict;
   6
   7 use String::ShellQuote qw/shell_quote/;
   8
   9 =head1 DESCRIPTION
  10
  11 Upon installation, the target system is probed for the presence of libzmq.  If
  12 it is not found, B<libzmq 3.2.2> is installed in a shared directory.  In
  13 short, modules that need libzmq can depend on this module to make sure that it
  14 is available.
  15
  16 This module is still B<EXPERIMENTAL>.  In particular, I'm still pondering on
  17 how S<libzmq-2.x> should be handled.  Currently, if S<libzmq-2.x> is found on
  18 the system, L<Alien::ZMQ> will use it, but there is no way to install
  19 S<libzmq-2.x> with L<Alien::ZMQ>.  I'm not sure what the most useful behavior
  20 with regards to S<libzmq-2.x> is, so please talk to me if you have any ideas.
  21
  22 =head1 SYNOPSIS
  23
  24     use Alien::ZMQ;
  25     use version;
  26
  27     my $version = version->parse(Alien::ZMQ::lib_version);
  28     my $lib_dir = Alien::ZMQ::lib_dir;
  29
  30     print "zeromq $version is installed at $lib_dir\n";
  31
  32 =head1 OPTIONS
  33
  34 These options to F<Build.PL> affect the installation of this module.
  35
  36 =over 4
  37
  38 =item --zmq-skip-probe
  39
  40 By default, libzmq is not compiled and installed if it is detected to already
  41 be on the system.  Use this to skip those checks and always install libzmq.
  42
  43 =item --zmq-cflags
  44
  45 Pass extra flags to the compiler when probing for an existing installation of
  46 libzmq.  You can use this, along with L</--zmq-libs>, to help the probing
  47 function locate your libzmq installation if it is installed in an unexpected
  48 place.  For example, if your libzmq is installed at F</opt/zeromq>, you can do
  49 something like this:
  50
  51     perl ./Build.PL --zmq-cflags="-I/opt/zeromq/include" \
  52                     --zmq-libs="-L/opt/zeromq/lib -lzmq"
  53
  54 These flags are only used by the probing function to locate libzmq; they will
  55 not be used when compiling libzmq from source (if it needs to be).  To affect
  56 the compiling of libzmq, using the L</--zmq-config> flag instead.
  57
  58 A better alternative to using L</--zmq-cflags> and L</--zmq-libs> is to help
  59 the L<pkg-config(1)> command find your libzmq using the C<PKG_CONFIG_PATH>
  60 environment variable.  Of course, this method requires that you have the
  61 L<pkg-config(1)> program installed.  Here's an example:
  62
  63     perl Build.PL
  64     PKG_CONFIG_PATH=/opt/zeromq/lib/pkgconfig ./Build
  65
  66 =item --zmq-libs
  67
  68 Pass extra flags to the linker when probing for an existing installation of
  69 libzmq.  You can use this, along with L</--zmq-cflags>, to help the probing
  70 function locate your libzmq installation if it is installed in an unexpected
  71 place.  Like L</--zmq-cflags>, these flags are only used by the probing
  72 function to locate libzmq.
  73
  74 =item --zmq-config
  75
  76 Pass extra flags to the libzmq F<configure> script.  You may want to consider
  77 passing either C<--with-pgm> or C<--with-system-pgm> if you need support for
  78 PGM; this is not enabled by default because it is not supported by every
  79 system.
  80
  81 =back
  82
  83 =head1 CAVEATS
  84
  85 Probing is only done during the installation of this module, so if you are
  86 using a system-installed version of libzmq and you uninstall or upgrade it,
  87 you will also need to reinstall L<Alien::ZMQ>.
  88
  89 =head1 BUGS
  90
  91 MSWin32 is not yet supported, but cygwin works.
  92
  93 =head1 SEE ALSO
  94
  95 =over 4
  96
  97 =item * L<GitHub project|https://github.com/chazmcgarvey/p5-Alien-ZMQ>
  98
  99 =item * L<ZMQ> - good perl bindings for zeromq
 100
 101 =item * L<ZeroMQ|http://www.zeromq.org/> - official libzmq website
 102
 103 =back
 104
 105 =head1 ACKNOWLEDGEMENTS
 106
 107 The design and implementation of this module were influenced by other L<Alien>
 108 modules, including L<Alien::GMP> and L<Alien::Tidyp>.
 109
 110 =method inc_version
 111
 112 Get the version number of libzmq as a v-string (version string), according to
 113 the F<zmq.h> header file.
 114
 115 =cut
 116
 117 sub inc_version { }
 118
 119 =method lib_version
 120
 121 Get the version number of libzmq as a v-string (version string), according to
 122 the F<libzmq.so> file.
 123
 124 =cut
 125
 126 sub lib_version { }
 127
 128 =method inc_dir
 129
 130 Get the directory containing the F<zmq.h> header file.
 131
 132 =cut
 133
 134 sub inc_dir { }
 135
 136 =method lib_dir
 137
 138 Get the directory containing the F<libzmq.so> file.
 139
 140 =cut
 141
 142 sub lib_dir { }
 143
 144 =method cflags
 145
 146 Get the C compiler flags required to compile a program that uses libzmq.  This
 147 is a shortcut for constructing a C<-I> flag using L</inc_dir>.
 148
 149 =cut
 150
 151 sub cflags {
 152     "-I" . shell_quote(inc_dir);
 153 }
 154
 155 =method libs
 156
 157 Get the linker flags required to link a program against libzmq.  This is
 158 a shortcut for constructing a C<-L> flag using L</lib_dir>, plus C<-lzmq>.  On
 159 some platforms, you may also want to add the library path to your executable
 160 or library as a runtime path; this can be done by passing C<-rpath> to the
 161 linker.  Something like this could work:
 162
 163     my $mylibs = Alien::ZMQ::libs . " -Wl,-rpath=" . Alien::ZMQ::lib_dir;
 164
 165 This will allow your program to find libzmq, even if it is installed in
 166 a non-standard location, but this isn't necessary on some platforms.
 167
 168 =cut
 169
 170 sub libs {
 171     "-L" . shell_quote(lib_dir) . " -lzmq";
 172 }
 173
 174 1;