README

=================================================
 Using Emacs Desktop Mode with Virtualenvwrapper
=================================================

Emacs desktop-mode_ lets you save the state of emacs (open buffers,
kill rings, buffer positions, etc.) between sessions.  It can also be
used as a project file similar to other IDEs.  This virtualenvwrapper_
plugin adds a trigger to save the current desktop file and load a new
one when activating a new virtualenv using ``workon``.

Installation
============

Install this plugin with pip::

  $ pip install virtualenvwrapper-emacs-desktop

Or by unpacking the source distribution and running ``setup.py`` directly::

  $ tar zxvf virtualenvwrapper-emacs-desktop-X.Y.tar.gz
  $ cd virtualenvwrapper-emacs-desktop-X.Y
  $ python setup.py install

You may need administrator privileges to install to a global location.

Configuring Desktop Mode in Emacs
=================================

Setup of desktop-mode is straightforward:

1. Run ``customize-group`` on the "desktop" group.

2. Turn ``desktop-save-mode`` **on** to enable the minor mode.

3. Optionally change the base name for desktop files in
   ``desktop-base-file-name``. For example, using "emacs.desktop"
   means the file will not be hidden.

4. Set a default search path for the desktop file in ``desktop-path``.
   Use your home directory, or the directory where you keep your emacs
   configuration files (``~/emacs.d`` or ``~/emacs``).  This value is
   the *default*.  Your real desktop files will be saved into the
   virtualenv directories.

5. Set ``desktop-save`` to **Always save**. There are other values
   that work, but some require interaction with the editor during the
   context move to confirm file saves.

There are a few other options that may be useful to tweak, depending
on the other features of emacs you use. For example,
``desktop-clear-preserve-buffers`` lets you control which buffers are
saved when the desktop is cleared on a reload.  It may be useful to
save the ``*Messages*``, ``*Org Agenda*``, and ``*scratch*`` buffers,
since those are related to emacs operation and not limited to any one
project.

VIRTUALENVWRAPPER_EMACSCLIENT
-----------------------------

If the ``emacsclient`` binary visible on your ``$PATH`` does not match
the version of emacs you are using, set
``VIRTUALENVWRAPPER_EMACSCLIENT`` to the full path of the version to
use instead.

::

    export VIRTUALENVWRAPPER_EMACSCLIENT=/Applications/Emacs.app/Contents/MacOS/bin/emacsclient

Enabling the Plugin
===================

Switching desktop sessions every time ``workon`` is used would make it
impossible to have two shells open and working on separate projects at
the same time.  Therefore, the plugin must be explicitly enabled in
the shell where it should control the emacs session.

Two shell functions (``emacs_desktop_controller_on`` and
``emacs_desktop_controller_off``) are provided to switch the plugin on
and off.  They do this by changing the variable
``DESKTOP_CONTROLLER``, which the plugin examines before taking any
action.  If the variable is not set, or is defined but empty, the
plugin makes no changes.  If the variable is set to any value, the
session is changed.

Most modern terminal programs make it easy to create custom
configurations with specific settings.  Use your terminal's
customization feature to create a "desktop controller" configuration
with ``DESKTOP_CONTROLLER`` set, then control
virtualenvwrapper-emacs-desktop from a terminal using that
configuration.

Terminal.app
------------

The default OS X terminal emulator Terminal.app lets you set up
profiles with custom configurations, including running a command when
the new window is opened.  Create a new profile, then under the
**Shell** tab, set:

 :Run command: emacs_desktop_controller_on
 :Run inside shell: Enabled


iTerm
-----

The third-party OS X terminal emulator iTerm_ lets you set up
"bookmarks" with custom configurations, including the "Working Dir".
One way to use this to control the plugin is to set up a special
bookmark with a working directory set to ``$WORKON_HOME``, then add a
check to ``~/.bashrc`` to check for that condition.

 :Name: emacs-control
 :Command: ``bash -l``
 :Working Dir: ``/Users/username/.virtualenvs``
 :Terminal: Default
 :Keyboard: Global
 :Display: Default

~/.bashrc settings::

    if [ "$(pwd)" = "$WORKON_HOME" ]
    then
        emacs_desktop_controller_on
    else
        emacs_desktop_controller_off
    fi

.. _iTerm: http://iterm.sourceforge.net/

emacs shell
-----------

shell-mode in emacs sets ``EMACS`` and ``INSIDE_EMACS``, so you can
test for those environment variables.

Gnome Terminal
--------------

?

KDE
---

?

.. note::

   If you have suggested configuration mechanisms for other terminal
   emulators or other platforms, please post them in the comments and I
   will add them to this README file.

References
==========

* `Saving Emacs Sessions <http://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Emacs-Sessions.html>`__
* `Desktop Save Mode <http://www.gnu.org/s/emacs/manual/html_node/elisp/Desktop-Save-Mode.html>`__
* desktop-mode_
* virtualenvwrapper_

.. _desktop-mode: http://www.emacswiki.org/emacs/DeskTop

.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/