Editing Developing and Distributing wxPerl Applications on Windows

== Update Notes - 3/10/2025! ==
Updates to the information on wxPerl on Strawberry Perl 5.40.0.1 + PDL 2.089.

Also added not on importance of using pp_autolink to find the DLLs for use with wxpar.

== Introduction ==
This article is about installing wxPerl under Strawberry Perl for application development and distribution as a Windows executable.

=== Why Perl GUIs, why Windows? ===
This is a critical ability for any freelance Perl developer, since it compliments a Perl journeyman's ability to do many things on servers, such as create remote services. Being able to transfer these skills to the desktop environment, particularly one that is full of users who are okay with paying for software (i.e., Windows). In short, Perl programmers who want to make a living on their own need to know how to create and distribute Windows GUI applications; this page covers a large piece of how to do that.
[[File:FreeAPIGUI.png|alt=wxPerl GUI running on Windows as a double-clicable EXE file!|thumb|wxPerl GUI running on Windows as a double-clicable EXE file! Created using RAD-ish tool, wxGlade. See [https://github.com/oodler577/FreeAPI-Perl-API-Explorer more images] on Github.]]
Instructions are provided with the versions detailed below. If there are newer versions of any of the modules, you may try it out (of course); but understand they have not been tried out and shown to work like version combinations below.

=== [https://dev.to/sciurius/wxperl-revival-5fde See] the original call for a [https://dev.to/sciurius/wxperl-revival-5fde wxPerl Revivial]! ===

== Installation ==

=== Step 1 - Install Strawberry Perl (5.40.0.1) ===
Install via following link,

<big>https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/download/SP_54001_64bit_UCRT/strawberry-perl-5.40.0.1-64bit.msi</big>

==== Installing Strawberry Perl (5.40.0.1) + PDL (2.089) ====
Note: there might be interest in providing a Windows wxPerl environment that includes the Perl Data Language. See [[Portal:SciTech|notes on creating a Perl environment using Strawberry Perl that includes PDL]]. Once this is set up, the rest of the instructions starting with Step 2 below all work the same!

=== Step 2 - Install Alien::wxWidgets (v 0.70) ===
Once Perl is installed, look in the Start menu for the Perl      "cmd" window or open up PowerShell

* go to "'''Start menu'''" > ''Strawberry Perl'' > "'''Perl (command line)'''"
* click the Start menu item, it'll open up a Windows CMD window (traditional black DOS prompt)

Type the command at the "C:" prompt,

<code><big>C:\> cpanm --verbose <nowiki>https://github.com/sciurius/wxPerl/releases/download/R3.004/Alien-wxWidgets-0.70.tar.gz</nowiki></big></code>

=== Step 3 - Install Wx (v 3.005) ===
<big><code>C:\> cpanm --verbose <nowiki>https://github.com/sciurius/wxPerl/releases/download/R3.005/Wx-3.005.tar.gz</nowiki></code></big>

== Verify Installation ==

=== Install Wx::Demo ===
Wx::Demo is nice demonstration application, highlight many (if not all) of the wxWidget features available via xPerl.

<big><code>C:\> cpanm --verbose Wx::Demo</code></big>

.. then once installed, run it with this command (which is available in the PATH already),

<big><code>C:\> wxperl_demo.pl</code></big>

== wxGlade - a Perl Friendly(cross-platform) GUI Builder ==

=== Trigger Warning: wxGlade is written in wxPython, so you must install it if you want ot use wxGlade to build your GUI. ===
Totally worth it!

=== Install wxGlade ===
[https://sourceforge.net/projects/wxglade/ wxGlade] is a GUI builder for wxWidgets applications. It is written in Python, but critically supports outputing Perl code. It is actively developed, the developer is very responsive on Github to bugs and feature requests. It is the closest thing we have in Perl to a RAD (rapid application development) environment (e.g., [https://www.lazarus-ide.org/ Lazarus] for FreePascal).

=== Step 1 - Install Python 3.12 for Windows ===
Install via following link,

https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe ([https://www.python.org/downloads/windows/ linked here])

'''Notes''':

# Last tested on '''25 Jan 2025''', although later versions of Python 3 were tested (specifically, 3.12.8), wxPython would install but not run wxGlade properly
# install as admin (checkbox should be already checked; also opt'd to add "python" to the PATH)

=== Step 2 - Install wxPython ===

# open up the Windows CMD window
# use pip,

<big><code>C:\> pip install wxPython</code></big>

'''Note''': if this fails, you may need to reinstall pip; but it should be available in the CMD window. Based on experience, pip doesn't seem to be available via the Strawberry Perl terminal, so be sure to get a standard Windows CMD window to do this part.

=== Step 3- Download and unzip wxGlade ===
https://github.com/wxGlade/wxGlade/archive/refs/tags/v1.1.0.zip (may want to also try [https://downloads.sourceforge.net/project/wxglade/wxglade/1.1.0/wxGlade-1.1.0_win_amd64.zip?ts=gAAAAABnlJMXBQlBk2CGz7kaN89RrjqS4GEmSk7spuPtf-gFaK_VqcAQAiFCT24GT-SYsq8SVVmCjmhkzq0VycLd7ofhOQoVlA%3D%3D&r=https%3A%2F%2Fsourceforge.net%2Fprojects%2Fwxglade%2Ffiles%2Fwxglade%2F1.1.0%2FwxGlade-1.1.0_win_amd64.zip%2Fdownload%3Fuse_mirror%3Dphoenixnap%26use_mirror%3Dphoenixnap%26r%3Dhttps%253A%252F%252Fsourceforge.net%252Fprojects%252Fwxglade%252Ffiles%252Fwxglade%252F1.1.0%252F wxGlade-1.1.0_win_amd64.zip] - the difference between the two is unclear, but both are tested and both work.)
[[File:WxgladeWinExample.png|alt=wxGlade running on Windows, showing the design window of a GUI about to be run using wxPerl!|thumb|wxGlade running on Windows, showing the design window of a GUI about to be run using wxPerl!]]
Via Windows CMD terminal, navigate to the unzip'd directory and run the command,

<big><code>C:\> python wxglade.py</code></big>

=== Getting wxGlade Help ===
''wxGlade''<nowiki/>'s developer is responsive on Github and there is a semi-active email list on SourceForge,

* Github repo - https://github.com/wxGlade/wxGlade
* email list - https://sourceforge.net/p/wxglade/mailman/wxglade-general/

== Development Workflow Notes ==
This section outlines some different workflows that are found among members of the community who use wxPerl. Like any workflow, the based on level of experience and particular application.
[[File:Wxperl-workflow.png|alt=Example layout with Strawberry Perl for running the application and Makefile, vim under MSYS2 for more streamlined workflow. wxGlade is under there, too; when there is a change to the GUI, the project is saved and code generated using "ctrl-g". vim is used to edit the code and will update whenever wxGlade updates it, if you do it right your custom code won't get clobbered.|thumb|Example layout with Strawberry Perl for running the application and Makefile, vim under MSYS2 for more streamlined workflow. wxGlade is under there, too; when there is a change to the GUI, the project is saved and code generated using "ctrl-g". vim is used to edit the code and will update whenever wxGlade updates it, if you do it right your custom code won't get clobbered.]]

=== Editor and <code>git</code> Options on Windows ===
The best way to recreate the "edit-run-fix" workflow of code editing enjoyed by vim users is to install [https://www.msys2.org/ MSYS2] and use its terminal to install both <code>vim</code> and <code>git</code>:

<code><big>pacman -S vim git</big></code>

Note: you do not want to run the Perl code generated by wxGlade inside of the MSYS2 terminal. When you install <code>git</code>, it will install its own perl and clobber Strawberry Perl in your <code>PATH</code>. Run the Perl code for your project from a Strawberry Perl terminal.

Just like the editor options in Windows is not ideal, neither are the Git options (GH's "Git for Windows" is exceptionally awkward to use, not sure how to it is possible to be good in "Windows" tbh; YMMV.) Under MSYS2's terminal,  you may install <code>git</code> and use it as you may be accustomed on Linux. You may want to generate an ssh-key, which will be vailable in `~/.ssh/` by default. So you can do all the normal git workflow stuff from there once your key is created and added to your Github keyset.

==== Pro Tip: Turn Off MSYS2's <code>vim</code> Mouse Support ====
I have found that this is required to "copy" text from the MSYS2 <code>vim</code>, you may not need it. But by default <code>vim</code> is aware of the mouse.

To turn it off, issue the command,

<code><big><ESC>set mouse=<ENTER></big></code>

=== Using wxGlade's "Single file" + "''Keep use code''" Options ===
wxGlade has some settings that tells it to not overwrite changes you made in the output Perl script, but '''beware''' - this option is not on by default. That means that means that your file will get overwritten if you tell wxGlade to generated new code again. The general workflow is as follows:

# start a new project (or open an existing one)
# click on the root "Application" object in the object viewer
# find the output pane, set the output to be "'''Perl'''"
# set version of wxWidgets to be "'''3.0'''"
# [[File:Applicationsettings.png|alt=Recommended settings for using wxGlade for Perl development.|thumb|Recommended settings for using wxGlade for Perl development.]]check "Keep user code", this will make sure wxGlade doesn't over write code that is outside the bounds of very clearly marked blocks in the code

=== Using wxGlade's "''Seperate file for each class''" Option ===
... to do

== Creating Windows EXEs ==
This section is more of a work in progress since a reliable method of distributing single file executables (or developing installation packages for Windows) is still an open question, there is hope that this will end up being a relatively smooth process. Needless to say, it is critical for Perl developer to be able to distribute Perl based GUI applications as single file (.exe) or via installation on Windows. The client should NOT need to be running through any of the instructions above to run a program that you would like to sell them for actual money.

Below are the initial instructions for generating an EXE file. There are also many ways that wxPerl developers go about doing, based on their use case and experience.

=== PAR::Package, App::PP::Autolink, and WX::Perl::Packager ===

==== Step 1 - Install PAR::Package, App::PP::Autolink, and Wx::Perl::Packager ====
<code><big>C:\> cpanm --verbose PAR::Package App::PP::Autolink Wx::Perl::Packager</big></code>

'''Note''': <code>pp_autolink</code>, provided by <code>App::PP::Autolink</code> has proven to be absolutely critical to finding the required DLLs that need to be added manually to the <code>wxpar</code> command below via the <code>--link</code> flag.

==== Step 2 - Generate the EXE ====
Assuming you have a Perl script generated either via wxGlade (see above) or one you have created/updated by hand, the command is as follows:

<code><big>C:\> wxpar YOURPROGRAM.pl -o YOURPROGRAM.exe</big></code>

===== Important Notes About wxGlade Generated Code =====
# earlier versions of wxGlade introduced an improper idiom at the bottom of the generated Perl script that caused a problem when running via a PAR::Packed packed executable. TLDR; remove the "unless(caller)" block and just run the Wx event loop unfettered. For more information, please read the [https://metacpan.org/dist/PAR/view/lib/PAR/FAQ.pod#If-I-try-to-compile-my-wxGlade-generated-script%2C-it-doesn%27t-run.-What%27s-wrong%3F PAR::FAQ.]
# earlier versions of wxGlade also used a non-Exporter import tage that wxpar could not properly follow; see the code "before" and "after" below:

 use Wx qw[:allclasses];
 use strict;
 
 ...
 
 package main;
 
 unless(caller){
     my $local = Wx::Locale->new("English", "en", "en"); # replace with ??
     $local->AddCatalog("app"); # replace with the appropriate catalog name
 
     my $app = MyApp->new();
     $app->MainLoop();
 }
Should be modified to look like the following:
 use Wx;
 use strict;
 
 ...
 
 package main;
 
 my $local = Wx::Locale->new("English", "en", "en"); # replace with ??
 $local->AddCatalog("app"); # replace with the appropriate catalog name
 
 my $app = MyApp->new();
 $app->MainLoop();
See [https://github.com/wxGlade/wxGlade/issues/568 this Github issue] for wxGlade, where both were fixed. At the time of this writing, the changes. have not been put out in an official release; but they are applied in the master branch.

==== Special Cases ====

===== <code>Makefile</code> for an Application uses HTTP::Tiny and calls out to SSL-enabled sites =====
Example - [https://github.com/StormSurgeLive/nhc-advisory-gui/blob/master/asgs-storm-bug.pl https://github.com/StormSurgeLive/nhc-advisory-gui/l]

(copied from the [https://github.com/StormSurgeLive/nhc-advisory-gui/blob/master/Makefile Makefile]) - Note, mentions using [https://metacpan.org/pod/App::PP::Autolink App::PP::Autolink] to sus out required DLLs (provides <code>pp_autolink</code>, which helped!)

  all:
          wxpar --verbose -o ./dist/nhc-explorer.exe -l c:/strawberry/c/bin/libcrypto-3-x64__.dll -l c:/strawberry/c/bin/zlib1__.dll -l c:/strawberry/c/bin/libssl-3-x64__.dll ./asgs-storm-bug.pl --gui
          wxpar --verbose -o ./dist/DEBUG-nhc-explorer.exe -l c:/strawberry/c/bin/libcrypto-3-x64__.dll -l c:/strawberry/c/bin/zlib1__.dll -l c:/strawberry/c/bin/libssl-3-x64__.dll ./asgs-storm-bug.pl
  
 # It was an adventure finding all the dependencies related to the wxpar command,
 # particularly those around what was needed, the basic process entailed:
 # 1. use wxpar, which generates an options files with all the Wx DLLs
 # 2. installed, App::PP::Autolink, which provides the utility "pp_autolink"; this
 #    utility scans the .pl file you're packing (in this case, "asgs-storm-bug.pl,")
 #    for DLLs - lo' and behold, it found the ones I needed; in particular the critical
 #    one that was not getting picked up by pp or wxpar, "libcrypto-3-x64___.dll!"
 # 3. ran the "wxpar" command above
 # 4. tested in a non-Strawberry Perl window (MSYS2 terminal) using the command,
 #
 #      PERL_DL_DEBUG=5 dist/nhc-explorer.exe
 #
 #    I learned about this command while searching, here:
 #
 #      https://stackoverflow.com/questions/423330/why-cant-dynaloader-pm-load-ssleay-dll-for-netssleay-and-cryptssleay
 #

==== Important Note About Finding all DLLs ====
It is worth repeating that <code>pp_autolink</code>, provided by <code>App::PP::Autolink</code> has proven to be absolutely ''critical'' to finding the required DLLs that need to be added manually to the <code>wxpar</code> command below via the <code>--link</code> flag.

If you are having problems finding all the DLLs (some which may not be obvious until the EXE generated is tried on a different machine,) you need to give <code>pp_autolink</code> a shot.

=== PPL (portable Perl loader) ===
... to fill in (Johan?)

== Creating Installers for Windows EXEs ==
Professional Windows programs are expected to provide installers. This section will be developed as I figure out how to do this. A few notes:

* Strawberry Perl itself uses '''[https://wixtoolset.org/ WiX Toolset]''' (Windows Installer XML Toolset) to generate its MSI installer (see [https://github.com/StrawberryPerl/Perl-Dist-Strawberry/blob/master/share/msi/MSI_main-v2.wxs.tt here])
* '''[https://nsis.sourceforge.io/Main_Page NSIS]''' (Nullsoft Scriptable Install System) is another option - ([https://nsis.sourceforge.io/Category:Tutorials tutorials], [https://nsis.sourceforge.io/Category:Code_Examples examples], [https://nsis.sourceforge.io/Screenshots screenshots]) - it also has its own IDE for visually designing installers! [https://nsis.sourceforge.io/NSIS_Dialog_Designer See more here].
* A possible "old school" approach, may be to use Office'97 Office Developer Edition (ODE) - via Access'97 there is an installer builder - this is a last resort and still needs to be verified to work for non-Access distributions
* [https://jrsoftware.org/isinfo.php Inno Setup] ([https://github.com/jrsoftware/issrc github]) - ''Inno Setup is a free installer for Windows programs by Jordan Russell and Martijn Laan. First introduced in 1997, Inno Setup today rivals and even surpasses many commercial installers in feature set and stability.''
* [https://www.revenera.com/install/products/installshield InstallShield] (commercial - software monetization services)

== Underdeveloped Sections ==
The following sections are "works in progress," and remain open questions (for this author anyway). Contributions to develop these sections are greatly appreciated, but not expected. Over time I will update these sections as I learn more about using wxGlade and Perl on Windows.

=== Distributing EXEs to other Windows Machines ===
While wxpar does indeed create EXEs that can run on Windows machines that do not otherwise have any required libraries on them, I have found some early problems that are most likely due to lack of experience in this area. An understanding of this area is forthcoming.

=== Maintaining Perl Applications using XRC ===
[https://docs.wxwidgets.org/latest/overview_xrc.html XRC] is a language agnostic and XML based way of describing the GUI layout for wxWidgets. It appears to be the right way to maintain the GUI layout of your production grade program, while maintaining the set of Perl handlers in your own source tree. Think of XRC as the separation of the controller and view in MVC - it to GUI programming what templates are to web application programming. It seems that as one advances his skills in this area, he will want to use XRC. The benefit also of this is that one may be able to create controllers in multiple languages rather than tie the GUI construction in Perl or some other language exclusive - of course, wxGlade can output in different languages, but none is as abstract as XRC.
[[File:Xrc.png|alt=Wx::Demo example of loading an XRC file; wxGlade can output directly to XRC, which can then be read in Perl. This is how.|thumb|Wx::Demo example of loading an XRC file; wxGlade can output directly to XRC, which can then be read in Perl. [https://metacpan.org/release/MDOOTSON/Wx-Demo-0.22/source/lib/Wx/DemoModules/wxXrc.pm This] is how.]]
Wx::Demo has a few [https://metacpan.org/release/MDOOTSON/Wx-Demo-0.22/source/lib/Wx/DemoModules/wxXrc.pm good examples] of running XRX applications; wxGlade can output XRC, but it is not aware of any language bindings or drivers for it.

Experience with managing XRC files may allow us as Perl programmers to use RAD tools and GUI builders that were not intended to support wxPerl, but can output XRC files. [http://www.anthemion.co.uk/dialogblocks/download.htm DialogBlocks] is such a professional and commercial GUI builder for wxWidgets, and it is actively maintained.

=== Frequently Asked Questions ===
Nobody actually asks contacts me to ask these questions, but they seem to be important.

==== Q: Can these wxPerl applications using Strawberry Perl make ''https'' requests? ====
A: Yes! Strawberry Perl comes with HTTP::Tiny (a core Perl module) and Net::SSLeay (used by HTTP::Tiny for https requests).

== Additional Resources ==

=== Printed Books ===
[[File:Wxbook.jpg|alt=This great, but out of print wxWidgets book is available for free (PDF) at https://wxwidgets.org/docs/book/. It mentions wxPerl and has an index of tools and programs that any wxWidgets programmer may find interest.|thumb|This great, but out of print wxWidgets book is available for free (PDF) at https://wxwidgets.org/docs/book/. It mentions wxPerl and has an index of tools and programs that any wxWidgets programmer may find interest.]]
'''Cross-Platform GUI programming with wxWidgets''' ([https://wxwidgets.org/docs/book/ free PDF!!]) by Julian Smart and Kevin Hock (with Stefan Csomor) is an old, but nice resource to have. It mentions wxPerl quite a bit and has a nice index of tools to help the wxWidgets GUI programmer, regardless of the language they are using. In particular, "Appendix E: Third-Party Tools for wxWidgets" is a very interesting read.

=== Longer List of RAD Tools and GUI Builders* ===


* [[Developing and Distributing wxPerl Applications on Windows#wxGlade - a Perl Friendly(cross-platform) GUI Builder|wxGlade]] (''Latest at this time'', '''Version 1.1.0, July 7, 2024''')
* [https://web.archive.org/web/20131020024033/http://www.wxdesigner-software.de/download.html wxDesigner] (''Latest at this time'', '''2.14 - wxWidgets 2.8.8/ 2.20a - wxidgets pre-3.0, May 2009''')
** outputs Perl code
** archived but a trial is downloadable [[https://web.archive.org/web/20131020024033/http://www.wxdesigner-software.de/download.html here]] (archive.org)
** Reliable contact for license: ''undetermined at this time''
* [http://www.anthemion.co.uk/dialogblocks/download.htm DialogBlocks] -  '''('''''Latest at this time'', '''Version 5.18, August 21st, 2024)'''
** can export C++, XRC, which wxGlade should be able to import
** No Perl export (see XRC)
** Cross Platform (Windows, Mac, Linux)
** Registration required, but support is discontinued - email support@anthemion.co.uk, they may just give you a free key if you are nice :-)

''*You may want to also check this duplicated internal [[Portal:Software Development Tools#wxPerl (wxWidgets wrapper)|page]].''