Commits

Anonymous committed 632e79d

various tweaks, expanded the bundlebuilder part considerably

  • Participants
  • Parent commits 79329e1

Comments (0)

Files changed (2)

pyobjc/Doc/intro.html

 :copyright: 2003 The PyObjC Project -->
 <h2>Contents</h2>
 <ul>
-<li><a href="#work-in-progress" id="id1" name="id1">WORK IN PROGRESS</a></li>
-<li><a href="#preface" id="id2" name="id2">Preface</a></li>
-<li><a href="#objective-c-for-pyobjc-users" id="id3" name="id3">Objective-C for PyObjC users</a></li>
-<li><a href="#overview-of-the-bridge" id="id4" name="id4">Overview of the bridge</a></li>
-<li><a href="#cocoa-for-python-programmers" id="id5" name="id5">Cocoa for Python programmers</a></li>
-<li><a href="#building-applications" id="id6" name="id6">Building applications</a><ul>
-<li><a href="#pure-python-buildapp-py" id="id7" name="id7">&quot;Pure python&quot; :  buildapp.py</a></li>
-<li><a href="#ide-approach-project-builder" id="id8" name="id8">&quot;IDE approach&quot; : Project builder</a></li>
+<li><a href="#work-in-progress" id="id2" name="id2">WORK IN PROGRESS</a></li>
+<li><a href="#preface" id="id3" name="id3">Preface</a></li>
+<li><a href="#objective-c-for-pyobjc-users" id="id4" name="id4">Objective-C for PyObjC users</a></li>
+<li><a href="#overview-of-the-bridge" id="id5" name="id5">Overview of the bridge</a></li>
+<li><a href="#cocoa-for-python-programmers" id="id6" name="id6">Cocoa for Python programmers</a></li>
+<li><a href="#building-applications" id="id7" name="id7">Building applications</a><ul>
+<li><a href="#pure-python-buildapp-py" id="id8" name="id8">&quot;Pure Python&quot; :  buildapp.py</a></li>
+<li><a href="#ide-approach-project-builder" id="id9" name="id9">&quot;IDE approach&quot; : Project builder</a></li>
 </ul>
 </li>
 </ul>
-<h2><a href="#id1" name="work-in-progress">WORK IN PROGRESS</a></h2>
+<h2><a href="#id2" name="work-in-progress">WORK IN PROGRESS</a></h2>
 <p>This document is work in progress and thin on details.</p>
-<h2><a href="#id2" name="preface">Preface</a></h2>
+<h2><a href="#id3" name="preface">Preface</a></h2>
 <p>PyObjC is a bridge between Python and Objective-C. It allows you to write 
 Python scripts that use and extend existing Objective-C class libraries, 
 most importantly the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a> by <a href="http://www.apple.com/">Apple</a>.</p>
 <p>This document describes how to use Objective-C class libraries from Python
 scripts and how to interpret the documentation of those libraries, from the 
 point of view of a Python programmer.</p>
-<h2><a href="#id3" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
-<p>Objective-C is an object-oriented programming language that is an extention 
+<h2><a href="#id4" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<p>Objective-C is an object-oriented programming language that is an extension 
 of C and borrows heavily from Smalltalk. It features single inheritance with
 (in theory) multiple root classes and dynamic dispatch of methods. This is
-basicly the same as python with single inheritance.</p>
+basicly the same as Python with single inheritance.</p>
 <p>An important difference between Python and Objective-C is that the latter is
 not a pure object-oriented language. Some values are not objects, but values
 of plain C types, such as <code><span>int</span></code> and <code><span>double</span></code>. These basic C types can also
 <ul>
 <li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
 </ul>
-<h2><a href="#id4" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h2><a href="#id5" name="overview-of-the-bridge">Overview of the bridge</a></h2>
 <p>Objective-C classes are visible as Python classes and can be subclassed just
 like normal Python classes. The major differences between normal Python classes
 and Objective-C classes are the way you create instances and the fact that 
-Objective-C classes have <i>odd</i> names.</p>
+Objective-C classes have odd names.</p>
 <p>As described in <a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 
 objects is a two-stage process. You first call the class method <code><span>alloc</span></code>, and
 then call some variation of <code><span>init</span></code> to initialize the objects. The newly
 created object is the result of the call to <code><span>init</span></code>. Most classes have 
 convienence class methods that combine the calls to <code><span>alloc</span></code> and <code><span>init</span></code>.</p>
-<p>Objective-C methods are bridged to python callables. Because Objective-C method 
+<p>Objective-C methods are bridged to Python callables. Because Objective-C method 
 names can contain colons it is necessary to translate methods names. The rules
 for translation are:</p>
 <ul>
 the bridged method has has an integer argument).  Data that is passed from the
 function results in additional return values from the function.</p>
 <p>When the bridge cannot automaticly deduce the right signature for a method, or
-if you want to add a method whose name cannot be transformed into python (
+if you want to add a method whose name cannot be transformed into Python (
 for example a methodname containing <code><span>$</span></code>), you'll have to add explicit hints
 to your code. You do this by calling the function <code><span>objc.selector</span></code> and using
 the result instead of your method definition:</p>
 additional information about the method to the bridge, see the online 
 documentation for more information about this function. It is almost never
 necessary to use this technique.</p>
-<p>The need for additional hints to the bridge often arises from implementing an
-(informal) protocol in Python. Because the methods compromising the protocol
-are probably not implemented in the superclass the bridge often cannot deduce 
-the correct method signatures for the methods you implemented. To avoid the
-need for using <code><span>objc.selector</span></code> and to make it explicit that your implementing
-an (informal) protocol the bridge has explicit support for these (informal)
-protocols.</p>
-<p>To tell the bridge that your implementing an informal protocol you use an
-<code><span>informal_protocol</span></code> object as a mixin:</p>
-<pre>
-class MyModel (NSObject, anInformalProtocol):
-        pass
-</pre>
-<p>The <code><span>AppKit</span></code> and <code><span>Foundation</span></code> modules define <code><span>informal_protocol</span></code> objects 
-for most (informal) protocols and defined by these frameworks (both the 
-explicitly documented protocols and the protocols used to communicate between
-an object and its delegate).</p>
-<h2><a href="#id5" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
+<p>If you write a method for an Objecitve-C class in Python, PyObjC will try to
+deduce the method's signature. If it's overriding a method, the signature of
+the method that is overridden is taken. If it's a method that appears
+<i>anywhere</i> in an informal protocol definition in a framework that's currently
+loaded, PyObjC takes the signature from there. (Most wrapped frameworks have a
+submodule named <code><span>protocols.py</span></code> that contains informal protocol definitions.)</p>
+<h2><a href="#id6" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
 <p>Cocoa frameworks are mapped onto Python packages with the same name, that is
 the classes, constants and functioins from the AppKit framework are available
 after you import <code><span>AppKit</span></code> in your Python script.</p>
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
-<h2><a href="#id6" name="building-applications">Building applications</a></h2>
+<h2><a href="#id7" name="building-applications">Building applications</a></h2>
 <p>There are two different ways to build applications with PyObjC. There are no
 major advantages to using either one of them, use the one that is most 
 convenient to you.</p>
-<h3><a href="#id7" name="pure-python-buildapp-py">&quot;Pure python&quot; :  buildapp.py</a></h3>
-<p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module will be part
-of the Python 2.3 MacPython release and is a to build distutil-style scripts 
-for building (standalone) applications.</p>
+<h3><a href="#id8" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
+<p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module will be
+part of the Python 2.3 MacPython release and offers a way to build
+distutil-style scripts  for building (standalone) applications.</p>
 <p>An example <code><span>buildapp.py</span></code> script:</p>
 <pre>
 from bundlebuilder import buildapp
         nibname = &quot;MainMenu&quot;,
 )   
 </pre>
+<p>During development you typically invoke it like this from the command line:</p>
+<pre>
+python buildapp.py --link build
+</pre>
+<p>This will build an application bundle in a folder named <code><span>build</span></code> in the
+current folder. The <code><span>--link</span></code> option tells <code><span>bundlebuilder</span></code> to add symbolic
+links to the application bundle instead of copies of your source and resource
+files, allowing you to edit them without having to rebuild the application. To
+build a standalone application, either use <code><span>--standalone</span></code> or
+<code><span>--semi-standalone</span></code>. The latter will put all used modules that are not in
+Python's standard library into the application bundle. The result will still
+depend on an installed Python, but yields a relatively compact application.
+<code><span>--standalone</span></code> will cause <code><span>bundlebuilder</span></code> to include <i>everything</i> needed
+into the app bundle, including the entire Python runtime. This is useful if
+you're using a different version of Python that the one that comes with MacOSX
+10.2, or if you fear that a future version of OSX may come with an
+incompatible Python version.</p>
 <p>The online documentation for <code><span>bundlebuilder</span></code> contains more information on 
-building <code><span>buildapp.py</span></code> scripts.</p>
-<h3><a href="#id8" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
+building <code><span>buildapp.py</span></code> scripts and how to invoke them. There are plenty of
+example <code><span>buildapp.py</span></code> scripts in the various <a href="../Examples">Examples</a> subfolders.</p>
+<h3><a href="#id9" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
 <p>PyObjC includes a number of Project Builder templates that can be used to 
 build (standalone) applications.</p>
 <p><strong>TODO</strong>:</p>

pyobjc/Doc/intro.txt

 Objective-C for PyObjC users
 ----------------------------
 
-Objective-C is an object-oriented programming language that is an extention 
+Objective-C is an object-oriented programming language that is an extension 
 of C and borrows heavily from Smalltalk. It features single inheritance with
 (in theory) multiple root classes and dynamic dispatch of methods. This is
-basicly the same as python with single inheritance.
+basicly the same as Python with single inheritance.
 
 An important difference between Python and Objective-C is that the latter is
 not a pure object-oriented language. Some values are not objects, but values
 Objective-C classes are visible as Python classes and can be subclassed just
 like normal Python classes. The major differences between normal Python classes
 and Objective-C classes are the way you create instances and the fact that 
-Objective-C classes have *odd* names.
+Objective-C classes have odd names.
 
 As described in `Objective-C for PyObjC users`_ the creation of Objective-C 
 objects is a two-stage process. You first call the class method ``alloc``, and
 created object is the result of the call to ``init``. Most classes have 
 convienence class methods that combine the calls to ``alloc`` and ``init``.
 
-Objective-C methods are bridged to python callables. Because Objective-C method 
+Objective-C methods are bridged to Python callables. Because Objective-C method 
 names can contain colons it is necessary to translate methods names. The rules
 for translation are:
 
 function results in additional return values from the function.
 
 When the bridge cannot automaticly deduce the right signature for a method, or
-if you want to add a method whose name cannot be transformed into python (
+if you want to add a method whose name cannot be transformed into Python (
 for example a methodname containing ``$``), you'll have to add explicit hints
 to your code. You do this by calling the function ``objc.selector`` and using
 the result instead of your method definition::
 documentation for more information about this function. It is almost never
 necessary to use this technique.
 
-The need for additional hints to the bridge often arises from implementing an
-(informal) protocol in Python. Because the methods compromising the protocol
-are probably not implemented in the superclass the bridge often cannot deduce 
-the correct method signatures for the methods you implemented. To avoid the
-need for using ``objc.selector`` and to make it explicit that your implementing
-an (informal) protocol the bridge has explicit support for these (informal)
-protocols. 
-
-To tell the bridge that your implementing an informal protocol you use an
-``informal_protocol`` object as a mixin::
-		
-		class MyModel (NSObject, anInformalProtocol):
-			pass
-
-The ``AppKit`` and ``Foundation`` modules define ``informal_protocol`` objects 
-for most (informal) protocols and defined by these frameworks (both the 
-explicitly documented protocols and the protocols used to communicate between
-an object and its delegate).
+If you write a method for an Objecitve-C class in Python, PyObjC will try to
+deduce the method's signature. If it's overriding a method, the signature of
+the method that is overridden is taken. If it's a method that appears
+*anywhere* in an informal protocol definition in a framework that's currently
+loaded, PyObjC takes the signature from there. (Most wrapped frameworks have a
+submodule named ``protocols.py`` that contains informal protocol definitions.)
 
 
 Cocoa for Python programmers
 major advantages to using either one of them, use the one that is most 
 convenient to you.
 
-"Pure python" :  buildapp.py
+"Pure Python" :  buildapp.py
 ............................
 
-PyObjC includes a copy of the ``bundlebuilder`` module. This module will be part
-of the Python 2.3 MacPython release and is a to build distutil-style scripts 
-for building (standalone) applications.
+PyObjC includes a copy of the ``bundlebuilder`` module. This module will be
+part of the Python 2.3 MacPython release and offers a way to build
+distutil-style scripts  for building (standalone) applications.
 
 An example ``buildapp.py`` script::
 
 		name = 'iClass',
 		mainprogram = "main.py",
 		resources = ["English.lproj", "datasource.py" ],
-	        nibname = "MainMenu",
+		nibname = "MainMenu",
 	)   
 
+During development you typically invoke it from the command line like this::
+
+	python buildapp.py --link build
+
+This will build an application bundle in a folder named ``build`` in the
+current folder. The ``--link`` option tells ``bundlebuilder`` to add symbolic
+links to the application bundle instead of copies of your source and resource
+files, allowing you to edit them without having to rebuild the application. To
+build a standalone application, either use ``--standalone`` or
+``--semi-standalone``. The latter will put all used modules that are not in
+Python's standard library into the application bundle. The result will still
+depend on an installed Python, but yields a relatively compact application.
+``--standalone`` will cause ``bundlebuilder`` to include *everything* needed
+into the app bundle, including the entire Python runtime. This is useful if
+you're using a different version of Python that the one that comes with MacOSX
+10.2, or if you fear that a future version of OSX may come with an
+incompatible Python version.
+
 The online documentation for ``bundlebuilder`` contains more information on 
-building ``buildapp.py`` scripts.
+building ``buildapp.py`` scripts and how to invoke them. There are plenty of
+example ``buildapp.py`` scripts in the various `Examples`__ subfolders.
+
+.. __: ../Examples
 
 
 "IDE approach" : Project builder