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 libzmq if it is installed in an unexpected place.  For
  48 example, if your libzmq is installed at F</opt/zeromq>, you can do something
  49 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)> program find your libzmq by 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 libzmq if it is installed in an unexpected place.  Like
  71 L</--zmq-cflags>, these flags are only used by the probing function to locate
  72 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>.  In scalar
 148 context, the flags are quoted using L<String::ShellQuote> and returned as
 149 a single string.
 150
 151 =cut
 152
 153 sub cflags {
 154     if (wantarray) {
 155         "-I" . inc_dir;
 156     } else {
 157         "-I" . shell_quote(inc_dir);
 158     }
 159 }
 160
 161 =method libs
 162
 163 Get the linker flags required to link a program against libzmq.  This is
 164 a shortcut for constructing a C<-L> flag using L</lib_dir>, plus C<-lzmq>.  In
 165 scalar context, the flags are quoted using L<String::ShellQuote> and returned
 166 as a single string.
 167
 168 On some platforms, you may also want to add the library path to your
 169 executable or library as a runtime path; this is usually done by passing
 170 C<-rpath> to the linker.  Something like this could work:
 171
 172     my @flags = (Alien::ZMQ::libs, "-Wl,-rpath=" . Alien::ZMQ::lib_dir);
 173
 174 This will allow your program to find libzmq, even if it is installed in
 175 a non-standard location, but some systems don't have this C<RPATH> mechanism.
 176
 177 =cut
 178
 179 sub libs {
 180     if (wantarray) {
 181         "-L" . lib_dir, "-lzmq";
 182     } else {
 183         "-L" . shell_quote(lib_dir) . " -lzmq";
 184     }
 185 }
 186
 187 1;