Mac/README - platform/external/python/cpython3 - Gitiles

 ============
 MacOSX Notes
 ============

 This document provides a quick overview of some Mac OS X specific features in
 the Python distribution.


 Building and using a universal binary of Python on Mac OS X
 ===========================================================

 1. What is a universal binary
 -----------------------------

 A universal binary build of Python contains object code for both PPC and i386
 and can therefore run at native speed on both classic powerpc based macs and
 the newer intel based macs.

 2. How do I build a universal binary
 ------------------------------------

 You can enable universal binaries by specifying the "--enable-universalsdk"
 flag to configure::

   $ ./configure --enable-universalsdk
   $ make
   $ make install

 This flag can be used a framework build of python, but also with a classic
 unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
 with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
 installing Xcode.


 Building and using a framework-based Python on Mac OS X.
 ========================================================


 1. Why would I want a framework Python instead of a normal static Python?
 --------------------------------------------------------------------------

 The main reason is because you want to create GUI programs in Python. With the
 exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
 from a fullblown MacOSX application (a ".app" bundle).

 While it is technically possible to create a .app without using frameworks you
 will have to do the work yourself if you really want this.

 A second reason for using frameworks is that they put Python-related items in
 only two places: "/Library/Framework/Python.framework" and
 "/Applications/MacPython 2.6".  This simplifies matters for users installing
 Python from a binary distribution if they want to get rid of it again. Moreover,
 due to the way frameworks work a user without admin privileges can install a
 binary distribution in his or her home directory without recompilation.

 2. How does a framework Python differ from a normal static Python?
 ------------------------------------------------------------------

 In everyday use there is no difference, except that things are stored in
 a different place. If you look in /Library/Frameworks/Python.framework
 you will see lots of relative symlinks, see the Apple documentation for
 details. If you are used to a normal unix Python file layout go down to
 Versions/Current and you will see the familiar bin and lib directories.

 3. Do I need extra packages?
 ----------------------------

 Yes, probably.  If you want Tkinter support you need to get the OSX AquaTk
 distribution, this is installed by default on Mac OS X 10.4 or later. If
 you want wxPython you need to get that. If you want Cocoa you need to get
 PyObjC.

 4. How do I build a framework Python?
 -------------------------------------

 This directory contains a Makefile that will create a couple of python-related
 applications (fullblown OSX .app applications, that is) in
 "/Applications/MacPython 2.6", and a hidden helper application Python.app
 inside the Python.framework, and unix tools "python" and "pythonw" into
 /usr/local/bin.  In addition it has a target "installmacsubtree" that installs
 the relevant portions of the Mac subtree into the Python.framework.

 It is normally invoked indirectly through the main Makefile, as the last step
 in the sequence

  1. ./configure --enable-framework

  2. make

  3. make install

 This sequence will put the framework in /Library/Framework/Python.framework,
 the applications in "/Applications/MacPython 2.6" and the unix tools in
 /usr/local/bin.

 Installing in another place, for instance $HOME/Library/Frameworks if you have
 no admin privileges on your machine, has only been tested very lightly. This
 can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
 The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
 will then also be deposited in $HOME. This is sub-optimal for the unix tools,
 which you would want in $HOME/bin, but there is no easy way to fix this right
 now.

 If you want to install some part, but not all, read the main Makefile. The
 frameworkinstall is composed of a couple of sub-targets that install the
 framework itself, the Mac subtree, the applications and the unix tools.

 There is an extra target frameworkinstallextras that is not part of the
 normal frameworkinstall which installs the Demo and Tools directories
 into "/Applications/MacPython 2.6", this is useful for binary distributions.

 What do all these programs do?
 ===============================

 "IDLE.app" is an integrated development environment for Python: editor,
 debugger, etc.

 "PythonLauncher.app" is a helper application that will handle things when you
 double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
 window and runs the scripts with the normal command-line Python. For the
 latter it runs the script in the Python.app interpreter so the script can do
 GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
 script to set runtime options. These options can be set once and for all
 through PythonLauncher's preferences dialog.

 The commandline scripts /usr/local/bin/python and pythonw can be used to run
 non-GUI and GUI python scripts from the command line, respectively.

 How do I create a binary distribution?
 ======================================

 Go to the directory "Mac/OSX/BuildScript". There you'll find a script
 "build-installer.py" that does all the work. This will download and build
 a number of 3th-party libaries, configures and builds a framework Python,
 installs it, creates the installer pacakge files and then packs this in a
 DMG image.

 The script will build a universal binary, you'll therefore have to run this
 script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.

 All of this is normally done completely isolated in /tmp/_py, so it does not
 use your normal build directory nor does it install into /.

 Because of the way the script locates the files it needs you have to run it
 from within the BuildScript directory. The script accepts a number of
 command-line arguments, run it with --help for more information.

 Odds and ends
 =============

 Something to take note of is that the ".rsrc" files in the distribution are
 not actually resource files, they're AppleSingle encoded resource files. The
 macresource module and the Mac/OSX/Makefile cater for this, and create
 ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
 files.

 	Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
 	Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006
	============
	MacOSX Notes
	============

	This document provides a quick overview of some Mac OS X specific features in
	the Python distribution.


	Building and using a universal binary of Python on Mac OS X
	===========================================================

	1. What is a universal binary
	-----------------------------

	A universal binary build of Python contains object code for both PPC and i386
	and can therefore run at native speed on both classic powerpc based macs and
	the newer intel based macs.

	2. How do I build a universal binary
	------------------------------------

	You can enable universal binaries by specifying the "--enable-universalsdk"
	flag to configure::

	$ ./configure --enable-universalsdk
	$ make
	$ make install

	This flag can be used a framework build of python, but also with a classic
	unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
	with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
	installing Xcode.


	Building and using a framework-based Python on Mac OS X.
	========================================================


	1. Why would I want a framework Python instead of a normal static Python?
	--------------------------------------------------------------------------

	The main reason is because you want to create GUI programs in Python. With the
	exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
	from a fullblown MacOSX application (a ".app" bundle).

	While it is technically possible to create a .app without using frameworks you
	will have to do the work yourself if you really want this.

	A second reason for using frameworks is that they put Python-related items in
	only two places: "/Library/Framework/Python.framework" and
	"/Applications/MacPython 2.6". This simplifies matters for users installing
	Python from a binary distribution if they want to get rid of it again. Moreover,
	due to the way frameworks work a user without admin privileges can install a
	binary distribution in his or her home directory without recompilation.

	2. How does a framework Python differ from a normal static Python?
	------------------------------------------------------------------

	In everyday use there is no difference, except that things are stored in
	a different place. If you look in /Library/Frameworks/Python.framework
	you will see lots of relative symlinks, see the Apple documentation for
	details. If you are used to a normal unix Python file layout go down to
	Versions/Current and you will see the familiar bin and lib directories.

	3. Do I need extra packages?
	----------------------------

	Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
	distribution, this is installed by default on Mac OS X 10.4 or later. If
	you want wxPython you need to get that. If you want Cocoa you need to get
	PyObjC.

	4. How do I build a framework Python?
	-------------------------------------

	This directory contains a Makefile that will create a couple of python-related
	applications (fullblown OSX .app applications, that is) in
	"/Applications/MacPython 2.6", and a hidden helper application Python.app
	inside the Python.framework, and unix tools "python" and "pythonw" into
	/usr/local/bin. In addition it has a target "installmacsubtree" that installs
	the relevant portions of the Mac subtree into the Python.framework.

	It is normally invoked indirectly through the main Makefile, as the last step
	in the sequence

	1. ./configure --enable-framework

	2. make

	3. make install

	This sequence will put the framework in /Library/Framework/Python.framework,
	the applications in "/Applications/MacPython 2.6" and the unix tools in
	/usr/local/bin.

	Installing in another place, for instance $HOME/Library/Frameworks if you have
	no admin privileges on your machine, has only been tested very lightly. This
	can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
	The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
	will then also be deposited in $HOME. This is sub-optimal for the unix tools,
	which you would want in $HOME/bin, but there is no easy way to fix this right
	now.

	If you want to install some part, but not all, read the main Makefile. The
	frameworkinstall is composed of a couple of sub-targets that install the
	framework itself, the Mac subtree, the applications and the unix tools.

	There is an extra target frameworkinstallextras that is not part of the
	normal frameworkinstall which installs the Demo and Tools directories
	into "/Applications/MacPython 2.6", this is useful for binary distributions.

	What do all these programs do?
	===============================

	"IDLE.app" is an integrated development environment for Python: editor,
	debugger, etc.

	"PythonLauncher.app" is a helper application that will handle things when you
	double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
	window and runs the scripts with the normal command-line Python. For the
	latter it runs the script in the Python.app interpreter so the script can do
	GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
	script to set runtime options. These options can be set once and for all
	through PythonLauncher's preferences dialog.

	The commandline scripts /usr/local/bin/python and pythonw can be used to run
	non-GUI and GUI python scripts from the command line, respectively.

	How do I create a binary distribution?
	======================================

	Go to the directory "Mac/OSX/BuildScript". There you'll find a script
	"build-installer.py" that does all the work. This will download and build
	a number of 3th-party libaries, configures and builds a framework Python,
	installs it, creates the installer pacakge files and then packs this in a
	DMG image.

	The script will build a universal binary, you'll therefore have to run this
	script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.

	All of this is normally done completely isolated in /tmp/_py, so it does not
	use your normal build directory nor does it install into /.

	Because of the way the script locates the files it needs you have to run it
	from within the BuildScript directory. The script accepts a number of
	command-line arguments, run it with --help for more information.

	Odds and ends
	=============

	Something to take note of is that the ".rsrc" files in the distribution are
	not actually resource files, they're AppleSingle encoded resource files. The
	macresource module and the Mac/OSX/Makefile cater for this, and create
	".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
	files.

	Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
	Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006