Commits  committed d992801

Explain how to install and uninstall the application.

  • Participants
  • Parent commits 5d53370
  • Branches default
  • Tags v1.0.1

Comments (0)

Files changed (1)

File docs/usage.rst

     reading manifest file 'Zzz.egg-info/SOURCES.txt'
     writing manifest file 'Zzz.egg-info/SOURCES.txt'
-.. tip::
-    Whenever you run the application, re-run this command first *if* you've
-    added/deleted any files or modified **. You do not have to re-run
-    it if you've merely modified the files.
 The application should now run out of the box:
 .. code-block:: sh
 If you're porting an existing Pylons application to Pyramid, the Architecture
 and Migration chapters should get you started.
+**Important**: Whenever you add or delete files in the application, remember to
+re-execute the "python egg_info" step before running the application
+again. This updates the package's metadata to reflect the new files. Otherwise
+Python may not be able to find them.
+Installing the application
+So far we haven't installed the application, so Python is looking in the
+current directory for the ``zzz`` package and ``Zzz.egg-info`` metadata. This
+is convenient during early development because we can create and delete scrath
+applications quickly without installing them into the virtualenv and
+uninstalling them. However, for production and beta testing you should formally
+install the application; that way you can run it from any directory (by
+specifying the path to the INI file). 
+You can install a link to the application's source directory by running "pip
+install -e .". This installs an "egg link" file pointing to the source
+directory, so that Python will immediately see any changes in the source. This
+is useful in development, and some production deployments also use this system.
+The other option is to install a snapshot of the application's current state.
+This copies the package's files to the virtualenv's *site-packages* directory,
+so that Python will not see any subsequent changes in the source until you
+reinstall the application. The command for this is "pip install .". This is the
+same thing that happens when you install a third-party package (e.g., "pip
+install Akhet").
+If you're using easy_install rather than pip, the command to install an egg
+link is "python develop". The command to install a snapshot is
+"easy_install ." or "python install".
+Uninstalling the application
+To uninstall an application that was installed as a pip snapshot, cd to a
+distant directory (not the application source or its parent) and run "pip
+uninstall Zzz". This should supposedly work with a pip egg link too but it
+hasn't always worked for me. It also works with external packages that were
+installed with pip; e.g., "pip uninstall Akhet".
+Easy_install does not have an uninstall command, so you'll have to uninstall it
+manually in that case.
+To uninstall the application (or any Python package) manually, cd to the
+virtualenv's *site-packages* directory. Delete any subdirectories and files
+corresponding to the Python package, its metadata, or its egg link. For our
+sample application these would be *zzz* (Python package), *Zzz.egg-info*
+(pip egg_info), *Zzz.egg* (easy_install directory or ZIP file), and
+*Zzz.egg-link* (egg link file). Also look in *easy-install.pth* and delete
+the application's line if present.
 .. _Pyramid documentation:
 .. _Pyramid tutorials:
 .. _virtualenv: