/Mac/README

http://unladen-swallow.googlecode.com/ · #! · 218 lines · 156 code · 62 blank · 0 comment · 0 complexity · ad8d31ec7dca91549bc2162241d48c43 MD5 · raw file

  1. ============
  2. MacOSX Notes
  3. ============
  4. This document provides a quick overview of some Mac OS X specific features in
  5. the Python distribution.
  6. Mac-specific arguments to configure
  7. ===================================
  8. * ``--enable-framework``
  9. If this argument is specified the build will create a Python.framework rather
  10. than a traditional Unix install. See the section
  11. _`Building and using a framework-based Python on Mac OS X` for more
  12. information on frameworks.
  13. * ``--with-framework-name=NAME``
  14. Specify the name for the python framework, defaults to ``Python``. This option
  15. is only valid when ``--enable-framework`` is specified.
  16. * ``--enable-universalsdk[=PATH]``
  17. Create a universal binary build of of Python. This can be used with both
  18. regular and framework builds.
  19. The optional argument specifies with OSX SDK should be used to perform the
  20. build. This defaults to ``/Developer/SDKs/MacOSX.10.4u.sdk``, specify
  21. ``/`` when building on a 10.5 system, especially when building 64-bit code.
  22. See the section _`Building and using a universal binary of Python on Mac OS X`
  23. for more information.
  24. * ``--with-univeral-archs=VALUE``
  25. Specify the kind of universal binary that should be created. This option is
  26. only valid when ``--enable-universalsdk`` is specified.
  27. Building and using a universal binary of Python on Mac OS X
  28. ===========================================================
  29. 1. What is a universal binary
  30. -----------------------------
  31. A universal binary build of Python contains object code for both PPC and i386
  32. and can therefore run at native speed on both classic powerpc based macs and
  33. the newer intel based macs.
  34. 2. How do I build a universal binary
  35. ------------------------------------
  36. You can enable universal binaries by specifying the "--enable-universalsdk"
  37. flag to configure::
  38. $ ./configure --enable-universalsdk
  39. $ make
  40. $ make install
  41. This flag can be used a framework build of python, but also with a classic
  42. unix build. Either way you will have to build python on Mac OS X 10.4 (or later)
  43. with Xcode 2.1 (or later). You also have to install the 10.4u SDK when
  44. installing Xcode.
  45. The option ``--enable-universalsdk`` has an optional argument to specify an
  46. SDK, which defaults to the 10.4u SDK. When you build on OSX 10.5 or later
  47. you can use the system headers instead of an SDK::
  48. $ ./configure --enable-universalsdk=/
  49. 2.1 Flavours of universal binaries
  50. ..................................
  51. It is possible to build a number of flavours of the universal binary build,
  52. the default is a 32-bit only binary (i386 and ppc). The flavour can be
  53. specified using the option ``--with-universal-archs=VALUE``. The following
  54. values are available:
  55. * ``32-bit``: ``ppc``, ``i386``
  56. * ``64-bit``: ``ppc64``, ``x86_64``
  57. * ``all``: ``ppc``, ``ppc64``, ``i386``, ``x86_64``
  58. * ``3-way``: ``ppc``, ``i386`` and ``x86_64``
  59. * ``intel``: ``i386``, ``x86_64``
  60. To build a universal binary that includes a 64-bit architecture you must build
  61. on a system running OSX 10.5 or later. The ``all`` flavour can only be build on
  62. OSX 10.5.
  63. Building and using a framework-based Python on Mac OS X.
  64. ========================================================
  65. 1. Why would I want a framework Python instead of a normal static Python?
  66. --------------------------------------------------------------------------
  67. The main reason is because you want to create GUI programs in Python. With the
  68. exception of X11/XDarwin-based GUI toolkits all GUI programs need to be run
  69. from a fullblown MacOSX application (a ".app" bundle).
  70. While it is technically possible to create a .app without using frameworks you
  71. will have to do the work yourself if you really want this.
  72. A second reason for using frameworks is that they put Python-related items in
  73. only two places: "/Library/Framework/Python.framework" and
  74. "/Applications/MacPython 2.6". This simplifies matters for users installing
  75. Python from a binary distribution if they want to get rid of it again. Moreover,
  76. due to the way frameworks work a user without admin privileges can install a
  77. binary distribution in his or her home directory without recompilation.
  78. 2. How does a framework Python differ from a normal static Python?
  79. ------------------------------------------------------------------
  80. In everyday use there is no difference, except that things are stored in
  81. a different place. If you look in /Library/Frameworks/Python.framework
  82. you will see lots of relative symlinks, see the Apple documentation for
  83. details. If you are used to a normal unix Python file layout go down to
  84. Versions/Current and you will see the familiar bin and lib directories.
  85. 3. Do I need extra packages?
  86. ----------------------------
  87. Yes, probably. If you want Tkinter support you need to get the OSX AquaTk
  88. distribution, this is installed by default on Mac OS X 10.4 or later. If
  89. you want wxPython you need to get that. If you want Cocoa you need to get
  90. PyObjC.
  91. 4. How do I build a framework Python?
  92. -------------------------------------
  93. This directory contains a Makefile that will create a couple of python-related
  94. applications (fullblown OSX .app applications, that is) in
  95. "/Applications/MacPython 2.6", and a hidden helper application Python.app
  96. inside the Python.framework, and unix tools "python" and "pythonw" into
  97. /usr/local/bin. In addition it has a target "installmacsubtree" that installs
  98. the relevant portions of the Mac subtree into the Python.framework.
  99. It is normally invoked indirectly through the main Makefile, as the last step
  100. in the sequence::
  101. $ ./configure --enable-framework
  102. $ make
  103. $ make install
  104. This sequence will put the framework in /Library/Framework/Python.framework,
  105. the applications in "/Applications/MacPython 2.6" and the unix tools in
  106. /usr/local/bin.
  107. It is possible to select a different name for the framework using the configure
  108. option ``--with-framework-name=NAME``. This makes it possible to have several
  109. parallel installs of a Python framework.
  110. Installing in another place, for instance $HOME/Library/Frameworks if you have
  111. no admin privileges on your machine, has only been tested very lightly. This
  112. can be done by configuring with --enable-framework=$HOME/Library/Frameworks.
  113. The other two directories, "/Applications/MacPython-2.6" and /usr/local/bin,
  114. will then also be deposited in $HOME. This is sub-optimal for the unix tools,
  115. which you would want in $HOME/bin, but there is no easy way to fix this right
  116. now.
  117. What do all these programs do?
  118. ===============================
  119. "IDLE.app" is an integrated development environment for Python: editor,
  120. debugger, etc.
  121. "PythonLauncher.app" is a helper application that will handle things when you
  122. double-click a .py, .pyc or .pyw file. For the first two it creates a Terminal
  123. window and runs the scripts with the normal command-line Python. For the
  124. latter it runs the script in the Python.app interpreter so the script can do
  125. GUI-things. Keep the "alt" key depressed while dragging or double-clicking a
  126. script to set runtime options. These options can be set once and for all
  127. through PythonLauncher's preferences dialog.
  128. "BuildApplet.app" creates an applet from a Python script. Drop the script on it
  129. and out comes a full-featured MacOS application. There is much more to this,
  130. to be supplied later. Some useful (but outdated) info can be found in
  131. Mac/Demo.
  132. The commandline scripts /usr/local/bin/python and pythonw can be used to run
  133. non-GUI and GUI python scripts from the command line, respectively.
  134. How do I create a binary distribution?
  135. ======================================
  136. Go to the directory "Mac/OSX/BuildScript". There you'll find a script
  137. "build-installer.py" that does all the work. This will download and build
  138. a number of 3th-party libaries, configures and builds a framework Python,
  139. installs it, creates the installer pacakge files and then packs this in a
  140. DMG image.
  141. The script will build a universal binary, you'll therefore have to run this
  142. script on Mac OS X 10.4 or later and with Xcode 2.1 or later installed.
  143. All of this is normally done completely isolated in /tmp/_py, so it does not
  144. use your normal build directory nor does it install into /.
  145. Because of the way the script locates the files it needs you have to run it
  146. from within the BuildScript directory. The script accepts a number of
  147. command-line arguments, run it with --help for more information.
  148. Odds and ends
  149. =============
  150. Something to take note of is that the ".rsrc" files in the distribution are
  151. not actually resource files, they're AppleSingle encoded resource files. The
  152. macresource module and the Mac/OSX/Makefile cater for this, and create
  153. ".rsrc.df.rsrc" files on the fly that are normal datafork-based resource
  154. files.
  155. Jack Jansen, Jack.Jansen@cwi.nl, 15-Jul-2004.
  156. Ronald Oussoren, RonaldOussoren@mac.com, 26-May-2006