local-lib5/man/man3/Module::Install::PAR.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Module::Install::PAR 3"
 132 .TH Module::Install::PAR 3 "2009-05-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::Install::PAR \- Module::Install Support for PAR::Dist packages
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 To offer your users the possibility to install binaries if no C
 138 compiler was found, you could use this simplistic stub:
 139 .PP
 140 .Vb 1
 141 \&    use inc::Module::Install;
 142 .Ve
 143 .PP
 144 .Vb 2
 145 \&    name            'Foo';
 146 \&    all_from        'lib/Foo.pm';
 147 .Ve
 148 .PP
 149 .Vb 2
 150 \&    # Which CPAN directory do we fetch binaries from?
 151 \&    par_base        'SMUELLER';
 152 .Ve
 153 .PP
 154 .Vb 6
 155 \&    unless ( can_cc() ) {
 156 \&        my $okay = extract_par( fetch_par );
 157 \&        if (not $okay) {
 158 \&            die "No compiler and no binary package found. Aborting.\en";
 159 \&        }
 160 \&    }
 161 .Ve
 162 .PP
 163 .Vb 1
 164 \&    WriteAll;
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 This module adds a couple of directives to Module::Install
 169 related to installing and creating PAR::Dist distributions.
 170 .Sh "par_base"
 171 .IX Subsection "par_base"
 172 This directive sets the \s-1CPAN\s0 \s-1ID\s0 from whose \s-1CPAN\s0 directory to
 173 fetch binaries from. For example, you can choose to download
 174 binaries from http://www.cpan.org/authors/id/S/SM/SMUELLER/
 175 or its ftp counterpart by writing:
 176 .PP
 177 .Vb 1
 178 \&  par_base 'SMUELLER';
 179 .Ve
 180 .PP
 181 By default, the name of the file to fetch is generated from
 182 the distribution name, its version, your platform name and your
 183 perl version concatenated with dashes.
 184 .PP
 185 The directive, however, takes an optional second
 186 argument which specifies the name of the file to fetch.
 187 (Though \f(CW\*(C`par_base\*(C'\fR does not fetch files itself, see below.)
 188 .PP
 189 .Vb 1
 190 \&  par_base 'SMUELLER', 'foo';
 191 .Ve
 192 .PP
 193 Once \f(CW\*(C`fetch_par\*(C'\fR is called, the file 'foo' will be downloaded
 194 from \s-1SMUELLER\s0's \s-1CPAN\s0 directory. (It doesn't exist.)
 195 .PP
 196 The second argument could be used to fetch platform-agnostic
 197 binaries:
 198 .PP
 199 .Vb 1
 200 \&  par_base 'SMUELLER', "Some\-Distribution\-0.01.par";
 201 .Ve
 202 .PP
 203 (Documentation \s-1TODO:\s0 Use the previously defined distribution
 204 name and version in example.)
 205 .Sh "fetch_par"
 206 .IX Subsection "fetch_par"
 207 Fetches the .par file previously referenced in the documentation
 208 of the \f(CW\*(C`par_base\*(C'\fR directive.
 209 .PP
 210 \&\f(CW\*(C`fetch_par\*(C'\fR can be used without arguments given the \f(CW\*(C`par_base\*(C'\fR
 211 directive was used before. It will return the name of the file it
 212 fetched.
 213 .PP
 214 If the first argument is an \s-1URL\s0 or a \s-1CPAN\s0 user \s-1ID\s0, the file is
 215 fetched from that directory unless an \s-1URL\s0 has been previously set.
 216 (Read that again.)
 217 .PP
 218 If the second argument is a file name
 219 it is used as the name of the file to download.
 220 .PP
 221 If the file could not be fetched, a suitable error message
 222 about no package being available, yada yada yada, is printed.
 223 You can turn this off by specifying a true third argument.
 224 .PP
 225 .Vb 3
 226 \&  # Try to fetch the package (see par_base) but
 227 \&  # don't be verbose about failures
 228 \&  my $file = fetch_par('', '', undef);
 229 .Ve
 230 .Sh "extract_par"
 231 .IX Subsection "extract_par"
 232 Takes the name of a PAR::Dist archive file as first argument. The 'blib/'
 233 directory of this archive is extracted and the 'pm_to_blib' is created.
 234 .PP
 235 Typical shorthand usage:
 236 .PP
 237 .Vb 1
 238 \&  extract_par( fetch_par ) or die "Could not install PAR::Dist archive.";
 239 .Ve
 240 .Sh "make_par"
 241 .IX Subsection "make_par"
 242 This directive requires PAR::Dist (version 0.03 or up) on your system.
 243 (And checks that it is available before continuing.)
 244 .PP
 245 Creates a PAR::Dist archive from the 'blib/' subdirectory.
 246 .PP
 247 First argument must be the name of the PAR::Dist archive to create.
 248 .PP
 249 If your Makefile.PL has a \f(CW\*(C`par_base\*(C'\fR directive, the \f(CW\*(C`make par\*(C'\fR
 250 make target will be available. It uses this \f(CW\*(C`make_par\*(C'\fR directive
 251 internally, so on your development system, you can do this to create
 252 a .par binary archive for your platform:
 253 .PP
 254 .Vb 3
 255 \&  perl Makefile.PL
 256 \&  make
 257 \&  make par
 258 .Ve
 259 .SH "AUTHOR"
 260 .IX Header "AUTHOR"
 261 Audrey Tang <cpan@audreyt.org>
 262 .PP
 263 With documentation from Steffen Mueller <smueller@cpan.org>
 264 .SH "COPYRIGHT"
 265 .IX Header "COPYRIGHT"
 266 Copyright (c) 2006. Audrey Tang.
 267 .PP
 268 This program is free software; you can redistribute it and/or modify it
 269 under the same terms as Perl itself.
 270 .PP
 271 See <http://www.perl.com/perl/misc/Artistic.html>