updated installation instructions for OS X 10.5 (including readline egg and SVN 1.5 patch instructions from wiki http://ipython.scipy.org/moin/InstallationOSXLeopard

docs/source/install/basic.txt

@@ -1,272 +1,286 b''
 =============================
 Basic installation of IPython
 =============================
 
 Installation
 ============
 
 Instant instructions
 --------------------
 
 If you are of the impatient kind, under Linux/Unix simply untar/unzip
 the download, then install with 'python setup.py install'. Under
 Windows, double-click on the provided .exe binary installer.
 
 Then, take a look at Customization_ section for configuring things
 optimally and `Quick tips`_ for quick tips on efficient use of
 IPython. You can later refer to the rest of the manual for all the
 gory details.
 
 See the notes in upgrading_ section for upgrading IPython versions.
 
 
     Detailed Unix instructions (Linux, Mac OS X, etc.)
 
 For RPM based systems, simply install the supplied package in the usual
 manner. If you download the tar archive, the process is:
 
    1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is
       the version number). It will make a directory called ipython-XXX.
       Change into that directory where you will find the files README
       and setup.py. Once you've completed the installation, you can
       safely remove this directory.
    2. If you are installing over a previous installation of version
       0.2.0 or earlier, first remove your $HOME/.ipython directory,
       since the configuration file format has changed somewhat (the '='
       were removed from all option specifications). Or you can call
       ipython with the -upgrade option and it will do this automatically
       for you.
    3. IPython uses distutils, so you can install it by simply typing at
       the system prompt (don't type the $)::
       
       	$ python setup.py install
       	
       Note that this assumes you have root access to your machine. If
       you don't have root access or don't want IPython to go in the
       default python directories, you'll need to use the ``--home`` option
       (or ``--prefix``). For example::
       
       	$ python setup.py install --home $HOME/local
       	
       will install IPython into $HOME/local and its subdirectories
       (creating them if necessary).
       You can type::
       
       	$ python setup.py --help
       	
       for more details.
       
       Note that if you change the default location for ``--home`` at
       installation, IPython may end up installed at a location which is
       not part of your $PYTHONPATH environment variable. In this case,
       you'll need to configure this variable to include the actual
       directory where the IPython/ directory ended (typically the value
       you give to ``--home`` plus /lib/python).
 
 
 Mac OSX information
 -------------------
 
 Under OSX, there is a choice you need to make. Apple ships its own build
-of Python, which lives in the core OSX filesystem hierarchy. You can
+of Python, which lives in the core OSX filesystem hierarchy (/System/Library/Frameworks/Python.framework). You can
 also manually install a separate Python, either purely by hand
-(typically in /usr/local) or by using Fink, which puts everything under
-/sw. Which route to follow is a matter of personal preference, as I've
-seen users who favor each of the approaches. Here I will simply list the
-known installation issues under OSX, along with their solutions.
+(typically in /usr/local), by using Fink or DarwinPorts, which put everything under /sw or /opt respectively, or using the python.org "Framework" python, which installs a framework similar to the system python in /Library/Frameworks. The Enthought Python Distribution (http://www.enthought.com/products/epd.php), uses the python.org "Framework" python and thus also installs into /Library/Frameworks. Which route to follow is a matter of personal preference, as I've seen users who favor each of the approaches. 
+
+For users of OS X 10.5 (Leopard), the system python installation contains support for `DTrace`_, a kernel-level profiling system integrated into OS X 10.5. This facility provides significant advantage to developers and users interested in high-performance computing by using the system python.
+
+.. _DTrace: http://www.apple.com/macosx/technology/unix.html
+
+IPython is known to work with all the above installation options. As such, we do not endorse one choice over the others. Here we will simply list the known installation issues under OSX, along with their solutions.
 
 This page: http://geosci.uchicago.edu/~tobis/pylab.html contains
 information on this topic, with additional details on how to make
 IPython and matplotlib play nicely under OSX.
 
-To run IPython and readline on OSX "Leopard" system python, see the 
-wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard
-
 
-GUI problems
-------------
+GUI problems (older versions of OS X)
+-------------------------------------
 
-The following instructions apply to an install of IPython under OSX from
-unpacking the .tar.gz distribution and installing it for the default
-Python interpreter shipped by Apple. If you are using a fink install,
-fink will take care of these details for you, by installing IPython
-against fink's Python.
+The following instructions apply to an install of IPython under OSX before OS X 10.5 (users of OS X 10.5 see [#]_ ) by unpacking the .tar.gz distribution and installing it for the default Python interpreter shipped by Apple. If you are using a fink or DarwinPorts install, they will take care of these details for you, by installing IPython against their Python.
 
 IPython offers various forms of support for interacting with graphical
 applications from the command line, from simple Tk apps (which are in
 principle always supported by Python) to interactive control of WX, Qt
 and GTK apps. Under OSX, however, this requires that ipython is
 installed by calling the special pythonw script at installation time,
 which takes care of coordinating things with Apple's graphical environment.
 
 So when installing under OSX, it is best to use the following command:: 
 
 	$ sudo pythonw setup.py install --install-scripts=/usr/local/bin
 
-or
+or::
 
 	$ sudo pythonw setup.py install --install-scripts=/usr/bin
 	
 depending on where you like to keep hand-installed executables.
 
 The resulting script will have an appropriate shebang line (the first
 line in the script whic begins with #!...) such that the ipython
 interpreter can interact with the OS X GUI. If the installed version
 does not work and has a shebang line that points to, for example, just
 /usr/bin/python, then you might have a stale, cached version in your
 build/scripts-<python-version> directory. Delete that directory and
 rerun the setup.py.
 
 It is also a good idea to use the special flag ``--install-scripts`` as
 indicated above, to ensure that the ipython scripts end up in a location
 which is part of your $PATH. Otherwise Apple's Python will put the
 scripts in an internal directory not available by default at the command
 line (if you use /usr/local/bin, you need to make sure this is in your
 $PATH, which may not be true by default).
 
+.. [#] Users of OS X 10.5 who choose to use the system-installed python should install IPython using ``sudo python setupegg.py install`` from the IPython source directory or from `PyPI`_ using ``sudo easy_install ipython``.
+
+.. _PyPI: http://pypi.python.org/pypi
 
 Readline problems
 -----------------
 
-By default, the Python version shipped by Apple does not include the
-readline library, so central to IPython's behavior. If you install
+By default, the Python version shipped by Apple before OS X 10.5 does not include the readline library, so central to IPython's behavior. If you install
 IPython against Apple's Python, you will not have arrow keys, tab
 completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt
 readline library here:
 http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip
 
 If you are using OSX 10.4 (Tiger), after installing this package you
 need to either:
 
    1. move readline.so from /Library/Python/2.3 to
       /Library/Python/2.3/site-packages, or
    2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip
 
-Users installing against Fink's Python or a properly hand-built one
-should not have this problem.
 
+Beginning with OS X 10.5, Apple's python installation uses libedit, a BSD-licensed not-quite-compatible readline replacement. As of IPython 0.9, many of the issues related to the differences between readline and libedit have been resolved. If you find that you are experiencing readline-related issues (e.g. problems with tab-completion, history movement, or line editing), you can install Ludwig Schwartz's readline package which effectively replaces libedit with readline for packages installed via setuptools. If you installed IPython from the source directory using::
+
+	sudo python setupegg.py
+
+or from PyPI with::
+
+	sudo easy_install ipython
+
+then you can install the readline egg via [#]_::
+
+	sudo easy_install readline
+
+If needed, the readline egg can be build and installed from source (see the 
+wiki page at http://ipython.scipy.org/moin/InstallationOSXLeopard).
+
+Users installing against Fink or DarwinPorts's Python or a properly hand-built python installation should not have this problem.
+
+.. [#] If you have installed SVN 1.5, you will also to install a patch to setuptools before installing the readline egg. Use ``sudo easy_install http://www.jaraco.com/ASP/eggs/setuptools-0.6c8_svn15fix.egg``.
 
 DarwinPorts
 -----------
 
 I report here a message from an OSX user, who suggests an alternative
 means of using IPython under this operating system with good results.
 Please let me know of any updates that may be useful for this section.
 His message is reproduced verbatim below:
 
     From: Markus Banfi <markus.banfi-AT-mospheira.net> 
 
     As a MacOS X (10.4.2) user I prefer to install software using
     DawinPorts instead of Fink. I had no problems installing ipython
     with DarwinPorts. It's just: 
 
     sudo port install py-ipython 
 
     It automatically resolved all dependencies (python24, readline,
     py-readline). So far I did not encounter any problems with the
     DarwinPorts port of ipython. 
 
 
 
 Windows instructions
 --------------------
 
 Some of IPython's very useful features are:
 
     * Integrated readline support (Tab-based file, object and attribute
       completion, input history across sessions, editable command line,
       etc.)
     * Coloring of prompts, code and tracebacks.
 
 .. _pyreadline:
 
 These, by default, are only available under Unix-like operating systems.
 However, thanks to Gary Bishop's work, Windows XP/2k users can also
 benefit from them. His readline library originally implemented both GNU
 readline functionality and color support, so that IPython under Windows
 XP/2k can be as friendly and powerful as under Unix-like environments.
 
 This library, now named PyReadline, has been absorbed by the IPython
 team (Jörgen Stenarson, in particular), and it continues to be developed
 with new features, as well as being distributed directly from the
 IPython site.
 
 The PyReadline extension requires CTypes and the windows IPython
 installer needs PyWin32, so in all you need:
 
    1. PyWin32 from http://sourceforge.net/projects/pywin32.
    2. PyReadline for Windows from
       http://ipython.scipy.org/moin/PyReadline/Intro. That page contains
       further details on using and configuring the system to your liking.
    3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes
       from http://starship.python.net/crew/theller/ctypes(you must use
       version 0.9.1 or newer). This package is included in Python 2.5,
       so you don't need to manually get it if your Python version is 2.5
       or newer.
 
 Warning about a broken readline-like library: several users have
 reported problems stemming from using the pseudo-readline library at
 http://newcenturycomputers.net/projects/readline.html. This is a broken
 library which, while called readline, only implements an incomplete
 subset of the readline API. Since it is still called readline, it fools
 IPython's detection mechanisms and causes unpredictable crashes later.
 If you wish to use IPython under Windows, you must NOT use this library,
 which for all purposes is (at least as of version 1.6) terminally broken.
 
 
 Installation procedure
 ----------------------
 
 Once you have the above installed, from the IPython download directory
 grab the ipython-XXX.win32.exe file, where XXX represents the version
 number. This is a regular windows executable installer, which you can
 simply double-click to install. It will add an entry for IPython to your
 Start Menu, as well as registering IPython in the Windows list of
 applications, so you can later uninstall it from the Control Panel.
 
 IPython tries to install the configuration information in a directory
 named .ipython (_ipython under Windows) located in your 'home'
 directory. IPython sets this directory by looking for a HOME environment
 variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH
 (these are always defined by Windows). This typically gives something
 like C:\Documents and Settings\YourUserName, but your local details may
 vary. In this directory you will find all the files that configure
 IPython's defaults, and you can put there your profiles and extensions.
 This directory is automatically added by IPython to sys.path, so
 anything you place there can be found by import statements.
 
 
 Upgrading
 ---------
 
 For an IPython upgrade, you should first uninstall the previous version.
 This will ensure that all files and directories (such as the
 documentation) which carry embedded version strings in their names are
 properly removed.
 
 
 Manual installation under Win32
 -------------------------------
 
 In case the automatic installer does not work for some reason, you can
 download the ipython-XXX.tar.gz file, which contains the full IPython
 source distribution (the popular WinZip can read .tar.gz files). After
 uncompressing the archive, you can install it at a command terminal just
 like any other Python module, by using 'python setup.py install'.
 
 After the installation, run the supplied win32_manual_post_install.py
 script, which creates the necessary Start Menu shortcuts for you.
 
 
 .. upgrading:
 
 Upgrading from a previous version
 ---------------------------------
 
 If you are upgrading from a previous version of IPython, you may want
 to upgrade the contents of your ~/.ipython directory. Just run
 %upgrade, look at the diffs and delete the suggested files manually,
 if you think you can lose the old versions. %upgrade will never
 overwrite or delete anything.