Application bundles
===================

Starting with EDM 1.10 (and Enthought Deployment Server 0.17), we have
support for publishing full applications and delivering them to the
desktop. This builds on the "bundle" functionality in EDM/EDS, which
allows complete, unambiguous and immutable description of the Python
environment within which applications run.

The basic workflow to create a bundle for an application is:

* Develop and test your app, making sure that all dependencies are available through EDM/EDS.
* Create a function somewhere in your code, and publish the function
  in a setuptools entry point. This function should return some
  configuration info in a dictionary: icons to create, name of the
  app, etc.
* Create an EDM bundle with your app & dependencies. Add a dependency
  on the special library "eam", available in enthought/free, which EDM
  will use for the setup process.
* Upload the bundle to EDS using the ``hatcher`` tool.
* Congratulations!  Your app is now installable via ``edm app install <name>``.


Detailed workflow
-----------------

Application bundles are normal EDM environment requirements bundles
that contain the Enthought Application Manager (EAM) package.


How to Create
^^^^^^^^^^^^^

To create an application bundle one needs two steps:

1. Register a function callable with the ``enthought_app_metadata``
   setuptools ``pkg_resources`` entry_point.
   The callable is expected to return a dictionary that follows the
   :ref:`metadata_schema` describing basic application
   metadata (e.g. version, user friendly name) and information on the
   commands to start the application and create desktop shortcuts.
2. Create an EDM bundle with the application requirements and the
   ``eam`` python package. The ``eam`` package provides a standard
   executable entry_point for deployment managers like EDM to execute
   configure, start and remove configuration tasks for each
   application.

Example setup.py::

  from setuptools import setup

  setup(
    name='eam_example_app',
    version='1.0.1',
    license='BSD',
    ...
    entry_points={
        'enthought_app_metadata': ['example_app = eam_example_app.info:info'],
    ...)

Example callable that returns application metadata::

  import os
  HERE = os.path.abspath(os.path.dirname(__file__))

  def info():
    """ Provides information to the "eam" package.
    """
    icon = os.path.join(HERE, 'data', 'icon.ico')
    return {
        'name': 'EAM Example',
        'description': 'Some information here',
        'license': 'BSD',
        'copyright': '(c) 2018 Enthought',
        'version': u'1.0.1',
        'schema_version': 2,
        'commands': [
            {'name': 'hello',
             'command': 'example_app',
             'shortcut': 'desktop',
             'icon': icon,
             'schema_version': 2}]}

.. note::

   - One needs to create a bundle with schema version 2.0 for
     applications.
   - EDM 1.10.0 supports only one application per bundle so having
     more contributions to ``enthought_app_metadata`` in a python
     environment will be ignored.


example
*******

Generate the edm bundle::

   edm bundle generate -f mayavi_demo-1.0.2-1.bundle mayavi eam eam_mayavi_app pyside --version 2.7 -m 2.0 --arch=win-x86

Which creates an edm bundle for windows 32 bit for latest mayavi
version in EDS using python 2.7.

.. note::

   The eam_mayavi_app is a simple egg that registers the mayavi2
   executable and icons with the eam package. This is necessary when
   the application is not ``eam`` aware. Custom applications do not
   have to use a separate egg to register with ``eam``, but can
   register the necessary callable in their ``setup.py``.

Upload
^^^^^^

To upload the bundle we use the hatcher ``bundles`` command group.

example
*******

::

  $ hatcher bundles upload enthought free mayavi_demo-1.0.2-1.bundle

Which will upload our application bundle to the ``enthought/free``
repository.

.. note::

   If the bundle is uploaded to any repository other than ``enthought/free``,
   the edm yaml config file needs to be updated with a new
   ``bundle_repositories`` entry, pointing to the repository containing the
   bundle file. See documentation on `EDM configuration <https://docs.enthought.com/edm/user/cli.html#configuration-properties>`_
   for more.

Deployment
^^^^^^^^^^

To deploy the application we use EDM and in particular the edm
``app/application`` command group to list, search, install, start and
remove applications. To support these operations EDM relies on the
fact that the ``eam`` package is part of the bundle requirements and
installed in the created python environment.

example
*******

**List available applications**

::

  $ edm app list-available
  Fetching indices for bundle repositories. done
  name         version    repository
  -----------  ---------  ------------------
  mayavi_demo  1.0.0-3    enthought/free
  mayavi_demo  1.0.0-4    enthought/free

This list will contain only bundles that use the ``eam`` python
package.

**Install application**

::

  $ edm app install mayavi_demo
  Fetching indices for bundle repositories. done
  Fetching indices for runtime repositories. done
  Fetching indices for package repositories.. done
  Installing runtime... done
  VTK-7.0.0-2.egg                                         [fetch]
  21.83 MiB [..................................................]   10.1 MiB/sec
  Installing/removing package(s)
  mayavi             [...........................................]

.. note::

   EDM will download the bundle and create the python environment.
   Next EDM will ask the ``eam`` package to create the any shortcuts
   for the registered application.

**Start application**

::

  $ edm app start mayavi_demo

In this case EDM with ask the ``eam`` package to start the registered
application.