Skip to content

Commit

Permalink
reorder osx packaging methods
Browse files Browse the repository at this point in the history
  • Loading branch information
dessant committed Jun 20, 2017
1 parent 33777b0 commit ac0d28f
Showing 1 changed file with 189 additions and 181 deletions.
370 changes: 189 additions & 181 deletions doc/sources/guide/packaging-osx.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,187 @@ Creating packages for OS X
==========================

.. note::
Packaging Kivy applications with the following methods must be done inside
OS X, 32-bit platforms are no longer supported.

This guide describes multiple ways for packaging Kivy applications.
Packaging with PyInstaller is recommended for general use.

.. _osx_pyinstaller:

Using PyInstaller and Homebrew
------------------------------
.. note::
Package your app on the oldest OS X version you want to support.

Complete guide
~~~~~~~~~~~~~~
#. Install `Homebrew <http://brew.sh>`_
#. Install Python::

$ brew install python

.. note::
To use Python 3, ``brew install python3`` and replace ``pip`` with
``pip3`` in the guide below.

#. (Re)install your dependencies with ``--build-bottle`` to make sure they can
be used on other machines::

$ brew reinstall --build-bottle sdl2 sdl2_image sdl2_ttf sdl2_mixer

.. note::
If your project depends on GStreamer or other additional libraries
(re)install them with ``--build-bottle`` as described
`below <additional libraries_>`_.

#. Install Cython and Kivy::

$ pip install -I Cython==0.23
$ USE_OSX_FRAMEWORKS=0 pip install -U kivy

#. Install PyInstaller::

$ pip install -U pyinstaller

#. Package your app using the path to your main.py::

$ pyinstaller -y --clean --windowed --name touchtracer \
--exclude-module _tkinter \
--exclude-module Tkinter \
--exclude-module enchant \
--exclude-module twisted \
/usr/local/share/kivy-examples/demo/touchtracer/main.py

.. note::
This will not yet copy additional image or sound files. You would need to
adapt the created ``.spec`` file for that.


Editing the spec file
~~~~~~~~~~~~~~~~~~~~~
The specs file is named `touchtracer.spec` and is located in the directory
where you ran the pyinstaller command.

You need to change the `COLLECT()` call to add the data of touchtracer
(`touchtracer.kv`, `particle.png`, ...). Change the line to add a Tree()
object. This Tree will search and add every file found in the touchtracer
directory to your final package. Your COLLECT section should look something
like this::


coll = COLLECT(exe, Tree('/usr/local/share/kivy-examples/demo/touchtracer/'),
a.binaries,
a.zipfiles,
a.datas,
strip=None,
upx=True,
name='touchtracer')

This will add the required hooks so that PyInstaller gets the required Kivy
files. We are done. Your spec is ready to be executed.

Build the spec and create a DMG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Open a console.
#. Go to the PyInstaller directory, and build the spec::

$ pyinstaller -y --clean --windowed touchtracer.spec

#. Run::

$ pushd dist
$ hdiutil create ./Touchtracer.dmg -srcfolder touchtracer.app -ov
$ popd

#. You will now have a Touchtracer.dmg available in the `dist` directory.


Additional Libraries
~~~~~~~~~~~~~~~~~~~~
GStreamer
^^^^^^^^^
If your project depends on GStreamer::

$ brew reinstall --build-bottle gstreamer gst-plugins-{base,good,bad,ugly}

.. note::
If your Project needs Ogg Vorbis support be sure to add the
``--with-libvorbis`` option to the command above.

If you are using Python from Homebrew you will also need the following step
until `this pull request <https://github.com/Homebrew/homebrew/pull/46097>`_
gets merged::

$ brew reinstall --with-python --build-bottle https://github.com/cbenhagen/homebrew/raw/patch-3/Library/Formula/gst-python.rb


Using PyInstaller without Homebrew
----------------------------------
First install Kivy and its dependencies without using Homebrew as mentioned here
http://kivy.org/docs/installation/installation.html#development-version.

Once you have kivy and its deps installed, you need to install PyInstaller.

Let's assume we use a folder like `testpackaging`::

cd testpackaging
git clone http://github.com/pyinstaller/pyinstaller

Create a file named touchtracer.spec in this directory and add the following
code to it::

# -*- mode: python -*-

block_cipher = None
from kivy.tools.packaging.pyinstaller_hooks import get_deps_all, hookspath, runtime_hooks

a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
pathex=['/path/to/yout/folder/containing/testpackaging'],
binaries=None,
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
hookspath=hookspath(),
runtime_hooks=runtime_hooks(),
**get_deps_all())
pyz = PYZ(a.pure, a.zipped_data,
cipher=block_cipher)
exe = EXE(pyz,
a.scripts,
exclude_binaries=True,
name='touchtracer',
debug=False,
strip=False,
upx=True,
console=False )
coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'),
Tree('/Library/Frameworks/SDL2_ttf.framework/Versions/A/Frameworks/FreeType.framework'),
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
name='touchtracer')
app = BUNDLE(coll,
name='touchtracer.app',
icon=None,
bundle_identifier=None)

Change the paths with your relevant paths::

a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
pathex=['/path/to/yout/folder/containing/testpackaging'],
...
...
coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'),

Then run the following command::

pyinstaller/pyinstaller.py touchtracer.spec

Replace `touchtracer` with your app where appropriate.
This will give you a <yourapp>.app in the dist/ folder.


.. _osx_kivy-sdk-packager:

Expand All @@ -14,6 +193,10 @@ Using Buildozer
cd /to/where/I/Want/to/package
buildozer init

.. note::
Packaging Kivy applications with the following method must be done inside
OS X, 32-bit platforms are no longer supported.

Edit the buildozer.spec and add the details for your app.
Dependencies can be added to the `requirements=` section.

Expand Down Expand Up @@ -49,6 +232,10 @@ section below.
Using the Kivy SDK
------------------

.. note::
Packaging Kivy applications with the following method must be done inside
OS X, 32-bit platforms are no longer supported.

Since version 1.9.0, Kivy is released for the OS X platform in a
self-contained, portable distribution.

Expand Down Expand Up @@ -160,182 +347,3 @@ To make a DMG of your app use the following command::
Note the lack of `/` at the end.
This should give you a compressed dmg that will further shrink the size of your
distributed app.


.. _osx_pyinstaller:


Using PyInstaller without Homebrew
----------------------------------
First install Kivy and its dependencies without using Homebrew as mentioned here
http://kivy.org/docs/installation/installation.html#development-version.

Once you have kivy and its deps installed, you need to install PyInstaller.

Let's assume we use a folder like `testpackaging`::

cd testpackaging
git clone http://github.com/pyinstaller/pyinstaller

Create a file named touchtracer.spec in this directory and add the following
code to it::

# -*- mode: python -*-

block_cipher = None
from kivy.tools.packaging.pyinstaller_hooks import get_deps_all, hookspath, runtime_hooks

a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
pathex=['/path/to/yout/folder/containing/testpackaging'],
binaries=None,
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
hookspath=hookspath(),
runtime_hooks=runtime_hooks(),
**get_deps_all())
pyz = PYZ(a.pure, a.zipped_data,
cipher=block_cipher)
exe = EXE(pyz,
a.scripts,
exclude_binaries=True,
name='touchtracer',
debug=False,
strip=False,
upx=True,
console=False )
coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'),
Tree('/Library/Frameworks/SDL2_ttf.framework/Versions/A/Frameworks/FreeType.framework'),
a.binaries,
a.zipfiles,
a.datas,
strip=False,
upx=True,
name='touchtracer')
app = BUNDLE(coll,
name='touchtracer.app',
icon=None,
bundle_identifier=None)

Change the paths with your relevant paths::

a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
pathex=['/path/to/yout/folder/containing/testpackaging'],
...
...
coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'),

Then run the following command::

pyinstaller/pyinstaller.py touchtracer.spec

Replace `touchtracer` with your app where appropriate.
This will give you a <yourapp>.app in the dist/ folder.


Using PyInstaller and Homebrew
------------------------------
.. note::
Package your app on the oldest OS X version you want to support.

Complete guide
~~~~~~~~~~~~~~
#. Install `Homebrew <http://brew.sh>`_
#. Install Python::

$ brew install python

.. note::
To use Python 3, ``brew install python3`` and replace ``pip`` with
``pip3`` in the guide below.

#. (Re)install your dependencies with ``--build-bottle`` to make sure they can
be used on other machines::

$ brew reinstall --build-bottle sdl2 sdl2_image sdl2_ttf sdl2_mixer

.. note::
If your project depends on GStreamer or other additional libraries
(re)install them with ``--build-bottle`` as described
`below <additional libraries_>`_.

#. Install Cython and Kivy::

$ pip install -I Cython==0.23
$ USE_OSX_FRAMEWORKS=0 pip install -U kivy

#. Install PyInstaller::

$ pip install -U pyinstaller

#. Package your app using the path to your main.py::

$ pyinstaller -y --clean --windowed --name touchtracer \
--exclude-module _tkinter \
--exclude-module Tkinter \
--exclude-module enchant \
--exclude-module twisted \
/usr/local/share/kivy-examples/demo/touchtracer/main.py

.. note::
This will not yet copy additional image or sound files. You would need to
adapt the created ``.spec`` file for that.


Editing the spec file
~~~~~~~~~~~~~~~~~~~~~
The specs file is named `touchtracer.spec` and is located in the directory
where you ran the pyinstaller command.

You need to change the `COLLECT()` call to add the data of touchtracer
(`touchtracer.kv`, `particle.png`, ...). Change the line to add a Tree()
object. This Tree will search and add every file found in the touchtracer
directory to your final package. Your COLLECT section should look something
like this::


coll = COLLECT(exe, Tree('/usr/local/share/kivy-examples/demo/touchtracer/'),
a.binaries,
a.zipfiles,
a.datas,
strip=None,
upx=True,
name='touchtracer')

This will add the required hooks so that PyInstaller gets the required Kivy
files. We are done. Your spec is ready to be executed.

Build the spec and create a DMG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Open a console.
#. Go to the PyInstaller directory, and build the spec::

$ pyinstaller -y --clean --windowed touchtracer.spec

#. Run::

$ pushd dist
$ hdiutil create ./Touchtracer.dmg -srcfolder touchtracer.app -ov
$ popd

#. You will now have a Touchtracer.dmg available in the `dist` directory.


Additional Libraries
~~~~~~~~~~~~~~~~~~~~
GStreamer
^^^^^^^^^
If your project depends on GStreamer::

$ brew reinstall --build-bottle gstreamer gst-plugins-{base,good,bad,ugly}

.. note::
If your Project needs Ogg Vorbis support be sure to add the
``--with-libvorbis`` option to the command above.

If you are using Python from Homebrew you will also need the following step
until `this pull request <https://github.com/Homebrew/homebrew/pull/46097>`_
gets merged::

$ brew reinstall --with-python --build-bottle https://github.com/cbenhagen/homebrew/raw/patch-3/Library/Formula/gst-python.rb

0 comments on commit ac0d28f

Please sign in to comment.