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

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