configsmoke(3)

📦
version 1.84 · 2 versions
, in fedora 43

💖 configsmoke(3) 💖

Okay bestie, we're diving into configsmoke — Explain the options during configuration. This is part 1, and it's giving very thorough. 💅

✨ NAME ✨

configsmoke — Explain the options during configuration.

✨ VERSION ✨

This is version: 0.094 💖

✨ SYNOPSIS ✨

Software installed in ~/perl5coresmoke/smoke

$ cd ~/perl5coresmoke
$ mkdir etc
$ cd etc
$ ../smoke/tsconfigsmoke.pl -c <prefix>

or on MSWin32 (installed in %HOMEDRIVE%%HOMEPATH%\perl5coresmoke\smoke):

%HOMEDRIVE%
cd %HOMEPATH%\perl5coresmoke
md etc
cd etc
..\smoke\tsconfigsmoke.bat -c <prefix>

✨ OPTIONS ✨

  • --config|-c <prefix> — Set the prefix for all related files
  • --des — Use all default settings, no questions asked
  • --help|-h — The short help for options
  • --show-config — Show the current values for these options

✨ DESCRIPTION ✨

Welcome to the Perl5 core smoke suite. 🌸

Test::Smoke is the symbolic name for a set of scripts and modules that try to run the perl core tests on as many configurations as possible and combine the results into an easy to read report.

The main script is tssmokeperl.pl, and this uses a configuration file that is created by this program (tsconfigsmoke.pl). There is no default configuration as some actions can be rather destructive, so you will need to create your own configuration by running this program! 🫶

By default the configuration file created is called smokecurrent_config, this can be changed by specifying the -c <prefix> switch at the command line.

$ perl ../smoke/configsmoke.pl -c mysmoke

will create mysmoke_config (in the current directory) as the configuration file and use mysmoke as prefix for related files.

The configfile is written with Data::Dumper, so it is a bit of Perl that will be put through eval() when read back for use.

After you are done configuring, a job command list (JCL) is written. For MSWin32 this is called <prefix>.cmd, for VMS this is called <prefix>.COM, otherwise this is called <prefix>.sh.

All output (stdout, stderr) from tssmokeperl.pl and its sub-processes is redirected to a logfile called <prefix>.log by the JCL.

This is a new version of the configure script, SOME THINGS ARE DIFFERENT! 💀

You will be asked some questions in order to configure this smoke suite. Please make sure to read the documentation perldoc configsmoke in case you do not understand a question.

  • Values in angled-brackets (<>) are alternatives (none other allowed)
  • Values in square-brackets ([]) are default values (<Enter> confirms)
  • Use single space to clear a value
  • Answer '&-d' to continue with all default answers

💖 ddir

ddir is the destination directory. This is used to put the source-tree in and build perl. If a source-tree appears to be there you will need to confirm your choice.

💖 w32args

For MSWin32 we need some extra information that is passed to Test::Smoke::Smoker in order to compensate for the lack of Configure.

Items involved:

  • w32cc: This is the CCTYPE (GCC|MSVC|BORLAND)
  • w32make: This is the make program (gmake|nmake)
  • w32args: Arrayref with:
    • --win32-cctype, w32cc
    • --win32-maker, w32make
    • osvers=$osvers
    • ccversarg

See also Configure_win32( ) in Test::Smoke::Util and tsw32configure.pl

💖 sync_type

We have dropped support for the sync_types: snapshot and hardlink. Gone bestie, gone.

sync_type can be one of three:

git (preferred)

This will use the git program to clone the master perl-source from GitHub into gitdir (the master can be changed gitorigin). For the actual smoking, yet another clone into ddir is used.

Items involved:

  • gitbin: Absolute location of the git program.
  • gitorigin: The origin of the Perl5 source tree (https://github.com/Perl/perl5.git).
  • gitdir: Absolute location for the main clone of gitorigin (perl-from-git).
  • gitdfbranch: The branch in the repository to smoke (blead).
  • gitbranchfile: Absolute location of the file that can hold the name of the branch to actually smoke (<prefix>.gitbranch).

rsync

This will use the rsync program to sync up with the repository. tsconfigsmoke.pl checks to see if it can find rsync in your path.

The default switches (opts) passed to rsync are: -az --delete

Items involved:

  • rsync: Absolute location of the rsync program.
  • opts: Options to pass to rsync (-az --delete).
  • source: Hostname:port/directory of the source (rsync://dromedary.p5h.org:5872/perl-current/)

copy

This will use File::Copy and File::Find to just copy from a local source directory (cdir).

Items involved:

  • cdir: Absolute location of the source tree on the local system.

See also Test::Smoke::Syncer

💖 make finetuning

Two different config options to accommodate the same thing: parallel build and serial testing

  • makeopt: used by Test::Smoke::Smoker::_make()
  • testmake: Use a different binary for make _test

💖 harnessonly

harnessonly indicates that make test is replaced by make test_harness.

💖 harness3opts

harness3opts are passed to HARNESS_OPTIONS for the make test_harness step.

💖 force_c_locale

force_c_locale is passed as a switch to tsrunsmoke.pl to indicate that $ENV{LC_ALL} should be forced to C during make test.

💖 defaultenv

defaultenv, when set will make tsrunsmoke.pl remove $ENV{PERLIO} and only do a single pass make test.

💖 perlio_only

perlio_only, when set will not run the tests with $ENV{PERLIO}=stdio and only with $ENV{PERLIO}=perlio (and with locale-setting if set).

💖 locale

locale and its value are passed to tsrunsmoke.pl and its value is passed to tsreporter.pl. tsrunsmoke.pl will do an extra pass of make test with $ENV{LC_ALL} set to that locale (and $ENV{PERL_UNICODE}="";, $ENV{PERLIO}=perlio). This feature should only be used with UTF8 locales, that is why this is checked (by regex only).

If you know of a way to get the utf8 locales on your system, which is not covered here, please let me know! 🦋

💖 skip_tests

This is a MANIFEST-like file with the paths to tests that should be skipped for this smoke.

The process involves on the fly modification of MANIFEST for tests in lib/ and ext/ and renaming of core-tests in t/.

💖 smokedb_url

Instead of flooding a mailing list, reposts should be sent to the Perl5CoreSmokeDB. The option to mail yourself a copy of the report still exists. The Perl5CoreSmokeDB however offers a central point of view to the smoke results.

Items involved:

  • smokedb_url: Where to post the report (https://perl5.test-smoke.org/report).
  • send_log: Can be one of always|on_fail|never (on_fail).
  • send_out: Can be one of always|on_fail|never (never).

💖 mail

The (boolean) option mail is used to see if the report is send via mail.

Items involved:

  • mail_type: Can be one of: sendmail|mail|mailx|sendemail|Mail::Sendmail|MIME::Lite depending on which of these is available.

See Test::Smoke::Mailer.

  • to: Email address to send the report to.
  • cc: Email address to send a carbon copy of the report to.
  • bcc: Email address to send a blind carbon copy of the report to.
  • ccp5p_onfail: Boolean to indicate if this report should be send to the perl5porters mailing list, please don't do that (unless they ask for it).
  • mailbin: Absolute location of the mail program is set as mailt_ype.
  • mailxbin: Absolute location of the mailx program if set as mail_type.
    • swcc: mailx command line switch for the CC email address (-c).
    • swbcc: mailx command line switch for the BCC email address (-b).
  • sendemailbin: Absolute location of the sendemail program if set as mail_type.
    • from: Email address to use in FROM.
    • mserver: The hostname of the SMTP server to use (localhost).
    • msport: The port on that host the SMTP servers uses (25).
    • msuser: The username for authenticating with the SMTP server.
    • mspass: The password for authenticating with the SMTP server.
  • sendmailbin: Absolute location of the sendmail program if set as mail_type.

Extra options: from

  • mail_type: Mail::Sendmail

Extra options: from|mserver|msport

  • mail_type: MIME::Lite

Extra options: from|mserver|msport|msuser|mspass

💖 Various files/directories

This section only handles the adir option interactively, but more options are set.

  • adir: Absolute location to use as a base for the archive of reports and other files, leave empty for no archiving. We archive outfile, rptfile, jsnfile and logfile.
  • outfile: The file that holds all information to create the report (mktest.out).
  • rptfile: The report that is generated at the end of the run (mktest.rpt).
  • jsnfile: The json that will be send to the Perl5CoreSmokeDB (mktest.jsn).
  • lfile: Absolute location of the logfile (<prefix>.log).

💖 hostname

By default we use the hostname reported by System::Info, but this can be changed here.

💖 un_file

One can add a usernote to the report, this usernote is kept in a file (<prefix>.usernote).

If the file does not exist, it will be created.

💖 un_position

This is the position (top|bottom) where the usernote is inserted into the report (bottom).

💖 cronbin

On unix-like systems we will check for the crontab program, on MSWin32 we will check for either the schtasks.exe or at.exe program.

crontab

For crontab we read the current entries and if we find ourselfs (the JCL) we will comment that line out and add a new line.

schtasks.exe

For schtasks we query the scheduler to see if our TaskName is already in the schedule and if so we will add the /F command line switch to override the current entry.

One can find the scheduled task by name: P5Smoke-<prefix> or a general schtasks /query | find "P5Smoke-"

at.exe

Microsoft has removed at.exe from Windows 10+ so we can no longer really maintain this feature and schtasks.exe is preferred.

💖 crontime

This is a HH::MM formated time.

💖 v

This option indicates the verbosity towards the logfile (lfile) and can be set to: 0|1|2, the default is 1.

smartsmoke 🧠✨

Okay bestie, smartsmoke is literally the vibe check for your smoke test. It means the smoke doesn't have to happen if the patchlevel — that's the git commit sha, iykyk — is the same after syncing the source-tree. No new commits? No smoke. Periodt.

killtime ⏰💀

When $Config{d_alarm} is found, we can use alarm() to abort those long-running smokes that are just… doing the most. Leave this value empty to keep the old behaviour (aka the "we suffer in silence" era).

07:30 => tssmokeperl.pl is aborted at 7:30 localtime
+23:45 => tssmokeperl.pl is aborted after 23 hours and 45 minutes

Thank you Jarkko for donating this suggestion! 💖 An absolute icon, a legend, the moment.

umask 🎭

umask will be set in the shell-script that starts the smoke.

renice 💅

renice will add a line in the shell-script that starts the smoke.

PERL5LIB 📚✨

If you have a value for PERL5LIB set in the config environment, you could have it transferred to the JCL. Do not bother asking if it is not there. Like, don't even.

PERL5OPT 🎀

If you have a value for PERL5OPT set in the config environment, you could have it transferred to the JCL. Again: do not bother asking if it is not there. Fr fr.

cfg 🗂️

cfg is the path to the file that holds the build-configurations. There are several build-cfg files provided with the distribution:

  • perlcurrent.cfg: for the blead-branch on unixy systems 🐧
  • w32current.cfg: for the blead-branch on MSWin32 🪟
  • vmsperl.cfg: for the blead-branch on OpenVMS 👑

One of these files is used as the default build configurations file, depending on the OS one is on. It's giving "we got options" energy.

🌈 COMMAND LINE OPTIONS Makefile.PL 🌈

--site-lib 🛍️

This will leave the "PREFIX" and "INSTALLSITESCRIPT" as-is and install as a regular Perl module. No drama, just vibes.

🌸 ENVIRONMENT VARIABLES 🌸

These change the behaviour of Makefile.PL:

SMOKE_INST_DIR 📁

Sets "PREFIX" and "INSTALLSITESCRIPT" to this directory.

SMOKE_INST_SITE_LIB 🧚

When true, will leave "PREFIX" and "INSTALLSITESCRIPT" as is, and install as a regular Perl module. No questions asked. 💅

PERL_MM_OPT ⚙️

This may contain "INSTALL_BASE=" that needs to be honoured. Respect the base, bestie.

AUTOMATED_TESTING 🤖

When true, will not ask for the installation dir and use whatever default is in place. Autopilot mode activated.

© MMII - MMXXIII Abe Timmerman <abeltje@cpan.org>

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

See:

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 😭

And that's a wrap on this configsmoke(3) manual page, bestie — brought to you by perl v5.42.0, dated 2025-07-25. Slay, read responsibly, and may your smokes always be smart. 💖🦋✨

📦 where this page comes from