diff options
| author | Johannes Schauer <josch@debian.org> | 2016-09-12 09:35:46 +0200 |
|---|---|---|
| committer | Johannes Schauer <josch@debian.org> | 2016-09-12 09:35:46 +0200 |
| commit | 4c55d374e405ee467d886a22347e3a905538db0d (patch) | |
| tree | e5ff44b19265ba10199250f4b43156b07273261e /doc | |
Import botch_0.18.orig.tar.xz
[dgit import orig botch_0.18.orig.tar.xz]
Diffstat (limited to 'doc')
70 files changed, 5306 insertions, 0 deletions
diff --git a/doc/man/botch-add-arch.pod b/doc/man/botch-add-arch.pod new file mode 100644 index 0000000..4323cb7 --- /dev/null +++ b/doc/man/botch-add-arch.pod @@ -0,0 +1,76 @@ +=head1 NAME + +botch-add-arch - add architecture to source packages + +=head1 SYNOPSIS + +=over + +=item B<botch-add-arch> [-h] [-v] I<toarch> I<inSources> I<outSources> + +=back + +=head1 DESCRIPTION + +Add architecture I<toarch> to the C<Architecture> field of all source packages +in I<inSources> which have an C<Architecture> field that does not match +I<toarch> yet. The system's C<dpkg-architecture> program is used to determine +whether any architecture of the source packages' C<Architecture> field matches +I<toarch>. + +The files I<inSources> and I<outSources> are control files given in deb822 +format like the ones found on archive mirrors and locally under +F</var/lib/apt/lists>. + +I<inSources> and I<outSources> can point to the same file name for in-place +operation. Compressed I<inSources> files are decompressed on the fly +independent of their filename extension. The output will be compressed as +determined by the filename extension of I<outSources>. + +If I<inSources> is equal to a single hyphen-minus (-) then its content will be +read from standard input. If I<outSources> is equal to a single hyphen-minus +(-) then the output will be written to standard output. + +=head1 OPTIONS + +=over 4 + +=item B<-v, --verbose> + +Be verbose. + +=item B<-h, --help> + +Print help message. + +=back + +=head1 EXAMPLE + +Make all source packages compilable on I<arm64>: + + botch-add-arch arm64 inSources outSources + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-annotate-strong.pod b/doc/man/botch-annotate-strong.pod new file mode 100644 index 0000000..a1d1a2b --- /dev/null +++ b/doc/man/botch-annotate-strong.pod @@ -0,0 +1,90 @@ +=head1 NAME + +botch-annotate-strong - add strong dependency information to a dependency graph + +=head1 SYNOPSIS + +=over + +=item B<botch-annotate-strong> [options] I<buildgraph.xml> I<srcgraph.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Annotates I<buildgraph.xml> and I<srcgraph.xml> with strong dependency +information. Strong dependencies are calculated for binary and source packages +from the information given in I<Packages> and I<Sources>. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do not print any messages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--deb-native-arch=>I<arch> + +Native architecture I<arch>. + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=item B<--bg=>I<Packages> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--fg=>I<Packages> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-apply-ma-diff.pod b/doc/man/botch-apply-ma-diff.pod new file mode 100644 index 0000000..dee2499 --- /dev/null +++ b/doc/man/botch-apply-ma-diff.pod @@ -0,0 +1,60 @@ +=head1 NAME + +botch-apply-ma-diff - applies a multiarch diff as created by B<botch-ma-diff> + +=head1 SYNOPSIS + +=over + +=item B<botch-apply-ma-diff> [options] I<diff> I<inPackages> I<outPackages> + +=back + +=head1 DESCRIPTION + +Applies the diff given by I<diff> to I<inPackages> and outputs the result in +I<outPackages>. It will fail if binary packages I<inPackages> have a different +Multi-Arch value than I<diff> expects. + +=head1 OPTIONS + +=over 4 + +=item B<--verbose> + +be more verbose + +=item B<-h, --help> + +show this help message and exit + +=back + +=head1 EXIT STATUS + +This program exits with a zero exit status on success and a non-zero exit +status otherwise. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-bin2src.pod b/doc/man/botch-bin2src.pod new file mode 100644 index 0000000..9d219cc --- /dev/null +++ b/doc/man/botch-bin2src.pod @@ -0,0 +1,91 @@ +=head1 NAME + +botch-bin2src - convert binary packages to their source packages + +=head1 SYNOPSIS + +=over + +=item B<botch-bin2src> [options] I<Packages..> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a list of binary packages by I<Packages>, output the corresponding source +packages. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<-o, --outfile=>I<FILE> + +Set the output file I<FILE> + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 EXAMPLE + +Get the source packages corresponding to all binary packages in myPackages.gz: + + botch-bin2src --deb-native-arch=amd64 myPackages.gz mySources.gz + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-build-fixpoint.pod b/doc/man/botch-build-fixpoint.pod new file mode 100644 index 0000000..66ea96f --- /dev/null +++ b/doc/man/botch-build-fixpoint.pod @@ -0,0 +1,119 @@ +=head1 NAME + +botch-build-fixpoint - find build order until dependency cycles occur + +=head1 SYNOPSIS + +=over + +=item B<botch-build-fixpoint> [options] B<--available=>I<AvailablePackages> I<Packages..> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a list of source packages I<Sources>, return the list of binary packages +that can be built without having to break a dependency cycle. The algorithm +repeatedly attempts to satisfy build dependencies of all source packages using +the available binary packages from I<AvailablePackages> and adds the binary +packages of those source packages that satisfy their build dependencies to the +set of available binary packages. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<-A, --available=>I<AvailablePackages> + +List of available packages (arch:all, crossed...) in control file format +(setting this argument is required). Packages in this list have to be part of +I<Packages>. + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<--output-order=>I<FILE> + +instead of stderr, write the calculated build order to this file. + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<-o, --outfile=>I<FILE> + +Set the output file I<FILE> + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 EXAMPLE + +Calculate the source packages that can be built in a given state: + + botch-build-fixpoint --deb-native-arch=amd64 --available packages-arch-all --output-order=order.lst packages sources + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-build-order-from-zero.pod b/doc/man/botch-build-order-from-zero.pod new file mode 100644 index 0000000..f2119a9 --- /dev/null +++ b/doc/man/botch-build-order-from-zero.pod @@ -0,0 +1,39 @@ +=head1 NAME + +botch-build-order-from-zero - find a build order for a non-existing architecture + +=head1 SYNOPSIS + +=over + +=item B<botch-build-order-from-zero> I<inPackages> I<inSources> + +=back + +=head1 DESCRIPTION + +Attempt to create a cross-build order for a non-existing architecture. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-buildcheck-more-problems.pod b/doc/man/botch-buildcheck-more-problems.pod new file mode 100644 index 0000000..697e39b --- /dev/null +++ b/doc/man/botch-buildcheck-more-problems.pod @@ -0,0 +1,56 @@ +=head1 NAME + +botch-buildcheck-more-problems - a tool like dose-builddebcheck but return more than the first reason + +=head1 SYNOPSIS + +=over + +=item B<botch-buildcheck-more-problems> [-h] [-v] I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +This is a wrapper around dose-builddebcheck. It accepts the exact same +commandline arguments and it outputs the same yaml format. The only difference +is, that instead of only giving on reason for why a source package cannot be +compiled, it gives multiple reasons. + +=head1 OPTIONS + +=over 4 + +=item B<--verbose> + +Be verbose. + +=item B<--help> + +Print help message. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-buildgraph2packages.pod b/doc/man/botch-buildgraph2packages.pod new file mode 100644 index 0000000..bf5a3ff --- /dev/null +++ b/doc/man/botch-buildgraph2packages.pod @@ -0,0 +1,55 @@ +=head1 NAME + +botch-buildgraph2packages - convert buildgraph to packages + +=head1 SYNOPSIS + +=over + +=item B<botch-buildgraph2packages> [-h] [-v] I<buildgraph.xml> I<Packages> + +=back + +=head1 DESCRIPTION + +Given a buildgraph in GraphML format and a Packages file, output all binary +packages in deb822 format that the build graph contains in its installation +sets. + +=head1 OPTIONS + +=over 4 + +=item B<-v, --verbose> + +Be verbose. + +=item B<-h, --help> + +Print help message. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-buildgraph2srcgraph.pod b/doc/man/botch-buildgraph2srcgraph.pod new file mode 100644 index 0000000..cd7287e --- /dev/null +++ b/doc/man/botch-buildgraph2srcgraph.pod @@ -0,0 +1,89 @@ +=head1 NAME + +botch-buildgraph2srcgraph - converts a buildgraph into a srcgraph + +=head1 SYNOPSIS + +=over + +=item B<botch-buildgraph2srcgraph> [options] I<buildgraph.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Given I<buildgraph.xml> and a corresponding pair of I<Packages> and I<Sources> +files, output the corresponding srcgraph ond standard output. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-calcportsmetric.pod b/doc/man/botch-calcportsmetric.pod new file mode 100644 index 0000000..20b83d3 --- /dev/null +++ b/doc/man/botch-calcportsmetric.pod @@ -0,0 +1,70 @@ +=head1 NAME + +botch-calcportsmetric - calculate source package importance + +=head1 SYNOPSIS + +=over + +=item B<botch-calcportsmetric> [options] I<strongsrcgraph.xml> I<closuresrcgraph.xml> + +=back + +=head1 DESCRIPTION + +Calculate a metric for source package importance based on how many source +packages (minimum and maximum) become compilable in a bootstrapping scenario +through the compilability of a given source package. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +show this help message and exit + +=item B<--online> + +Retrieve popcon results for source packages + +=item B<-v, --verbose> + +print additional information + +=back + +=head1 EXAMPLE + +Calculate source package importance: + + zcat packages_amd64.gz | grep-dctrl -FArchitecture all > available + botch-create_graph --deb-native-arch=amd64 --available=available --strongtype packages sources > strongbuildgraph.xml + botch-buildgraph2srcgraph --deb-native-arch=amd64 strongbuildgraph.xml packages sources > strongsrcgraph.xml + botch-create_graph --deb-native-arch=amd64 --available=available --closuretype packages sources > closurebuildgraph.xml + botch-buildgraph2srcgraph --deb-native-arch=amd64 closurebuildgraph.xml packages sources > closuresrcgraph.xml + botch-calcportsmetric --online strongsrcgraph.xml closuresrcgraph.xml > importance_metric_noall.txt + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-calculate-fas.pod b/doc/man/botch-calculate-fas.pod new file mode 100644 index 0000000..ceb82e5 --- /dev/null +++ b/doc/man/botch-calculate-fas.pod @@ -0,0 +1,93 @@ +=head1 NAME + +botch-calculate-fas - calculate a feedback arc set + +=head1 SYNOPSIS + +=over + +=item B<botch-calculate-fas> [options] I<buildgraph.xml> I<packages> I<sources> + +=back + +=head1 DESCRIPTION + +Give a buildgraph and corresponding I<packages> and I<sources> files, calculate +a feedback arc set for it. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--max-length-fas=>I<INT> + +maximum length of found cycles for fas search (default=4). + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-check-ma-same-versions.pod b/doc/man/botch-check-ma-same-versions.pod new file mode 100644 index 0000000..1da901c --- /dev/null +++ b/doc/man/botch-check-ma-same-versions.pod @@ -0,0 +1,59 @@ +=head1 NAME + +botch-check-ma-same-versions - check if Multi-Arch:same versions are in sync + +=head1 SYNOPSIS + +=over + +=item B<botch-check-ma-same-versions> [options] I<packages1> I<packages2> + +=back + +=head1 DESCRIPTION + +checks if Multi-Arch: Same packages in two package files agree in their +versions and also outputs, should there be packages in one but not the other + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help message + +=item B<-v, --verbose> + +be verbose + +=back + +=head1 EXIT STATUS + +If the two packages file have the same binary packages and agree on their +version, return a zero exit status. Otherwise return a non-zero exit status. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-checkfas.pod b/doc/man/botch-checkfas.pod new file mode 100644 index 0000000..e049d81 --- /dev/null +++ b/doc/man/botch-checkfas.pod @@ -0,0 +1,63 @@ +=head1 NAME + +botch-checkfas - check which edges in the fas are not droppable + +=head1 SYNOPSIS + +=over + +=item B<botch-checkfas> [options] I<fas> + +=back + +=head1 DESCRIPTION + +given any number of droppable dependencies and a feedback arc set, show which +edges in the feedback arc set are not droppable + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +show the help message + +=item B<--remove-weak=>I<REMOVE_WEAK> + +A filename containing a list of weak build dependencies + +=item B<--remove-reduced=>I<REMOVE_REDUCED> + +One or more filename containing a list of droppable build dependencies, +separated by commas. + +=item B<-v, --verbose> + +be verbose + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-clean-repository.pod b/doc/man/botch-clean-repository.pod new file mode 100644 index 0000000..13c6b5f --- /dev/null +++ b/doc/man/botch-clean-repository.pod @@ -0,0 +1,114 @@ +=head1 NAME + +botch-clean-repository - clean errors in a repository by removing transitively uninstallable or compilable packages + +=head1 SYNOPSIS + +=over + +=item B<botch-clean-repository> [options] I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +given a repository of binary packages and source packages, clean up that +repository by removing packages that can't be compiled or installed and +packages which don't have an associated binary or source package and packages +which do not match the specified architecture. + +This effectively creates a self contained repository of maximal size. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--reqsrcarchall> + +require source packages for arch:all binary packages + +=item B<--addsrcarchall> + +add source packages which only build arch:all binary packages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<-o, --outfile=>I<FILE> + +Set the output file I<FILE> + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=item B<--deb-ignore-essential> + +By default, installing any binary package requires the coinstallation set of +all binary packages marked as Essential:yes to be installed as well. This +option drops this requirement. + +=back + +=head1 EXAMPLE + +Clean up a repository: + + botch-clean-repository --deb-native-arch=amd64 packages sources > packages-clean + botch-bin2src --deb-native-arch=amd64 packages-clean sources > sources-clean + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-collapse-srcgraph.pod b/doc/man/botch-collapse-srcgraph.pod new file mode 100644 index 0000000..68e23b9 --- /dev/null +++ b/doc/man/botch-collapse-srcgraph.pod @@ -0,0 +1,88 @@ +=head1 NAME + +botch-collapse-srcgraph - make a srcgraph acyclic by collapsing its strongly connected components + +=head1 SYNOPSIS + +=over + +=item B<botch-collapse-srcgraph> [options] I<srcgraph.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a srcgraph, collapse all strongly connected components to a single vertex + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-convert-arch.pod b/doc/man/botch-convert-arch.pod new file mode 100644 index 0000000..1b240d4 --- /dev/null +++ b/doc/man/botch-convert-arch.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-convert-arch - convert the architecture of a Packages file + +=head1 SYNOPSIS + +=over + +=item B<botch-convert-arch> [options] I<fromarch> I<toarch> I<inPackages> I<outPackages> + +=back + +=head1 DESCRIPTION + +convert architecture of a Packages file from I<fromarch> to I<toarch> + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +show help + +=item B<-v, --verbose> + +be verbose + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-create-graph.pod b/doc/man/botch-create-graph.pod new file mode 100644 index 0000000..c406bdc --- /dev/null +++ b/doc/man/botch-create-graph.pod @@ -0,0 +1,151 @@ +=head1 NAME + +botch-create-graph - create graph based on installation sets, strong dependency sets or dependency closures + +=head1 SYNOPSIS + +=over + +=item B<botch-create-graph> [options] I<Packages..> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a repository of source packages and binary packages, create the build +graph and source graph for it + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<-A, --available=>I<FILE> + +List of available packages (arch:all, crossed...) in control file format + +=item B<--custom-is=>I<FILE> + +list of files with dependencies that should not be part of the IS + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<--progress> + +print progress bars + +=item B<--timers> + +print timing information + +=item B<--strongtype> + +generate a strong build graph (only strong dependencies) + +=item B<--closuretype> + +generate a dependency closure build graph (all dependency relationships) + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=item B<--deb-ignore-essential> + +By default, installing any binary package requires the coinstallation set of +all binary packages marked as Essential:yes to be installed as well. This +option drops this requirement. + +=item B<--optgraph> + +Calculate a dependency graph where each installation set contains the minimal +number of unavailable binary packages. + +=item B<--num_cores=>I<NUM> + +How many worker processes to run in parallel. Default: 1 + +=back + +=head1 EXAMPLE + +Calculate a self-contained repository: + + zcat packages | grep-dctrl -X \( -FPackage build-essential --or -FEssential yes \) > minimal + dose-deb-coinstall --deb-native-arch=amd64 --bg=packages --fg=minimal > minimal-amd64 + botch-bin2src --deb-native-arch=amd64 minimal-amd64 sources > minimal-src + grep-dctrl -FArchitecture all packages > available + botch-create-graph --deb-ignore-essential -A available --deb-native-arch=amd64 --bg sources packages minimal-src > graph.xml + botch-buildgraph2packages graph.xml packages > min-closure + botch-packages-union min-closure minimal-amd64 min-closure + botch-bin2src --deb-native-arch=amd64 min-closure sources > min-closure-src + dose-builddebcheck --deb-native-arch=amd64 min-closure min-closure-src + +The self-contained repository will then be I<min-closure> and +I<min-closure-src>. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-cross.pod b/doc/man/botch-cross.pod new file mode 100644 index 0000000..ffaeebc --- /dev/null +++ b/doc/man/botch-cross.pod @@ -0,0 +1,171 @@ +=head1 NAME + +botch-cross - execute botch tools in the cross phase + +=head1 SYNOPSIS + +=over + +=item B<botch-cross> [options] [I<buildarch> I<hostarch> I<buildpackages> I<sources>] + +=back + +=head1 DESCRIPTION + +Use the botch tools to analyze the cross bootstrap phase. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help message + +=item B<-k, --keep> + +Keep the temporary files + +=item B<-w, --online> + +Produce stat.html for online consumption + +=item B<-o, --output=>I<DIR> + +Output directory. Default is the current directory + +=item B<-t, --tmp=>I<DIR> + +Temporary directory. Default is created by I<mktemp(1)> + +=item B<-G, --optgraph> + +Calculate a dependency graph where each installation set contains the minimal +number of unavailable binary packages. + +=item B<-T, --timers> + +time all program executions + +=item B<-m, --allowsrcmismatch> + +Allow binary packages to be associated with a source package of a different +version than themselves + +=item B<-e, --ignoresrclessbin> + +Ignore binary packages without a source package. + +=item B<-b, --sapsb> + +Calculate strong articulation points and bridges + +=item B<-j, --jobs=>I<NUM> + +Number of threads or processes to run in parallel where applicable. + +=item B<-I, --deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies. + +=item B<-v, --verbose> + +Be more verbose + +=item B<-d, --debug> + +Maximum verbosity + +=item B<-D, --develop> + +Execute tools from the source checkout instead of I<$PATH> + +=back + +=head1 FILES + +The following files are created in the output directory: + +=over 4 + +=item F<buildgraph_acyclic.xml> + +The output of botch-profile-build-fvs. + +=item F<buildgraph.xml> + +The output of botch-create-graph. + +=item F<cross.json> + +The output of botch-dose2html. + +=item F<cyclic_src:*.xml> + +The strongly connected components created by botch-extract-scc. + +=item F<fas> + +The standard output of botch-extract-scc. + +=item F<feedback_vertex_set.list> + +The concatenated output of multiple runs of botch-find-fvs. + +=item F<ma.diff> + +The output of botch-ma-diff. + +=item F<order1.lst> + +The output of botch-build-fixpoint. + +=item F<order2.lst> + +The output of botch-partial-order. + +=item F<remove.list> + +The output of botch-fasofstats. + +=item F<srcgraph_acyclic.xml> + +F<buildgraph_acyclic.xml> converted by botch-buildgraph2srcgraph. + +=item F<srcgraph.xml> + +F<buildgraph.xml> converted by botch-buildgraph2srcgraph. + +=item F<stats.html> + +The standard output of botch-stat-html + +=item F<stats.json> + +The JSON output of botch-stat-html + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-distcheck-more-problems.pod b/doc/man/botch-distcheck-more-problems.pod new file mode 100644 index 0000000..9b1f31c --- /dev/null +++ b/doc/man/botch-distcheck-more-problems.pod @@ -0,0 +1,56 @@ +=head1 NAME + +botch-distcheck-more-problems - a tool like dose-distcheck but return more than the first reason + +=head1 SYNOPSIS + +=over + +=item B<botch-distcheck-more-problems> [-h] [-v] I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +This is a wrapper around dose-distcheck. It accepts the exact same commandline +arguments and it outputs the same yaml format. The only difference is, that +instead of only giving on reason for why a binary package cannot be installed, +it gives multiple reasons. + +=head1 OPTIONS + +=over 4 + +=item B<--verbose> + +Be verbose. + +=item B<--help> + +Print help message. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-dose2html.pod b/doc/man/botch-dose2html.pod new file mode 100644 index 0000000..57e6b62 --- /dev/null +++ b/doc/man/botch-dose2html.pod @@ -0,0 +1,94 @@ +=head1 NAME + +botch-dose2html - turn the yaml output by B<dose-builddebcheck> into html + +=head1 SYNOPSIS + +=over + +=item B<botch-toolname> [options] I<in.yaml> I<out.html> + +=back + +=head1 DESCRIPTION + +Given a buildcheck or distcheck result, create a html overview and machine +readable json data. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--btsuser> + +bts user to associate packages with. Must be given in conjunction with B<--btstag>. + +=item B<--btstag> + +bts tag to associate packages with. Must be given in conjunction with B<--btsuser>. + +=item B<--desc> + +A HTML description that will be put on top of the generated page. + +=item B<--srcsdir> + +Output directory for individual source package overviews. Must be given in conjunction with B<--packages>. + +=item B<--wnpp> + +Retrieve and print wnpp status for packages. Must be given in conjunction with B<--packages>. + +=item B<--packages> + +Packages file to create a mapping from binary to source packages. Must be given in conjunction with B<--srcsdir>. + +=item B<--timestamp> + +Add timestamp to generated HTML. + +=item B<--wwwroot> + +This string will be removed from the beginning of the hyperlinks to the source +package overviews created with the B<--srcsdir> option. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Generate overview: + + dose-builddebcheck --explain --successes --failures --deb-native-arch=amd64 \ + packages-build packages-host sources | botch-dose2html - out.html + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-download-pkgsrc.pod b/doc/man/botch-download-pkgsrc.pod new file mode 100644 index 0000000..89410c0 --- /dev/null +++ b/doc/man/botch-download-pkgsrc.pod @@ -0,0 +1,48 @@ +=head1 NAME + +botch-download-pkgsrc - download Packages and Sources + +=head1 SYNOPSIS + +=over + +=item B<botch-download-pkgsrc> [I<arch> I<suite>] + +=back + +=head1 DESCRIPTION + +Download Packages and Sources files from a mirror. If I<arch> and I<suite> are +not specified, then the default is to download a snapshot of Debian Sid of +January 1. 2014 from snapshot.debian.org. + +The value I<arch> can be set to a valid Debian architecture and the value +I<suite> can either be a Debian release in which case, the Packages and Sources +files are retrieved from http.debian.net or it can be a Ubuntu release in which +case the files are retrieved from archive.ubuntu.com or it can be a year after +2005 in which case a snapshot of Debian sid of January 1. of that year is +retrieved from snapshot.debian.org + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-droppable-diff.pod b/doc/man/botch-droppable-diff.pod new file mode 100644 index 0000000..90edcd2 --- /dev/null +++ b/doc/man/botch-droppable-diff.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-droppable-diff - difference between two *.droppable files + +=head1 SYNOPSIS + +=over + +=item B<botch-droppable-diff> [options] I<droppable1> I<droppable2> + +=back + +=head1 DESCRIPTION + +Display the difference between two files with droppable build dependencies. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help message. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-droppable-union.pod b/doc/man/botch-droppable-union.pod new file mode 100644 index 0000000..ca44c91 --- /dev/null +++ b/doc/man/botch-droppable-union.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-droppable-union - union of two *.droppable files + +=head1 SYNOPSIS + +=over + +=item B<botch-droppable-union> [options] I<droppable1> I<droppable2> + +=back + +=head1 DESCRIPTION + +Calculate the set union of two files of droppable build dependencies. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-extract-scc.pod b/doc/man/botch-extract-scc.pod new file mode 100644 index 0000000..8332b7d --- /dev/null +++ b/doc/man/botch-extract-scc.pod @@ -0,0 +1,103 @@ +=head1 NAME + +botch-extract-scc - extract all strongly connected components + +=head1 SYNOPSIS + +=over + +=item B<botch-extract-scc> [options] I<graph.xml> [I<prefix>] + +=back + +=head1 DESCRIPTION + +Extract strongly connected components (SCC) from an input graph in GraphML or +dot format. + +The strongly connected components are stored as one file each in either the +current directory or the directory given by the B<--outdir> option. + +The file names that were generated for them are printed on standard output. + +By default that filename is of the format PREFIX_VERTEX_SIZE.EXT where PREFIX +can be set on the command line, while VERTEX defaults to the vertex ID chosen +by network, SIZE is the size of the SCC and EXT is xml by default but can be +set using the B<--extension> option. This is to reduce the possibility that two +output graph files happen to have the same name. You can make them more unique +by using the B<--outfnameverts> and B<--outfnameattr> options which refine the +string that will be printed for VERTEX. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--outdir=>I<DIR> + +output directory. Default is current directory + +=item B<--outfnameverts=>I<VERT> [I<VERT> ...] + +This option picks the set of vertices from which the smallest one will be +picked to be stored in VERTEX in the output file name. Each VERT option is a +key/value pair of graph attribute and its value. The vertices that match all +VERT selections will form the final set. By default, all vertices of the graph +are candidates. + +The special key C<__ID__> allows one to select the unique vertex identifier. + +Since this argument can take more than one option, it has to come after all +positional arguments. + +=item B<--outfnameattr=>I<attribute> + +This option picks the vertex attribute that is to be printed in VERTEX in the +output file name. + +=item B<--extension=>I<EXT> + +Output files have extension I<EXT>. Default is xml. This option also governs +the output format. The xml extension saves in GraphML format while the dot +extension saves in the dot format. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Extract the strongly connected components of a buildgraph and store them in the +directory "out", prefixing each filename with "cyclic" and let the VERTEX value +be the cudfname field of source packages only. + + botch-extract-scc --verbose --outdir=out --outfnameattr=cudfname buildgraph.xml cyclic --outfnameverts type:src + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-fasofstats.pod b/doc/man/botch-fasofstats.pod new file mode 100644 index 0000000..fc4a964 --- /dev/null +++ b/doc/man/botch-fasofstats.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-fasofstats - extract feedback arc set from output of B<botch-print-stats> + +=head1 SYNOPSIS + +=over + +=item B<botch-toolname> [options] I<stats.json> + +=back + +=head1 DESCRIPTION + +extract feedback arc set from stats.json + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-filter-src-builds-for.pod b/doc/man/botch-filter-src-builds-for.pod new file mode 100644 index 0000000..c9c7dda --- /dev/null +++ b/doc/man/botch-filter-src-builds-for.pod @@ -0,0 +1,64 @@ +=head1 NAME + +botch-filter-src-builds-for - filter a Sources file for the packages building for a certain architecture + +=head1 SYNOPSIS + +=over + +=item B<botch-filter-src-builds-for> [options] I<inSources..> I<architecture> I<outSources> + +=back + +=head1 DESCRIPTION + +Filter a Sources control file, such that it only contains the stanzas for those +source packages which build binary dependent packages for a certain +architecture. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Find all source packages that build architecture dependent binary packages for +armhf: + + botch-filter-src-builds-for Sources armhf - \ + | dose-builddebcheck --successes --explain-minimal --deb-native-arch=amd64 --deb-host-arch=armhf Packages_amd64 Packages_armhf \ + | sed -n 's/^\s\+success: src://p' + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-find-fvs.pod b/doc/man/botch-find-fvs.pod new file mode 100644 index 0000000..460106f --- /dev/null +++ b/doc/man/botch-find-fvs.pod @@ -0,0 +1,110 @@ +=head1 NAME + +botch-find-fvs - calculate a feedback vertex set + +=head1 SYNOPSIS + +=over + +=item B<botch-find-fvs> [options] I<buildgrahp.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a buildgraph find a set of source packages which, if profile build, make +the graph acyclic + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--max-length-fvs=>I<INT> + +maximum length of found cycles for fvs search (default=4) + +=item B<--remove-weak=>I<FILE> + +path to list of weak build dependencies + +=item B<--remove-reduced=>I<LIST> + +remove droppable build dependencies supplied by comma separated list of reduced +dep files + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 EXAMPLE + +Extract a feedback vertex set: + + botch-find-fvs --remove-weak=/usr/share/botch/droppable/weak-build-dependencies.list \ + --remove-reduced=/usr/share/botch/droppable/gentoo.list,/usr/share/botch/droppable/selfcycles.list \ + --deb-native-arch=amd64 scc.xml packages sources + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-fix-cross-problems.pod b/doc/man/botch-fix-cross-problems.pod new file mode 100644 index 0000000..fafc3b7 --- /dev/null +++ b/doc/man/botch-fix-cross-problems.pod @@ -0,0 +1,54 @@ +=head1 NAME + +botch-fix-cross-problems - fix Packages files with the output of B<botch-cross-problems> + +=head1 SYNOPSIS + +=over + +=item B<botch-fix-cross-problems> [options] I<dose.yaml> I<buildpackages> I<hostpackages> + +=back + +=head1 DESCRIPTION + +fix build and host architecture Packages files according to the result of +botch-dose2html + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-ancestors.pod b/doc/man/botch-graph-ancestors.pod new file mode 100644 index 0000000..a165383 --- /dev/null +++ b/doc/man/botch-graph-ancestors.pod @@ -0,0 +1,101 @@ +=head1 NAME + +botch-graph-ancestors - find all ancestors of a vertex in a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-ancestors> [options] [I<ingraph>] [I<outgraph>] --target I<TARGET> [I<TARGET> ...] + +=back + +=head1 DESCRIPTION + +Extract the subgraph of all ancestors of a specific node in the input graph. + +The B<--target> option is mandatory. Since it can take more than one argument, +it has to come after the positional arguments. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard +output, respectively. Passing a '-' as either argument, explicitly specifies +to read the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<--target=>I<TARGET> [I<TARGET> ...] + +key:value pairs to match the target vertex + +The special key C<__ID__> allows one to select the unique vertex identifier. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Extract the subgraph of all ancestors of a binary packages vertex with name +"build-essential" and version "11.7". + + botch-graph-ancestors --target name:build-essential version:11.7 type:bin < in.xml > out.xml + +or giving input and output as positional arguments: + + botch-graph-ancestors in.xml out.xml --target name:build-essential version:11.7 type:bin + +Find all source packages that build depend on C<texlive-binaries:amd64 (=2015.20150524.37493-5)>. + +Using package selection and reverse dependency cone computation by ceve: + + dose-ceve -r "texlive-binaries:amd64 (= 2015.20150524.37493-5)" --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +Using package selection and ancestor vertex computation by botch: + + dose-ceve --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-ancestors - - --target realpackage:texlive-binaries:amd64 realversion:2015.20150524.37493-5 \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-descendants.pod b/doc/man/botch-graph-descendants.pod new file mode 100644 index 0000000..b87982e --- /dev/null +++ b/doc/man/botch-graph-descendants.pod @@ -0,0 +1,84 @@ +=head1 NAME + +botch-graph-descendants - find all descendants of a vertex in a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-descendants> [options] [I<ingraph>] [I<outgraph>] --source I<SOURCE> [I<SOURCE> ...] + +=back + +=head1 DESCRIPTION + +Extract the subgraph of all descendants of a specific node in the input graph. + +The B<--source> option is mandatory. Since it can take more than one argument, +it has to come after the positional arguments. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard +output, respectively. Passing a '-' as either argument, explicitly specifies +to read the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<--source=>I<SOURCE> [I<SOURCE> ...] + +key:value pairs to match the source vertex + +The special key C<__ID__> allows one to select the unique vertex identifier. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Extract the subgraph of all descendants of a binary packages vertex with name +"build-essential" and version "11.7". + + botch-graph-descendants --source name:build-essential version:11.7 type:bin < in.xml > out.xml + +or giving input and output as positional arguments: + + botch-graph-descendants in.xml out.xml --source name:build-essential version:11.7 type:bin + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-difference.pod b/doc/man/botch-graph-difference.pod new file mode 100644 index 0000000..36ca6d6 --- /dev/null +++ b/doc/man/botch-graph-difference.pod @@ -0,0 +1,57 @@ +=head1 NAME + +botch-graph-difference - graph diff + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-difference> [options] I<g.xml> I<h.xml> + +=back + +=head1 DESCRIPTION + +Find if two GraphML or dot files differ and show the difference. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXIT STATUS + +If the files differ, the exit status is non-zero, otherwise it is zero. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-info.pod b/doc/man/botch-graph-info.pod new file mode 100644 index 0000000..28e0acc --- /dev/null +++ b/doc/man/botch-graph-info.pod @@ -0,0 +1,54 @@ +=head1 NAME + +botch-graph-info - show info about a buildgraph or sourcegraph + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-info> [options] I<g.xml> + +=back + +=head1 DESCRIPTION + +Print type and number of vertices, edges and SCC of a graph in GraphML or dot +format. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-neighborhood.pod b/doc/man/botch-graph-neighborhood.pod new file mode 100644 index 0000000..ca23f22 --- /dev/null +++ b/doc/man/botch-graph-neighborhood.pod @@ -0,0 +1,78 @@ +=head1 NAME + +botch-graph-neighborhood - extract the neighborhood around a vertex + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-neighborhood> [options] [I<ingraph>] [I<outgraph>] --center I<CENTER> [I<CENTER> ...] + +=back + +=head1 DESCRIPTION + +Extract the neighborhood around a center vertex of a graph in GraphML or dot +format. + +The B<--center> option is mandatory. Since it can take more than one argument, +it has to come after the positional arguments. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard output, +respectively. Passing a '-' as either argument, explicitly specifies to read +the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<--depth=>I<DEPTH> + +range of neighborhood to extract (Default: 1) + +=item B<--center=>I<CENTER> [I<CENTER> ...] + +key:value pairs to match the center vertex + +The special key C<__ID__> allows one to select the unique vertex identifier. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-shortest-path.pod b/doc/man/botch-graph-shortest-path.pod new file mode 100644 index 0000000..d2ef5a2 --- /dev/null +++ b/doc/man/botch-graph-shortest-path.pod @@ -0,0 +1,95 @@ +=head1 NAME + +botch-graph-shortest-path - find the shortest path(s) between two vertices of a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-shortest-path> [options] [I<ingraph>] [I<outgraph>] --source I<SOURCE> [I<SOURCE> ...] --target I<TARGET> [I<TARGET> ...] + +=back + +=head1 DESCRIPTION + +Extract the subgraph of the shortest path between two specific nodes in the +input graph. + +The B<--target> and B<--source> options are mandatory. Since they can take more +than one argument, they have to come after the positional arguments. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard +output, respectively. Passing a '-' as either argument, explicitly specifies +to read the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<--target=>I<TARGET> [I<TARGET> ...] + +key:value pairs to match the target vertex + +The special key C<__ID__> allows one to select the unique vertex identifier. + +=item B<--source=>I<SOURCE> [I<SOURCE> ...] + +key:value pairs to match the source vertex + +The special key C<__ID__> allows one to select the unique vertex identifier. + +=item B<--all> + +instead of finding an arbitrary shortest path, find all shortest paths + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Extract the subgraph of the shortest path from a certain version of the +build-essential binary vertex to a certain version of the ghc source vertex. + + botch-graph-shortest-path --source name:build-essential version:11.7 type:bin --target name:ghc version:7.8.4-8 type:src < in.xml > out.xml + +or giving input and output as positional arguments: + + botch-graph-shortest-path in.xml out.xml --source name:build-essential version:11.7 type:bin --target name:ghc version:7.8.4-8 type:src + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-sinks.pod b/doc/man/botch-graph-sinks.pod new file mode 100644 index 0000000..efebb6b --- /dev/null +++ b/doc/man/botch-graph-sinks.pod @@ -0,0 +1,65 @@ +=head1 NAME + +botch-graph-sinks - find all sinks (vertices without successors) in a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-sinks> [options] [I<ingraph>] [I<outgraph>] + +=back + +=head1 DESCRIPTION + +Extract the subgraph of all sinks (vertices without successors) in the input +graph. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard +output, respectively. Passing a '-' as either argument, explicitly specifies +to read the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-sources.pod b/doc/man/botch-graph-sources.pod new file mode 100644 index 0000000..86d1fa1 --- /dev/null +++ b/doc/man/botch-graph-sources.pod @@ -0,0 +1,84 @@ +=head1 NAME + +botch-graph-sources - find all sources (vertices without predecessors) in a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-sources> [options] [I<ingraph>] [I<outgraph>] + +=back + +=head1 DESCRIPTION + +Extract the subgraph of all sources (vertices without predecessors) in the +input graph. + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard +output, respectively. Passing a '-' as either argument, explicitly specifies +to read the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Find all source packages that build depend on C<texlive-binaries:amd64 (=2015.20150524.37493-5)>. + +Using package selection and reverse dependency cone computation by ceve: + + dose-ceve -r "texlive-binaries:amd64 (= 2015.20150524.37493-5)" --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +Using package selection and ancestor vertex computation by botch: + + dose-ceve --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-ancestors - - --target realpackage:texlive-binaries:amd64 realversion:2015.20150524.37493-5 \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph-tred.pod b/doc/man/botch-graph-tred.pod new file mode 100644 index 0000000..407633c --- /dev/null +++ b/doc/man/botch-graph-tred.pod @@ -0,0 +1,72 @@ +=head1 NAME + +botch-graph-tred - find the transitive reduction of a graph in GraphML or dot format + +=head1 SYNOPSIS + +=over + +=item B<botch-graph-tred> [options] [I<ingraph>] [I<outgraph>] + +=back + +=head1 DESCRIPTION + +Create a graph with as few edges as possible while maintaining the same +reachability relationships. + +Calculating the transitive reduction particularly helps to facilitate rendering +of dense graphs as it removes the clutter of extra edges. + +This tool is the does the same as tred(1) from the graphviz suite but for the +GraphML and dot input instead of only for dot input. It is also orders of +magnitude faster (for unknown reasons). + +If either (or both) of the positional arguments is/are omitted, then read +GraphML or dot from standard input and/or write GraphML or dot to standard output, +respectively. Passing a '-' as either argument, explicitly specifies to read +the input from standard input and write the output to standard output, +respectively. + +The input graph type will be determined automatically. If the output graph is +given as a filename, then the output type will be GraphML if the filename ends +with .xml and dot if the filename ends with .dot. If the output is done on +standard output then it will happen in the same format as the input graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graph2text.pod b/doc/man/botch-graph2text.pod new file mode 100644 index 0000000..0bd0a16 --- /dev/null +++ b/doc/man/botch-graph2text.pod @@ -0,0 +1,90 @@ +=head1 NAME + +botch-graph2text - for each vertex in a graph print a formatted line on standard output + +=head1 SYNOPSIS + +=over + +=item B<botch-graph2text> [options] [I<ingraph>] formatstring --vertices I<VERT> [I<VERT> ...] + +=back + +=head1 DESCRIPTION + +Given a B<formatstring> of the form C<{attr1} {attr2}...>, print a line with +this format for every vertex in the graph, replacing C<{attr}> placeholders +with the value of the attribute C<"attr"> for that vertex. If no attribute with +name C<"attr"> was found, then the placeholder C<{XXX}> remains in the output +string. To write a literal opening or closing curly brace, type them twice, +respectively. The special placeholder C<{__ID__}> is replaced with the vertex +identifier. + +Since the B<--vertices> option can take more than one argument, it has to come +after the positional arguments. + +If the positional arguments is omitted, then read GraphML or dot from standard +input. Passing a '-' as either argument, explicitly specifies to read the +input from standard input. The input graph type will be determined +automatically. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<--vertices=>I<VERT> [I<VERT> ...] + +key:value pairs to match the vertices to output + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Find all source packages that build depend on C<texlive-binaries:amd64 (=2015.20150524.37493-5)>. + +Using package selection and reverse dependency cone computation by ceve: + + dose-ceve -r "texlive-binaries:amd64 (= 2015.20150524.37493-5)" --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +Using package selection and ancestor vertex computation by botch: + + dose-ceve --deb-native-arch=amd64 -G pkg -T grml deb://Packages debsrc://Sources \ + | botch-graph-ancestors - - --target realpackage:texlive-binaries:amd64 realversion:2015.20150524.37493-5 \ + | botch-graph-sources - - \ + | botch-graph2text - "{realpackage} (= {realversion})" --vertices type:src \ + | sort + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-graphml2dot.pod b/doc/man/botch-graphml2dot.pod new file mode 100644 index 0000000..a90573e --- /dev/null +++ b/doc/man/botch-graphml2dot.pod @@ -0,0 +1,65 @@ +=head1 NAME + +botch-graphml2dot - converts graphml to dot + +=head1 SYNOPSIS + +=over + +=item B<botch-graphml2dot> [options] [I<g.xml>] [I<h.dot>] + +=back + +=head1 DESCRIPTION + +Convert a graph in GraphML format to dot. If either (or both) of the positional +arguments is/are omitted, then read graphml from standard input and/or write +graphml to standard output, respectively. Passing a '-' as either argument, +explicitly specifies to read the input from standard input and write the output +to standard output, respectively. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Do some graph operations: + + botch-graph-neighborhood --depth=1 srcgraph_acyclic.xml icewease.xml src:iceweasel + botch-graphml2dot iceweasel.xml iceweasel.dot + tred < iceweasel.dot > iceweasel_tred.dot + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-latest-version.pod b/doc/man/botch-latest-version.pod new file mode 100644 index 0000000..512bb12 --- /dev/null +++ b/doc/man/botch-latest-version.pod @@ -0,0 +1,54 @@ +=head1 NAME + +botch-latest-version - only keep the latest version + +=head1 SYNOPSIS + +=over + +=item B<botch-latest-version> [options] I<inPackages> I<outPackages> + +=back + +=head1 DESCRIPTION + +Filters a Packages file so that only the newest version of each package +remains. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-ma-diff.pod b/doc/man/botch-ma-diff.pod new file mode 100644 index 0000000..54f67de --- /dev/null +++ b/doc/man/botch-ma-diff.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-ma-diff - diff two packages files for differences in their multiarch values + +=head1 SYNOPSIS + +=over + +=item B<botch-ma-diff> [options] I<packages1> I<packages2> + +=back + +=head1 DESCRIPTION + +Check for differences in multiarch annotations between two packages files. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-multiarch-interpreter-problem.pod b/doc/man/botch-multiarch-interpreter-problem.pod new file mode 100644 index 0000000..1f1995b --- /dev/null +++ b/doc/man/botch-multiarch-interpreter-problem.pod @@ -0,0 +1,78 @@ +=head1 NAME + +botch-multiarch-interpreter-problem - find all arch:all packages that allow switching architectures + +=head1 SYNOPSIS + +=over + +=item B<botch-multiarch-interpreter-problem> [-h] [-v] graph.xml + +=back + +=head1 DESCRIPTION + +Given a package graph, this program outputs a page in plain text format listing +all Architecture:all and not Multi-Arch:foreign packages that are on a +dependency path between two Architecture:any packages. + +More precisely, dose-ceve creates a graph with binary packages being the nodes +and their dependency and provides relationship being the edges. This page +prints all nodes that have a (possibly transitive) predecessor (a reverse +dependency) that is not Architecture:all and that have a (possibly transitive) +successor (a dependency) that is not Architecture:all and not +Multi-Arch:foreign. If a Multi-Arch:foreign package is encountered while +walking the successors, then the successors of that package are not further +traversed. + +=head1 OPTIONS + +=over 4 + +=item B<-v, --verbose> + +Be verbose. + +=item B<-h, --help> + +Print help message. + +=item B<--packages> + +Packages file to retrieve binary package size + +=item B<-H, --html> + +Output HTML document with additional statistics + +=back + +=head1 EXAMPLE + + dose-ceve -G pkg -T grml -t deb Packages.gz > graph.xml + botch-multiarch-interpreter-problem --packages=Packages.gz graph.xml > out.html + w3m out.html + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-native.pod b/doc/man/botch-native.pod new file mode 100644 index 0000000..ff93286 --- /dev/null +++ b/doc/man/botch-native.pod @@ -0,0 +1,195 @@ +=head1 NAME + +botch-native - execute botch tools in the native phase + +=head1 SYNOPSIS + +=over + +=item B<botch-native> [options] [I<architecture> I<Packages> I<Sources>] + +=back + +=head1 DESCRIPTION + +Execute the botch tools to produce a build order for the native phase. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-k, --keep> + +Keep the temporary files + +=item B<-c, --self-contained> + +Do not work on the full repository but on a smaller self-contained repository + +=item B<-O, --optuniv> + +Calculate a self-contained repository with a minimal number of source packages + +=item B<-G, --optgraph> + +Calculate a dependency graph where each installation set contains the minimal +number of unavailable binary packages. + +=item B<-T, --timers> + +time all program executions + +=item B<-m, --allowsrcmismatch> + +Allow binary packages to be associated with a source package of a different +version than themselves + +=item B<-e, --ignoresrclessbin> + +Ignore binary packages without a source package. + +=item B<-p, --no-drop> + +Do not drop known droppable build dependencies + +=item B<-s, --strong> + +Calculate strong dependencies + +=item B<-b, --sapsb> + +Calculate strong articulation points and bridges + +=item B<-f, --no-fixpoint> + +Do not run fixpoint algorithm + +=item B<-n, --clean> + +Clean the repository beforehand + +=item B<-l, --latest> + +Select only the highest package versions + +=item B<-w, --online> + +Produce stat.html for online consumption + +=item B<-a, --available=>I<FILE> + +Deb822 list of available binary packages + +=item B<-o, --output=>I<DIR> + +Output directory. Default is the current directory + +=item B<-t, --tmp=>I<DIR> + +Temporary directory. Default is created by mktemp(1) + +=item B<-j, --jobs=>I<NUM> + +Number of threads or processes to run in parallel where applicable. + +=item B<-I, --deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies. + +=item B<-v, --verbose> + +Be more verbose + +=item B<-d, --debug> + +Maximum verbosity + +=item B<-D, --develop> + +Execute tools from the source checkout instead of $PATH + +=back + +=head1 FILES + +The following files will be placed in the output directory + +=over 4 + +=item F<buildgraph_acyclic.xml> + +The output of botch-profile-build-fvs. + +=item F<buildgraph.xml> + +The output of botch-create-graph. + +=item F<cyclic_src:*.xml> + +The output of botch-profile-build-fvs. + +=item F<fas> + +The standard output of botch-extract-scc. + +=item F<feedback_vertex_set.list> + +The concatenated output of multiple runs of botch-find-fvs. + +=item F<order1.lst> + +The output of botch-build-fixpoint. + +=item F<order2.lst> + +The output of botch-partial-order. + +=item F<remove.list> + +The output of botch-fasofstats. + +=item F<srcgraph_acyclic.xml> + +F<buildgraph_acyclic.xml> converted by botch-buildgraph2srcgraph. + +=item F<srcgraph.xml> + +F<buildgraph.xml> converted by botch-buildgraph2srcgraph. + +=item F<stats.html> + +The standard output of botch-stat-html + +=item F<stats.json> + +The JSON output of botch-stat-html + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-optuniv.pod b/doc/man/botch-optuniv.pod new file mode 100644 index 0000000..167278b --- /dev/null +++ b/doc/man/botch-optuniv.pod @@ -0,0 +1,103 @@ +=head1 NAME + +botch-optuniv - self contained repository with minimal number of source packages + +=head1 SYNOPSIS + +=over + +=item B<botch-optuniv> [options] I<Packages..> I<Sources> + +=back + +=head1 DESCRIPTION + +remove all conflicts and calculate an optimal self-contained universe with +respect to the number of source packages in it using aspcud. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--all> + +also add source packages for Architecture:all packages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<-o, --outfile=>I<FILE> + +Set the output file I<FILE> + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-packages-diff.pod b/doc/man/botch-packages-diff.pod new file mode 100644 index 0000000..53dc2ff --- /dev/null +++ b/doc/man/botch-packages-diff.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-packages-diff - create a diff between two Packages or Sources files + +=head1 SYNOPSIS + +=over + +=item B<botch-packages-diff> [options] I<inPackages1> I<inPackages2> + +=back + +=head1 DESCRIPTION + +print the binary packages whose fields differ between two packages files. + +=head1 OPTIONS + +=over 4 + +=item B<--verbose> + +Be verbose. + +=item B<-h, --help> + +Display help. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-packages-difference.pod b/doc/man/botch-packages-difference.pod new file mode 100644 index 0000000..3584cd0 --- /dev/null +++ b/doc/man/botch-packages-difference.pod @@ -0,0 +1,54 @@ +=head1 NAME + +botch-packages-difference - calculate the asymmetric set difference + +=head1 SYNOPSIS + +=over + +=item B<botch-packages-difference> [options] I<inPackages1> I<inPackages2> I<outPackages> + +=back + +=head1 DESCRIPTION + +calculate the asymmetric difference of two packages files, removing from the +first packages file all packages that are in the second file + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-packages-intersection.pod b/doc/man/botch-packages-intersection.pod new file mode 100644 index 0000000..5068738 --- /dev/null +++ b/doc/man/botch-packages-intersection.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-packages-intersection - calculate the set intersection + +=head1 SYNOPSIS + +=over + +=item B<botch-packages-intersection> [options] I<inPackages1> I<inPackages2> I<outPackages> + +=back + +=head1 DESCRIPTION + +calculate the set intersection of two packages files + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-packages-union.pod b/doc/man/botch-packages-union.pod new file mode 100644 index 0000000..4eb58ab --- /dev/null +++ b/doc/man/botch-packages-union.pod @@ -0,0 +1,53 @@ +=head1 NAME + +botch-packages-union - calculate the set union + +=head1 SYNOPSIS + +=over + +=item B<botch-packages-union> [options] I<inPackages..> I<outPackages> + +=back + +=head1 DESCRIPTION + +calculate the union of two packages files, effectively merging the two. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-partial-order.pod b/doc/man/botch-partial-order.pod new file mode 100644 index 0000000..103d86c --- /dev/null +++ b/doc/man/botch-partial-order.pod @@ -0,0 +1,88 @@ +=head1 NAME + +botch-partial-order - calculate the partial vertex order + +=head1 SYNOPSIS + +=over + +=item B<botch-partial-order> [options] I<srcgraph.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Given an acyclic srcgraph, calculate a partial order + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-print-stats.pod b/doc/man/botch-print-stats.pod new file mode 100644 index 0000000..b0f8ede --- /dev/null +++ b/doc/man/botch-print-stats.pod @@ -0,0 +1,119 @@ +=head1 NAME + +botch-print-stats - find cycles, selfcycles, amount of cycles through edges, feedback arc and vertex set, strong articulation points and bridges + +=head1 SYNOPSIS + +=over + +=item B<botch-print-stats> [options] I<buildgraph.xml> I<srcgraph.xml> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Output statistics about the graphs in JSON format on standard output. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<--max-length=>I<INT> + +maximum length of found cycles (default=2) + +=item B<--max-length-fas=>I<INT> + +maximum length of found cycles for fas search (default=4) + +=item B<--remove-weak=>I<FILE> + +path to list of weak build dependencies + +=item B<--sapsb> + +calculate strong articulation points and strong bridges + +=item B<--remove-reduced=>I<FILES> + +remove droppable build dependencies supplied by comma separated list of reduced +dep files. + +=item B<-A, --available=>I<FILE> + +List of available packages (arch:all, crossed...) in control file format + +=item B<--deb-drop-b-d-indep> + +Drop Build-Depends-Indep dependencies + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-profile-build-fvs.pod b/doc/man/botch-profile-build-fvs.pod new file mode 100644 index 0000000..3329ecb --- /dev/null +++ b/doc/man/botch-profile-build-fvs.pod @@ -0,0 +1,63 @@ +=head1 NAME + +botch-profile-build-fvs - remove droppable dependencies from graph + +=head1 SYNOPSIS + +=over + +=item B<botch-profile-build-fvs> [options] I<graph.xml> I<fvs.list> + +=back + +=head1 DESCRIPTION + +Remove droppable dependencies from a given set of source packages. List is +given on standard input if not supplied as the last positional argument. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--remove-weak=>I<FILE> + +A filename containing a list of weak build dependencies + +=item B<--remove-reduced=>I<FILE> + +One or more filename containing a list of droppable build dependencies, +separated by commas. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-remove-virtual-disjunctions.pod b/doc/man/botch-remove-virtual-disjunctions.pod new file mode 100644 index 0000000..e46e44c --- /dev/null +++ b/doc/man/botch-remove-virtual-disjunctions.pod @@ -0,0 +1,67 @@ +=head1 NAME + +botch-remove-virtual-disjunctions - remove virtual dependency disjunctions + +=head1 SYNOPSIS + +=over + +=item B<botch-remove-virtual-disjunctions> [options] I<inPackages> I<inSources> I<outPackages> I<outSources> + +=back + +=head1 DESCRIPTION + +For binary packages: remove virtual packages from disjunctions with real packages. + +For source packages: remove all but the first alternative of disjunctions just +as sbuild does it. This is useful to emulate sbuild behaviour with dependency +solvers like dose3 and aspcud which do not respect the order of dependency +disjunctions. + +This program is meant to modify a set of Packages and Sources files. If you +only want to modify one, specify /dev/null as input and output for the one you +do not want in the command line arguments. + +=head1 OPTIONS + +=over 4 + +=item B<--remove-nonvirtual> + +Also remove all but the first alternative from binary packages. This applies +the same algorithm to binary packages as is applied to source packages. + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-src2bin.pod b/doc/man/botch-src2bin.pod new file mode 100644 index 0000000..17f13a1 --- /dev/null +++ b/doc/man/botch-src2bin.pod @@ -0,0 +1,104 @@ +=head1 NAME + +botch-src2bin - turn source packages into their binary packages + +=head1 SYNOPSIS + +=over + +=item B<botch-src2bin> [options] I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Given a list of source packages, return the binary packages those source +packages build. + +=head1 OPTIONS + +=over 4 + +=item B<--version> + +show program's version and exit + +=item B<-h, --help> + +show this help message and exit + +=item B<-v, --verbose> + +print additional information + +=item B<--quiet> + +do no print any messages + +=item B<-A, --available=>I<FILE> + +List of available packages (arch:all, crossed...) in control file format. + +=item B<--allowsrcmismatch> + +If a binary package is without a source package but there is a source package +of same name but different version, match this binary package to that source +package. + +=item B<--ignoresrclessbin> + +Ignore binary packages that do not have an associated source package. If +B<--allowsrcmismatch> is supplied, then this rule is applied after it. + +=item B<--fg=>I<PKGS> + +Additional Packages lists that are checked and used for resolving dependencies +(can be repeated) + +=item B<--bg=>I<PKGS> + +Additional Packages lists that are NOT checked but used for resolving +dependencies (can be repeated) + +=item B<-o, --outfile=>I<FILE> + +Set the output file I<FILE> + +=item B<--deb-native-arch=>I<ARCH> + +Native architecture I<ARCH> + +=item B<--deb-host-arch=>I<arch> + +Host architecture I<arch>. Defaults to native architecture. + +=item B<--deb-foreign-archs=>I<archs> + +Comma-separated foreign architectures in addition to native and host +architectures. + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-stat-html.pod b/doc/man/botch-stat-html.pod new file mode 100644 index 0000000..4e333c2 --- /dev/null +++ b/doc/man/botch-stat-html.pod @@ -0,0 +1,57 @@ +=head1 NAME + +botch-stat-html - turn the JSON output of B<botch-print-stats> into human readable HTML + +=head1 SYNOPSIS + +=over + +=item B<botch-stat-html> [options] I<infile> + +=back + +=head1 DESCRIPTION + +Turn json statistics into human readable html. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<--verbose> + +Be verbose. + +=item B<--online> + +Generate online version (puts timestamp and adjusts links). + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-transition.pod b/doc/man/botch-transition.pod new file mode 100644 index 0000000..d1b1e47 --- /dev/null +++ b/doc/man/botch-transition.pod @@ -0,0 +1,39 @@ +=head1 NAME + +botch-transition - calculate a transition order + +=head1 SYNOPSIS + +=over + +=item B<botch-transition> [options] I<query> I<date> + +=back + +=head1 DESCRIPTION + +Calculate a transition order as ben would do it. Uses ben to parse the query. + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-wanna-build-sortblockers.pod b/doc/man/botch-wanna-build-sortblockers.pod new file mode 100644 index 0000000..218bd65 --- /dev/null +++ b/doc/man/botch-wanna-build-sortblockers.pod @@ -0,0 +1,94 @@ +=head1 NAME + +botch-wanna-build-sortblockers - importance of source packages for ports + +=head1 SYNOPSIS + +=over + +=item B<botch-wanna-build-sortblockers> [options] I<build-attempt-list> I<importance-metric> + +=back + +=head1 DESCRIPTION + +Filter the output of botch-calcportsmetric for "build-attempted" packages from +wanna-build. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Show help. + +=item B<-r, --reverse> + +reverse the result of comparisons + +=item B<-m, --min> + +sort by minimum number of blocked source packages (default) + +=item B<-M, --max> + +sort by maximum number of blocked source packages + +=item B<--min-popcon> + +sort by minimum sum of popcon values of the blocked source packages + +=item B<--max-popcon> + +sort by maximum sum of popcon values of the blocked source packages + +=item B<-v, --verbose> + +Be verbose. + +=back + +=head1 EXAMPLE + +Either download an importance file: + + wget http://bootstrap.debian.net/importance_metric_noall.txt + +Or generate it: + + zcat packages_amd64.gz | grep-dctrl -FArchitecture all > available + botch-create_graph --deb-native-arch=amd64 --available=available --strongtype packages sources > strongbuildgraph.xml + botch-buildgraph2srcgraph --deb-native-arch=amd64 strongbuildgraph.xml packages sources > strongsrcgraph.xml + botch-create_graph --deb-native-arch=amd64 --available=available --closuretype packages sources > closurebuildgraph.xml + botch-buildgraph2srcgraph --deb-native-arch=amd64 closurebuildgraph.xml packages sources > closuresrcgraph.xml + botch-calcportsmetric --online strongsrcgraph.xml closuresrcgraph.xml > importance_metric_noall.txt + +And then do: + + ssh buildd_arm64@buildd.debian-ports.org wanna-build -A arm64 -d unstable -l build-attempted > build-attempted + botch-wanna-build-findblockers build-attempted importance_metric_noall.txt + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-y-u-b-d-transitive-essential.pod b/doc/man/botch-y-u-b-d-transitive-essential.pod new file mode 100644 index 0000000..39fa88d --- /dev/null +++ b/doc/man/botch-y-u-b-d-transitive-essential.pod @@ -0,0 +1,82 @@ +=head1 NAME + +botch-y-u-b-d-transitive-essential - Find out why source packages are B-D transitive essential. + +=head1 SYNOPSIS + +=over + +=item B<botch-y-u-b-d-transitive-essential> [options] I<architecture> I<Packages> I<Sources> [pkgname] + +=back + +=head1 DESCRIPTION + +Find the reasons why source packages are B-D transitive essential. +Assumes that Architecture:all packages need not be bootstrapped. +Operates on the strong dependency graph. + +An optional package name as the last argument limits the output to that +package. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-k, --keep> + +Keep the temporary files + +=item B<-T, --timers> + +time all program executions + +=item B<-o, --output=>I<DIR> + +Output directory. Default is the current directory + +=item B<-t, --tmp=>I<DIR> + +Temporary directory. Default is created by mktemp(1) + +=item B<-v, --verbose> + +Be more verbose + +=item B<-d, --debug> + +Maximum verbosity + +=item B<-D, --develop> + +Execute tools from the source checkout instead of $PATH + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/botch-y-u-no-bootstrap.pod b/doc/man/botch-y-u-no-bootstrap.pod new file mode 100644 index 0000000..b92e46d --- /dev/null +++ b/doc/man/botch-y-u-no-bootstrap.pod @@ -0,0 +1,84 @@ +=head1 NAME + +botch-y-u-no-bootstrap - Find out why Debian cannot be bootstrapped. + +=head1 SYNOPSIS + +=over + +=item B<botch-y-u-no-bootstrap> [options] I<architecture> I<Packages> I<Sources> + +=back + +=head1 DESCRIPTION + +Find the reasons why Debian is currently not bootstrappable. +Assumes that Architecture:all packages need not be bootstrapped. +Operates on the strong dependency graph. + +=head1 OPTIONS + +=over 4 + +=item B<-h, --help> + +Display help. + +=item B<-k, --keep> + +Keep the temporary files + +=item B<-T, --timers> + +time all program executions + +=item B<-m, --allowsrcmismatch> + +Allow binary packages to be associated with a source package of a different +version than themselves + +=item B<-o, --output=>I<DIR> + +Output directory. Default is the current directory + +=item B<-t, --tmp=>I<DIR> + +Temporary directory. Default is created by mktemp(1) + +=item B<-v, --verbose> + +Be more verbose + +=item B<-d, --debug> + +Maximum verbosity + +=item B<-D, --develop> + +Execute tools from the source checkout instead of $PATH + +=back + +=head1 BUGS + +See L<http://bugs.debian.org/botch>. + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. + diff --git a/doc/man/generate-botch-manpage.py b/doc/man/generate-botch-manpage.py new file mode 100755 index 0000000..30716a5 --- /dev/null +++ b/doc/man/generate-botch-manpage.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 + +import os +import sys + +tools = { + "set operations on Packages or Sources files": [ + "botch-packages-difference", + "botch-packages-intersection", + "botch-packages-union", + ], + "transform Packages and Sources control files": [ + "botch-latest-version", + "botch-bin2src", + "botch-src2bin", + "botch-clean-repository", + "botch-add-arch", + "botch-convert-arch", + "botch-remove-virtual-disjunctions", + "botch-optuniv", + "botch-fix-cross-problems", + "botch-filter-src-builds-for", + ], + "analysis of Packages and Sources control files": [ + "botch-packages-diff", + "botch-ma-diff", + "botch-apply-ma-diff", + "botch-check-ma-same-versions", + ], + "create graphs of different types": [ + "botch-create-graph", + "botch-annotate-strong", + ], + "conversion of graphs": [ + "botch-buildgraph2srcgraph", + "botch-graphml2dot", + "botch-collapse-srcgraph", + "botch-profile-build-fvs", + "botch-buildgraph2packages", + "botch-graph-tred", + "botch-graph2text", + ], + "extract regions from graphs": [ + "botch-graph-neighborhood", + "botch-extract-scc", + "botch-graph-ancestors", + "botch-graph-descendants", + "botch-graph-shortest-path", + "botch-graph-sinks", + "botch-graph-sources", + ], + "dose3 wrappers": [ + "botch-dose2html", + "botch-buildcheck-more-problems", + "botch-distcheck-more-problems", + ], + "analyze graphs": [ + "botch-calcportsmetric", + "botch-calculate-fas", + "botch-find-fvs", + "botch-graph-difference", + "botch-graph-info", + "botch-partial-order", + "botch-print-stats", + "botch-multiarch-interpreter-problem", + ], + "create build orders": [ + "botch-build-fixpoint", + "botch-build-order-from-zero", + "botch-wanna-build-sortblockers", + ], + "handling of botch-internal formats": [ + "botch-stat-html", + "botch-droppable-diff", + "botch-droppable-union", + "botch-checkfas", + "botch-fasofstats", + "botch-download-pkgsrc", + ], + "shell scripts connecting the tools for meaningful operations": [ + "botch-cross", + "botch-native", + "botch-transition", + "botch-y-u-no-bootstrap", + "botch-y-u-b-d-transitive-essential", + ] + } + +toolnames = set([t for s in tools.values() for t in s]) + +scriptpath = os.path.dirname(os.path.realpath(__file__)) +manpages = set([f[:-4] for f in os.listdir(scriptpath) + if os.path.isfile(os.path.join(scriptpath,f)) + and f.startswith("botch-") and f.endswith(".pod")]) + +tool_but_no_man = toolnames - manpages + +if tool_but_no_man: + print("tool bat no man: %s"%tool_but_no_man, file=sys.stderr) + exit(1) + +man_but_no_tool = manpages - toolnames + +if man_but_no_tool: + print("man but no tool: %s"%man_but_no_tool, file=sys.stderr) + exit(1) + +print(""" +=head1 NAME + +botch - bootstrap/build order tool chain + +=head1 DESCRIPTION + +botch is a collection of tools to create and analyze dependency graphs. This +task is facilitated by a range of individual tools which use the deb822 and +graphml formats to exchange information with each other. + +Also consider browsing the HTML based doc-base Manual at F</usr/share/doc/botch/wiki/Home.html> + +The tools that botch ships allow one to: + +=over 4 +""") + +for n,s in tools.items(): + print(""" +=item %s + +=over 4 +"""%n) + for t in s: + with open(os.path.join(scriptpath,"%s.pod"%t)) as f: + l = f.readlines()[2] + try: + tn, descr = l.split(" - ", 1) + except: + raise Exception("invalid third line format") + if tn != t: + raise Exception("invalid third line format") + descr = descr.strip() + print(""" +=item B<%s>: %s +"""%(tn, descr)) + + print(""" +=back +""") + +print(""" +=back + +=head1 SEE ALSO + +Debian doc-base Manual F</usr/share/doc/botch/wiki/Home.html> + +=head1 AUTHOR + +This man page was written by Johannes Schauer. Botch is written by Johannes +Schauer and Pietro Abate. + +=head1 COPYRIGHT + +Copyright 2012-2014 Johannes Schauer, Pietro Abate + +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. A special linking exception to the GNU Lesser General Public +License applies to this library, see the COPYING file for more information. +""") diff --git a/doc/wiki/ExamplesGraphs.markdown b/doc/wiki/ExamplesGraphs.markdown new file mode 100644 index 0000000..c2ca8db --- /dev/null +++ b/doc/wiki/ExamplesGraphs.markdown @@ -0,0 +1,54 @@ +This page gives an overview over the dependency graphs used by botch. Consider the following dependency situation: + + $ cat Sources + Package: a + Version: 1.0 + Architecture: any + Build-Depends: binaryB + + Package: b + Version: 1.0 + Architecture: any + Build-Depends: binaryA + $ cat Packages + Package: binaryA + Version: 1.0 + Architecture: amd64 + Source: a + Depends: binaryB + + Package: binaryB + Version: 1.0 + Architecture: amd64 + Source: b + +Three different types of package interdependencies are expressed: + + - build dependencies (`Build-Depends` field in `Sources`) + - binary or runtime dependencies (`Depends` field in `Packages`) + - builds-from relationship (`Source` field in `Packages` or implicitly the same name as the binary package) + +We can visualize this situation as the following graph: + + + +Source package vertices are displayed as rectangles while binary package vertices are displayed as ellipses. Build dependencies are represented by dashed edges, binary dependencies by dotted edges and builds-from relationships by solid edges. + +Binary dependencies (the dependency of `binaryA` on `binaryB`) cannot conditionally be broken so we merge the two vertices for `binaryA` and `binaryB` into a single vertex to simplify the graph. + + + +The new vertex now contains all vertices that represent an installation set of `binaryA`. This is why this type of vertex is called installation set vertex. The vertex of `binaryB` was also turned into an installation set vertex but since `binaryB` does not depend on any other binary packages it is the only binary package in its installation set. + +The next figure shows the final graph which we call "build graph". The information about interdependencies between binary packages within an installation set is removed. + + + +The build graph allows to easily spot the two dependency cycles in this setup. A build graph only has two edge types (build dependency and builds-from dependency) and two vertex types (source vertex and installation set vertex). Since an installation set vertex can represent more than one binary package, it can have more than one outgoing builds-from edge. + +A so called source graph reduces the graph even further by removing the installation set vertices but keeping the interdependencies between source vertices intact. Here is the source graph of the build graph above: + + + +A source graph is required to reason about strong dependencies between source packages. + diff --git a/doc/wiki/FirstSteps.markdown b/doc/wiki/FirstSteps.markdown new file mode 100644 index 0000000..7772ad6 --- /dev/null +++ b/doc/wiki/FirstSteps.markdown @@ -0,0 +1,54 @@ +# First steps # + + +Because there was no dose3 upstream release since January 2013, botch needs some features of dose3 which are only available via git. Dose3 itself can only release a new version once a new upstream version of libcudf is released. So dose3 depends on the git version of libcudf as well. + +To check out the dose submodule you need git. To check out the libcudf submodule you need ca-certificates. + + $ apt-get install git ca-certificates + $ git clone https://gitlab.mister-muffin.de/debian-bootstrap/botch.git + $ cd botch + $ git submodule update --init + $ (cd dose; git submodule update --init;) + +You now can install all dependencies to build libcudf, dose3 and botch: + + $ apt-get install build-essential ocaml-nox camlp4 libzip-ocaml-dev libbz2-ocaml-dev ocaml-findlib libextlib-ocaml-dev libre-ocaml-dev libocamlgraph-ocaml-dev + $ make doselib + $ apt-get install libatdgen-ocaml-dev libxmlm-ocaml-dev + $ make + $ apt-get install zutils dctrl-tools wget python python-apt python-networkx + $ ./native.sh + +Botch is a set of tools which are concatenated in a meaningful manner by `./native.sh`. The result of above invocation will be: + + * the files `buildgraph.xml` and `srcgraph.xml` which are the buildgraph and sourcegraph in graphml format for the current dependency situation + * several graphs in graphml format `cyclic_src*_*.xml` representing the strongly connected components before any dependencies were dropped + * a file `stats.json` containing the results of running several heuristics on the cyclic graph that help to make the graph acyclic + * a file `stats.html` which contains the information of `stats.json` in human readable format + * a file `remove.list` which contains a close to minimal selection (a feedback arc set) of build dependencies which have to be dropped in addition to the known droppable ones (given by files in the `./droppable` directory) to make the graph acyclic + * a file `feedback_vertex_set.list` which contains a close to minimal selection (a feedback vertex set) of source packages which were selected to be profile built according to the information in `./droppable` and `remove.list` to make the graph acyclic + * the files `order1.lst` and `order2.lst` which contain the resulting build order to bootstrap the whole distribution + +The `./native.sh` script makes the assumption that a minimal build system including `Essential:yes` packages, `build-essential` and `debhelper` exists. Look at the `--help` output for more options. Investigate the script to see how it combines the multiple tools together. + +You can also use graphviz to look at the graphs: + + $ apt-get install graphviz python-pygraphviz + $ ./tools/graphml2dot < cyclic_src:foo_0.xml > cyclic_src:foo_0.dot + $ dot -Tpng cyclic_src:foo_0.dot > cyclic_src:foo_0.png + +The number in the graph filename indicates the amount of vertices. Do not use `dot` to look at large graphs as computation can take hours. Furthermore, even after computation finished, the result will not be very useful due to the sheer amount of vertices and edges. If you nevertheless want to look at it, use `sfdp` instead. + +Instead of looking at a huge graph you might want to look at the neighborhood of a specific node in the graph: + + $ ./tools/extract_neighborhood.py --depth=2 src:foo < cyclic_src:foo_0.xml > foo.xml + $ ./tools/graphml2dot < foo.xml > foo.dot + +If that is still too much, try a transitive reduction of the graph (not unique if the graph has cycles): + + $ tred < foo.dot > foo_tred.dot + +But instead of investigating the graph manually you should really look at and follow the calculated heuristics: + + $ iceweasel stats.html diff --git a/doc/wiki/Heuristics.markdown b/doc/wiki/Heuristics.markdown new file mode 100644 index 0000000..0333b89 --- /dev/null +++ b/doc/wiki/Heuristics.markdown @@ -0,0 +1,75 @@ +# Breaking dependency cycles + +Depending on build dependency there exist multiple ways to make that build dependency optional for bootstrapping. + + 1. Introduce [build profiles](https://wiki.debian.org/BuildProfileSpec) + 2. Move dependencies from Build-Depends to Build-Depends-Indep + 3. Choose different installation sets for not-strong dependencies + 4. Split the source package (so that the part that creates the cycle can be built separately) or join the source packages forming the cycle (so that the cycle can be broken in `debian/rules`) + 5. Cross compile the appropriate set of source packages + +While (1) is probably the most obvious solution, it cannot be implemented until the Debian archive accepts source packages with the build profile syntax. Depending on the type of build dependency, (2) can already be implemented right now for build dependencies on documentation generating packages and the like. Point (3) requires a deeper insight into the overall dependency situation and should be left to an actual bootstrapper instead of a package maintainer. This is because of the required inside knowledge and the fact that strong dependencies might change rapidly over time. Point (4) is most likely undesirable in most situations. The last point (5) is again up to the bootstrapper but cross buildability is a welcome feature in any source package. + +# Self-Cycles + +Self-cycles are dependency cycles of source packages with themselves. There exist three types of self cycles. For Debian to be bootstrappable, all self-cycles must be breakable. Self-cycles have a special status compared to cycles of larger sizes because they only leave one option to break them. This makes them a hard heuristic as they are not-optional and have to be worked on by package maintainers. + +## Type 1 Self-Cycles + +These are the most obvious self-cycles and mostly consist of compilers which need themselves to be built. Cycles of this type can easily be found by checking whether a source package builds a binary package it also build depends on. On the other hand, the solution to these cycles is often hard because it requires to make the compiler able to bootstrap itself. Upstream often does not provide this functionality. + +## Type 2 Self-Cycles + +These self-cycles are of the same size as the former ones but are not anymore as obvious. They consist of a source package A builld depending on a binary package B which strongly depends on another binary package C which in turn is built from source package A. Since only build dependencies can be modified, the only way to break this cycle is to not have the source package A build depend on binary package B anymore. Binary package B might be completely unrelated to source package A as it is only connected to C via a long dependency chain but nevertheless this is the only way to break these cycles. + +## Type 3 Self-Cycles + +These are like type 2 self-cycles except that the dependency relationship between B and C is not strong anymore. This means that this cyclic dependency might be solvable using other means. + +# Degree based heuristics + +Degree based heuristics are those which take no other input than the connectivity of single vertices in the dependency graph with their neighbors. + +## Amount of Missing Build Dependencies + +This heuristic maps source packages to the amount of their build dependencies which are not available. This is not equal to the amount of build dependencies but less because some of the build dependencies might already be available. + +## Only Weak Build Dependencies Missing + +This heuristic maps source packages to the amount of their build dependencies which have been classified as "weak". This classification is a soft one and mostly considers binary packages which are in most cases used for documentation generation. Often, these "weak" build dependencies can be dealt with by moving them into `Build-Depends-Indep` + +## Ratio Binary Heuristic + +Find binary packages A that are only needed by few source package B but need many other source packages C to be built to satisfy the runtime dependencies of A. Maybe the source packages B that needs the binary packages A can be built without them? + +## Ratio Source Heuristic + +Find source packages A that build-depend on many others but are only needed by few binary packages B which are in turn only needed buy a few source packages C. Maybe the source packages C that need those few binary packages B can be built without them and thus not require all the source packages A? + +# Cycle based heuristics + +Cycle based heuristics are those which take no other input than a list of cycles in the dependency graph. Since the total amount of cycles goes in the millions, only cycles up to a small length are considered. + +## Amount of Cycles through Edges + +This heuristics finds build dependencies of source packages on binary packages which are part of many dependency cycles in the graph. If such a build dependency can be broken, then this means that all those dependency cycles are immediately broken as well. + +## Cycles + +This heuristic lists the found cycles. For small cycles it might be possible to immediately identify and easy way to break them. + +# Feedback Arc Set + +A feedback arc set is a set of edges which, if removed from the graph, make the graph acyclic. The heuristic used produces a very small feedback arc set. If a build dependency is listed as being part of a calculated feedback arc set, then making it removable would greatly simplify the cyclic dependency situation. + +# Strong bridges and articulation points + +Strong bridges and strong articulation points are the edges and vertices respectively that, if removed from the graph, split it into more strongly connected components than before. + +## Strong Articulation Points + +If a source package is listed as a strong articulation point of the dependency graph, then its removal will break the graph into multiple strongly connected components. If the amount of resulting strongly connected components the dependency graph will be split into is high, then it might be worthwhile to make the source package available, for example by cross compilation. + +## Strong Bridges + +If a build dependency is listed as a strong bridge of the dependency graph, then its removal will break the graph into multiple strongly connected components. If the amount of resulting strongly connected compoents the dependency graph will be split into is high, then it might be worthwhile to make this build dependency droppable. diff --git a/doc/wiki/Makefile b/doc/wiki/Makefile new file mode 100644 index 0000000..acca492 --- /dev/null +++ b/doc/wiki/Makefile @@ -0,0 +1,23 @@ +md=$(wildcard *.markdown) +html=$(patsubst %.markdown,%.html,$(md)) +dot=$(wildcard *.dot) +png=$(patsubst %.dot,%.png,$(dot)) +docdir=/usr/share/doc/botch + +.PHONY: all +all: $(html) $(png) + +%.html: %.markdown + sed -e 's/\[\([^]]\+\)\](\([^\/)]\+\))/<a href="\2.html">\1<\/a>/' -e 's#https://gitlab.mister-muffin.de/uploads/debian-bootstrap/botch/.\{10\}/\([^)]\+\)#\1#' $< | markdown > $@ + +%.png: %.dot + dot -T png $< > $@ + +.PHONY: install +install: all + mkdir -p $(DESTDIR)$(docdir)/wiki + cp $(html) $(png) $(DESTDIR)$(docdir)/wiki + +.PHONY: clean +clean: + rm -f $(html) $(png) diff --git a/doc/wiki/Terminology.markdown b/doc/wiki/Terminology.markdown new file mode 100644 index 0000000..950eae7 --- /dev/null +++ b/doc/wiki/Terminology.markdown @@ -0,0 +1,88 @@ +# Dependency Relationships # + +Binary packages express binary dependencies on other binary packages. Source packages express build dependencies on binary packages. Both dependency relationships are expressed in conjunctive normal form. A conjunctive normal form is a conjunction of disjunctions. A conjunction is an AND-relationship while a disjunction is an OR-relationship. Here an example: + + Depends: blub, foo, bar | baz + +The dependencies `blub`, `foo` and `bar | baz` form a conjunction because to fulfill this dependency relationship they must all be satisfied. The clauses are connected by multiple ANDs. The clause `bar | baz` is a disjunction of `bar` and `baz` because to fulfill this clause it is enough if only one of them is satisfied. The packages `bar` and `baz` are connected by an OR. + +The other type of dependency is the builds-from relationship which is a dependency from a binary package to the source package that builds it. This dependency exists because a binary package can only exist if its source package can be built. + +# Architecture # + + * **build architecture** the architecture the package is built **on** + * **host architecture** the architecture the package is built **for** + * **target architecture** the architecture the bootstrap is done for. During cross compilation the host architecture is the target architecture. + +# Dependency Closure and Installation Sets # + +A dependency closure is the set of binary packages closed under their dependency relationship. This is, if all dependency relationships from a starting binary or source package were followed (including all disjunctions) recursively, then the resulting set of visited binary packages would form the dependency closure of the starting binary or source package. The dependency closure of a binary or source package therefore contains all binary packages that this binary or source package directly or indirectly could possibly require to satisfy its runtime or build dependencies respectively. + +Since disjunctive dependencies are also followed, a dependency closure often contains more binary packages that are actually necessary to fulfill a given binary or source package's dependencies. It is also possible for two packages in a dependency closure to conflict with each other. An installation set is a subset of a dependency closure. An installation set must fulfill the following properties: + + * Every package in the installation set has its dependencies satisfied + * No two packages in the installation set conflict with each other + +Usually there exist different choices of installation sets and choosing one is the task of a solver and its given metrics. The set of packages which satisfies the dependencies for installing or building more than one binary or source package is called a co-installation set. The same conditions as for normal installation sets hold. Some sets of binary or source packages might not have a co-installation set as they themselves or their respective dependencies conflict with each other. + +# Strong Dependencies # + +The set of strong dependencies of a binary or source package is the intersection of all its possible installation sets. In other words: a binary package is a strong dependency of another binary (or source) package, if the latter cannot be installed (or compiled) without the former. The strong dependency set therefore creates a lower bound and at the same time a strict minimum requirement for installation or build dependency satisfaction of any binary or source package. + +# Repositories and Metadata Repositories # + +A repository is a set of binary packages and source packages including their metadata information and the actual binaries and source code they contain, respectively. Package managers have access to repositories to facilitate the retrieval and installation of new or upgraded packages on the system of the end user. Repositories are usually either accessed over HTTP or FTP or can be stored on a local filesystem. + +The dependency analysis of botch is carried out on the metadata stored inside a repository. We call a repository that only consists of metadata like package names, versions and their relationships but without the binary content or source code a metadata repository. The metadata information for binary and source packages is stored in Packages and Sources files respectively. Those two files conform to the control file format. To start a bootstrap analysis with botch the only needed input are a pair of those Packages and Sources files for the desired distribution and target architecture. + +Most repositories offered by binary distributions are self-contained. A self-contained repository is a set of binary packages B and a set of source packages S for which the following holds: + + * All binary packages B (except `Architecture:all` binary packages) must be compilable from the source packages in S. + * All source packages in S must be compilable from the binary packages in B. + +The exception for `Architecture:all` packages is made because in a bootstrap situation, those binary packages do not need to be compiled anymore. It is therefore not necessary to make source packages that build `Architecture:all` binary packages part of the problem. + +`Essential:yes` binary packages are an implicit dependency of every binary package and the `build-essential` package is an implicit build dependency of all source packages. Therefore all `Essential:yes` binary packages and the `build-essential` binary package plus all binary dependencies of both are always part of a self-contained repository. Same holds for the source packages that build those binary packages except for those binary packages that are `Architecture:all` for reasons explained earlier. + +# Availability # + +Throughout the bootstrap process we associate the boolean property of availability to packages. Availability means that the package including all its data files exists for a given architecture. This property is particularly interesting for binary packages as source packages are always available for all architectures. Additionally, all `Architecture:all` binary packages are always available for any architecture as they are architecture independent. To make an architecture dependent binary package available it must be compiled natively or cross compiled. It is the goal of the bootstrap process to make all architecture dependent binary packages of the target architecture available. + +This property is not to be confused with the availability of only the metadata of a given binary package for an architecture. Meta data information and full metadata repositories can always be generated for all binary packages for all architectures. The set of available binary packages refers to an actual repository of binary packages with their binary and data content available in addition to their metadata. + +Having full metadata information available in form of metadata repositories before the actual binary packages associated with it are available is also a necessary property to analyze the dependency relationships between binary and source packages for the target architecture. For example, calculating an installation set for a given binary or source package depends on this metadata information. + +The goal of the bootstrap process is to make more and more binary packages available through cross or native compilation until all architecture dependent binary packages are available for the target architecture and all source packages can be compiled on the target architecture without running into dependency cycles. The bootstrapping process starts with no binary packages of the target architecture being available. Some source packages have to be cross compiled so that enough binary packages for a minimal build system become available. The rest of the binary packages is then made available through native compilation. + +# Installability # + +Installability means that a package can be installed and more precisely, that there exists an installation set of this binary package for which all its members are available for a given architecture. Installability is therefore stronger than availability and installability of a package also implies its availability. + +We sometimes use the term installability for source packages. For a source package to be installable it means that all binary packages of one of its installation sets are available. Installability for source packages is therefore equal to its compilability. + +In a healthy distribution all binary packages are available and installable and all source packages are compilable. During bootstrapping only a subset of all binary packages are available and therefore even fewer are installable. + +# Build Dependency Cycles # + +During the bootstrapping of a distribution, only a small subset of all binary packages is initially made available through cross compilation. To make more binary packages available their respective source packages have to be compiled. But those source packages might build depend on binary packages that are not yet available themselves and whose source packages can't be built for the same reason. Build dependency cycles are created. + +Build dependency cycles do not only exist during native compilation but also during cross compilation of the minimal build system. In that scenario, build dependency cycles are created because not all of the cross build dependencies of source packages can be satisfied by packages of the build architecture but require not-yet-built binary packages of the host architecture. But since in most source packages at least some cross build dependencies can be satisfied by packages of the build architecture, there exist much fewer build dependency cycles during cross compilation than during native compilation. It has been shown that in practice, a minimal build system can be cross compiled by only modifying a dozen source packages. + +# Strongly Connected Component # + +While dependency cycles are an intuitve way to talk about the problem, a dependency graph does usually never contain individual cycles. Instead, a subset of vertices in the graph are all involved in cyclic dependencies whith each other. This subset of vertices is called a strongly connected component or SCC. All vertices of a strongly connected component are in at least one dependency cycle with every other vertex of the SCC. In Debian, there exists one big strongly connected component of several hundred vertices which contains all of Debian's core packages as well as browsers, window managers, compilers and most of qt and gtk. The other strongly connected components in the dependency graph are no bigger than 10 vertices and mostly involve compilers that need themselves to be built. The main strongly connected component in Debian contains more than several million dependency cycles. + +# Build Graph and Source Graph # + +Botch handles two different graph types which we called build graph and source graph. A build graph consists of two types of vertices: + + * InstSet vertices represent one binary package and one of its installation sets + * SrcPkg vertices represent one source package + +InstSet vertices are connected to SrcPkg vertices to show a "builds-from" relationship for all the binary packages that are port of the installation set. + +SrcPkg vertices are connected to InstSet vertices to show a "build-depends" relationship for all the build dependencies of the source package. + +Vertices of the same type cannot connect to each other. + +A build graph can be converted into a source graph. A source graph only contains SrcPkg vertices. InstSet vertices are removed through path contraction over all pairs of SrcPkg vertices that are connected by a single InstSet vertex. Therefore, a source graph keeps the ordering relationship of the build graph. A source graph cannot be turned back into a build graph. A source graph can be annotated with strong dependency information. This information is not useful in the build graph.
\ No newline at end of file diff --git a/doc/wiki/Tools.markdown b/doc/wiki/Tools.markdown new file mode 100644 index 0000000..4978872 --- /dev/null +++ b/doc/wiki/Tools.markdown @@ -0,0 +1,201 @@ +# botch-native + +The tools will be explained by going through what `native.sh` does, step-by-step. This way it might be possible to get a good overview of how the tools can work together in a meaningful manner. + +`botch-native` takes three or no positional arguments. If no argument is given, then `botch-download-pkgsrc` is run to download a default set of Packages and Sources files from http://snapshot.debian.org. + +## botch-download-pkgsrc + +`botch-download-pkgsrc` takes two or no positional arguments. If no argument is given, then a default set of Packages and Sources for amd64 is downloaded from http://snapshot.debian.org. Otherwise the two positional arguments are an architecture and a suite name which can be any of etch, lenny, squeeze, wheezy, jessie or sid. In addition the suite can be a year from 2007 to 2013 and will then download Debian sid from January 01 that year. + +## botch-single-version + +If the `--latest` option is given to `botch-native`, then `botch-single-version` will be run on the input Packages file. + +`botch-single-version` takes two positional arguments which are the input and output Packages files. If either of them is a `-` then data is read from standard inptut or written to standard output, respectively. It goes through all packages in the given file and keeps for each architecture, the package with the highest version. + +## botch-clean-repository + +If the `--clean` options is given to `botch-native`, then `botch-clean-repository` will be run on the input Packages and Sources files. + +`botch-clean-repository` removes all binary packages which: + + * can't be installed + * don't have a corresponding source package (`Architecture:all` binary packages are excluded from this check by default. This can be changed with the `--reqsrcarchall` option) + +`botch-clean-repository` also removes all source packages which: + + * can't be compiled + * do not produce any binary packages (Source packages only producing `Architecture:all` binary packages are removed by default. This can be changed with the `--addsrcarchall` option) + +`botch-clean-repository` does this removal iteratively until nothing gets removed anymore. The result is a self-contained repository (see [[Terminology]]). + +`botch-build-closure` also outputs a self-contained repository but while `botch-build-closure` results in roughly the smallest possible self-contained repository, `botch-clean-repository` will calculate the biggest possible self-contained repository. + +## grep-dctrl + +After this initial cleanup, `grep-dctrl` is used to select the binary packages which have to be part of the minimal native build system. The default is: + + grep-dctrl -X \( \ + -FPackage build-essential --or \ + -FPackage apt --or \ + -FPackage debhelper --or \ + -FEssential yes \ + \) + +These packages alone are not enough to be installed together. To find a selection of packages which make it possible to install this selection (a co-installation set), `dose-deb-coinstall` will be run. + +## dose-deb-coinstall + +`dose-deb-coinstall` takes a set of foreground packages and a set of background packages. It outputs a set of packages which make it possible to install the foreground packages into the background packages. + +## botch-bin2src + +Lots of operations like those carried out by `botch-single-version`, `botch-clean-repository` or `dose-deb-coinstall` only work on binary packages. But bootstrapping needs a list of source packages as well. + +`botch-bin2src` takes a list of binary packages and outputs the source packages that are needed to build them. + +The analogous tool to `botch-bin2src` is `botch-src2bin`. + +## botch-build-closure + +If the `--self-contained` option is given to `botch-native` then `botch-build-closure` will be run on the input Packages file. + +`botch-build-closure` is given a minimal selection of co-installable packages and then: + + * adds all source packages that build the included binary packages + * adds all binary packages needed to compile the included source packages + +`botch-build-closure` does this addition iteratively until nothing gets added anymore. +The result is a self-contained repository (see [[Terminology]]). + +`botch-clean-repository` also outputs a self-contained repository but while `botch-clean-repository` results in the biggest possible self-contained repository, `botch-build-closure` will calculate the roughly smallest possible self-contained repository. + +## dose-builddebcheck + +If the `--self-contained` option is given to `botch-native` then `dose-builddebcheck` will be run on the output of `botch-build-closure`. + +`dose-builddebcheck` takes a Packages and Sources file and checks if all source packages in Sources can be compiled with the binary packages in Packages. If not it outputs the reason by giving the arguments `--explain` and `--failures`. + +## botch-build-fixpoint + +If the `--no-fixpoint` option is not given to `botch-native` then `botch-build-fixpoint` will be run the input Packages file. + +Given a Packages and Sources file, as well as a set of available packages, `botch-build-fixpoint` finds which source packages are already compilable and adds the resulting binary packages to the set of available packages. This step is repeated until no more source packages can be built. It calcuates the build order of source packages without having to break any build dependencies. This step can help to increase the amount of initially available binary packages which in turn helps to simplify the dependency graph. + +The `--output-order` option specifies a file into which to write the deduced build order. + +`botch-build-fixpoint` writes the list of compilable source packages to standard output. + +## botch-src2bin + +Since `botch-build-fixpoint` outputs source packages, `botch-src2bin` has to be used to calculate a list of corresponding binary packages. Given a list of source packages, `botch-src2bin` outputs the list of binary packages that these source packages build. + +## botch-packages-union + +The list of available binary packages is extended using the tool `botch-packages-union`. It takes two or more positional arguments. All arguments but the last are treated as input while the last is treated as the output. If the argument is a `-` then it will be read from standard input or written to standard output, respectively. + +`botch-packages-union` creates a union of all input files, writing the result to the output file. It merges multiple packages files into one, leaving no duplicates. + +## botch-create-graph + +After all these preprocessing steps, `botch-create-graph` is run to calculate the dependency graph. + +`botch-create-graph` takes a Packages and Sources file as well as a list of Packages which are available (see [[Terminology]]). Available packages are those which were initially cross compiled (here, the calculated co-installation set) as well as `Architecture:all` binary packages. All binary packages which are marked as available are not connected to a source package in the dependency graph. + +The output of `botch-create-graph` is given on standard output and redirected to `./buildgraph.xml` by `botch-native`. + +The default dependency graph is created by arbitrarily choosing installation sets for binary package installation and source package compilation. The choice of installation sets can be influenced by passing the `--custom-is` option with a path to a file which lists dependencies that should not part of the calculated installation set. + +By default, `Build-Depends-Indep` dependencies are not considered. This can be changed by passing the `--keep-indep` option. + +Instead of generating an installation set and connecting vertices accordingly with edges, the `--strongtype` option can be used to calculate strong dependencies while the `--closuretype` option can be used to calculate dependency closures instead. + +## botch-buildgraph2srcgraph + +After `buildgraph.xml` has been created `botch-buildgraph2srcgraph` is used to create `srcgraph.xml`. Build graphs and source graphs are explained in [[Terminology]]. + +## botch-annotate-strong + +If the `--strong` option is given to `botch-native` then `botch-annotate-strong` will be run on the source graph to mark edges as strong or not. + +## botch-print-stats + +After all this processing, the build graph and source graph are analyzed and heuristics for how to make them acyclic are computed by `botch-print-stats`. Some of these heuristics for the source graph require it to be annotated with strong dependency information first. + +`botch-print-stats` runs all algorithms by default except for calculating strong bridges and strong articulation points which can be calculated by giving the `--sapsb` option. + +The `--max-length` option indicates the maximum length for the cycles that shall be listed. + +The `--max-length-fas` option indicates the maximum length for cycles that shall initially be used in the feedback arc set algorithm. +The list of available binary packages as passed with the `--available` option is needed to identify self-cycles in the source graph. + +Listing dependencies which could possibly be marked as droppable by using build profiles or which could be moved to `Build-Depends-Indep` requires to specify the list of weak dependencies with the `--weak-deps` option. + +The output of `botch-print-stats` is given in json format on standard output. It is redirected to `./stats.json` by `botch-native`. + +## botch-stat-html + +Since the json file is not human readable it is converted into html format by `botch-stat-html`. The output is written to standard output and redirected to `stats.html` by `botch-native`. + +## botch-fasofstats + +The existing droppable build dependencies might not have been enough to make the whole graph acyclic. The tool `botch-fasofstats` extracts a set of build dependencies which would make the graph acyclic from `./stats.json`. The output is written to standard output and redirected to `./remove.list` by `botch-native`. + +## botch-extract-scc + +The tool `botch-extract-scc` extracts all strongly connected components from the build graph and saves them into separate files with a given prefix. The default prefix given by `botch-native` is `cyclic`. The output filename is structured as `${prefix}_${pkgname}_${vertnum}.xml` where `${prefix}` is the selected prefix, `${pkgname}` is the smallest package in the strongly connected component and `${vertnum}` is the number of vertices in the strongly connected component. + +## botch-find-fvs + +Given a dependency graph and a list of known droppable build dependencies, `botch-find-fvs` will find a small selection of source packages (a feedback vertex set) which, if their droppable build dependencies were removed from the graph, made the whole graph acyclic. + +`botch-native` runs `botch-find-fvs` on all extracted strongly connected components and concatenates the resulting selection into the file `./feedback_vertex_set.list`. + +## botch-profile-build-fvs + +After a feedback vertex set which would make the graph acyclic has been found, `botch-profile-build-fvs` is used to modify the build graph accordingly. + +`botch-profile-build-fvs` writes the resulting graph to standard output which is redirected into `./buildgraph_acyclic.xml` by `botch-native`. + +## botch-partial-order + +Given an acyclic source graph, `botch-partial-order` will output a build order of source packages on standard output. The output is redirected to `./order2.lst` by `botch-native`. + +All source packages which can be built in parallel are given in the same line. + +## botch-graph-info + +The tool `botch-graph-info` takes a buildgraph or source graph as an argument and outputs one line with tab delimetered values. The values are: + + * the filename + * the graph type (build graph or source graph) + * the number of vertices + * the number of edges + * the number of strongly connected components (if this number is zero, then the graph is acyclic) + +# Other tools + +## botch-collapse-srcgraph + +A build order can only be deduced from an acyclic graph. Sometimes, only a small remote cycle remains in the source graph which doesnt affect the major part of the graph. In that case, `botch-collapse-srcgraph` allows to collapse all remaining strongly connected components of the input source graph into one single vertex, thus making the input graph acyclic. + +## botch-extract-neighborhood + +Rendering a big graph takes time and the graph might be too big to make a rendering of it useful. For this purpose, `botch-extract-neighborhood` allows to extract the neighborhood of a vertex. It takes three positional arguments: the nodename, the input graph and the output graph. The `--depth` argument allows to specify until what depth the neighborhood shall be extracted. + +## botch-graph-difference + +For regression testing, `botch-graph-difference` allows to check whether two input graphs are equal or not. It does not calculate which parts are different but just outputs the first difference in case there is one. + +## botch-graphml2dot + +The graphviz tools contain powerful visualization and processing tools but graphs have to be in the dot format. `botch-graphml2dot` converts an input build graph or source graph in graphml format into dot format for consumption by graphviz tools. + +## botch-packages-difference + +`botch-packages-difference` works analogous to `botch-packages-union` and `botch-packages-intersection`. Given three positional arguments it removes the packages in the second file from the first file and writes the result to the third. + +## botch-packages-intersection + +`botch-packages-intersection` works analogous to `botch-packages-difference` and `botch-packages-union`. Given three positional arguments it outputs all packages to the third file which are present in both, the first and the second.
\ No newline at end of file diff --git a/doc/wiki/buildgraph1.dot b/doc/wiki/buildgraph1.dot new file mode 100644 index 0000000..07719e5 --- /dev/null +++ b/doc/wiki/buildgraph1.dot @@ -0,0 +1,12 @@ +digraph G { + "src:b" [shape=rectangle] + "src:a" [shape=rectangle] + binaryB1 [label="binaryB"]; + binaryA -> binaryB1 [style=dotted]; + binaryB2 [label="binaryB"]; + binaryB2 -> "src:b"; + binaryB1 -> "src:b"; + binaryA -> "src:a"; + "src:a" -> binaryB2 [style=dashed]; + "src:b" -> binaryA [style=dashed]; +} diff --git a/doc/wiki/buildgraph2.dot b/doc/wiki/buildgraph2.dot new file mode 100644 index 0000000..474d105 --- /dev/null +++ b/doc/wiki/buildgraph2.dot @@ -0,0 +1,18 @@ +digraph G { + "src:b" [shape=rectangle] + "src:a" [shape=rectangle] + subgraph cluster_a { + label = "InstSet binaryA"; + binaryB1 [label="binaryB"]; + binaryA -> binaryB1 [style=dotted]; + } + subgraph cluster_b { + label = "InstSet binaryB"; + binaryB2 [label="binaryB"]; + } + binaryB2 -> "src:b"; + binaryB1 -> "src:b"; + binaryA -> "src:a"; + "src:a" -> binaryB2 [style=dashed]; + "src:b" -> binaryA [style=dashed]; +} diff --git a/doc/wiki/buildgraph3.dot b/doc/wiki/buildgraph3.dot new file mode 100644 index 0000000..7e03729 --- /dev/null +++ b/doc/wiki/buildgraph3.dot @@ -0,0 +1,11 @@ +digraph G { + "src:b" [shape=rectangle] + "src:a" [shape=rectangle] + binaryA [label="InstSet binaryA"] + binaryB [label="InstSet binrayB"] + binaryB -> "src:b"; + binaryA -> "src:a"; + binaryA -> "src:b"; + "src:a" -> binaryB [style=dashed]; + "src:b" -> binaryA [style=dashed]; +} diff --git a/doc/wiki/home.markdown b/doc/wiki/home.markdown new file mode 100644 index 0000000..ae00715 --- /dev/null +++ b/doc/wiki/home.markdown @@ -0,0 +1,29 @@ +Botch stands for Bootstrap/Build Order ToolCHain. It consists of a number of tools that aid in breaking dependency cycles and generating a build order so that Debian can be bootstrapped. + +# Source code # + + git clone http://gitlab.mister-muffin.de/debian-bootstrap/botch.git + +# Documentation # + + * [First Steps](FirstSteps) + * [Tools](Tools) + * [Terminology](Terminology) + * [Heuristics](Heuristics) + * [Examples/Graphs](ExamplesGraphs) + * [Master Thesis about botch](http://mister-muffin.de/bootstrap/thesis.pdf) + * [FOSDEM Talk](https://fosdem.org/2013/schedule/event/debian_bootstrap/) ([Slides](http://mister-muffin.de/bootstrap/fosdem2013.pdf)) ([Video](http://video.fosdem.org/2013/crossdistro/Bootstrapping_Debian_based_distributions_for_new_architectures.webm), [Mirror](http://mister-muffin.de/bootstrap/fosdem2013.webm)) + * [DebConf13 Talk](http://penta.debconf.org/dc13_schedule/events/984.en.html) ([Slides](http://mister-muffin.de/bootstrap/debconf13.pdf)) ([Video](http://meetings-archive.debian.net/pub/debian-meetings/2013/debconf13/webm-high/984_An_introduction_to_the_BootstrapBuild_Ordering_Toolchain.webm), [Mirror](http://mister-muffin.de/bootstrap/debconf13.webm)) + * [CBSE2013](http://comparch2013.org/program/cbse.html) ([Paper](http://mister-muffin.de/bootstrap/cbse2013.pdf)) ([Slides](http://mister-muffin.de/bootstrap/cbse2013slides.pdf)) ([Video](http://mister-muffin.de/bootstrap/cbse2013talk.mkv)) + * [Informatiktage 2013](http://informatiktage.gi.de/informatiktage/rueckblicke/informatiktage-2013/wissenschafts-und-absolventenworkshop.html) ([Paper](http://mister-muffin.de/bootstrap/informatiktage2013.pdf#page=96)) + +# Contact # + + * Email: `j.schauer@email.de` + * IRC: `#debian-bootstrap` on `irc.debian.org` + +# Links # + + * [General Bootstrapping Introduction on the Debian wiki](http://wiki.debian.org/DebianBootstrap) + * [TODO list for developers](http://wiki.debian.org/DebianBootstrap/TODO) + * [Blog](http://blog.mister-muffin.de)
\ No newline at end of file diff --git a/doc/wiki/srcgraph.dot b/doc/wiki/srcgraph.dot new file mode 100644 index 0000000..09f7db9 --- /dev/null +++ b/doc/wiki/srcgraph.dot @@ -0,0 +1,7 @@ +digraph G { + "src:a" [shape=rectangle] + "src:b" [shape=rectangle] + "src:b" -> "src:b" + "src:a" -> "src:b" + "src:b" -> "src:a" +} |