Does the devguide document the benchmarking suite anywhere?  I can't see it anywhere in the index on http://docs.python.org/devguide/ and google doesn't seem to show anything.

suggested content:
  * how to run the benchmarks for a Python 2 implementation
  * how to run the benchmarks for a Python 3 implementation

Sorry if it exists and I missed it

No it does not, but it should.

Mmmh... I'm not very warm on this one. If we start documenting the benchmark suite in the devguide, then people will start to be all gung ho about it, be obsessed with benchmark numbers, etc.

I guess what I'm saying is that *if* it's covered, then the very beginning of the section should explain that benchmarking is not important in most cases, and time spent on Python is generally better spent fixing bugs and adding features.

Benchmarking is also useful to test that existing patches (that fix bug or add features) don't have a negative effect on the performance.  Some kind of warning that advises against using benchmarks just to try and optimize everything sounds like a good idea though.

I think this will be useful information.  I tend to doing benchmarks
rather infrequently.  Whenever I do them I forgot how I setup the suite
the previous time around.

In fact, I found this issue just now while googling for how to setup and
run the official benchmark suite :-)

Documenting this would be useful because it appears to be non-trivial to actually run the benchmark suite with Python 3. 

* Using "python perf.py -b default" fails due to some code in the
  benchmarks that is not python3 compatible

* Using "make_perf3.sh" and then running "... -b default" still fails,
  because not all libraries are translated (the test run stopped because
  splitfire couldn't be found)

* Using "-b 2n3" instead instead of "-b default" or "-b all" works, but
  runs only a subset of the benchmark.

> * Using "-b 2n3" instead instead of "-b default" or "-b all" works,
> but
>   runs only a subset of the benchmark.

I think we should include a copy of the 2to3'ed third-party libs in
the benchmarks repo, this would running avoid the length and tedious
conversion on every user's computer.

The overhead of 2to3 isn't too bad, especially because only a subset of the benchmarks is translated in the first place. 

It is more important that there is better documentation than there is now, it seems that you're supposed to use either '-b 2n3' or make_perf3.sh with '-b py3k'.  Neither of which are mentioned in README.txt.

> The overhead of 2to3 isn't too bad, especially because only a subset
> of the benchmarks is translated in the first place.

Well, the biggest time is spent translating the third-party libraries,
not benchmark files.
Also, it's simply tedious manual work (you have to create a separate
directory etc.).

> It is more important that there is better documentation than there is
> now, it seems that you're supposed to use either '-b 2n3' or
> make_perf3.sh with '-b py3k'.  Neither of which are mentioned in
> README.txt.

That's because the benchmark suite was initially 2.x-only, and the
"make_perf3.sh" was a quick hack to make some of the benchmarks work
on 3.x.

Nowadays the goal is for benchmark files to be 2.x and 3.x compatible
in the same codebase, so that only third-party libs remain to
translate. Adding 3.x-compatible versions of the third-party libs
would eliminate that last step.

The attached patch for the benchmark README.txt should document the status quo.

On Mon, 2013-07-29 at 14:01 +0000, Ronald Oussoren wrote:
> Ronald Oussoren added the comment:
> 
> The attached patch for the benchmark README.txt should document the status quo.
> 
> ----------
> Added file: http://bugs.python.org/file31073/issue-18181-full-v3.txt
It looks like you attached the wrong patch: the patch you attached seems
to be unrelated to benchmarking (and presumably relates to issue 18181)

Sorry about that. I stored the patch file in the wrong directory and attached the most recent file in the directory where I had expected the patch to be.

I agree with Antoine that the time has come to drop make_perf3.sh and make it so that Python 3 doesn't require a separate build of the benchmark directory. Created http://bugs.python.org/issue18586 to track this idea.

Now that bug #18586 is closed, could the Dev Guide point benchmarkers to the benchmarks repo and its README?

http://hg.python.org/benchmarks/file/9a1136898539/README.txt

Jeff: yes it could :) Do you want to provide a patch?

I added a `Benchmarking` section in the dev guide with the relevant links and the intended use (testing rather than optimizing).
I also added an entry for the section in the Index.

Testing/verification:
I built the docs and visually inspected them.

New changeset 428b6350307e by Benjamin Peterson in branch 'default':
add a pointer to the benchmarks repo (closes #17449)
http://hg.python.org/devguide/rev/428b6350307e