Source

pyobjc / pyobjc-xcode / Doc / XcodeIntegration.txt

Full commit
======================
PyObjC Xcode Templates
======================

:Author: Bob Ippolito
:Contact: bob@redivi.com

The PyObjC Xcode Templates offer an alternative to developing
applications "by hand" using py2app, as described in the
tutorial.  As of PyObjC 1.3.1, these templates are py2app based,
so there is no longer a technical reason not to use them.

.. contents::

Installing
----------

If you have installed PyObjC 1.3.1 or later using the installer, then
the Xcode templates are already installed.  

If you have installed any version of PyObjC prior to 1.3.1, then you
may have old Xcode templates installed.  These Xcode templates named
"Cocoa-Python Application" and "Cocoa-Python Document Based Application"
should NOT be used, and it would be wise to remove them.  They can
be found here::

    /Library/Application Support/Apple/Developer Tools/Project Templates

If you want to install the packages using setuptools use the following 
commands::

   $ easy_install pyobjc-xcode
   $ pyobjc-xcode-install

The latter command makes the templates available to Xcode as the former installs
the templates and support code in a location where Xcode won't pick them up.

Removing the templates is easy as well, but requires some manual intervention
at this time. Use ``pyobjc-xcode-uninstall`` to remove the templates from 
Xcode's search path, and then install the ``pyobjc-xcode`` egg the usual way.




Notes
-----

- These templates are brand new in PyObjC 1.3.1 and haven't had much
  use yet.  If you think that you have found a bug or would like them to be
  changed in some way, please speak up on the `pyobjc-dev`_
  mailing list, and/or `report a bug`_.

.. _`pyobjc-dev`: http://lists.sourceforge.net/lists/listinfo/pyobjc-dev
.. _`report a bug`: http://sourceforge.net/tracker/?group_id=14534&atid=114534


- The Python interpreter used by the templates is determined by the
  first line of the ``setup.py`` file.  By default, it points to::

      #!/usr/bin/env python

  This means that whichever Python that comes first on the ``PATH``
  will be used.  This will normally be the Python 2.3 interpreter
  that ships with Mac OS X.  If you would like to use a different
  interpreter, you have two choices:

  1. Edit the first line of ``setup.py`` to point to the desired
     interpreter explicitly, for example::

         #!/usr/local/bin/python2.4

     This change must be done to every project that you use the
     template from.  Alternatively, you can make this change
     to the templates themselves so that this is set for all
     new projects.  See the Installing section above for the
     location of these templates.  If you choose to do this,
     edit the ``setup.py`` directly.  Do not open the
     ``.xcode`` project in the template, as Xcode templates
     can be rather fragile.

  2. Change your ``PATH`` environment variable so that the location
     of your Python interpreter appears before the others.  Since
     LaunchServices and thus Xcode is not started by your user shell,
     you will need to specify it in a plist.  See `QA1067`_, 
     `Runtime Configuration: Environment Variables`_, and the 
     `EnvironmentPrefs`_ System Preferences plug-in example that
     comes with PyObjC for more information about how to do this.

.. _`QA1067`: http://developer.apple.com/qa/qa2001/qa1067.html
.. _`Runtime Configuration: Environment Variables`: http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Concepts/EnvironmentVars.html
.. _`EnvironmentPrefs`: file:///Developer/Python/PyObjC/Examples/Plugins/EnvironmentPrefs

     This change will be specific to your user account, and will
     take effect globally, which may or may not be a good thing.

- The Clean command currently does not remove everything, if you
  want to ensure that the project has actually been completely
  cleaned, then you should remove the ``build`` folder yourself.

- Like Xcode, the built product and temporary files will both end
  up in the ``build`` folder unless explicitly specified that they
  should go elsewhere.  When not using these templates, py2app
  would normally put the result in a ``dist`` folder.

- If you need to include non-system frameworks or dylibs that are not otherwise
  referenced by a Python extension, then link to them from an Objective-C
  plug-in.  py2app will find them and put them into your application!
  See PyObjC Mixed Application below for more information about using
  plug-ins to integrate non-Python code into your application.

Groups
------

The PyObjC Xcode templates use py2app to build applications,
but they parse the ``.xcode`` project file to determine
how they should be built, rather than directly in the
``setup.py``.  The parser, in ``PyObjCTools.XcodeSupport``,
gives special meaning to several groups.  If these groups
are renamed or removed, your project may not build correctly!

Main Script:
    This group should contain exactly one file, the main script
    of your application.  The default main script in the template
    generally does not need to be changed.

    If you need to ensure that additional code is imported, simply
    place it in the Classes group.  You shouldn't need to modify
    your main script.

    ONLY the main script should be in this group.

Resources:
    Every file in this group goes into the ``Resources`` folder
    inside of your application bundle.

    Any ``.nib`` files that are in this folder will
    be parsed with ``PyObjCTools.NibClassBuilder.extractClasses``
    by  the main script before any modules in the Classes group
    are imported, and before the run loop is started.  You should
    not need to call ``extractClasses`` manually in your code.

    Source code should not go in here.
    
Classes:
    Modules in the classes group will be imported by the main
    script in the order that they appear in the Xcode project,
    after all classes are extracted from the nibs.

    Every Python module in this group is guaranteed to be scanned
    by py2app for dependencies.

Other Sources:
    This group is not actually special.  You may put anything you
    want in this group.  It is used by the templates to store
    files and source code that do not fit into any of the above
    categories, such as the ``Info.plist`` and the ``setup.py``.

    setup.py:
        This is the script that is actually used to build your
        project.  It may also be used from the command line
        either directly or via ``xcodebuild``.  Read the file
        for more instructions.  This script must not be renamed
        or removed.

        If you need to customize the py2app or distutils
        build process, you should modify the ``setup_options``
        dict before the ``setup(...)`` function is called.

    Info.plist:
        When present, this file is used as a template for your
        application's ``Info.plist``.  If you rename or delete
        it, then it will not be used and plist will be
        generated by py2app.  For information about what
        can go in this plist, see
        `Runtime Configuration: Property List Key Reference`__.

.. __: http://developer.apple.com/documentation/MacOSX/Conceptual/BPRuntimeConfig/Concepts/PListKeys.html

Targets
-------

Development:
    This target will use py2app ``--alias`` build mode.  Executables
    built with this mechanism are produced very quickly, and use the
    sources in-place via symlinks and ``sys.path`` manipulations.
    These executables are not redistributable, much like development
    executables produced by Xcode when using Zero-Link.

Deployment:
    This target will use py2app's default build mode, ``--standalone``.
    This will create a standalone bundle out of your application that is
    redistributable.  Everything that py2app determines to be
    needed by your application will be included in the executable,
    including Python itself, extensions you use, and dynamic
    libraries or frameworks that are linked to by these extensions.
    
    If you are using a Python distributed by
    Apple, then it will be built in ``--semi-standalone`` mode.
    This means that Python and its standard library *will not*
    be included in the application.

    Using the Deployment *target* does not automatically
    imply that you are using the Deployment *build style*.  This is
    only relevant when using the PyObjC Mixed Application template,
    or are otherwise using the same project to compile non-Python
    source code.  To change the current build style, Get Info on the
    project.  The build style has no effect on Python code.

Custom Executable
-----------------

The custom executable enables for your built application to be run from Xcode.

If you rename your main script or fiddle around with your ``Info.plist``,
the path to your application may change and this will no longer work.
If that is the case, use Get Info on the custom executable and change
the Arguments to point to the correct path.

By default, executables are launched with the ``USE_PDB`` environment variable
set for both Development and Deployment targets.  This turns on verbose stack
traces whenever an exception crosses the PyObjC bridge, and will drop you at
a pdb prompt in the console when an uncaught exception occurs.

Other useful environment variables that you can set, such as ``NSZombieEnabled``,
as well as all kinds of other debugging tricks you should know are covered
in `TN2124: Mac OS X Debugging Magic`__.

.. __: http://developer.apple.com/technotes/tn2004/tn2124.html

If Xcode screwed up and didn't create a Custom Executable, which is not
beyond the realm of possibility, then you can create one as follows:

1. Create a Custom Executable for ``/usr/bin/env`` (yes, Xcode is dumb)
2. Set that it runs from the Built Product directory
3. Use ``YourProject.app/Contents/MacOS/YourProject`` as the first (and only) argument
4. Optionally set the ``USE_PDB`` (or any other) environment variables

Note that when debugging using gdb, you'll get a trap signal because
``/usr/bin/env`` will be ``execve``'ing your application.  Unfortunately,
there's nothing we can do from the template, because Xcode can only create
Custom Executables to absolute paths.  However, you can probably modify
yours such that it points directly to your built application after it
has been built once.

Custom executables are specific to a particular user in Xcode, so anything
you do to this part of the template won't be seen by anyone else unless
they happen to have the same short user name as you.

PyObjC Application
------------------

This is a simple template that has a window and an application delegate.

PyObjC Document Based Application
---------------------------------

This is template demonstrates a Document-based application written in Python.
It is a simple text editor (like the TinyTinyEdit example).

PyObjC Mixed Application
------------------------

This template contains both Objective-C and Python code.  The Objective-C code
is built as a "ProjectNamePlugIn.bundle" plug-in in a separate target.  The plug-in
is placed in the ``Resources`` directory of your application.  A wrapper script
in the Classes group, "ProjectNamePlugIn.py" can be imported from Python and will
contain all of the Objective-C classes referenced in the plug-in (even if there
is more than just the example ``ProjectNamePlugIn`` class).

The example class implements a simple method, ``-(BOOL)plugInLoaded`` which will
always return ``YES``.  The Python application delegate creates an instances of
this class, and will beep when the application has finished launching if the
plug-in loaded correctly.  If it didn't load correctly, you would get an exception,
but that shouldn't happen :)

Note that this template doesn't have any special machinery behind it.  If you find
that you later need to add Objective-C code to a project that you started with
one of the other templates, you can do the following:

1. Create a new Objective-C loadable bundle target
2. Make the Development and Deployment targets depend on this target
3. Drag the product loadable bundle into the Resources group
4. Create a wrapper module, that uses ``objc.loadBundle(...)`` in the
   Classes group (see the example in the template).

Note that switching between Development and Deployment targets does
not imply that you are switching to the build style of the same name.
See the Targets section for more information.