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

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

 This document provides a quick introduction to framework-based Python, its
 advantages, and how to build it.

 1. Why would I want a framework Python in stead 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 it appears that 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.3.
 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.

 Incidentally, the procedure described here is also the procedure that is
 used to create the MacPython binary installer, so the information here
 should theoretically allow you to rebuild that.

 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 to be able to use the PythonIDE you will need to
 get Waste, an all-singing-all-dancing TextEdit replacement, from
 www.merzwaren.com. It will unpack into a folder named something like "Waste
 2.1 Distribution". Make a symlink called "waste" to this folder, somewhere
 beside your Python source distribution (it can be "../waste", "../../waste",
 etc).

 If you want Tkinter support you need to get the OSX AquaTk distribution. If
 you want wxPython you need to get that. If you want Cocoa you need to get
 pyobjc. Because all these are currently in a state of flux please refer to
 http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more
 information.

 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.3, 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 frameworkinstall

 This sequence will put the framework in /Library/Framework/Python.framework,
 the applications in /Applications/Python 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.3 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.

 Note that there are no references to the actual locations in the code or
 resource files, so you are free to move things around afterwards. For example,
 you could use --enable-framework=/tmp/newversion/Library/Frameworks and use
 /tmp/newversion as the basis for an installer or something.

 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.3, this is useful for binary distributions.

 If you want to run the Makefile here directly, in stead of through the main
 Makefile, you will have to pass various variable-assignments. Read the
 beginning of the Makefile for details.


 5. What do all these programs do?
 ---------------------------------

 PythonIDE.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.

 BuildApplet.app creates an applet from a Python script. Drop the script on it
 and out comes a full-featured MacOS application. There is much more to this,
 to be supplied later. Some useful (but outdated) info can be found in
 Mac/Demo.

 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.

 6. How do I create a binary distribution?
 -----------------------------------------

 Go to the Mac/OSX/Dist directory. There you find a script "build" that
 does all the work: it configures and builds a framework Python, installs
 it, creates the installer package file and packs this in a DMG image.

 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 the build script locates the Python source tree relative to its own
 pathname you may have to run it with a full pathname. If you are debugging your
 install you can pass one argument: the pathname where the build directory
 is located (i.e. where configure and make will be run), then this directory
 will be saved between runs of the build script. Do *not* specify your normal
 build directory here.

 build will ask you whether you have updated the readme file, and it will offer
 to include the full documentation in the installer. That option has not
 been used for a while, and it may not work.

 If you need to execute code on the client machine after installing Python
 you can add this to resources/postflight. If you need to do even stranger things
 you have to read Apple's documentation on PackageMaker and read the source
 of Mac/scripts/buildpkg.py.

 7. Odds and ends.
 -----------------

 The PythonLauncher is actually an Objective C Cocoa app built with Project
 Builder. It could be a Python program, except for the fact that pyobjc is not
 a part of the core distribution, and is not completely finished yet as of this
 writing.

 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, 20-Jun-2003.
	Building and using a framework-based Python on Mac OS X.
	--------------------------------------------------------

	This document provides a quick introduction to framework-based Python, its
	advantages, and how to build it.

	1. Why would I want a framework Python in stead 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 it appears that 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.3.
	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.

	Incidentally, the procedure described here is also the procedure that is
	used to create the MacPython binary installer, so the information here
	should theoretically allow you to rebuild that.

	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 to be able to use the PythonIDE you will need to
	get Waste, an all-singing-all-dancing TextEdit replacement, from
	www.merzwaren.com. It will unpack into a folder named something like "Waste
	2.1 Distribution". Make a symlink called "waste" to this folder, somewhere
	beside your Python source distribution (it can be "../waste", "../../waste",
	etc).

	If you want Tkinter support you need to get the OSX AquaTk distribution. If
	you want wxPython you need to get that. If you want Cocoa you need to get
	pyobjc. Because all these are currently in a state of flux please refer to
	http://www.cwi.nl/~jack/macpython.html, which should contain pointers to more
	information.

	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.3, 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 frameworkinstall

	This sequence will put the framework in /Library/Framework/Python.framework,
	the applications in /Applications/Python 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.3 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.

	Note that there are no references to the actual locations in the code or
	resource files, so you are free to move things around afterwards. For example,
	you could use --enable-framework=/tmp/newversion/Library/Frameworks and use
	/tmp/newversion as the basis for an installer or something.

	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.3, this is useful for binary distributions.

	If you want to run the Makefile here directly, in stead of through the main
	Makefile, you will have to pass various variable-assignments. Read the
	beginning of the Makefile for details.


	5. What do all these programs do?
	---------------------------------

	PythonIDE.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.

	BuildApplet.app creates an applet from a Python script. Drop the script on it
	and out comes a full-featured MacOS application. There is much more to this,
	to be supplied later. Some useful (but outdated) info can be found in
	Mac/Demo.

	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.

	6. How do I create a binary distribution?
	-----------------------------------------

	Go to the Mac/OSX/Dist directory. There you find a script "build" that
	does all the work: it configures and builds a framework Python, installs
	it, creates the installer package file and packs this in a DMG image.

	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 the build script locates the Python source tree relative to its own
	pathname you may have to run it with a full pathname. If you are debugging your
	install you can pass one argument: the pathname where the build directory
	is located (i.e. where configure and make will be run), then this directory
	will be saved between runs of the build script. Do not specify your normal
	build directory here.

	build will ask you whether you have updated the readme file, and it will offer
	to include the full documentation in the installer. That option has not
	been used for a while, and it may not work.

	If you need to execute code on the client machine after installing Python
	you can add this to resources/postflight. If you need to do even stranger things
	you have to read Apple's documentation on PackageMaker and read the source
	of Mac/scripts/buildpkg.py.

	7. Odds and ends.
	-----------------

	The PythonLauncher is actually an Objective C Cocoa app built with Project
	Builder. It could be a Python program, except for the fact that pyobjc is not
	a part of the core distribution, and is not completely finished yet as of this
	writing.

	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, 20-Jun-2003.