Merge pull request #28 from ctismer/master

Finalizing the OS X doku (in-progress)

1 files changed, 326 insertions, 38 deletions

diff --git a/README.rst b/README.rst
index 8f9625f0c..f8ce39ef9 100644
--- a/README.rst
+++ b/README.rst
@@ -26,10 +26,10 @@ PySide requires Python 2.6 or later and Qt 4.6 or better. Qt 5.x is currently no
 Installation
 ============
 
-Installing prerequisities
--------------------------
+Installing prerequisites
+------------------------
 
-Install latest `pip` distribution: download `get-pip.py
+Install latest ``pip`` distribution: download `get-pip.py
 <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_ and run it using
 the ``python`` interpreter.
 
@@ -38,13 +38,13 @@ Installing PySide on a Windows System
 
 To install PySide on Windows you can choose from the following options:
 
-#. Use pip to install the `wheel` binary packages:
+#. Use pip to install the ``wheel`` binary packages:
    
    ::
 
       pip install -U PySide --use-wheel -f http://download.qt-project.org/official_releases/pyside/
 
-#. Use setuptools to install the `egg` binary packages (deprecated):
+#. Use setuptools to install the ``egg`` binary packages (deprecated):
    
    ::
 
@@ -73,13 +73,13 @@ Alternatively you can use `Homebrew <http://brew.sh/>`_ and install Qt with
 
 To install PySide on Mac OS X you can choose from the following options:
 
-#. Use pip to install the `wheel` binary packages:
+#. Use pip to install the ``wheel`` binary packages:
    
    ::
 
       $ pip install -U PySide --use-wheel -f http://download.qt-project.org/official_releases/pyside/
 
-#. Use setuptools to install the `egg` binary packages (deprecated):
+#. Use setuptools to install the ``egg`` binary packages (deprecated):
    
    ::
 
@@ -105,11 +105,12 @@ Installing PySide on a Linux System
 We do not provide binaries for Linux. Please read the build instructions in section
 ``Building PySide on a Linux System``.
 
+
 Building PySide on a Windows System
 ===================================
 
-Installing prerequisities
--------------------------
+Windows: Installing prerequisites
+---------------------------------
 
 #. Install `Python
    <http://www.python.org/download/>`_.
@@ -117,6 +118,7 @@ Installing prerequisities
 #. Install `Qt 4.8 libraries for Windows VS 2008 edition
    <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2008.exe>`_
    when building against Python 2.6, 2.7 or 3.2.
+   
    Install `Qt 4.8 libraries for Windows VS 2010 edition
    <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2010.exe>`_
    when building against Python 3.3 or 3.4.
@@ -127,6 +129,7 @@ Installing prerequisities
 #. Install `Windows SDK v7.0
    <http://www.microsoft.com/en-us/download/details.aspx?id=3138>`_
    when building against Python 2.6, 2.7 or 3.2.
+   
    Install `Windows SDK v7.1
    <http://www.microsoft.com/en-us/download/details.aspx?id=8279>`_
    when building against Python 3.3 or 3.4.
@@ -137,7 +140,7 @@ Installing prerequisities
 #. (Optional) Install `OpenSSL
    <http://slproweb.com/products/Win32OpenSSL.html>`_.
 
-#. Install latest `pip` distribution into the Python you
+#. Install latest ``pip`` distribution into the Python you
    installed in the first step: download `get-pip.py 
    <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_ and run it using
    the ``python`` interpreter of your Python 2.7 installation using a
@@ -153,8 +156,9 @@ Installing prerequisities
 
       c:\> c:\Python27\Scripts\pip install wheel
 
-Building PySide distribution
-----------------------------
+
+Windows: Building PySide distribution
+-------------------------------------
 
 #. Download and extract `PySide source distribution
    <https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz>`_
@@ -165,14 +169,15 @@ Building PySide distribution
 
       c:\> cd PySide-1.2.2
 
-#. Build the `wheel` binary distribution:
+#. Build the ``wheel`` binary distribution:
 
    ::
 
       c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
 
-Building PySide distribution from git repository
-------------------------------------------------
+
+Windows: Building PySide distribution from a Git repository
+-----------------------------------------------------------
 
 #. Clone ``PySide`` setup scripts from git repository:
 
@@ -198,8 +203,9 @@ Building PySide distribution from git repository
 
       c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
 
-Installing PySide distribution
-------------------------------
+
+Windows: Installing PySide distribution
+---------------------------------------
 
 #. After the successful build, install the distribution with ``pip``:
    
@@ -207,16 +213,17 @@ Installing PySide distribution
 
       c:\> c:\Python27\Scripts\pip install --use-wheel dist\PySide-1.2.2-cp27-none-win32.whl
 
-Installing PySide distribution into ``virtual`` Python environment
-------------------------------------------------------------------
 
-#. Install latest `virtualenv` distribution:
+Windows: Installing PySide distribution into ``virtual`` Python environment
+---------------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
 
    ::
 
       c:\> c:\Python27\Scripts\pip install virtualenv
 
-#. Use `virtualenv` to make a workspace:
+#. Use ``virtualenv`` to make a workspace:
 
    ::
 
@@ -234,11 +241,287 @@ Installing PySide distribution into ``virtual`` Python environment
 
       c:\> Scripts\pip install --use-wheel ..\dist\PySide-1.2.2-cp27-none-win32.whl
 
+
+Building PySide on a Mac OS X System
+====================================
+
+Mac OS X is a Unix flavor, partially based upon 
+`BSD Unix <http://en.wikipedia.org/wiki/Berkeley_Software_Distribution>`_.
+
+The supported Mac OS X versions created by `Apple <http://www.apple.com/>`_ are
+
+- OS X 10.6 *Snow Leopard*
+- OS X 10.7 *Lion*
+- OS X 10.8 *Mountain Lion*
+- OS X 10.9 *Mavericks*
+
+Mac OS X is a proprietary UNIX flavor of BSD Unix and only partially similar to
+Linux. Therefore, the usual packages from Linux distributions cannot be used
+without modifications.
+
+There are several known package managers which provide support for Mac OS X, namely
+
+- `MacPorts <http://www.macports.org/>`_
+- `Fink <http://www.finkproject.org/>`_
+- `Homebrew <http://brew.sh/>`_
+
+The main purpose of all of these projects is to provide the missing Linux packages
+for Mac OS X.
+
+Throughout this tutorial, we are only using `Homebrew <http://brew.sh/>`_, because
+it appears to be the most light-weight package manager available. All installations
+are made to /usr/local/(bin|lib|include|shared) by simple symlinks.
+
+But it should be easy to translate these instructions for the other, heavier package managers.
+
+
+Mac OS X: Installing prerequisites
+----------------------------------
+
+#. Install Package Manager:
+
+   ::
+   
+      $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
+
+Follow the on-screen instructions to make adjustions, especially run
+ 
+   ::
+        
+      $ brew doctor
+      
+Also see the `homebrew homepage <http://brew.sh/>`_ for further information
+
+#. Install `Xcode <https://itunes.apple.com/en/app/xcode/id497799835?mt=12>`_ (optional):
+
+Follow the on-screen instructions. If you selected any extensions to be installed,
+wait for their completion before you proceed.
+
+.. note::
+
+    If you are using Mavericks, you can also use the Xcode Command Line Tools without actually installing Xcode
+    (not tested, see this article: `How to Install Command Line Tools in OS X Mavericks (Without Xcode)
+    <http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/>`_).
+
+#. Install the Xcode command Line Tools:
+
+   After Xcode installation has finished, you can open a command shell and issue
+   
+   ::
+   
+      $ xcode-select --install
+      
+   This will open a dialog window with further instructions.
+   After the command line tools are installed, you will not need to use Xcode again
+   in order to set up PySide.
+
+#. Install build dependencies:
+
+   ::
+
+      $ brew install python cmake qt
+
+Remark: This installs ``Homebrew`` Python, which is fine for you as a single user.
+If you are considering to build installers for external users, see the section
+``About PySide Distributions``.
+
+#. Install latest ``pip`` distribution into the Python you
+   installed in the first step: download `get-pip.py 
+   <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_ and run it using
+   the ``python`` interpreter of your Python 2.7 installation using a
+   command prompt:
+
+   ::
+
+      $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
+      $ sudo python2.7 get-pip.py
+
+.. note::
+    
+  There are situations with older Python versions, where the above procedure does not work.
+  You can then use this last-resort work-around (tested)::
+  
+      $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
+      $ sudo python2.7 ez_setup.py
+      $ sudo easy_install pip
+      $ sudo pip install setuptools -U
+      $ sudo pip install wheel -U
+
+
+#. Install latest ``wheel`` distribution:
+
+   ::
+
+      $ sudo pip2.7 install wheel
+
+
+Mac OS X: About PySide Distribution
+-----------------------------------
+
+If you want to build PySide for your own use, the above instructions are ok.
+
+But when you are considering to build PySide for other versions or other users, you need
+to be aware of the following caveat:
+
+- Mac OS X has the concept of a ``MACOSX_DEPLOYMENT_TARGET``
+
+- The current deployment targets which work with PySide are 10.6 to 10.9 .
+
+- All binary installers from https://www.python.org are built with the setting
+
+    ::
+    
+        $ export MACOSX_DEPLOYMENT_TARGET=10.6  # Snow Leopard
+
+- The default setting for the deployment target of an extension (like PySide)
+  is always inherited from the Python used for building.
+  You can set the deployment target higher than that, but not below the
+  OS X version that was set during building your Python installation.
+  
+- Current distributions like Homebrew set the deployment target to the same
+  value as the OS version they are built with. (I.E. 10.9 for Mavericks).
+  
+- Example: A PySide, built on Mavericks, will therefore not run on a Python that was built
+  for Mountain Lion.
+
+Recommendation:
+
+- Use Homebrew's simplicity for your own machine. Do not use it for distributing.
+
+- Use one of the `Python.org Distributions <https://www.python.org/downloads/>`_
+  or 
+  
+- Build your own Python, either from a tar archive (
+  `Python 2.7 <https://www.python.org/ftp/python/2.7.6/Python-2.7.6.tgz>`_ or
+  `Python 3.4 <https://www.python.org/ftp/python/3.4.0/Python-3.4.0.tgz>`_), or from a
+  `Mercurial repository <https://docs.python.org/devguide/>`_ with an explicit setting of
+  ``MACOSX_DEPLOYMENT_TARGET``.
+
+Mac OS X: Building PySide distribution
+--------------------------------------
+
+#. Download ``PySide`` source distribution:
+
+   ::
+
+      $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz
+
+#. Extract the source distribution:
+
+   ::
+
+      $ tar -xvzf PySide-1.2.2.tar.gz
+
+#. Switch to the distribution directory:
+
+   ::
+
+      $ cd PySide-1.2.2
+
+#. Build the ``wheel`` binary distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel
+
+
+Mac OS X: Building PySide distribution from a Git repository
+------------------------------------------------------------
+
+#. Clone ``PySide`` setup scripts from git repository:
+
+   ::
+
+      $ git clone https://github.com/PySide/pyside-setup.git pyside-setup
+
+#. Switch to the ``pyside-setup`` directory:
+
+   ::
+
+      $ cd pyside-setup
+
+#. Build ``PySide`` distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --version=1.2.2
+
+   ..  commented out, working on this
+        #. Optionally you can build standalone version of distribution with embedded Qt libs:
+        
+           ::
+        
+              $ python2.7 setup.py bdist_wheel --version=1.2.2 --standalone
+
+#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel
+
+
+Mac OS X: Installing PySide distribution
+----------------------------------------
+
+#. After the successful build, install the distribution with ``pip``:
+   
+   ::
+
+      $ sudo pip2.7 install --use-wheel dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+   
+   ::
+
+      $ sudo python2.7 pyside_postinstall.py -install
+
+
+Mac OS X: Installing PySide distribution into ``virtual`` Python environment
+----------------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
+
+   ::
+
+      $ sudo pip2.7 virtualenv
+
+#. Use ``virtualenv`` to make a workspace:
+
+   ::
+
+      $ virtualenv-2.7 env
+
+#. Activate the virtual Python in the ``env`` directory:
+
+   ::
+
+      $ source env/bin/activate
+
+#. Install the distribution with ``pip``:
+   
+   ::
+
+      (env) $ pip install --use-wheel ../dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+   
+   ::
+
+      (env) $ pyside_postinstall.py -install
+      
+#. Leave the virtual environment (optional):
+
+   ::
+   
+      (env) $ deactivate
+      $ 
+
+
 Building PySide on a Linux System (Ubuntu 12.04 - 14.04)
 ========================================================
 
-Installing prerequisities
--------------------------
+Linux: Installing prerequisites
+-------------------------------
 
 #. Install build dependencies:
 
@@ -246,7 +529,7 @@ Installing prerequisities
 
       $ sudo apt-get install build-essential git cmake libqt4-dev libphonon-dev python2.7-dev libxml2-dev libxslt1-dev qtmobility-dev
 
-#. Install latest `pip` distribution into the Python you
+#. Install latest ``pip`` distribution into the Python you
    installed in the first step: download `get-pip.py 
    <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`_ and run it using
    the ``python`` interpreter of your Python 2.7 installation using a
@@ -257,14 +540,15 @@ Installing prerequisities
       $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
       $ sudo python2.7 get-pip.py
 
-#. Install latest `wheel` distribution:
+#. Install latest ``wheel`` distribution:
 
    ::
 
       $ sudo pip2.7 install wheel
 
-Building PySide distribution
-----------------------------
+
+Linux: Building PySide distribution
+-----------------------------------
 
 #. Download ``PySide`` source distribution:
 
@@ -284,7 +568,7 @@ Building PySide distribution
 
       $ cd PySide-1.2.2
 
-#. Build the `wheel` binary distribution:
+#. Build the ``wheel`` binary distribution:
 
    ::
 
@@ -296,8 +580,9 @@ Building PySide distribution
 
       $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --standalone
 
-Building PySide distribution from git repository
-------------------------------------------------
+
+Linux: Building PySide distribution from a Git repository
+---------------------------------------------------------
 
 #. Clone ``PySide`` setup scripts from git repository:
 
@@ -329,8 +614,9 @@ Building PySide distribution from git repository
 
       $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4
 
-Installing PySide distribution
-------------------------------
+
+Linux: Installing PySide distribution
+-------------------------------------
 
 #. After the successful build, install the distribution with ``pip``:
    
@@ -344,16 +630,17 @@ Installing PySide distribution
 
       $ sudo python2.7 pyside_postinstall.py -install
 
-Installing PySide distribution into ``virtual`` Python environment
-------------------------------------------------------------------
 
-#. Install latest `virtualenv` distribution:
+Linux: Installing PySide distribution into ``virtual`` Python environment
+-------------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
 
    ::
 
       $ sudo pip2.7 virtualenv
 
-#. Use `virtualenv` to make a workspace:
+#. Use ``virtualenv`` to make a workspace:
 
    ::
 
@@ -388,13 +675,14 @@ Usage on a Windows System
 
       c:\> c:\Python27\python.exe setup.py [distribution_type] [options]
 
-Usage on a Linux System
------------------------
+Usage on a Linux/Mac OS X System
+--------------------------------
     
    ::
 
       python2.7 setup.py [distribution_type] [options]
 
+
 Distribution types
 ------------------