.. @+leo-ver=5-thin
.. @+node:ekr.20131008041326.16093: * @file installing.txt
.. @@language rest
.. @@tabwidth -4
.. @+all
.. @+node:ekr.20131008041326.16094: ** @rst html/installing.html
##############
Installing Leo
##############

.. Links used in this document...

.. _`Leo's download page`: http://sourceforge.net/project/showfiles.php?group_id=3458&package_id=29106
.. _`PyEnchant`: https://sourceforge.net/projects/pyenchant/
.. _`PyQt`: http://www.riverbankcomputing.com/software/pyqt/intro
.. _`Python`: http://www.python.org
.. _`bzr`: http://bazaar.canonical.com/
.. _`Leo's help forum`: http://groups.google.com/group/leo-editor
.. _`Running Leo`: http://leoeditor.com/running.html

.. index:: Installing Leo

This chapter tells how to install and run Leo on Windows or Linux.
Leo can be installed on MacOS, but the process is difficult and not recommended.

**Important**: If you have *any* problems installing Leo,
please ask for help on `Leo's help forum`_.

.. contents::
    :depth: 2
    
.. @+node:ekr.20101125062332.5090: *3* Installing packages
Leo requires the `Python`_ and `PyQt_` package.
The `PyEnchant`_ package is optional. 

**Python**: Leo will work on any platform that supports Python 2.6 or
above, including Python 3.0 and above. To install Python, see
http://python.org.

**PyQt**: PyQt provides Leo's widgets. To install PyQt, get the binary
package from: http://www.riverbankcomputing.co.uk/software/pyqt/download
The PyQt version must match your installed Python version. Remember that
Leo requires Python 2.6 or later, or Python 3.0 or later. Now run the
binary PyQt installer.

**PyEnchant**: You must install the PyEnchant package if you want to use
Leo's Spell tab. Download and install the PyEnchant package from
http://pythonhosted.org/pyenchant/download.html There is an executable
installer for Windows users.

.. @+node:ekr.20100817101952.4303: *3* Installing Leo itself
.. links

.. _`latest stable release`: http://sourceforge.net/projects/leo/files/Leo/4.10%20final/
.. _`SourceForge`: https://sourceforge.net
.. _`Leo's snapshots page`:     http://www.greygreen.org/leo/
.. _`nightly snapshot`:             http://www.greygreen.org/leo/
.. _`Leo's latest sources`: https://code.launchpad.net/leo-editor/
.. _`Launchpad`: https://code.launchpad.net/


Leo's core code is always being improved and developed. Unit-testing
ensures that the daily commits are as bug-free as possible. Almost all of
the time, downloading the most recent `nightly snapshot`_ of the
development code is going to give you code that is just as stable and much
more up-to-date than the most recent `latest stable release`_ which most
Leonistas would consider already outdated.

If you are just checking Leo out, feel free to use the `latest stable release`_
download if it makes you feel more secure, but once you've
decided to work with Leo on a regular basis, we highly recommend regularly
keeping your installation up to date with the most recent `nightly snapshot`_.

To summarize, you may get Leo in three ways:

1. Download the `latest stable release`_ from `SourceForge`_. This release
   contains an executable installer. This release will usually be a bit out
   of date.

2. Download a `nightly snapshot`_ from `Leo's snapshots page`_. This page
   contains .zip archives of Leo's code from 1, 2, 5, 10, 30 and 90 days
   ago.
   
3. Download `Leo's latest sources`_ from `Launchpad`_ using `bzr`_.
   Installing bzr is non-trivial, but once set up this is the easiest way
   to get the latest version of Leo's code.
.. @+node:ekr.20100731112744.7276: *4* Installing Leo on Windows
Install Python and Qt, as described above (`Installing Packages`_).

Now you have a choice.  You can use Leo's binary (single-click) installer
or download Leo's sources directly.
.. @+node:ekr.20130807203905.16602: *5* Using the single-click installer
Leo has a binary installer for Windows, available at
http://sourceforge.net/projects/leo/files/Leo/ The binary installer
installs Leo and sets Windows file associations. Now see `Running Leo`_ for
how to run Leo after installing it.
.. @+node:ekr.20130807203905.16603: *5* Installing from sources
You may download Leo's sources in one of three ways, as described at:
http://leoeditor.com/download.html If the sources are zipped, unpack them
into a temp folder. You may place the sources anywhere you like, including
Python's \*site-packages* folder, for example,
C:\\Python26\\Lib\\site-packages.

Next, you will find it convenient to create Windows files associations for
.leo files, as described in the next section.
.. @+node:ekr.20130807203905.16597: *6* Creating Windows file associations
*Important*: Leo's binary Windows installer sets file associations
automatically, so this section is needed only if you are installing Leo
from a .zip file or other sources.

There are two ways of associating .leo files with Leo. The first uses the
Windows control panel, the second, the Windows console.

**Method 1: Using the Windows Control Panel**

The goal is that you want to associate .leo files with the following command::

    "<path to python>\python.exe" "<path to launchLeo.py>\launchLeo.py" "%1"
    
Before Windows 7, you do this with using the Folder Options control panel.
In Windows 7, you do this with the Default Programs control panel.

*Note*: "%1" passes just the file being clicked on, quoted for spaces etc.
The quotation marks are needed to handle file paths containing spaces.

*Warning:* In a batch file, %1 passes just the first command line parameter.
It is logical to expect %* to work for file associations just as in batch
files. Alas, it does not.

**Method 2: Using the Windows Console**

Open a Windows console with administrator privileges, then type::

    ftype LeoFile="<path to python>\pythonw.exe" "<path to launchLeo.py>\launchLeo.py" "%1" %*
    assoc .leo=LeoFile

And put this leo.bat in %PATH%::

    @start /b "Leo" "<path to python>\python.exe" "<path to launchLeo.py>\launchLeo.py" %*
    
You may omit the /b option if you want to create a separate console window for Leo.
.. @+node:ekr.20100731112744.7274: *4* Installing Leo on Linux
If you are using Debian/Ubuntu, find and install the debian package. This
provides the best integration with your desktop (file associations, icons, launcher
item). Failing that, follow the instructions below.

You may download Leo's sources in one of three ways, as described at:
http://leoeditor.com/download.html If the sources are zipped, unzip them
into the **unpacked folder** in your home directory. The unpacked folder
will be called something like leo-4-11.

You now have two choices:

1. You can run Leo from your home directory.
   Just add  ~/leo-4-5 to your path.

2. You can install leo into /usr/local/lib and /usr/local/bin by running Leo's install script as follows::

    cd ~/leo-4-11-final # Change version as appropriate.
    chmod u+x install
    sudo ./install

The install script will instruct you to add /usr/local/bin to your path.
You can, instead, add the following link::

    sudo ln -s /usr/local/lib/leo/ /usr/local/lib/python2.6/site-packages/

That's it!  See `Running Leo`_ for how to run Leo after installing it.
.. @+node:ekr.20100731112744.7275: *4* @rst-ignore Installing Leo on MacOS X
**Important**: Installing Leo on MacOS is difficult and not recommended.
Furthermore, Leo does not work as well on MacOS as on other platforms.

Here is how to install Leo on MacOS 10.5 (Leopard):

1. MacOS 10.5 comes with Python pre-installed.

   See http://www.python.org/download/mac/ and
   http://wiki.python.org/moin/MacPython/Leopard
   for information about using the latest version of Python.

2. Download and install bzr:

   - Download bzr from http://bazaar-vcs.org/Download

   - Install bzr using the file just downloaded.

3. Get Leo's sources from Leo's trunk::

    cd ~
    mkdir leo.repo
    cd leo.repo
    bzr init
    bzr branch lp:leo-editor
    cd leo-editor

4. If you already have Qt and PyQt installed, you can run the qt version of Leo as follows::

    python launchLeo.py --gui=qt

5. If you don't have Qt or PyQt installed, you will have to install Qt and PyQt
    from sources. There does not seem to be any pre-built binaries.

    A: You may need to install XCode from http://developer.apple.com/mac/
       in order to get a development environment.

    B: Download and install the sip package, following the direction at
       http://www.riverbankcomputing.co.uk/software/sip/download

    C: Download the OpenSource Qt libraries for Mac from
       http://www.qtsoftware.com/downloads

    D: At various points along the way you will need to build the sources::

         python configure.py 
         make
         sudo make install
.. @+node:ekr.20120229094652.15098: *4* Installing Leo on MacOs 10.7 Lion
.. .. http://groups.google.com/group/leo-editor/browse_thread/thread/92ae059cc5213ad3

**Important**: Installing Leo on MacOS is challenging. Furthermore, Leo
does not work as well on MacOS as on other platforms.

Many thanks to Ludwig Schwardt for the following installation instructions.

I recently received a new MacBook Pro and did a fresh upgrade to Mac OS
10.7 (Lion). I then used the opportunity to test out installation
procedures of various software on a clean system. My main finding is that
the excellent Homebrew (mxcl.github.com/homebrew/) makes things much easier
these days.

Why Homebrew? It does not try to replace every single bit of functionality
on your Mac with their own version, like Macports or fink. It reuses the
existing libraries as far as possible. No need to reinstall Python, for
example (one of my pet gripes when people try to install new software on
their Macs, and the source of much confusion and pain). It installs to
/usr/local, the standard place to find third-party libraries and headers,
instead of the obscure /opt or /sw. It's simple to use and to extend.

I last installed Leo on Mac OS 10.4 (Tiger) back in the Tk days, and
wondered what it looked like in Qt. All the horror stories of PyQT on Mac
discouraged me from trying this before, so I was keen to see if Homebrew
helps. Here is my installation write-up:

- Read the Homebrew installation instructions at
  https://github.com/mxcl/homebrew/wiki/Installation

- Make sure you have Xcode installed (test it by confirming that "gcc" runs
  in the Terminal). You can either get the full Xcode beast or the
  lean-and-mean Command-Line Tools for Xcode, as suggested in the Homebrew
  installation instructions.

- In preparation for Homebrew, the best option in my opinion is
  to delete /usr/local via::

    sudo rm -rf /usr/local

  and install any software in it via Homebrew instead. If this step
  fills you with dread and you do not want to lose your beloved
  third-party software, the second-best option is to make sure you
  have write permission for the directory via::

    sudo chown -R <your user name>:admin /usr/local

  If you don't know your username, run "whoami". :-) This is
  useful because homebrew actually discourages you from
  installing third-party software as the superuser (the usual Mac
  apps in /Applications are also installed as the normal user,
  for that matter).

- Install Homebrew (http://mxcl.github.com/homebrew/) by running the
  following command in the Terminal::

    /usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
    
- Run "brew doctor" and check any further suggestions to improve your system.

- Run "brew update" to get the latest formulas

- Install sip and note the caveat::

    brew install sip

  This warns you to add the local python directory to your PYTHONPATH.
  Make a note of what this is (especially if you are not on Lion!).

- Add the following lines to your ~/.bash_profile
  (or ~/.profile on Leopard). This is the default for LION::

      export PATH=/usr/local/bin:$PATH
      # This is for SIP (and PyQT) as suggested by Homebrew
      export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH

- Install PyQT::

    brew install pyqt
 
- Open a new Terminal tab / window so that the above settings take effect,
  and install Leo. I downloaded the Leo-4.9-final-a.zip, unzipped it, and
  ran "python launchLeo.py" inside the Leo directory.

It would really be great to get a Leo formula going for Homebrew. As
mentioned before, the main question is just where to place all the Leo
files in the /usr/local hierarchy.
.. @+node:ekr.20100817101952.4306: *4* Contributing to Leo with bzr


**Important**: This section tells how to set up bzr_ so that you can grab
the latest bzr sources using ``bzr pull``. However, you can get a nightly
snapshot of Leo's bzr repository (without installing bzr) from
http://www.greygreen.org/leo/

Many users will want to track the development version of Leo, in order to stay
on top of the latest features and bug fixes. Running the development version is
quite safe and easy, and it's also a requirement if you want to contribute to
Leo.

1. First, you need to get bzr_ (Bazaar) from http://bazaar-vcs.org. For windows
   users we recommend the standalone installer; the python installer may have
   problems pushing to Launchpad. Plain bzr installer only contains the command
   line version, so you might want to augment that with a friendly GUI - qbzr is
   recommended as it's the easiest one to install. It provides command like
   bzr qlog, bzr qannotate etc.

2. Get Leo from launchpad by doing::

     bzr branch lp:leo-editor

And that's it! You can run leo/core/leo.py directly. When you want to refresh the
code with latest modifications from Launchpad, run bzr pull.

If you make modifications to Leo (with the interest in sharing them with the Leo
community), you can check them in to your local branch by doing bzr checkin.
Now, to actually request your changes to be merged to Leo trunk, you need a
Launchpad account with RSA keys in place. There is showmedo video about how to
accomplish this in Windows using puttygen and pageant at
http://showmedo.com/videos/video?name=1510070&fromSeriesID=151.

After your Launchpad account is set up, go to
https://launchpad.net/leo-editor, choose "Code" tab -> Register Branch,
select Branch type "Hosted" and fill in descriptive details about the branch.
After that, go to the branch home page from Code tab again, and copy-paste the
push command line to terminal. For example, for branch::

    https://code.launchpad.net/~leo-editor-team/leo-editor/mod_rclick

The push command is::

    bzr push bzr+ssh://my_name@bazaar.launchpad.net/~leo-editor-team/leo-editor/mod_rclick    

You may wish to add --remember command line option to bzr push, to direct all
future pushes to that location. Then, you only need to execute bzr push.

After your branch is pushed, you can email the Leo mailing list and request it
to be reviewed and merged to trunk.
.. @-all
.. @-leo
