1 files changed, 141 insertions, 0 deletions
diff --git a/iphone/doc/install.rst b/iphone/doc/install.rst
new file mode 100644
index 0000000..b86ac45
--- /dev/null
+++ b/iphone/doc/install.rst
@@ -0,0 +1,141 @@
+Installing the SDK
+==================
+
+These are the basic instructions for obtaining the SDK and adding it to an
+Xcode project.
+
+You may want to try things out with the :doc:`tutorial` before hacking at your
+own project.
+
+
+Requirements
+------------
+
+You will need *all* of the following to develop iPhone applications
+using this SDK:
+
+* Mac OS X >= 10.6.x (Snow Leopard)
+* Xcode >= 4.5.1
+* iPhone SDK >= 4.0
+* An iPhone 3GS, iPhone 4 or newer iOS device with an auto-focus camera
+* iOS >= 4.0 running on the device
+
+.. warning::
+
+   *Only* the iPhone 3GS, iPhone 4 and newer models are supported, as they
+   have a camera with auto-focus.  The iPad 2 and iPad 3 will also work, *iff*
+   the barcode is printed large enough to achieve good focus.  The ZBar
+   library does not support the iPhone 3G and is unlikely to ever support it.
+
+
+Downloading
+-----------
+
+Download the latest binary release of the ZBar SDK from
+
+http://zbar.sourceforge.net/iphone
+
+
+Integration
+-----------
+
+The recommended installation method is to simply copy the SDK into your
+Xcode project:
+
+1. Open ZBarSDK-|version|.dmg in the Finder.
+
+2. Drag the :file:`ZBarSDK` folder into your Xcode project.  In the dialog
+   that appears, you should choose to **copy** the SDK into your project by
+   checking the box.  The target that you want to link with the library should
+   also be selected in the target list.
+
+3. Link the following additional frameworks to any targets that link with the
+   ZBarSDK.  You should set the first three to use weak references and
+   configure an appropriate deployment target if you still need to support
+   iOS 3:
+
+   * :file:`AVFoundation.framework` (weak)
+   * :file:`CoreMedia.framework` (weak)
+   * :file:`CoreVideo.framework` (weak)
+   * :file:`QuartzCore.framework`
+   * :file:`libiconv.dylib`
+
+   If you check "Link Binary With Libraries" for the target(s), you should see
+   all of these frameworks followed by :file:`libzbar.a`.
+
+   .. note::
+
+      Link order may be important for some versions of Xcode; the referenced
+      libraries should be listed *before* :file:`libzbar.a` in the link order.
+
+4. Import the SDK header from your prefix header to make the barcode reader
+   APIs available::
+
+      #import "ZBarSDK.h"
+
+Proceed to :doc:`camera` or :doc:`picker` to learn about using the reader APIs
+to scan barcodes.  Use the :doc:`apiref` for specific interface details.
+
+
+Upgrading from an Older Version
+-------------------------------
+
+If you are using an older version of the *SDK* (NB, skip to the next section
+if you are currently using Mercurial), upgrading is straightforward:
+
+1. Delete the current ZBarSDK group from your project.  You should choose
+   to delete the files if you copied them into your project.
+2. Drag the new ZBarSDK from the DMG into your project.
+
+Clean out and rebuild your project with the new version.
+
+
+Upgrading a Pre-SDK Integration
+-------------------------------
+
+If your project was using the library directly from the Mercurial repository,
+before the SDK was introduced, there are a few incompatibilities that you must
+resolve in order to upgrade.  Don't worry - all of your source stays the same,
+you just need to update how the library is included in the project and how the
+headers are imported.
+
+Switching to the Binary Distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This approach is recommended - the binary releases provide you with a stable
+development platform, isolating you from temporary instability and transient
+problems that may occur at the bleeding edge.
+
+The first task is to reverse the previous ZBar integration:
+
+1. Remove the reference to zbar.xcodeproj from your project.
+2. Remove any :file:`zbar-*` files from your Resources.
+3. In the target build settings, remove any "Header Search Paths" that
+   reference zbar.
+4. Remove any references to zbar headers in your :file:`prefix.pch` or source
+   files.
+
+Now just continue with the `integration`_ instructions above and you should be
+back up and running!
+
+Continuing with Mercurial
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Alternatively, you may still prefer to select Mercurial revisions.  You have a
+few choices for this:
+
+* You may build your own ZBarSDK and copy/link it into your project.  This is
+  the same as `Switching to the Binary Distribution`_, except that you use
+  your own version of the SDK.  In this case you need to manually rebuild the
+  SDK when you update it.
+* You may leave zbar.xcodeproj as a project dependency and pull the SDK into
+  your project.  This is not well tested, so ymmv.
+* You may leave zbar.xcodeproj as a project dependency and just link libzbar.a
+  into your project, as before.  You will need to update the target dependency
+  (the library target changed names to libzbar) and add the
+  :file:`iphone/include/ZBarSDK` directory to "Header Search Paths"
+
+In any case, you should remove the references to the zbar headers from
+:file:`prefix.pch` (or your source files) and replace them with::
+
+   #import "ZBarSDK.h"