summaryrefslogtreecommitdiffstats
path: root/urpm
diff options
context:
space:
mode:
authorThierry Vignaud <tv@mageia.org>2012-08-31 16:45:16 +0000
committerThierry Vignaud <tv@mageia.org>2012-08-31 16:45:16 +0000
commitd90e2c33fec88adabef87549ec3d1b4fb65d9587 (patch)
treed52440e9b830446ca5560a2533cf00850ef3804d /urpm
parent3cd85172bf689b679e8c1fc626690ba87b136d74 (diff)
downloadurpmi-d90e2c33fec88adabef87549ec3d1b4fb65d9587.tar
urpmi-d90e2c33fec88adabef87549ec3d1b4fb65d9587.tar.gz
urpmi-d90e2c33fec88adabef87549ec3d1b4fb65d9587.tar.bz2
urpmi-d90e2c33fec88adabef87549ec3d1b4fb65d9587.tar.xz
urpmi-d90e2c33fec88adabef87549ec3d1b4fb65d9587.zip
convert a couple comments to POD
Diffstat (limited to 'urpm')
-rw-r--r--urpm/download.pm32
-rw-r--r--urpm/get_pkgs.pm21
-rw-r--r--urpm/install.pm16
-rw-r--r--urpm/lock.pm27
-rw-r--r--urpm/mirrors.pm20
-rw-r--r--urpm/orphans.pm33
-rw-r--r--urpm/select.pm138
-rw-r--r--urpm/sys.pm62
-rw-r--r--urpm/xml_info_pkg.pm59
9 files changed, 321 insertions, 87 deletions
diff --git a/urpm/download.pm b/urpm/download.pm
index 9cc6f555..de8abf45 100644
--- a/urpm/download.pm
+++ b/urpm/download.pm
@@ -180,9 +180,14 @@ sub get_proxy_ {
get_proxy($urpm);
}
-#- reads and loads the proxy.cfg file ;
-#- returns the global proxy settings (without arguments) or the
-#- proxy settings for the specified media (with a media name as argument)
+=item get_proxy($media)
+
+Reads and loads the proxy.cfg file ;
+Returns the global proxy settings (without arguments) or the
+proxy settings for the specified media (with a media name as argument)
+
+=cut
+
sub get_proxy (;$) {
my ($o_media) = @_; $o_media ||= '';
load_proxy_config();
@@ -226,7 +231,12 @@ sub copy_cmd_line_proxy {
}
}
-#- overrides the config file proxy settings with values passed via command-line
+=item set_cmdline_proxy(%h)
+
+Overrides the config file proxy settings with values passed via command-line
+
+=cut
+
sub set_cmdline_proxy {
my (%h) = @_;
load_proxy_config();
@@ -239,7 +249,12 @@ sub set_cmdline_proxy {
$proxy_config->{cmd_line}{$_} = $h{$_} foreach keys %h;
}
-#- changes permanently the proxy settings
+=item set_proxy_config($key, $value, $o_media)
+
+Changes permanently the proxy settings
+
+=cut
+
sub set_proxy_config {
my ($key, $value, $o_media) = @_;
$proxy_config->{$o_media || ''}{$key} = $value;
@@ -821,7 +836,12 @@ sub progress_text {
N(" %s%% completed, speed = %s", $percent, $speed)) : '';
}
-#- default logger suitable for sync operation on STDERR only.
+=item sync_logger($mode, $file, $percent, $_total, $_eta, $_speed)
+
+Default logger (callback) suitable for sync operation on STDERR only.
+
+=cut
+
sub sync_logger {
my ($mode, $file, $percent, $_total, $_eta, $_speed) = @_;
if ($mode eq 'start') {
diff --git a/urpm/get_pkgs.pm b/urpm/get_pkgs.pm
index f82b2e41..7f6bcc28 100644
--- a/urpm/get_pkgs.pm
+++ b/urpm/get_pkgs.pm
@@ -178,7 +178,13 @@ sub verify_partial_rpm_and_move {
"$cachedir/rpms/$filename";
}
-# get the filesize of packages to download from remote media.
+
+=item get_distant_media_filesize(undef, $blists, $sources)
+
+Get the filesize of packages to download from remote media.
+
+=cut
+
sub get_distant_media_filesize {
my (undef, $blists, $sources) = @_;
@@ -199,10 +205,15 @@ sub get_distant_media_filesize {
$filesize;
}
-# download packages listed in $blists,
-# and put the result in $sources or $error_sources
-#
-#- options: quiet, callback,
+=item download_packages_of_distant_media($urpm, $blists, $sources, $error_sources, %options)
+
+Download packages listed in $blists, and put the result in $sources or
+$error_sources
+
+Options: quiet, callback,
+
+=cut
+
sub download_packages_of_distant_media {
my ($urpm, $blists, $sources, $error_sources, %options) = @_;
diff --git a/urpm/install.pm b/urpm/install.pm
index 8754fe85..c539af3c 100644
--- a/urpm/install.pm
+++ b/urpm/install.pm
@@ -178,15 +178,17 @@ sub options {
=item install($urpm, $remove, $install, $upgrade, %options)
+Install packages according to each hash (remove, install or upgrade).
+
+options:
+ test, excludepath, nodeps, noorder (unused), delta,
+ callback_inst, callback_trans, callback_report_uninst,
+ post_clean_cache, verbose
+ (more options for trans->run)
+ excludedocs, nosize, noscripts, oldpackage, repackage, replacepkgs, justdb, ignorearch
+
=cut
-#- install packages according to each hash (remove, install or upgrade).
-#- options:
-#- test, excludepath, nodeps, noorder (unused), delta,
-#- callback_inst, callback_trans, callback_report_uninst,
-#- post_clean_cache, verbose
-#- (more options for trans->run)
-#- excludedocs, nosize, noscripts, oldpackage, repackage, replacepkgs, justdb, ignorearch
sub install {
my ($urpm, $remove, $install, $upgrade, %options) = @_;
$options{translate_message} = 1;
diff --git a/urpm/lock.pm b/urpm/lock.pm
index 12ab7394..d480b25d 100644
--- a/urpm/lock.pm
+++ b/urpm/lock.pm
@@ -27,16 +27,33 @@ urpm::lock - urpm/rpm DB locking related routines for urpmi
################################################################################
#- class functions
-#- lock policy concerning chroot :
-# - lock rpm db in chroot
-# - lock urpmi db in /
-# (options: nofatal, wait)
+
+=item rpm_db($urpm, $b_exclusive, %options)
+
+Lock urpmi DB.
+
+Lock policy concerning chroot : lock rpm db in chroot
+
+Options: nofatal, wait
+
+=cut
+
sub rpm_db {
my ($urpm, $b_exclusive, %options) = @_;
my $f = ($urpm->{root} ? "$urpm->{root}/" : '') . "/var/lib/rpm/.RPMLOCK";
urpm::lock->new($urpm, $f, 'rpm', $b_exclusive, %options);
}
-# (options: nofatal, wait)
+
+=item urpmi_db($urpm, $b_exclusive, %options)
+
+Lock urpmi DB.
+
+Lock policy concerning chroot : lock urpmi db in /
+
+Options: nofatal, wait
+
+=cut
+
sub urpmi_db {
my ($urpm, $b_exclusive, %options) = @_;
urpm::lock->new($urpm, "$urpm->{statedir}/.LOCK", 'urpmi', $b_exclusive, %options);
diff --git a/urpm/mirrors.pm b/urpm/mirrors.pm
index f3ef162b..3fcf9b13 100644
--- a/urpm/mirrors.pm
+++ b/urpm/mirrors.pm
@@ -18,9 +18,12 @@ urpm::mirrors - Mirrors routines for urpmi
=over
-=cut
+=item try($urpm, $medium, $try)
+
+$medium fields used: mirrorlist, with-dir
+
+=cut
-#- $medium fields used: mirrorlist, with-dir
#- side-effects: $medium->{url}
#- + those of _pick_one ($urpm->{mirrors_cache})
sub try {
@@ -36,10 +39,15 @@ sub try {
0;
}
-#- similar to try() above, but failure is "normal"
-#- (useful when we lookup a file)
-#-
-#- $medium fields used: mirrorlist, with-dir
+=item try_probe($urpm, $medium, $try)
+
+Similar to try() above, but failure is "normal" (useful when we lookup
+a file)
+
+$medium fields used: mirrorlist, with-dir
+
+=cut
+
#- side-effects: $medium->{url}
#- + those of list_urls ($urpm->{mirrors_cache})
sub try_probe {
diff --git a/urpm/orphans.pm b/urpm/orphans.pm
index 02c655ea..256470c3 100644
--- a/urpm/orphans.pm
+++ b/urpm/orphans.pm
@@ -203,9 +203,15 @@ sub add_unrequested {
append_to_file(unrequested_list__file($urpm), join('', map { "$_\t\t$l{$_}\n" } keys %l));
}
-#- we don't want to check orphans on every auto-select,
-#- doing it only after many packages have been added
-#-
+=item check_unrequested_orphans_after_auto_select($urpm)
+
+We don't want to check orphans on every auto-select.
+We do it only after many packages have been added.
+
+Returns whether we should look for orphans depending on a threshold.
+
+=cut
+
#- side-effects: none
sub check_unrequested_orphans_after_auto_select {
my ($urpm) = @_;
@@ -214,13 +220,20 @@ sub check_unrequested_orphans_after_auto_select {
$nb_added >= $urpm->{options}{'nb-of-new-unrequested-pkgs-between-auto-select-orphans-check'};
}
-#- this function computes wether removing $toremove packages will create
-#- unrequested orphans.
-#-
-#- it does not return the new orphans since "whatsuggests" is not available,
-#- if it detects there are new orphans, _all_unrequested_orphans()
-#- must be used to have the list of the orphans
-#-
+
+=item unrequested_orphans_after_remove($urpm, $toremove)
+
+This function computes wether removing $toremove packages will create
+unrequested orphans.
+
+It does not return the new orphans since "whatsuggests" is not
+available,
+
+If it detects there are new orphans, _all_unrequested_orphans() must
+be used to have the list of the orphans
+
+=cut
+
#- side-effects: none
sub unrequested_orphans_after_remove {
my ($urpm, $toremove) = @_;
diff --git a/urpm/select.pm b/urpm/select.pm
index 8c352ccf..96d5801a 100644
--- a/urpm/select.pm
+++ b/urpm/select.pm
@@ -89,15 +89,32 @@ sub build_listid_ {
$urpm->build_listid(undef, undef, searchmedia_idlist($urpm));
}
-#- search packages registered by their names by storing their ids into the $packages hash.
-#- Recognized options:
-#- all
-#- caseinsensitive
-#- fuzzy
-#- no_substring
-#- src
-#- use_provides
-#-
+
+=item search_packages($urpm, $packages, $names, %options)
+
+Search packages registered by their names by storing their ids into the $packages hash.
+
+Recognized options:
+
+=over
+
+
+=item * all
+
+=item * caseinsensitive
+
+=item * fuzzy
+
+=item * no_substring
+
+=item * src
+
+=item * use_provides
+
+=back
+
+=cut
+
#- side-effects: $packages, flag_skip
sub search_packages {
my ($urpm, $packages, $names, %options) = @_;
@@ -252,19 +269,48 @@ sub _search_packages_keep_best {
join('|', map { $_->id } @l);
}
-#- Resolves dependencies between requested packages (and auto selection if any).
-#- handles parallel option if any.
-#- The return value is true if program should be restarted (in order to take
-#- care of important packages being upgraded (priority upgrades)
-#- %options :
-#- auto_select
-#- install_src
-#- priority_upgrade
-#- %options passed to ->resolve_requested:
-#- callback_choices
-#- keep
-#- nodeps
-#- no_suggests
+
+=item resolve_dependencies($urpm, $state, $requested, %options)
+
+
+Resolves dependencies between requested packages (and auto selection if any).
+Handles parallel option if any.
+
+The return value is true if program should be restarted (in order to take
+care of important packages being upgraded (priority upgrades)
+
+$state->{selected} will contain the selection of packages to be
+installed or upgraded
+
+
+%options :
+
+=over
+
+=item * auto_select
+
+=item * install_src
+
+=item * priority_upgrade
+
+=back
+
+%options passed to ->resolve_requested:
+
+=over
+
+=item * callback_choices
+
+=item * keep
+
+=item * nodeps
+
+=item * no_suggests
+
+=back
+
+=cut
+
sub resolve_dependencies {
#- $state->{selected} will contain the selection of packages to be
#- installed or upgraded
@@ -400,14 +446,31 @@ sub get_preferred {
my $fullname2name_re = qr/^(.*)-[^\-]*-[^\-]*\.[^\.\-]*$/;
-#- find packages to remove.
-#- options:
-#- callback_base
-#- callback_fuzzy
-#- callback_notfound
-#- force
-#- matches
-#- test
+
+=item find_packages_to_remove($urpm, $state, $l, %options)
+
+Find packages to remove.
+
+Options:
+
+=over
+
+=item * callback_base
+
+=item * callback_fuzzy
+
+=item * callback_notfound
+
+=item * force
+
+=item * matches
+
+=item * test
+
+=back
+
+=cut
+
sub find_packages_to_remove {
my ($urpm, $state, $l, %options) = @_;
@@ -508,13 +571,24 @@ sub _prohibit_packages_that_would_be_removed {
} intersection(\@to_remove, \@base_fn);
}
-#- misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=item unselected_packages(undef, $state)
+
+misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=cut
+
sub unselected_packages {
my (undef, $state) = @_;
grep { $state->{rejected}{$_}{backtrack} } keys %{$state->{rejected} || {}};
}
-#- misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+=item already_installed($state)
+
+misc functions to help finding ask_unselect and ask_remove elements with their reasons translated.
+
+=cut
+
sub already_installed {
my ($state) = @_;
uniq(map { scalar $_->fullname } values %{$state->{rejected_already_installed} || {}});
diff --git a/urpm/sys.pm b/urpm/sys.pm
index e615b215..64b807f1 100644
--- a/urpm/sys.pm
+++ b/urpm/sys.pm
@@ -23,8 +23,13 @@ urpm::sys - OS-related routines for urpmi
=cut
-#- get the list of packages that should not be upgraded or installed,
-#- typically from the inst.list or skip.list files.
+=item get_packages_list($file, $o_extra)
+
+Get the list of packages that should not be upgraded or installed,
+typically from the inst.list or skip.list files.
+
+=cut
+
sub get_packages_list {
my ($file, $o_extra) = @_;
my @l = split(/,/, $o_extra || '');
@@ -51,6 +56,12 @@ sub _read_fstab_or_mtab {
@l;
}
+=item find_a_mntpoint($dir)
+
+Find used mount point from a pathname
+
+=cut
+
sub find_a_mntpoint {
my ($dir) = @_;
_find_a_mntpoint($dir, {});
@@ -104,7 +115,12 @@ sub _find_a_mntpoint {
undef;
}
-#- return the size of the partition and its free space in KiB
+=item df($mntpoint)
+
+Return the size of the partition and its free space in KiB
+
+=cut
+
sub df {
my ($mntpoint) = @_;
require Filesys::Df;
@@ -160,7 +176,13 @@ sub proc_mounts() {
@l;
}
-#- returns the first unused loop device, or an empty string if none is found.
+
+=item first_free_loopdev()
+
+Returns the first unused loop device, or an empty string if none is found.
+
+=cut
+
sub first_free_loopdev () {
my %loopdevs = map { $_ => 1 } grep { ! -d $_ } glob('/dev/loop*');
foreach (proc_mounts()) {
@@ -181,7 +203,12 @@ sub trim_until_d {
$dir;
}
-#- checks if the main filesystems are writeable for urpmi to install files in
+=item check_fs_writable()
+
+Checks if the main filesystems are writeable for urpmi to install files in
+
+=cut
+
sub check_fs_writable () {
foreach (proc_mounts()) {
(undef, our $mountpoint, undef, my $opts) = split ' ';
@@ -288,12 +315,25 @@ sub migrate_back_rpmdb_db_version {
clean_rpmdb_shared_regions($root);
}
-#- create a plain rpm from an installed rpm and a delta rpm (in the current directory)
-#- returns the new rpm filename in case of success
-#- params :
-#- $deltarpm : full pathname of the deltarpm
-#- $o_dir : directory where to put the produced rpm (optional)
-#- $o_pkg : URPM::Package object corresponding to the deltarpm (optional)
+
+=item apply_delta_rpm($deltarpm, $o_dir, $o_pkg)
+
+Create a plain rpm from an installed rpm and a delta rpm (in the current directory)
+Returns the new rpm filename in case of success.
+Params :
+
+=over
+
+=item * $deltarpm : full pathname of the deltarpm
+
+=item * $o_dir : directory where to put the produced rpm (optional)
+
+=item * $o_pkg : URPM::Package object corresponding to the deltarpm (optional)
+
+=back
+
+=cut
+
our $APPLYDELTARPM = '/usr/bin/applydeltarpm';
sub apply_delta_rpm {
my ($deltarpm, $o_dir, $o_pkg) = @_;
diff --git a/urpm/xml_info_pkg.pm b/urpm/xml_info_pkg.pm
index d75bd2ce..889bfabd 100644
--- a/urpm/xml_info_pkg.pm
+++ b/urpm/xml_info_pkg.pm
@@ -12,9 +12,12 @@ urpm::xml_info_pkg - XML Package data retrieving related routines for urpmi
=over
-=cut
+=item new($class, $hash, $pkg)
-# proxy object: returns the xml info if available, otherwise redirects to URPM::Package
+Returns a proxy object
+It enable to get the XML info if available, otherwise redirects to URPM::Package
+
+=cut
sub new {
my ($class, $hash, $pkg) = @_;
@@ -25,7 +28,23 @@ sub new {
}
-# only available in synthesis/hdlist
+=item id($pkg)
+
+=item group($pkg)
+
+=item size($pkg)
+
+=item epoch($pkg)
+
+=item buildhost($pkg)
+
+=item packager($pkg)
+
+=item summary($pkg)
+
+Only available in synthesis/hdlist
+=cut
+
sub id { $_[0]{pkg}->id }
sub group { $_[0]{pkg}->group }
sub size { $_[0]{pkg}->size }
@@ -35,7 +54,22 @@ sub packager { $_[0]{pkg}->packager }
sub summary { $_[0]{pkg}->summary }
-# can be directly available in xml_info
+=item url($pkg)
+
+=item license($pkg)
+
+=item sourcerpm($pkg)
+
+=item description($pkg)
+
+=item changelogs($pkg)
+
+=item files($pkg)
+
+Can be directly available in xml_info
+
+=cut
+
sub url { exists $_[0]{url} ? $_[0]{url} : $_[0]{pkg}->url }
sub license { exists $_[0]{license} ? $_[0]{license} : $_[0]{pkg}->license }
sub sourcerpm { exists $_[0]{sourcerpm} ? $_[0]{sourcerpm} : $_[0]{pkg}->sourcerpm }
@@ -47,7 +81,22 @@ sub files { exists $_[0]{files} ? split("\n", $_[0]{files}) : $_[0]{pkg}->files
my $fullname_re = qr/^(.*)-([^\-]*)-([^\-]*)\.([^\.\-]*)$/;
-# available in both {pkg} and {fn}
+=item name($pkg)
+
+=item version($pkg)
+
+=item release($pkg)
+
+=item arch($pkg)
+
+=item fullname($pkg)
+
+=item filename($pkg)
+
+Available in both {pkg} and {fn}
+
+=cut
+
sub name { exists $_[0]{pkg} ? $_[0]{pkg}->name : $_[0]{fn} =~ $fullname_re && $1 }
sub version { exists $_[0]{pkg} ? $_[0]{pkg}->version : $_[0]{fn} =~ $fullname_re && $2 }
sub release { exists $_[0]{pkg} ? $_[0]{pkg}->release : $_[0]{fn} =~ $fullname_re && $3 }