Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
This directory contains a brief tutorial on using esky in your frozen applications. It assumes some basic familiarity with distutils and and a freezer module such as py2exe. The sub-directories "stage0" through "stage4" contain example code showing the evolution of a simple example app. To run them you'll need to be on a Windows machine with py2exe installed. Step 1: Freezing with Esky =========================== In order to use the functionality of esky in your application, it must be frozen using a certain file layout and directory structure. The easiest way to achieve this is to use the "bdist_esky" distutils command as a wrapper around your freezer module of choice. Consider the example application in the "stage0" directory. This is a simple application designed to be frozen with py2exe. Run "python setup.py py2exe" in this directory and you will see that the "dist" folder is created with the frozen application directly inside it. Now consider the modified application in the "stage1" directory. Here we have changed the setup.py script to use esky instead of directly calling py2exe. Run "python setup.py bdist_esky" in this directory - esky will automatically detect that you have py2exe installed and use that to freeze the application. The "dist" directory will now contain a file named "example-app-0.1.win32.zip". This zipfile contains a specific version of the application frozen in the format expected by esky. If you unzip it, you will see the application is laid out according to the following structure: example.exe <-- bootstrapping exe produced by esky appdata/ example-app-0.1.win32/ <-- directory containing the frozen application example.exe as produced by py2exe library.zip python26.dll esky-files/ bootstrap-manifest.txt <-- extra metadata for use during updates The top-level "example.exe" is a bootstrapping executable produced by esky. The "example-app-0.1.win32" directory contains the application exactly as frozen by py2exe, but with some extra files containing metadata for use when updating the app. You can distribute these files to your users in any manner - e.g. by having them download and extract the zipfile directly, or by packaging it up into an installer. As long as the above file layout and directory structure is maintained, the application will be capable of auto-updating itself with esky. Step 2: Looking For Updates ============================ Next, we must add code to our application to make it search for, download and installed updated versions of itself. The interface for doing so is the "Esky" class, which represents a container for your frozen application. We create one like so: app = esky.Esky(sys.executable,"http://example-app.com/downloads/") The Esky must be given its location on disk, and a url at which to look for updated versions. Instances of Esky then have the following useful methods: find_update(): check for updated versions of the app fetch_version(): download a specific version of the app install_version(): install a specific version of the app uninstall_version(): uninstall a specific version of the app cleanup(): remove any old versions, partial downloads etc. For convenience, it also has this method: auto_update(): check for an updated version; install it if found Looking at the code in stage2/example.py, we can see that the application now checks whether it is running as a frozen app, and if so it: * creates an Esky pointing at an appropriate URL, and * calls the "auto_update" method on the esky to search for and install a new version of the app. A real application would probably want to perform these tasks in a background thread, prompt the user for confirmation, and so-on. Nonetheless, our simple example application is now capable of auto-updating itself over the internet. Step 3: Distributing Updates ============================= You've already seen how this step works. Whenever a new version of the application is released, run the "bdist_esky" command and make the resulting zipfile available for download from the update URL specified in your code. The app will automatically detect the update, download and install it. One point of watch out for: you must not change the name of the zipfile produced by bdist_esky. Since it embeds version and platform information, changing the name could cause esky to get confused about which version really is the latest. Esky also supports distributing your updates as a patch instead of (or as well as) a full zipfile download. To see this in action, copy the "dist" folder you built in stage 2 into the "stage3" folder. You should have the following files: stage3/example.py stage3/setup.py stage3/dist/example-0.2.win32.zip Now run "python setup.py bdist_esky_patch" in the stage3 directory. This will generate the zipfile for the new version along with a patch against any other zipfiles found in the "dist" dir. You should now have: stage3/dist/example-0.2.win32.zip stage3/dist/example-0.3.win32.zip stage3/dist/example-0.3.win32.from-0.2.patch As before, simply make this patch file available for download from your update URL and esky will detect and use it as appropriate. It's also possible to generate patches between two existing zipfiles, without going through the setup.py script. Simply invoke the "esky.patch" module directly as follows: python -m esky.patch -Z diff ../stage1/dist/example-0.1.win32.zip ./dist/example-0.2.win32.zip ./dist/example-0.2.win32.from-0.1.patch Don't forget the "-Z" argument - it tells the patcher to unzip the source files before starting work. You should now have: stage3/dist/example-0.2.win32.zip stage3/dist/example-0.2.win32.from-0.1.patch stage3/dist/example-0.3.win32.zip stage3/dist/example-0.3.win32.from-0.2.patch By the way, esky is smart enough to apply a sequence of patches to get to the latest version, so there's no need to also generate a patch from version 0.1 to 0.3 in this case. Step 4: Customising the Freeze Process ======================================= Most users will not need to customise the freeze procees performed by the bdist_esky command - it automatically detects any available freezer modules (e.g. py2exe, cx_Freeze, bbfreeze) and applies some sensible defaults for you. If necessary, however, you can pass options either on the setup.py command line, or using the "options" argument to the setup() function. The code in the "stage4" directory shows an example of how to customise the freeze process. Here we specify a custom icon for the executable, list some modules to explicitly include and exclude from the freeze, and give additional options that are passed through to py2exe.