/ 
Pod-Weaver-Plugin-Bencher-Scenario-0.253
River stage one • 1 direct dependent • 1 total dependent
/ Pod::Weaver::Plugin::Bencher::Scenario

NAME

Pod::Weaver::Plugin::Bencher::Scenario - Plugin to use when building Bencher::Scenario::* distribution

VERSION

This document describes version 0.253 of Pod::Weaver::Plugin::Bencher::Scenario (from Perl distribution Pod-Weaver-Plugin-Bencher-Scenario), released on 2024-02-13.

SYNOPSIS

In your weaver.ini:

[-Bencher::Scenario]
;exclude_module=Foo

DESCRIPTION

This plugin is to be used when building Bencher::Scenario::* distribution. It can also be used for Acme::CPANModules::* distribution which contain benchmarking information. Currently it does the following:

For each lib/Bencher/Scenario/* or lib/Acme/CPANModules/* module file:

  • Add a Synopsis section (if doesn't already exist) containing a few examples on how to benchmark using the scenario

  • Add a description about Bencher in the Description section

    Only for lib/Bencher/Scenario/* module files.

  • Add a Benchmark Participants section containing list of participants from the scenario

  • Add a Benchmark Sample Results containing result from a bencher run

    Both normal benchmark and a separate module startup benchmark (if eligible) are run and shown.

  • Add a Benchmarked Modules section containing list of benchmarked modules (if any) from the scenario and their versions

  • Create lib/Bencher/ScenarioR/* or lib/Acme/CPANModules_ScenarioR/* module files that contain sample benchmark result data

    These module files contain the raw data, while the Benchmark Sample Results POD section of the scenario module contains the formatted result. The raw data might be useful later. For example I'm thinking of adding a utility later, perhaps in the form of an lcpan subcommand, that can guess whether a module is relatively fast or slow (compared to similar implementations, which are other participants on benchmark scenarios). The utility can then suggest faster alternatives.

For each lib/Bencher/ScenarioBundle/* module file:

  • Add list of scenario modules at the beginning of Description section

CONFIGURATION

include_module+ => str

Filter only certain scenario modules that get processed. Can be specified multiple times.

exclude_module+ => str

Exclude certain scenario modules from being processed. Can be specified multiple times.

gen_scenarior_include_module+ => str

Filter only certain scenario modules that we create Bencher::ScenarioR::* modules for. Can be specified multiple times.

Note that modules excluded using include_module and/or exclude_module are already excluded.

gen_scenarior_exclude_module+ => str

Exclude certain scenario modules from getting their Bencher::ScenarioR::* modules created. Can be specified multiple times.

Note that modules excluded using include_module and/or exclude_module are already excluded.

sample_bench+ => hash

Add a sample benchmark. Value is a hash which can contain these keys: cmdline_comment (specify commenttitle for the benchmark command), args (hash arguments for bencher()) or file (instead of running bencher(), use the result from JSON file). Can be specified multiple times.

bench => bool (default: 1)

Set to 0 if you do not want to produce any sample benchmarks (including module startup benchmark).

bench_startup => bool (default: 1)

Set to 0 if you do not want to produce module startup sample benchmark.

gen_html_tables => bool (default: 0)

result_split_fields => str

If specified, will split result table into multiple tables using the specified fields (comma-separated). For example:

result_split_fields = dataset

or:

result_split_fields = participant

Note that module startup benchmark result is not split.

chart => bool (default: 0)

Whether to produce chart or not. The chart files will be stored in share/images/bencher-result-N.png where N is the table number.

Note that this plugin will produce this snippets:

# IMAGE: share/images/bencher-result-N.png

and you'll need to add the plugin Dist::Zilla::Plugin::InsertDistImage to convert it to actual HTML.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Pod-Weaver-Plugin-Bencher-Scenario.

SOURCE

Source repository is at https://github.com/perlancar/perl-Pod-Weaver-Plugin-Bencher-Scenario.

SEE ALSO

Bencher

Dist::Zilla::Plugin::Bencher::Scenario

Acme::CPANModules

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024, 2020, 2019, 2017, 2016, 2015 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Weaver-Plugin-Bencher-Scenario

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.