You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

136 lines
5.7 KiB

  1. # Packaging Gooey as a Stand Alone Application
  2. <p align="center">
  3. <img src="https://github.com/chriskiehl/GooeyImages/raw/images/docs/packaging/packaged-application.png" />
  4. </p>
  5. >:warning: Packaging Gooey is an ongoing science. Gooey currently runs on all the major platforms, can be installed in a bajillion different ways, and has several active versions in wide usage. In short, edge cases abound. If you run into any problems, hit up [this issue](https://github.com/chriskiehl/Gooey/issues/259).
  6. You can package all of your programs files into a single easy to distribute executable using PyInstaller.
  7. Packing Gooey into a standalone executable is super straight forward thanks to [PyInstaller](http://www.pyinstaller.org/). It is the only dependency you'll need and can be installed via the following.
  8. ```
  9. pip install pyinstaller
  10. ```
  11. **Setting up the build:**
  12. PyInstaller uses [spec files](http://pythonhosted.org/PyInstaller/#using-spec-files) to determine how to bundle the project. These are a bit like `setup.py` files, but contain rules for how PyInstaller should bundle your whole application as a stand alone executable.
  13. This file is usually placed in the root of your project. e.g.
  14. ```
  15. MyProject/
  16. - src/
  17. - build.spec # <-- goes here!
  18. - LICENCE.txt
  19. - README.md
  20. ```
  21. **Download Spec Files**
  22. * Windows users can grab a pre-built spec file [here](https://raw.githubusercontent.com/chriskiehl/Gooey/master/docs/packaging/build-win.spec).
  23. * For OSX users, you'll want [this one](https://raw.githubusercontent.com/chriskiehl/Gooey/master/docs/packaging/build-osx.spec).
  24. The exact contents of the spec files will vary based on your OS, but at a high level, they'll share the same core pieces: `Analysis`, `EXE`, and, if you're on OSX, `BUNDLE`
  25. ```
  26. # -*- mode: python ; coding: utf-8 -*-
  27. block_cipher = None
  28. a = Analysis(
  29. ['main.py'], # replace me with the main entry point
  30. pathex=['/path/to/main.py'], # replace me with the appropriate path
  31. ...
  32. )
  33. pyz = PYZ(a.pure)
  34. options = [('u', None, 'OPTION'), ('v', None, 'OPTION'), ('w', None, 'OPTION')]
  35. exe = EXE(pyz,
  36. ...
  37. name='MyCoolApplication' # replace me with exe name
  38. console=False)
  39. ## OSX only below!
  40. app = BUNDLE(exe,
  41. name='APPNAME.app', # osx users replace me!
  42. bundle_identifier=None,
  43. info_plist=info_plist
  44. )
  45. ```
  46. The `Analysis` section is where you'll tell PyInstaller about your program. Using the build.spec from above, you'll need to make two edits to this section.
  47. 1. replace `APPNAME` in the `Analysis()` section with the name of _your_ application
  48. 2. replace the `pathex` value in the `Analysis()` section with the path to your application's root
  49. > note: If you use additional data resources (e.g. images, data, etc..) you'll also need to explicitly add them to the EXE section. See [packaging custom images] for more info.
  50. Next is `EXE`. In this section you'll replace the `name` argument with what you'd like the final `.exe` to be named.
  51. >Note: if you're providing your own icon file, EXE is where you'll provide it.
  52. If you're on OSX, you'll have an additional `BUNDLE` section. You'll need to make one final edit here as well to control the name of the `.app` bundle that PyInstaller produces. Additionally, if you're customizing the bundle's icon, this is where you would supply the override (versus Windows, which places it in the EXE section).
  53. Once you've updated the `.spec` to reflect your program's details. All that's left to do is build the executable!
  54. ### Running the .spec file
  55. From the command line, run
  56. ```
  57. pyinstaller -F --windowed build.spec
  58. ```
  59. * `-F` tells PyInstaller to create a single bundled output file
  60. * `--windowed` disables the terminal which would otherwise launch when you opened your app.
  61. And that's it. Inside of the `dist/` directory, you'll find a beautiful stand-alone executable that you can distribute to your users.
  62. ## Troubleshooting
  63. **PROBLEM: My bundled Application won't work!**
  64. First things first: _See if you can package your application **without** Gooey!_
  65. Read and understand all of the PyInstaller docs. If you're referencing binaries or external data files, you may have to do a little extra work in your `.spec` to get PyInstaller to understand all of your dependencies.
  66. Rebuild your bundle with `debug=True` set in the `.spec` file. This will give lots of useful output when your application bootstraps which can make pinning down the problem much easier.
  67. Rebuild your bundle without the `-F` flag (e.g. just `pyinstaller build.spec`). This will build a directory with all of your dependencies. This can make it easier to poke around and see what PyInstaller's view of your project actually is.
  68. **PROBLEM: I'm seeing the wrong icon on my executable**
  69. First things first: Is Windows gas lighting you?
  70. Windows caches icons semi-aggressively. This can lead to it showing an icon in the file explorer that doesn't actually reflect reality.
  71. ![image](https://github.com/chriskiehl/GooeyImages/raw/images/docs/packaging/cached-icon.png)
  72. Right-click on the executable and select "properties." This will show you the icon that's actually associated with file. As long as everything looks good there, you're golden. Windows will catch up... _eventually_.
  73. **PROBLEM: Exception: This program needs access to the screen. Please run with a Framework build of python, and only when you are logged in on the main display of your Mac.**
  74. This happens on OSX when you neglect the `--windowed` flag during your build step.
  75. wrong:
  76. ```
  77. pyinstaller build.spec ## oops! forgot the required flags
  78. ```
  79. Correct:
  80. ```
  81. pyinstaller --windowed build.spec
  82. ```
  83. Checkout the [Pyinstaller Manual](https://github.com/pyinstaller/pyinstaller/wiki/FAQ) for more details.