Docs: How to compile to a standalone single file with Nuitka

[laundmo]

I have recently attempted, and after some effort managed, to compile a python ahk script to a standalone single file exe using nuitka.

Heres the process:

• Install nuitka
• Copy your AutoHotkey.exe into the same folder as your script
• Use this code block to create your AHK instance, since when compiling to a single file with nuitka the path needs to be specified relative to __file__

  from ahk import AHK
  from pathlib import Path
  
  AHK_EXE = Path(__file__).parent / "AutoHotkey.exe"
  ahk = AHK(executable_path=str(AHK_EXE))

• compile to a single file nuitka exe with the following command

  py -m nuitka --include-data-file=AutoHotkey.exe=./AutoHotkey.exe --include-package-data=ahk --onefile --standalone script.py

  --include-data-file will include the ahk exe in the single file app, and --include-package-data is required to include all the templates that this library uses.

I thought this might be interesting to document, since one of the best features of auto hotkey is IMO that it compiles to a standalone exe that i can share. I wasn't sure whether this is documentation that is wanted, or in what form/where, hence the issue and not a PR.

[spyoungtech]

Thanks for this! I agree ability to compile to standalone executables is a key feature that users are looking for.

After we get to a 1.0 release I'll work to document (and add automated testing) how to compile to a standalone exe for at least one tool (probably pyinstaller at first, then maybe nuitka shortly thereafter).

Before 1.0, the implementation details around the AHK code template files is likely to change somewhat and may impact instructions for bundling ahk, so my thought was to avoid writing too much documentation around this just yet :-)

Until then, this issue can stand as a good reference points for users trying to use nuitka with AHK. #46 has some discussion around pyinstaller.

[laundmo]

hm, i don't really know whether template changes could cause any issues, since Nuitka auto-discovers the templates based on package name. so unless they are moved outside the libraries install directory, it should continue working.

Another thing to consider for the 1.0 release is asking the Nuitka devs about adding ahk include files to Nuitka directly, they already do this for common libraries like NumPy and Tkinter.

[spyoungtech]

Another thing to consider for the 1.0 release is asking the Nuitka devs about adding ahk include files to Nuitka directly, they already do this for common libraries like NumPy and Tkinter.

Do you mean for the AutoHotkey.exe file? I'm not familiar with Nuitka, but this library is certainly not as popular as numpy/tk and I'm not sure if we could reasonably warrant the attention of the Nuitka developers :)

There is also the ahk-binary package (can be installed as an 'extra': pip install "ahk[binary]"), which serves the purpose of providing that file when installed (to a location where it should be on PATH, if pip is also on PATH).

I'm wondering if that were used, maybe users of Nuitka can add something like --include-package-data ahk-binary and perhaps that would do the trick and avoid the step to copy AutoHotkey.exe.
It might also remove the need to provide executable_path -- ahk-binary normally adds AutoHotkey.exe to the <python-install>\Scripts directory, making it available on PATH, so ahk finds it automatically with shutil.which. But I'm actually not sure if this works in practice with an app bundled with Nuitka.

[laundmo]

Do you mean for the AutoHotkey.exe file?

i was more thinking about the template files, the ahk.exe is a bit much to ask, so compiling with just the templates would mean scripts would run on systems where ahk is installed.

There is also the ahk-binary package

i wasn't aware of this, gonna make a note to test this once i have some time.

But I'm actually not sure if this works in practice with an app bundled with Nuitka.

yeah, i would think not, since nuitka unpacks dependencies to the temp folder, so this library likely wont be able to find the file.

[spyoungtech]

v1 now includes better support for freezing. Missing template issues are now resolved by falling back to string constants with the template content. So that should no longer be a concern for compiling.

So, the only thing you need to ensure is that either (1) the target machine has AHK available (on PATH or in a standard location) or (2) that your frozen bundle includes the autohotkey executable and you set executable_path accordingly.

[hiroshi-ya]

I used to use pyinstaller to pack the py into exe, and then use enigma virtual box (free to use but closed source, so not that free) to pack the py-exe and the ahk binary alongside other resource files like images. Not very elegant, but if you don't want to deal with the resource_path and relative_path shenanigans, enigma virtual box saves some hassle. I guess Nuitka is a more elegant solution.

[spyoungtech]

For what it's worth, I have a small project using ahk that is packaged into an executable using PyInstaller and creates a Windows setup file as well using InnoSetup. I distribute it both as a zip and setup executable. The project is available here and the build/release process is entirely automated in GitHub Actions.

I used this video tutotial to learn how to do most of the setup with InnoSetup. Getting the paths of extra resource files (which is a part of my other project, not necessarily a requirement for freezing ahk) correct in the code to work both frozen and unfrozen was the hardest part. I think mostly due to some changes in recent versions of PyInstaller.

This is what I had to do to correctly refer to a file that was alongside the script running this code becuase PyInstaller creates a _internal folder when bundling:

if getattr(sys, 'frozen', False):
    _DEFAULT_CONFIG_FILE = pathlib.Path(sys.executable).parent / '_internal' / 'config.toml'
else:
    _DEFAULT_CONFIG_FILE = pathlib.Path(__file__).parent / 'config.toml'

I may create a guide on this at some point in the future, but since this package no longer necessarily relies on its data files, freezing with any tool should be straightforward by following the documentation of your preferred tool.

If you want to package the AutoHotkey executable with your program, that may be the hardest part. But keep in mind the GPL license requirements of AutoHotkey (and any other software you're bundling) if you're going to redistribute it with your application.