Improve PyInstaller Hook and it's documentation

[SirGnip]

Document how to create a self-contained .exe for arcade apps.

I've done some experimentation and have been able to build a redistributable, self-contained single .exe with this command:

pyinstaller src\myapp.py --add-binary "venv\Lib\site-packages\pymunk\chipmunk.dll;." --add-binary "venv\Lib\site-packages\arcade\soloud\soloud*.dll;.\arcade\soloud" --add-data "venv\Lib\site-packages\arcade\resources;.\arcade\resources" --windowed --onefile

I'll write up a "how to package your game to distribute..." doc and add it under the "Tutorial" section of: https://arcade.academy/.

Note: this requires Pymunk 5.7.0 (released a couple days ago) to work properly. I chimed in on a Pymunk issue dealing with better pyinstaller support. A fix got merged and released with 5.7.0 which makes the pyinstaller command above possible. There were issues surrounding Pymunks handling of chipmunk.dll.

Also looking to add a basic pyinstaller call to build.bat so that it is executed as a part of the Travis CI run (resulting .exe will not be used for anything). This will alert us when anything is changed in the repo that breaks compatibility with pyinstaller.

• create functional Windows-centric PyInstaller hook file
• add a couple notes for Arcade developers about how to locally edit and test PyInstaller hook files
• write a "how do I package up my game so I can distribute it easily?" tutorial for users
• add a section to tutorial that explains how to package up resource files with PyInstaller and make sure your code can read them
• do a PyInstaller run in .travis.yaml for CI
• make hook file work for mac and linux (I can't do this as I don't have the hardware)
• do some better testing to make sure there are no assumptions about current working directory, resource directories used by the game, etc.

[SirGnip]

Discussion of packaging in arcade's past: https://github.com/pythonarcade/arcade/issues?q=is%3Aissue+pyinstaller

[einarf]

Would be awesome to get a contribution related to this. I think the three active people developing already have way too much on their list already 😄

[eruvanos]

This is my spec file to ship my game:

import pymunk
from PyInstaller.building.api import PYZ, EXE
from PyInstaller.building.build_main import Analysis
from PyInstaller.utils.hooks import collect_dynamic_libs, collect_data_files

block_cipher = None

arcade_resources = [
    *collect_data_files(
        'arcade',
        includes=[
            '**/*.glsl',  # shaders
            '**/*.yml',  # styles
        ]
    ),
    *collect_dynamic_libs('arcade') # soloud and other libs
]

a = Analysis(['start_client.py'],
             pathex=['D:\\workspace\\shiped'],
             binaries=[
                 (pymunk.chipmunk_path, '.'),
             ],
             datas=[
                 ('resources', 'resources'),
                 *arcade_resources
             ],
             hiddenimports=[],
             hookspath=[],
             runtime_hooks=[],
             excludes=['tkinter'],
             win_no_prefer_redirects=False,
             win_private_assemblies=False,
             cipher=block_cipher,
             noarchive=False)
pyz = PYZ(a.pure, a.zipped_data,
          cipher=block_cipher)
exe = EXE(pyz,
          a.scripts,
          a.binaries,
          a.zipfiles,
          a.datas,
          [],
          name='start_client',
          debug=False,
          bootloader_ignore_signals=False,
          strip=False,
          upx=True,
          upx_exclude=[],
          runtime_tmpdir=None,
          console=False)

I also change the current work directory to the extracted path:

    if hasattr(sys, '_MEIPASS'):
        # Change current working directory to ease resource loading
        os.chdir(Path(getattr(sys, '_MEIPASS', '.')))

With the fixed pymunk, a hookfile for arcade would be a good idea.

[SirGnip]

I can add documentation for using pyinstaller as arcade currently stands today. Or I can look into creating a pyinstaller hook file and getting the testing all wired up in travis. I'm new to pyinstaller, but after a quick skim of the hook file docs, it doesn't seem too bad. But creating/testing a hookfile will delay the docs. What do people think?

[eruvanos]

@SirGnip I thing first hook then docs, with the hook in place it is way easier to ship with pyinstaller and the docs are would have to be updated the other way around :) .

[SirGnip]

Sounds logical to me! :) I'll read the pyinstaller hook docs again and have at it.

[SirGnip]

I've added a PyInstaller hook to arcade. With that in place, a simple pyinstaller mygame.py --onefile is able to make a one-file .exe out of an arcade app!

So, that is the first bit of PyInstaller work done, with more to come. I put a task list in the first comment above.

If you want to experiment with the hook locally, you can do the following on Windows:

mkdir arcade_installer_test
cd arcade_installer_test
py -3 -m venv venv
venv\Scripts\activate
pip install git+git://github.com/SirGnip/arcade@installing
pip install pyinstaller
    
notepad myapp.py  # paste and save code below into the file

    import arcade, pymunk
    arcade.open_window(400, 400, "my app")
    arcade.start_render()
    arcade.draw_circle_filled(200, 200, 100, arcade.color.BLUE)
    arcade.finish_render()
    arcade.run()

pyinstaller myapp.py --onefile
dist\myapp.exe

[SirGnip]

Both the hook and tutorial are complete. I pushed them up as separate PR's. Looking for feedback (especially on the workflow proposed by the tutorial).

The tutorial as written is slightly Windows-centric (pyinstaller commands use semi-colons instead of colons, ".exe" files are referenced once or twice). I'm open to ideas on how to cleanly make this tutorial work for Mac/Linux users. Just add a line or two to the docs that say "Unix/Mac users use a colon istead"? What OS is the most common for people using Arcade?