Bug#671496: /usr/bin/apt-ftparchive: undocumented and unusable
Excerpts from David Kalnischkies's message of Fri May 04 18:45:42 +0200 2012:
> On Fri, May 4, 2012 at 6:06 PM, Michal Suchanek
> <michal.suchanek@ruk.cuni.cz> wrote:
> > As the format of apt archives has been changed silently and my
> > dpkg-scanpackages script generates archives that apt no longer
> > understands.
>
> I don't know about such a change.
> And there shouldn't be such a change either.
> Can you give an example so we can fix apt?
It has been reported as bug 644900 and the conclusion was that my
archive was of unwanted format and hence was not supposed to be usable
in the first place.
However, there is no spec for apt archives other than implicit
"readabale by current apt" so when apt was "fixed" that way it would no
longer read "readable by current apt" from some time past.
>
> > It's been suggested that I use apt-ftparchive instead since it works out
> > all the details.
>
> That depends.
> For a "works out details" tool rerepro might be the better option.
> apt-ftparchive is more for people who want to control the details themself…
>
> > However, the main problem remains:
> >
> > THE APT REPOSITORY FORMAT IS NOT DOCUMENTED.
> >
> > THE TOOL TO GENERATE IT IS NOT SUFFICIENTLY DOCUMENTED, EITHER.
>
> Oh yeah, who hasn't heard all the good stories about
> "scream-generated documentation"… :/
This is kind of an ages old issue.
It is getting quite frustrating :/
>
> > It far less obvious that these should be prefixed with APT::FTPArchive::
> > but some values explicitly mentioned in the man page are prefixed so.
>
> That the settings aren't prefixed with APT::FTPArchive:: has the reason
> that they are not interpreted if you prefix them.
Oh, that way it did not work for me either.
Does that mean some values require the prefix and some require that they
are not prefixed?
That's totally awesome.
>
> Feel free to refer to the example file included in the apt-utils package.
> It features an example for BinDirectory style repos. Mostly because the
> Tree style repo is even easier to setup, but i agree that we should have
> an example for that in the package, too.
Indeed, there is an example included. However, it is NOT referenced in
the man page. The man page is grossly incomplete without an example. It
is totally NOT obvious what the syntax of the configuration file(s) is
from the man page.
>
> > It is not said what parts are required, if any.
> > Hopefully filling in what parts of the archive I want is sufficient.
> >
> > Now I can presumably put some random values in the config file and
> > generate my repo, eh?
> >
> > Except the syntax is:
> >
> > apt-ftparchve generate config section...
> >
> > It iss uspposed to be able to generate multiple sections so hopefully
> > the section is not required?
> > $ apt-ftparchive generate repo.conf
> > Packages done, Starting contents.
> > Done. 0 B in 0 archives. Took 0s
>
> No, section is not required.
> Your setup is just wrong…
> As said, no prefix and you will be fine.
As said, does not work either.
>
> > I would really appreciate documentation describing the damn archives.
>
> Feel free to have a look at:
> http://anonscm.debian.org/loggerhead/apt/debian-sid/annotate/head:/doc/examples/ftp-archive.conf
>
> This is NOT how the archive is generated (see dak instead) and is (a bit)
> dated, but still an other valid example.
That is an example of how the archive can be generated with
apt-ftparchive. Still that is NOT a document describing what an archive
is supposed to include and where.
> All in all, while you have some valid points a nicer wording would not
> have hurt. And raising this as a question rather than a bugreport wouldn't
> have been the worst of all possible ideas either because a bugreport is
> usually full of details and not full of demoralizational rambling.
I provided as much detail as is possible from the available
documentation and error messages. Indeed, that's not much.
Thanks
Michal
Reply to: