Win32::Exe(3pm)

💖 Win32::Exe — the manual, but make it cute 💖

okay bestie, gather round, because we're talking about Win32::Exe — the Perl module that lets you poke at Win32 executable files and make them do what you want. no cap, this thing is powerful. let's get into it 🫶

---

✨ VERSION ✨

this doc describes version 0.17 of Win32::Exe, released July 19, 2011. vintage but iconic, honestly 💅

---

✨ SYNOPSIS ✨

here's the vibe, in code:

use Win32::Exe;
my $exe = Win32::Exe->new('c:/windows/notepad.exe');

# add a default resource structure if none exists
# create_resource_section only works on MSWin and
# does not work on Windows XP - requires Vista or
# above

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

# Get version information
my $info = $exe->get_version_info;
print qq($_ = $info->{$_}\n) for (sort keys(%$info));

# Extract icons from an executable
my @iconnames = $exe->get_group_icon_names;
for ( my $i = 0; $i < @iconnames; $i++ ) {
    my $filename = 'icon' . $i . '.ico';
    my $iconname = $iconnames[$i];
    $exe->extract_group_icon($iconname,$filename);
}

# Import icons from a .exe or .ico file and write back the file
$exe->update( icon => '/c/windows/taskman.exe' );
$exe->update( icon => 'myicon.ico' );

# Change it to a console application, then save to another .exe
$exe->set_subsystem_console;
$exe->write('c:/windows/another.exe');

# Add a manifest section
$exe->update( manifest => $mymanifestxml );
# or a default
$exe->update( defaultmanifest => 1 );

# or specify manifest args
$exe->update( manifestargs => { ExecLevel => 'requireAdministrator' } );

# Get manifest object
$manifest = $exe->get_manifest if $exe->has_manifest;

# change execution level
$manifest->set_execution_level('requireAdministrator');
$exe->set_manifest($manifest);
$exe->write;

like, look at all that. we're out here editing executables. main character energy fr 🌟

---

✨ DESCRIPTION ✨

so this module parses and manipulates Win32 PE/COFF executable headers — that's version information, icons, manifest, and other resources, all of it. and when it comes to manifest handling specifically, the module Win32::Exe::Manifest is the one you wanna hang with.

there's also a script called exe_update.pl provided, for when you just wanna do simple file updates. convenient, slay.

also also — please go look at the test files in the source distribution's t/ directory, because there are examples of using this module in there. genuinely the best place to learn by osmosis. 🦋

---

✨ METHODS ✨

🌸 new

my $exe = Win32::Exe->new($filename);

makes you a Win32::Exe object out of $filename. and bestie, $filename can be an executable or a DLL. either one, we don't discriminate 💜

🌸 update

$exe->update( icon         => 'c:/my/icon.ico',
              gui          => 1,
              info         => [ 'FileDescription=My File', 'FileVersion=1.4.3.3567' ],
              manifest     => 'c:/my/manifest.xml',
              manifestargs => [ 'ExecLevel=asInvoker', 'CommonControls=1' ],
              );

update is the convenience method for the most common actions — it's giving "one stop shop" and we're obsessed. it writes the info you hand it into the file that was opened by Win32::Exe->new($filename). and here's the nice part: you do not have to call $exe->write — the method automatically updates the opened file. no extra steps, periodt ✨

param detail, one by one:

• icon — pass the name of an executable, dll or ico file, and it extracts the icon and makes it the main icon for the Win32 executable.
• info — pass a reference to an array of strings containing key - value pairs separated by '='. e.g. info => [ 'FileDescription=My File', 'FileVersion=1.4.3.3567' ]

recognised keys are:

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

• gui or console — use parameter 'gui' or 'console' to set the executable subsystem to Windows or Console. and yeah, you can only use one or the other of gui / console, not both. pick a lane bestie 😌
• manifest — specify a manifest file to add to the executable resources.
• manifestargs — as an alternative to specifying a manifest file, pass a reference to an array of strings containing key - value pairs separated by '='.

e.g. manifestargs => [ 'ExecLevel=asInvoker', 'CommonControls=1' ]

recognised keys are:

ExecutionLevel  UIAccess     ExecName   Description
CommonControls  Version

🌸 create_resource_section

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

if an executable file doesn't have an existing resource section, you must create one before you even think about adding version, icon or manifest resources. so real.

here's the tea though: create_resource_section is only available on MSWin platforms. and on top of that, the method will fail if your windows version is Windows XP or below. 💀 you can check whether it's even possible to call create_resource_section by calling $exe->can_create_resource_section.

after you call create_resource_section, the original Win32::Exe object does not reference the updated data. so the method returns a reference to a new Win32::Exe object that references the updated data. that's why you always call it like this:

$exe = $exe->create_resource_section if
$exe->can_create_resource_section;

and good news: if $exe already has a resource section, this call will safely return a reference to the original object without updating the original exe. no damage done, we love a safe no-op 🎀

🌸 can_create_resource_section

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

checks if the operating system and version actually allow addition of a resource section when none exists in the target executable. vibe check for your OS 🫶

🌸 get_manifest

my $manifest = $exe->get_manifest;

retrieves a Win32::Exe::Manifest object. (see the docs for Win32::Exe::Manifest — they're right there, go read 'em 💖)

🌸 set_manifest

$exe->set_manifest($manifest);
$exe->write;

takes a Win32::Exe::Manifest object. heads up: you must explicitly call 'write' to commit the changes to file. it also takes a filepath to an xml file containing raw manifest information. flexible icon 💅

🌸 set_manifest_args

$exe->set_manifest_args($argref);
$exe->write;

accepts a reference to a hash with one or more of the keys:

ExecutionLevel  UIAccess     ExecName   Description
CommonControls  Version

also accepts a reference to an array of strings of the format:

[ 'key1=value1', 'key2=value2' ]

example values:

ExecutionLevel=asInvoker
UIAccess=false
CommonControls=1
Version=6.8.67.334534
ExecName=My.Application
Description=My Application

and the CommonControls argument can be specified to add a dependency on Common Controls Library version 6.0.0.0. fancy ✨

🌸 get_version_info

my $inforef = $exe->get_version_info;

returns a reference to a hash with the keys:

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

🌸 set_version_info

$exe->set_version_info($inforef);
$exe->write;

accepts a reference to a hash with one or more of the keys:

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

also accepts a reference to an array of strings of the format:

[ 'key1=value1', 'key2=value2' ]

🌸 set_subsystem_windows

$exe->set_subsystem_windows;
$exe->write;

sets the executable system as 'windows' (GUI). you may also call $exe->SetSubsystem('windows); — and this is the equivalent of $exe->update( gui => 1);

🌸 set_subsystem_console

$exe->set_subsystem_console;
$exe->write;

sets the executable system as 'console'. you may also call $exe->SetSubsystem('console); — and this is the equivalent of $exe->update( console => 1);

🌸 get_subsystem

my $subsys = $exe->get_subsystem;

returns a descriptive string for the subsystem. possible values: windows | console | posix | windowsce | native

and fr fr — you can usefully update executables with the windows or console subsystem. the others are just there vibing 🌈

🌸 set_single_group_icon

$exe->set_single_group_icon($iconfile);
$exe->write;

accepts the path to an icon file. replaces all the icons in the exec with the icons from the file. all of them. it's giving clean slate 💅

🌸 get_group_icon_names

my @iconnames = $exe->get_group_icon_names;

returns a list of the names of all the group icons in the executable or dll. if there are no group icons, it returns an empty list — no drama, just emptiness 🍓

the names returned can be used as parameters to other icon handling methods. so remember them, they're your keys 🔑

🌸 get_group_icon

$exe->get_group_icon($groupiconname);

accepts a group icon name as returned by get_group_icon_names. returns the Wx::Exe::Resource::GroupIcon object for the named GroupIcon. (yes, spelled exactly like that in the original, we don't make the rules 😭)

🌸 add_group_icon

$exe->add_group_icon($groupiconname, $iconfilepath);
$exe->write;

accepts a group icon name and a path to an icon file. adds the icon to the exec without affecting existing icons. the group icon name must not already exist — so don't try to reuse a name, it's not that kind of party 🙈

🌸 replace_group_icon

$exe->replace_group_icon($groupiconname, $iconfilepath);
$exe->write;

accepts a group icon name and a path to an icon file. replaces the groupicon named with the contents of the icon file. out with the old, in with the new ✨

🌸 remove_group_icon

$exe->remove_group_icon($groupiconname);
$exe->write;

accepts a group icon name. removes the group icon with that name from the exec or dll. bye bestie 👋

🌸 export_group_icon

$exe->export_group_icon($groupiconname, $iconfilepath);

accepts a group icon name and a .ico filepath. writes the named icon group to the file in filepath. icon liberation, we love to see it 🕊️

---

✨ AUTHORS ✨

the legends behind this:

• Audrey Tang <cpan@audreyt.org>
• Mark Dootson <mdootson@cpan.org>
• Steffen Mueller <smueller@cpan.org>

---

✨ COPYRIGHT ✨

Copyright 2004-2007, 2010 by Audrey Tang <cpan@audreyt.org>.

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

see <http://www.perl.com/perl/misc/Artistic.html>

---

and that's the whole page, bestie — go forth and manipulate some executables responsibly 💖✨

okay one last cute sign-off: this page came to you from perl v5.34.0, dated 2022-08-14, and it lives under the name Win32::Exe(3pm). stay slay, stay compiling 🎀👑