From d90e2c33fec88adabef87549ec3d1b4fb65d9587 Mon Sep 17 00:00:00 2001 From: Thierry Vignaud Date: Fri, 31 Aug 2012 16:45:16 +0000 Subject: convert a couple comments to POD --- urpm/download.pm | 32 +++++++++--- urpm/get_pkgs.pm | 21 ++++++-- urpm/install.pm | 16 +++--- urpm/lock.pm | 27 ++++++++-- urpm/mirrors.pm | 20 +++++--- urpm/orphans.pm | 33 ++++++++---- urpm/select.pm | 138 +++++++++++++++++++++++++++++++++++++++------------ urpm/sys.pm | 62 +++++++++++++++++++---- urpm/xml_info_pkg.pm | 59 ++++++++++++++++++++-- 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 } -- cgit v1.2.1