Yosys docs reproducibility (Was: Yosys in Debian)

[Emil Jiří Tywoniak]

Hi Daniel,

On the .rst side, in docs/source/cmd_ref.rst you'll find /cmd/* which Sphinx
expands
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>
such that "matches are inserted into the list alphabetically". This is
related specifically to the docs build, not to the binary help message. I
thought the irreproducibility was in the output of the help command used in
the yosys binary and not in the docs generated via Sphinx from rst
generated by write_rst in kernel/register.cc, is that not the case?

Cheers
Emil



On Tue, Jul 9, 2024 at 12:37 PM Daniel Gröber <dxld at darkboxed.org> wrote:

> Hi Emil, Hi Krystine,
>
> On Tue, Jul 09, 2024 at 11:37:02AM +0200, Emil Jiří Tywoniak wrote:
> > Thank you for the extensive information. I have looked at the ordering of
> > pass short_help strings and I find them to be ordered by iterating over
> > std::map<std::string, Pass*> pass_register; which clearly is defined
> > regardless of locale since std::map uses std::less for comparison which
> > uses operator< which for std::string is given as
> std::lexicographical_compare
> > which is described
> > <https://en.cppreference.com/w/cpp/algorithm/lexicographical_compare> as
> > "If one range is a prefix of another, the shorter range is
> > lexicographically *less* than the other."
>
> Right I had found those docs too, but lexicographical ordering may still
> depend on locale.
>
> > Therefore synth_intel ought to always come before synth_intel_alm
> > regardless of stability or locale. Would you mind sharing information
> about
> > which locale was used and the commit this was tested at?
>
> I don't have that noted down unfortunately. These notes are from the
> trenches :]
>
> Reprotest just picks "random" locales AFAIK, but perhaps biased towards
> ones with interesting behaviours.
>
> On Tue, Jul 09, 2024 at 09:54:12PM +1200, Krystine Sherwin wrote:
> > If this is about the order of .rst files read by Sphinx during a docs
> build
> > (and in turn the order they are output and/or listed in the contents),
> the
> > command reference pages are detected by sphinx via globbing of
> > /docs/source/cmd/*.
>
> Aah, that would make sense. I forgot about disorderfs. Reprotest
> intentionally introduces readdir() reordering (if enabled/installed). That
> was IIRC why I could initially not reproduce this locally and only saw it
> in CI.
>
> > If that is giving different orders depending on locale
> > I imagine that would be a problem with Sphinx and not something we can
> > solve without providing a complete list of source files, which isn’t
> really
> > feasible.
>
> Where is this glob? Who expands it?
>
> Surely there should be a way sort the list after expansion.
>
> --Daniel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.reproducible-builds.org/pipermail/rb-general/attachments/20240709/79bfc60e/attachment.htm>