Raising a Working wxPerl Shop on Windows

This is the third essay in the series Essays about The Virtuous Perl Programmer. It follows The Perl Lazarus Workshop and moves from explaining the selected tools to assembling and using them.

A collection of tools is not yet a workshop.

The craftsman must know where each tool belongs, how to verify that it works, and how to move from one stage of the work to the next without losing what he has already made.

This essay will raise a practical wxPerl shop on Windows. By the end, the programmer should possess:

• a known Strawberry Perl environment;
• a working installation of Alien::wxWidgets and Wx;
• a visible wxPerl demonstration;
• wxGlade configured to emit Perl;
• an MSYS2 terminal with vim and Git;
• a small wxGlade project;
• generated Perl source;
• at least one working event;
• and a Git commit preserving the first successful state of the shop.

This is not yet the construction of a commercial application. It is the preparation of the place in which such an application can be built.

The distinction matters.

A programmer who begins a major project before verifying the workshop may later be unable to tell whether a failure belongs to the application, the GUI design, the active Perl, the native library, the generated code, or the operating environment.

The prudent craftsman proves each layer before placing the next one upon it.

What counts as a working shop?

The shop is working when the entire development cycle can be repeated:

1. Open or create a wxGlade project.
2. Change the graphical design.
3. Emit Perl source code.
4. Inspect the generated changes.
5. Add or revise application behavior.
6. Run the application with the intended Strawberry Perl.
7. Correct the work.
8. Preserve a known-good state in Git.

The goal is not merely to install several programs without error messages.

The goal is to establish a rhythm of work.

The daily wxPerl working cycle

Stage	Primary tool	Result
Design	wxGlade	A saved .wxg XML project
Emit	wxGlade	Perl source generated from the visual design
Inspect and edit	vim under MSYS2	Reviewed source and handwritten behavior
Run	Strawberry Perl terminal	The actual wxPerl application
Compare and preserve	Git under MSYS2	A diff and recoverable checkpoint

The distinction between these environments will be repeated throughout this essay because it prevents one of the most confusing failures in the workflow:

Use MSYS2 to edit and manage the project, but run the wxPerl application using Strawberry Perl.

MSYS2 may have its own Perl. That Perl is not the Perl against which the selected wxPerl stack was built.

Begin with a tested profile

A craftsman may enjoy experimenting with the newest tools, but he should first establish a known working reference point.

The living version matrix is maintained at Developing and Distributing wxPerl Applications on Windows. At the time this essay was prepared, the documented profiles included:

Selected wxPerl installation profiles

Status	Strawberry Perl	Alien::wxWidgets	Wx	Use
Previously tested reference	5.40.2.1, 64-bit UCRT MSI	0.71	3.008	The safer starting point for reproducing the established workflow
Newer PDL-oriented profile	5.42.2.1, 64-bit UCRT PDL ZIP	0.73	3.009	A newer path which should be treated according to the current verification status on the wiki
Archived reference	5.40.0.1, 64-bit UCRT MSI	0.70	3.005	Historical comparison and regression troubleshooting

The exact versions will change. This essay therefore explains the process using the previously tested 5.40.2.1 profile, while the maintained installation page remains authoritative for current links and newly verified combinations.

A tested profile is not a claim that newer software is bad.

It is a statement about evidence.

The programmer who chooses an experimental profile should record that decision. He should not later describe the result as though it had received the same testing as the reference profile.

Prepare a work record before installing anything

Create a plain-text file named:

wxperl-environment.txt

Record:

• the date;
• Windows edition and version;
• whether the system is 64-bit;
• the selected Strawberry Perl profile;
• the selected Alien::wxWidgets version;
• the selected Wx version;
• the wxGlade version;
• the Python version used by wxGlade;
• the MSYS2 installation date;
• and links to the instructions followed.

This file is not bureaucracy.

It is a record of the workshop at the moment it was built. Six months later, when another machine behaves differently, the file may be more useful than memory.

Create a directory for installation logs as well:

C:\wxperl-shop\logs

The installation BAT file being developed for the Perl Lazarus Project should eventually automate much of this work. It should preserve the same order and should make each stage visible:

1. identify the selected profile;
2. run one installation stage;
3. preserve its output;
4. stop clearly when that stage fails;
5. verify the result;
6. and continue only when the layer beneath it is sound.

The batch file should preserve successful labor. It should not turn the installation into an unknowable ritual.

The manual steps remain important because they allow the craftsman to understand and repair the automated process.

Install Strawberry Perl

For the previously tested profile, use the instructions at:

• Wx 3.008, Alien::wxWidgets 0.71, Strawberry Perl 5.40.2.1

The documented installer is the 64-bit UCRT MSI distribution of Strawberry Perl 5.40.2.1.

Run the installer normally. When it completes, close any command windows which were already open. A terminal started before installation may not see the updated PATH.

Open:

Start menu → Strawberry Perl → Perl (command line)

This should produce an ordinary Windows command prompt prepared for Strawberry Perl.

Run:

where perl
perl -v
perl -V:archname
perl -V:cc
where gcc
where gmake

The first perl reported by where perl should be the intended Strawberry Perl executable, normally under a path resembling:

C:\Strawberry\perl\bin\perl.exe

The exact compiler version is less important than proving that Strawberry Perl's compiler and build tools are available.

Save the output:

where perl                         >  C:\wxperl-shop\logs\strawberry-baseline.txt
perl -v                           >> C:\wxperl-shop\logs\strawberry-baseline.txt
perl -V:archname                  >> C:\wxperl-shop\logs\strawberry-baseline.txt
perl -V:cc                        >> C:\wxperl-shop\logs\strawberry-baseline.txt
where gcc                         >> C:\wxperl-shop\logs\strawberry-baseline.txt
where gmake                       >> C:\wxperl-shop\logs\strawberry-baseline.txt

Do not proceed until the intended Perl is clear.

A large number of Windows development failures are not failures of the language or module under examination. They are failures to identify which executable is actually running.

Install Alien::wxWidgets

Remain in the Strawberry Perl command-line window.

For the tested profile, run:

cpanm --verbose https://github.com/sciurius/perl-Alien-wxWidgets/releases/download/R0.71/Alien-wxWidgets-0.71.tar.gz

Preserve the output if practical:

cpanm --verbose https://github.com/sciurius/perl-Alien-wxWidgets/releases/download/R0.71/Alien-wxWidgets-0.71.tar.gz > C:\wxperl-shop\logs\alien-wxwidgets-install.txt 2>&1

This stage may require time. Native libraries and build configuration are involved.

Do not mistake a quiet period for certain failure. Do not mistake a long stream of compiler output for success either.

Wait for the final result.

Then verify:

perl -MAlien::wxWidgets -e "print qq{Alien::wxWidgets $Alien::wxWidgets::VERSION\n}"

For this profile, the output should identify version 0.71.

If Perl reports that the module cannot be found, do not attempt to install Wx repeatedly in the hope that the missing layer will repair itself. Read the log and correct this stage first.

Install Wx / wxPerl

Once Alien::wxWidgets is installed and can be loaded, install the Perl binding:

cpanm --verbose https://github.com/sciurius/wxPerl/releases/download/R3.008/Wx-3.008.tar.gz

To preserve the complete output:

cpanm --verbose https://github.com/sciurius/wxPerl/releases/download/R3.008/Wx-3.008.tar.gz > C:\wxperl-shop\logs\wxperl-install.txt 2>&1

Then verify:

perl -MWx -e "print qq{Wx $Wx::VERSION\n}"

The selected profile should report:

Wx 3.008

Also verify both layers in one command:

perl -MAlien::wxWidgets -MWx -e "print qq{Alien::wxWidgets $Alien::wxWidgets::VERSION\nWx $Wx::VERSION\n}"

A successful module load is important, but it is not yet a complete graphical test.

The binding must create an application and enter the Windows event loop.

Run a minimal hand-written wxPerl application

Create:

C:\wxperl-shop\hello-wx.pl

with the following contents:

<syntaxhighlight lang="perl"> use strict; use warnings; use Wx;

package HelloWxApp; use parent 'Wx::App';

sub OnInit {

   my ($self) = @_;

   my $frame = Wx::Frame->new(
       undef,
       -1,
       'The Perl Lazarus Workshop',
   );

   $frame->SetSize(640, 360);
   $frame->Centre();
   $frame->Show(1);

   return 1;

}

package main;

my $app = HelloWxApp->new(); $app->MainLoop(); </syntaxhighlight>

Run it from the Strawberry Perl terminal:

cd /d C:\wxperl-shop
perl hello-wx.pl

A blank frame titled “The Perl Lazarus Workshop” should appear.

This small program proves several things at once:

• Strawberry Perl is active.
• Wx can be loaded.
• The native wxWidgets libraries can be found.
• A Windows frame can be created.
• The event loop can run.
• The application can close normally.

Do not dismiss the blank window as trivial.

It is the first physical proof that the shop has been raised.

Install and run Wx::Demo

The next verification is broader.

From the Strawberry Perl terminal:

cpanm --verbose Wx::Demo

Then run:

wxperl_demo.pl

Wx::Demo provides working examples of controls and facilities exposed through wxPerl. It is both a verification program and an early reference catalog.

Spend some time opening examples.

Look at:

• buttons and text controls;
• list and tree controls;
• notebooks;
• menus;
• dialogs;
• drawing examples;
• timers;
• and event handling.

The purpose is not to memorize the entire toolkit. It is to understand that wxPerl is larger than the blank frame and that many common interface patterns already have working examples.

If hello-wx.pl runs but Wx::Demo does not, the error is narrower than it would have been without the first test. The core binding works; the problem lies in the additional module, its scripts, or its dependencies.

This is why the craftsman tests in layers.

Install wxGlade

wxGlade supplies the visual portion of the shop. It is written using wxPython, but it can emit Perl source code directly.

wxGlade is a separate application. It is written using Python and wxPython, even though the application being developed will use Perl and wxPerl.

That is not a contradiction.

A tool need not be written in the same language as the work it helps produce.

The tested recipe currently documented at Developing and Distributing wxPerl Applications on Windows uses:

• Python 3.10.11;
• wxPython installed through pip;
• and wxGlade 1.1.1.

Later Python combinations may work, but the living page should be consulted before replacing a tested profile merely because a newer Python release exists.

Install Python 3.10.11 using the link in the maintained instructions. Enable the option to add Python to the Windows PATH.

Open a normal Windows Command Prompt, not the Strawberry Perl terminal, and verify:

where python
python --version
python -m pip --version

Install wxPython:

python -m pip install wxPython

Download and unpack wxGlade 1.1.1. A reasonable location is:

C:\Tools\wxGlade-1.1.1

Change to that directory:

cd /d C:\Tools\wxGlade-1.1.1
python wxglade.py

If the distribution provides wxglade.pyw, it can also be launched without retaining a console window.

Create a small wrapper named:

C:\Tools\wxGlade-1.1.1\start-wxglade.cmd

with:

@echo off
cd /d "C:\Tools\wxGlade-1.1.1"
start "" pythonw wxglade.pyw

Adjust the path and filename to match the actual installation.

A Windows shortcut may then point to start-wxglade.cmd. The change of directory is useful because wxGlade may expect to find supporting files relative to its own directory.

The desktop shortcut is not a mere convenience. A tool used frequently should be easy to start correctly. Requiring the programmer to remember a fragile launch ritual creates needless opportunities for error.

Install MSYS2, vim, and Git

MSYS2 provides a Unix-like terminal and package-management environment for Windows.<ref>MSYS2, “What is MSYS2?”</ref>

Install MSYS2 using its current official installer. Follow the official update procedure, which may require closing and reopening the terminal during a full system update.

Then install vim and Git:

pacman -S vim git

Verify:

vim --version
git --version

If Git will communicate with a remote repository over SSH, create or import the appropriate key and register the public key with the remote service.

A useful optional ~/.vimrc for the author's preferred MSYS2 workflow is:

set mouse=
set noautoindent
set nosmartindent
set nocindent

These are personal workflow choices rather than universal requirements. They make ordinary terminal copying easier and prevent automatic indentation from interfering with pasted or generated blocks.

The critical check is:

which perl
perl -v

Inside MSYS2, the reported Perl may be:

/usr/bin/perl

This is not Strawberry Perl.

That is acceptable because MSYS2 is being used for vim, Git, shell navigation, and source inspection.

Do not use that Perl to run the generated wxPerl application.

Use the Strawberry Perl command-line window for:

perl your-application.pl

and later for:

cpanm
wxpar
pp_autolink
gmake

The following table should remain mentally visible:

Two terminals, two responsibilities

Environment	Use it for	Do not assume
MSYS2	vim, Git, SSH, diffs, shell navigation	That its perl is Strawberry Perl
Strawberry Perl command line	Perl modules, wxPerl execution, application tests, packaging	That Unix paths or MSYS2-specific shell behavior will apply

A craftsman should know which shop he is standing in.

Create the first project directory

Use a simple project for the first complete cycle.

From the MSYS2 terminal:

mkdir -p /c/work/hello-wxperl/screenshots
cd /c/work/hello-wxperl
git init

Create a short README.md:

# Hello wxPerl

First wxGlade-generated wxPerl project created while raising the
Perl Lazarus development shop.

The directory will eventually contain:

hello-wxperl/
├── hello-wxperl.wxg
├── hello-wxperl.pl
├── README.md
└── screenshots/

This is intentionally smaller than the structure of a production application.

The purpose is to prove the cycle before introducing application modules, tests, build directories, installer files, and documentation.

Design the first interface in wxGlade

Open wxGlade.

Create a new application containing:

• one frame;
• one panel;
• one vertical box sizer;
• one static-text control;
• one button.

Use names which communicate purpose:

Object	Suggested name	Label
Frame	MainFrame	The Perl Lazarus Workshop
Static text	status_text	The shop is ready.
Button	hello_button	Test wxPerl

Select the root Application object in the wxGlade object tree.

Set:

• output language to Perl;
• wxWidgets compatibility to 3.0;
• output path to the project Perl file;
• code generation to Single file;
• and Keep user code to enabled.

The important initial wxGlade settings include Perl output and Keep user code. Without code preservation, a later generation may overwrite handwritten work.

Save the wxGlade project as:

C:\work\hello-wxperl\hello-wxperl.wxg

Set the Perl output file to:

C:\work\hello-wxperl\hello-wxperl.pl

Press:

Ctrl-G

to generate the Perl source.

The .wxg file is not the Perl program. It is the XML project describing the visual design.

The .pl file is the code emitted from that design.

Both are valuable source artifacts and both should be kept in Git.

Inspect what wxGlade emitted

Return to the MSYS2 terminal:

cd /c/work/hello-wxperl
ls -l
vim hello-wxperl.pl

Do not immediately begin changing random portions of the generated code.

First inspect:

• the packages wxGlade created;
• the frame constructor;
• the controls;
• the sizers;
• the generated identifiers;
• the event-handler placeholders;
• the application class;
• and the final call to the event loop.

Look for wxGlade's generated-code markers. Their exact form may change among releases, but they identify sections which wxGlade owns and may regenerate.

The Keep user code option is intended to preserve code outside those protected generation blocks.

It is not permission to ignore source control.

Before adding handwritten behavior, commit the generated baseline:

git add hello-wxperl.wxg hello-wxperl.pl README.md
git commit -m "Generate initial wxGlade wxPerl application"

Now there is a recoverable point before the first manual edit.

Run the generated Perl with Strawberry Perl

Open the Strawberry Perl command-line window.

Run:

cd /d C:\work\hello-wxperl
where perl
perl hello-wxperl.pl

The frame should appear with the static text and button.

The button may not yet perform useful work. That is expected.

At this stage the entire visual generation path has been verified:

```text wxGlade .wxg project

       ↓

Perl source emission

       ↓

Strawberry Perl

       ↓

wxPerl / wxWidgets

       ↓

Windows frame