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:

wxGlade .wxg project
        ↓
Perl source emission
        ↓
Strawberry Perl
        ↓
wxPerl / wxWidgets
        ↓
Windows frame

If the generated program does not run, do not begin installing PAR or building an executable.

The source application must work first.

Read the error from the Strawberry terminal. Confirm that the active Perl is correct. Compare the generated application with the hand-written hello-wx.pl which already worked.

The proven lower layer is a diagnostic advantage.

Wire the first event

Return to wxGlade and select the button.

Assign its button-click event to a handler named:

on_hello

Save the project and press Ctrl-G again.

Return to vim. Allow vim to reload the changed file if it detects that wxGlade has modified it.

Locate the generated on_hello handler. Add behavior only in the user-preserved area intended for the handler:

<syntaxhighlight lang="perl"> sub on_hello {

   my ($self, $event) = @_;

   Wx::MessageBox(
       'Your wxPerl shop is working.',
       'Perl Lazarus Project',
       Wx::wxOK(),
       $self,
   );

} </syntaxhighlight>

The exact generated function signature or location may vary with the wxGlade release and project structure. Preserve the structure emitted by wxGlade and add the application behavior to the appropriate handler.

Save the file.

Run it again from Strawberry Perl:

perl hello-wxperl.pl

Click the button.

A message box should appear.

The shop now supports the complete elementary cycle:

• visual design;
• Perl generation;
• manual wiring;
• execution;
• and user interaction.

Commit the result:

git add hello-wxperl.wxg hello-wxperl.pl
git commit -m "Wire first wxPerl button event"

Practice the edit–emit–wire–run cycle

A practical working arrangement: wxGlade emits Perl, vim under MSYS2 inspects and edits it, and the Strawberry Perl terminal runs the application.

Make one further visual change:

• change the frame title;
• add another label;
• alter the button text;
• or adjust the spacing.

Before generating, check Git:

git status

Commit or stash any unfinished handwritten work.

Generate again with Ctrl-G.

Inspect the diff:

git diff

Confirm that the handler remains present.

Run the application with Strawberry Perl.

Then commit the visual revision.

This cycle should become habitual:

Design in wxGlade
        ↓
Save the .wxg project
        ↓
Generate Perl with Ctrl-G
        ↓
Inspect the diff in MSYS2
        ↓
Wire or revise behavior in vim
        ↓
Run with Strawberry Perl
        ↓
Test the actual user action
        ↓
Commit the known-good result

Generated code should never become an excuse to stop reading code.

The craftsman should know what changed.

Using AI without surrendering the craft

AI can be effective at two points in this workflow.

First, it can prepare a first-draft wxGlade XML project from a plain-language description.

Second, it can assist with the Perl wiring which connects generated controls to application behavior.

The wxPerl and wxGlade template repository demonstrates this possibility. Its GUI templates were initially created with ChatGPT and then used as wxGlade projects and Perl examples.

A productive AI-assisted cycle is:

1. Describe the intended window and controls.
2. Ask for a wxGlade-compatible .wxg draft.
3. Save the XML to a file.
4. Open it in wxGlade.
5. Correct invalid properties, names, nesting, and layout.
6. Save it through wxGlade.
7. Emit Perl.
8. Run the generated application.
9. Ask for assistance wiring a named event.
10. Review every change.
11. Test the user action.
12. Commit only the result which has actually been verified.

A useful prompt might specify:

Create a first-draft wxGlade 1.1.1 XML project for a wxWidgets 3.0
application. The output language will be Perl. Include one frame,
a panel, a vertical box sizer, a status label, and a button named
hello_button. The button event handler should be named on_hello.

The AI-generated file is not authoritative merely because it is well formed.

wxGlade is the first practical judge of whether the XML describes a valid project. The generated Perl and the running application provide further tests. The craftsman provides the final judgment.

God is the source of human intelligence and talent. AI is a human-made tool assembled from created materials, accumulated knowledge, infrastructure, and labor. It is not a person, an apprentice, a master, or a moral agent.

It can assist the work.

It cannot accept responsibility for it.

Troubleshoot in the order the shop was built

When the project fails, resist the temptation to change everything at once.

Use this order:

1. Confirm the active Perl

In the Strawberry command window:

where perl
perl -v

In MSYS2:

which perl
perl -v

Know which result belongs to which environment.

2. Confirm the modules

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

3. Run the hand-written frame

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

If this fails, the problem is beneath wxGlade.

4. Run Wx::Demo

wxperl_demo.pl

This provides a broader binding test.

5. Run the generated program

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

Read the first meaningful error rather than only the last line.

6. Inspect the most recent generation

From MSYS2:

git diff
git status

Check whether handwritten code disappeared or a generated block changed unexpectedly.

7. Return to the last known-good commit

Do not destroy evidence in panic. Create a branch or preserve the broken state before reverting.

8. Change one layer at a time

Do not simultaneously update Strawberry Perl, wxPerl, Python, wxGlade, and MSYS2 while investigating one failure.

A workshop can be repaired only when the craftsman knows what changed.

The craft and the virtue

This stage of the journey requires spiritedness, or fortitude, rather than impatience.

Installation work is often wearying because the visible reward comes late. The programmer may spend considerable time reading compiler output, comparing paths, waiting for native builds, and discovering that one command was executed from the wrong terminal.

Impatience responds by changing versions randomly, rerunning commands without reading their output, disabling safeguards, or abandoning the whole effort as soon as the first path fails.

Fortitude does not mean mindless repetition.

It means remaining with a worthy difficulty long enough to understand it.

“And if a man love justice: her labours have great virtues; for she teacheth temperance, and prudence, and justice, and fortitude.”
— Wisdom 8:7, Douay-Rheims

The craftsman begins with gratitude.

The world in which he works was created by God. His intelligence, memory, patience, opportunity, and capacity to learn are gifts. The compiler, language, GUI library, editor, examples, documentation, and operating system also contain the labor and talents of other persons.

Raising the shop is therefore an exercise in stewardship.

The programmer receives tools and knowledge, develops his own abilities, and prepares himself to perform work for others.

A failure does not diminish the programmer's God-given dignity. A successful installation does not make him superior to the apprentice who is still learning. Technical progress measures the present state of the work, not the worth of the worker.

Fortitude allows the programmer to admit:

• “I used the wrong Perl.”
• “I do not yet understand this generated block.”
• “The experimental profile has not been verified.”
• “I need to return to the documented version.”
• “My AI-generated XML is invalid.”
• “I overwrote my code because I failed to enable the correct setting.”
• “I need help from another craftsman.”

These admissions are not defeats.

They are acts of truth.

The shop becomes dependable when the craftsman prefers truth over appearance: a real test over an assumption, a saved log over memory, a Git diff over confidence, and a known working profile over the prestige of using the newest release.

The purpose is not to boast that wxPerl can display a window.

The purpose is to prepare a place in which useful software can be built faithfully and brought to completion.

At the workbench: the first-shop checkpoint

Before proceeding, confirm that all of the following exist:

Check	Evidence
Strawberry Perl is active	Saved output from where perl and perl -v
Native build tools exist	gcc and gmake are found
Alien::wxWidgets loads	Version command succeeds
Wx loads	Version command succeeds
A hand-written frame runs	hello-wx.pl opens and closes
Wx::Demo runs	Demonstration controls can be opened
wxGlade runs	The application launches through a repeatable shortcut or command
wxGlade emits Perl	hello-wxperl.pl exists
The generated application runs	The frame appears under Strawberry Perl
An event is wired	The button displays a message
MSYS2 contains vim and Git	Both version commands succeed
The two Perl environments are understood	which perl and where perl have been compared
The project is preserved	At least two meaningful Git commits exist
The process is documented	wxperl-environment.txt and logs exist

Also preserve:

• the .wxg project;
• the emitted Perl;
• the hand-written verification program;
• one screenshot of the running application;
• the installation logs;
• and the project history.

The result is modest, but it is real.

The programmer now possesses a working Windows wxPerl shop.

Continue the journey

The next essay, From wxGlade Layout to Working Perl Application, will move beyond the demonstration project.

It will examine:

• how wxGlade-generated Perl is organized;
• which parts of the source belong to the generator;
• how controls should be named;
• how events should be assigned;
• how business logic can be kept outside the GUI;
• how repeated regeneration can remain safe;
• when separate generated classes or XRC may become useful;
• and how a graphical prototype becomes a maintainable Perl application.

The shop has been raised.

The next task is to practice the craft within it.

<references />

Previous essay: The Perl Lazarus Workshop

Series: Essays about The Virtuous Perl Programmer

Next essay: From wxGlade Layout to Working Perl Application