CPAN::Mini(3pm)

1CPAN::Mini(3)         User Contributed Perl Documentation        CPAN::Mini(3)
2
3
4

NAME

6       CPAN::Mini - create a minimal mirror of CPAN
7

VERSION

9       version 1.111016
10

SYNOPSIS

12       (If you're not going to do something weird, you probably want to look
13       at the minicpan command, instead.)
14
15         use CPAN::Mini;
16
17         CPAN::Mini->update_mirror(
18           remote => "http://cpan.mirrors.comintern.su",
19           local  => "/usr/share/mirrors/cpan",
20           log_level => 'debug',
21         );
22

DESCRIPTION

24       CPAN::Mini provides a simple mechanism to build and update a minimal
25       mirror of the CPAN on your local disk.  It contains only those files
26       needed to install the newest version of every distribution.  Those
27       files are:
28
29       ·   01mailrc.txt.gz
30
31       ·   02packages.details.txt.gz
32
33       ·   03modlist.data.gz
34
35       ·   the last non-developer release of every dist for every author
36

METHODS

38   update_mirror
39         CPAN::Mini->update_mirror(
40           remote => "http://cpan.mirrors.comintern.su",
41           local  => "/usr/share/mirrors/cpan",
42           force  => 0,
43           log_level => 'debug',
44         );
45
46       This is the only method that need be called from outside this module.
47       It will update the local mirror with the files from the remote mirror.
48
49       If called as a class method, "update_mirror" creates an ephemeral
50       CPAN::Mini object on which other methods are called.  That object is
51       used to store mirror location and state.
52
53       This method returns the number of files updated.
54
55       The following options are recognized:
56
57       ·   "local"
58
59           This is the local file path where the mirror will be written or
60           updated.
61
62       ·   "remote"
63
64           This is the URL of the CPAN mirror from which to work.  A
65           reasonable default will be picked by default.  A list of CPAN
66           mirrors can be found at <http://www.cpan.org/SITES.html>
67
68       ·   "dirmode"
69
70           Generally an octal number, this option sets the permissions of
71           created directories.  It defaults to 0711.
72
73       ·   "exact_mirror"
74
75           If true, the "files_allowed" method will allow all extra files to
76           be mirrored.
77
78       ·   "ignore_source_control"
79
80           If true, CPAN::Mini will not try to remove source control files
81           during cleanup. See "clean_unmirrored" for details.
82
83       ·   "force"
84
85           If true, this option will cause CPAN::Mini to read the entire
86           module list and update anything out of date, even if the module
87           list itself wasn't out of date on this run.
88
89       ·   "skip_perl"
90
91           If true, CPAN::Mini will skip the major language distributions:
92           perl, parrot, and ponie.  It will also skip embperl, sybperl,
93           bioperl, and kurila.
94
95       ·   "log_level"
96
97           This defines the minimum level of message to log: debug, info,
98           warn, or fatal
99
100       ·   "errors"
101
102           If true, CPAN::Mini will warn with status messages on errors.
103           (default: true)
104
105       ·   "path_filters"
106
107           This options provides a set of rules for filtering paths.  If a
108           distribution matches one of the rules in "path_filters", it will
109           not be mirrored.  A regex rule is matched if the path matches the
110           regex; a code rule is matched if the code returns 1 when the path
111           is passed to it.  For example, the following setting would skip all
112           distributions from RJBS and SUNGO:
113
114            path_filters => [
115              qr/RJBS/,
116              sub { $_[0] =~ /SUNGO/ }
117            ]
118
119       ·   "module_filters"
120
121           This option provides a set of rules for filtering modules.  It
122           behaves like path_filters, but acts only on module names.  (Since
123           most modules are in distributions with more than one module, this
124           setting will probably be less useful than "path_filters".)  For
125           example, this setting will skip any distribution containing only
126           modules with the word "Acme" in them:
127
128            module_filters => [ qr/Acme/i ]
129
130       ·   "also_mirror"
131
132           This option should be an arrayref of extra files in the remote CPAN
133           to mirror locally.
134
135       ·   "skip_cleanup"
136
137           If this option is true, CPAN::Mini will not try delete unmirrored
138           files when it has finished mirroring
139
140       ·   "offline"
141
142           If offline, CPAN::Mini will not attempt to contact remote
143           resources.
144
145       ·   "no_conn_cache"
146
147           If true, no connection cache will be established.  This is mostly
148           useful as a workaround for connection cache failures.
149
150   new
151         my $minicpan = CPAN::Mini->new;
152
153       This method constructs a new CPAN::Mini object.  Its parameters are
154       described above, under "update_mirror".
155
156   mirror_indices
157         $minicpan->mirror_indices;
158
159       This method updates the index files from the CPAN.
160
161   mirror_file
162         $minicpan->mirror_file($path, $skip_if_present)
163
164       This method will mirror the given file from the remote to the local
165       mirror, overwriting any existing file unless $skip_if_present is true.
166
167   file_allowed
168         next unless $minicpan->file_allowed($filename);
169
170       This method returns true if the given file is allowed to exist in the
171       local mirror, even if it isn't one of the required mirror files.
172
173       By default, only dot-files are allowed.  If the "exact_mirror" option
174       is true, all files are allowed.
175
176   clean_unmirrored
177         $minicpan->clean_unmirrored;
178
179       This method looks through the local mirror's files.  If it finds a file
180       that neither belongs in the mirror nor is allowed (see the
181       "file_allowed" method), "clean_file" is called on the file.
182
183       If you set "ignore_source_control" to a true value, then this doesn't
184       clean up files that belong to source control systems. Currently this
185       ignores:
186
187               .cvs .cvsignore
188               .svn .svnignore
189               .git .gitignore
190
191       Send patches for other source control files that you would like to have
192       added.
193
194   clean_file
195         $minicpan->clean_file($filename);
196
197       This method, called by "clean_unmirrored", deletes the named file.  It
198       returns true if the file is successfully unlinked.  Otherwise, it
199       returns false.
200
201   log_warn
202   log
203   log_debug
204         $minicpan->log($message);
205
206       This will log (print) the given message unless the log level is too
207       low.
208
209       "log", which logs at the info level, may also be called as "trace" for
210       backward compatibility reasons.
211
212   read_config
213         my %config = CPAN::Mini->read_config(\%options);
214
215       This routine returns a set of arguments that can be passed to
216       CPAN::Mini's "new" or "update_mirror" methods.  It will look for a file
217       called .minicpanrc in the user's home directory as determined by
218       File::HomeDir.
219
220   config_file
221         my $config_file = CPAN::Mini->config_file( { options } );
222
223       This routine returns the config file name. It first looks at for the
224       "config_file" setting, then the "CPAN_MINI_CONFIG" environment
225       variable, then the default ~/.minicpanrc, and finally the
226       CPAN/Mini/minicpan.conf. It uses the first defined value it finds.  If
227       the filename it selects does not exist, it returns false.
228
229       OPTIONS is an optional hash reference of the "CPAN::Mini" config hash.
230
231   remote_from
232         my $remote = CPAN::Mini->remote_from( $remote_from, $orig_remote, $quiet );
233
234       This routine take an string argument and turn it into a method call to
235       handle to retrieve the a cpan mirror url from a source.  Currently
236       supported methods:
237
238           cpan     - fetch the first mirror from your CPAN.pm config
239           cpanplus - fetch the first mirror from your CPANPLUS.pm config
240
241   remote_from_cpan
242         my $remote = CPAN::Mini->remote_from_cpan;
243
244       This routine loads your CPAN.pm config and returns the first mirror in
245       mirror list.  You can set this as your default by setting
246       remote_from:cpan in your .minicpanrc file.
247
248   remote_from_cpanplus
249         my $remote = CPAN::Mini->remote_from_cpanplus;
250
251       This routine loads your CPANPLUS.pm config and returns the first mirror
252       in mirror list.  You can set this as your default by setting
253       remote_from:cpanplus in your .minicpanrc file.
254

THANKS

264       Thanks to David Dyck for letting me know about my stupid documentation
265       errors.
266
267       Thanks to Roy Fulbright for finding an obnoxious bug on Win32.
268
269       Thanks to Shawn Sorichetti for fixing a stupid octal-number-as-string
270       bug.
271
272       Thanks to sungo for implementing the filters, so I can finally stop
273       mirroring bioperl, and Robert Rothenberg for suggesting adding coderef
274       rules.
275
276       Thanks to Adam Kennedy for noticing and complaining about a lot of
277       stupid little design decisions.
278
279       Thanks to Michael Schwern and Jason Kohles, for pointing out missing
280       documentation.
281
282       Thanks to David Golden for some important bugfixes and refactoring.
283

AUTHORS

285       ·   Ricardo SIGNES <rjbs@cpan.org>
286
287       ·   Randal Schwartz <merlyn@stonehenge.com>
288

COPYRIGHT AND LICENSE

290       This software is copyright (c) 2004 by Ricardo SIGNES.
291
292       This is free software; you can redistribute it and/or modify it under
293       the same terms as the Perl 5 programming language system itself.
294
295
296
297perl v5.30.1                      2020-01-29                     CPAN::Mini(3)