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.100630
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          trace  => 1
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          trace  => 1
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       ·   "dirmode"
58
59           Generally an octal number, this option sets the permissions of
60           created directories.  It defaults to 0711.
61
62       ·   "exact_mirror"
63
64           If true, the "files_allowed" method will allow all extra files to
65           be mirrored.
66
67       ·   "ignore_source_control"
68
69           If true, CPAN::Mini will not try to remove source control files
70           during cleanup. See "clean_unmirrored" for details.
71
72       ·   "force"
73
74           If true, this option will cause CPAN::Mini to read the entire
75           module list and update anything out of date, even if the module
76           list itself wasn't out of date on this run.
77
78       ·   "skip_perl"
79
80           If true, CPAN::Mini will skip the major language distributions:
81           perl, parrot, and ponie.
82
83       ·   "trace"
84
85           If true, CPAN::Mini will print status messages to STDOUT as it
86           works.
87
88       ·   "errors"
89
90           If true, CPAN::Mini will warn with status messages on errors.
91           (default: true)
92
93       ·   "path_filters"
94
95           This options provides a set of rules for filtering paths.  If a
96           distribution matches one of the rules in "path_filters", it will
97           not be mirrored.  A regex rule is matched if the path matches the
98           regex; a code rule is matched if the code returns 1 when the path
99           is passed to it.  For example, the following setting would skip all
100           distributions from RJBS and SUNGO:
101
102            path_filters => [
103              qr/RJBS/,
104              sub { $_[0] =~ /SUNGO/ }
105            ]
106
107       ·   "module_filters"
108
109           This option provides a set of rules for filtering modules.  It
110           behaves like path_filters, but acts only on module names.  (Since
111           most modules are in distributions with more than one module, this
112           setting will probably be less useful than "path_filters".)  For
113           example, this setting will skip any distribution containing only
114           modules with the word "Acme" in them:
115
116            module_filters => [ qr/Acme/i ]
117
118       ·   "also_mirror"
119
120           This option should be an arrayref of extra files in the remote CPAN
121           to mirror locally.
122
123       ·   "skip_cleanup"
124
125           If this option is true, CPAN::Mini will not try delete unmirrored
126           files when it has finished mirroring
127
128       ·   "offline"
129
130           If offline, CPAN::Mini will not attempt to contact remote
131           resources.
132
133       ·   "no_conn_cache"
134
135           If true, no connection cache will be established.  This is mostly
136           useful as a workaround for connection cache failures.
137
138   new
139         my $minicpan = CPAN::Mini->new;
140
141       This method constructs a new CPAN::Mini object.  Its parameters are
142       described above, under "update_mirror".
143
144   mirror_indices
145         $minicpan->mirror_indices;
146
147       This method updates the index files from the CPAN.
148
149   mirror_file
150         $minicpan->mirror_file($path, $skip_if_present)
151
152       This method will mirror the given file from the remote to the local
153       mirror, overwriting any existing file unless $skip_if_present is true.
154
155   file_allowed
156         next unless $minicpan->file_allowed($filename);
157
158       This method returns true if the given file is allowed to exist in the
159       local mirror, even if it isn't one of the required mirror files.
160
161       By default, only dot-files are allowed.  If the "exact_mirror" option
162       is true, all files are allowed.
163
164   clean_unmirrored
165         $minicpan->clean_unmirrored;
166
167       This method looks through the local mirror's files.  If it finds a file
168       that neither belongs in the mirror nor is allowed (see the
169       "file_allowed" method), "clean_file" is called on the file.
170
171       If you set "ignore_source_control" to a true value, then this doesn't
172       clean up files that belong to source control systems. Currently this
173       ignores:
174
175               .cvs .cvsignore
176               .svn .svnignore
177               .git .gitignore
178
179       Send patches for other source control files that you would like to have
180       added.
181
182   clean_file
183         $minicpan->clean_file($filename);
184
185       This method, called by "clean_unmirrored", deletes the named file.  It
186       returns true if the file is successfully unlinked.  Otherwise, it
187       returns false.
188
189   trace
190         $minicpan->trace($message);
191
192       If the object is mirroring verbosely, this method will print messages
193       sent to it.
194
195   read_config
196         my %config = CPAN::Mini->read_config;
197
198       This routine returns a set of arguments that can be passed to
199       CPAN::Mini's "new" or "update_mirror" methods.  It will look for a file
200       called .minicpanrc in the user's home directory as determined by
201       File::HomeDir.
202
203   config_file
204         my %config = CPAN::Mini->config_file( { options } );
205
206       This routine returns the config file name. It first looks at for the
207       "config_file" setting, then the "CPAN_MINI_CONFIG" environment
208       variable, then the default ~/.minicpanrc, and finally the
209       CPAN/Mini/minicpan.conf. It uses the first defined value it finds.  If
210       the filename it selects does not exist, it returns the empty list.
211
212       OPTIONS is an optional hash reference of the "CPAN::Mini" config hash.
213

THANKS

223       Thanks to David Dyck for letting me know about my stupid documentation
224       errors.
225
226       Thanks to Roy Fulbright for finding an obnoxious bug on Win32.
227
228       Thanks to Shawn Sorichetti for fixing a stupid octal-number-as-string
229       bug.
230
231       Thanks to sungo for implementing the filters, so I can finally stop
232       mirroring bioperl, and Robert Rothenberg for suggesting adding coderef
233       rules.
234
235       Thanks to Adam Kennedy for noticing and complaining about a lot of
236       stupid little design decisions.
237
238       Thanks to Michael Schwern and Jason Kohles, for pointing out missing
239       documentation.
240
241       Thanks to David Golden for some important bugfixes and refactoring.
242

AUTHORS

244         Ricardo SIGNES <rjbs@cpan.org>
245         Randal Schwartz <merlyn@stonehenge.com>
246

COPYRIGHT AND LICENSE

248       This software is copyright (c) 2010 by Ricardo SIGNES.
249
250       This is free software; you can redistribute it and/or modify it under
251       the same terms as the Perl 5 programming language system itself.
252
253
254
255perl v5.12.0                      2010-03-04                     CPAN::Mini(3)