iOS: Plugin documentation

tutorials/plugins/ios/index.rst

@@ -0,0 +1,8 @@
+iOS plugins
+===========
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-plugins-ios
+
+   ios_plugin

tutorials/plugins/ios/ios_plugin.rst

@@ -0,0 +1,141 @@
+.. _doc_ios_plugin:
+
+Creating iOS plugins
+====================
+
+Introduction
+------------
+
+iOS plugins are powerful tools to extend the capabilities of the Godot engine
+by tapping into the functionality provided by the iOS platform and ecosystem.
+
+In‑App Purchases, GameCenter integration or ARKit are such examples since it requires features
+and capabilities that don't belong to the core feature set of a game engine:
+
+-  Analytics
+-  In-app purchases
+-  Receipt validation
+-  Ads
+-  A/B testing
+-  Login
+-  Cloud saves
+-  Leaderboards and scores
+-  User support & feedback
+-  Posting to Facebook, Twitter, etc.
+-  Push notifications
+
+iOS plugin
+----------
+
+At its core, a Godot iOS plugin is a iOS static library (*a* archive file) 
+with the following caveats:
+
+-  The library must have a dependency on the Godot engine headers.
+
+-  The library must come with a ``.gdip`` configuration file.
+
+iOS plugin can have the same functionality as Godot modules, 
+but provides more flexibility and doesn't require engine being rebuilt.
+
+Building an iOS plugin
+^^^^^^^^^^^^^^^^^^^^^^
+
+**Prerequisite:** `Xcode <https://developer.apple.com/develop/>`_ is strongly recommended as the IDE to use to create iOS plugins.
+The instructions below assumes that you're using Xcode.
+
+1.  Create an Objective-C static library for your plugin inside Xcode IDE.
+
+2.  Add the Godot engine header files as a dependency for your plugin library in ``HEADER_SEARCH_PATHS`` at ``Build Settings`` tab:
+
+    -  Download the Godot engine source from the `Godot GitHub page <https://github.com/godotengine/godot>`_.
+
+    -  Generate autogenerated headers by running SCons. Reference can be found at :ref:`Compiling for iOS<doc_compiling_for_ios>`. 
+       You don't have to wait for compilation complition as headers are generated before engine starts actual compilation.
+
+    -  Header files that used for plugin should be the same that was used for iOS template compilation.
+
+3.  Specify correct compilation flags for static library in ``OTHER_CFLAGS`` at ``Build Settings`` tab.
+    Most important ones are ``-fcxx-modules``, ``-fmodules``, ``-DDEBUG`` if debug is required.
+    Other flags should be the same as for Godot compilation (e.g.: ``-DPTRCALL_ENABLED -DDEBUG_ENABLED, -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND``).
+
+4.  Add the required logic for your plugin and build your library to generate ``a`` file.
+    You will probably need to build both ``debug`` and ``release`` targeted ``a`` files.
+    Depending on your need, pick only one or both.
+    If you need both ``a`` files their name should match following pattern: ``[PluginName].[TargetType].a``.
+    Static library can also be build with SCons configuration.
+
+5.  Create a Godot iOS Plugin configuration file to help the system detect and load your plugin:
+
+    -   The configuration file extension must be ``gdip`` (e.g.: ``MyPlugin.gdip``).
+    
+    -   The configuration file format is as follow::
+    
+            [config]
+            name="MyPlugin"
+            binary="MyPlugin.a"
+
+            initialization="init_my_plugin"
+            deinitialization="deinit_my_plugin"
+
+            [dependencies]
+            linked=[]
+            embedded=[]
+            system=["Foundation.framework"]
+
+            capabilities=["arkit", "metal"]
+
+            files=["data.json"]
+
+            [plist]
+            PlistKey="Some Info.plist key you might need"
+            
+        The ``config`` section and fields are required and defined as follow:
+        
+            -   **name**: name of the plugin
+
+            -   **binary**: this should be the filepath of the plugin ``a`` file.
+
+                -   The filepath can be relative (e.g.: ``MyPlugin.a``) in which case it's relative to the directory where ``gdip`` file is located.
+                -   The filepath can be absolute: ``res://some_path/MyPlugin.aar``.
+                -   In case you need multitarget library usage, filename should be ``MyPlugin.a`` and ``a`` files should be name as ``MyPlugin.release.a`` and ``MyPlugin.debug.a``.
+                
+        The ``dependencies`` and ``plist`` sections are optional and defined as follow:
+
+            -   **dependencies**:
+        
+                -   **linked**: contains a list of iOS frameworks that result iOS application should be linked with.
+
+                -   **embedded**: contains a list of iOS frameworks or libraries that should be both linked and embedded into resulting iOS application.
+
+                -   **system**: contains a list of iOS system frameworks that required for plugin.
+
+                -   **capabilities**: contains a list of iOS capabilities that is required for plugin. List of available capabilities can be found at `Apple UIRequiredDeviceCapabilities documentation page <https://developer.apple.com/documentation/bundleresources/information_property_list/uirequireddevicecapabilities>`_.
+
+                -   **files**: contains a list of files that should be copied on export. This is usefull for data files or images.
+
+            -   **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"``
+            
+
+
+Loading and using an iOS plugin
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Move the plugin configuration file (e.g: ``MyPlugin.gdip``) and its local binary (e.g: ``MyPlugin.a``) and dependencies to the Godot project's ``res://ios/plugins`` directory or any directory inside it (e.g: ``res://ios/plugins/my_plugin``).
+
+The Godot editor will automatically parse all ``.gdip`` files inside ``res://ios/plugins`` directory and it's subdirectories and show a list of detected and toggleable plugins in the iOS export presets window under the **Plugins** section.
+
+.. image:: img/ios_export_preset_plugins_section.png
+
+
+From your script::
+
+    if Engine.has_singleton("MyPlugin"):
+        var singleton = Engine.get_singleton("MyPlugin")
+        print(singleton.foo())
+
+Reference implementations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-   `Godot iOS plugin template <https://github.com/naithar/godot_ios_plugin>`_ 
+
+    -  Contains template/example for iOS plugin as well as SCons configuration and setup Xcode project.