Merge pull request #4213 from NathanLovato/feature/ios-plugin

Document iOS plugins

tutorials/platform/index.rst

@@ -6,6 +6,7 @@ Platform-specific
    :name: toc-learn-features-platform
 
    android/index
+   ios/index
    services_for_ios
    platform_html5
    consoles

tutorials/platform/ios/index.rst

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

tutorials/platform/ios/ios_plugin.rst

@@ -0,0 +1,110 @@
+.. _doc_ios_plugin:
+
+Creating iOS plugins
+====================
+
+This page explains what iOS plugins can do for you, how to use an existing plugin, and the steps to code a new one.
+
+iOS plugins allow you to use third-party libraries and support iOS-specific features like In-App Purchases, GameCenter integration, ARKit support, and more.
+
+Loading and using an existing plugin
+------------------------------------
+
+An iOS plugin requires a ``.gdip`` configuration file, a ``.a`` binary file, and possibly other dependencies. To use it, you need to:
+
+1. Copy the plugin's files to your Godot project's ``res://ios/plugins`` directory. You can also group files in a sub-directory, like ``res://ios/plugins/my_plugin``.
+
+2. The Godot editor automatically detects and imports ``.gdip`` files inside ``res://ios/plugins`` and its subdirectories.
+
+3. You can find and activate detected plugins by going to Project -> Export... -> iOS and in the Options tab, scrolling to the Plugins section.
+
+.. image:: img/ios_export_preset_plugins_section.png
+
+When a plugin is active, you can access it in your using ``Engine.get_singleton()``::
+
+    if Engine.has_singleton("MyPlugin"):
+        var singleton = Engine.get_singleton("MyPlugin")
+        print(singleton.foo())
+
+Creating an iOS plugin
+----------------------
+
+At its core, a Godot iOS plugin is an iOS static library (*.a* archive file) with the following requirements:
+
+- The library must have a dependency on the Godot engine headers.
+
+- The library must come with a ``.gdip`` configuration file.
+
+An iOS plugin can have the same functionality as a Godot module but provides more flexibility and doesn't require to rebuild the engine.
+
+Here are the steps to get a plugin's development started. We recommend using `Xcode <https://developer.apple.com/develop/>`_ as your development environment.
+
+.. seealso:: The `Godot iOS plugin template <https://github.com/naithar/godot_ios_plugin>`_ gives you all the boilerplate you need to get your iOS plugin started.
+
+
+To build an iOS plugin:
+
+1. Create an Objective-C static library for your plugin inside Xcode.
+
+2. Add the Godot engine header files as a dependency for your plugin library in ``HEADER_SEARCH_PATHS``. You can find the setting inside the ``Build Settings`` tab:
+
+    - Download the Godot engine source from the `Godot GitHub page <https://github.com/godotengine/godot>`_.
+
+    - Run SCons to generate headers. You can learn the process by reading :ref:`doc_compiling_for_ios`. You don't have to wait for compilation to complete to move forward as headers are generated before the engine starts to compile.
+
+    - You should use the same header files for iOS plugins and for the iOS export template.
+
+3. In the ``Build Settings`` tab, specify the compilation flags for your static library in ``OTHER_CFLAGS``. The most important ones are ``-fcxx-modules``, ``-fmodules``, and ``-DDEBUG`` if you need debug support. Other flags should be the same you use to compile Godot. For instance, ``-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 ``.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``. You can also build the static library with your 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 the iOS application should be linked with.
+
+                -   **embedded**: contains a list of iOS frameworks or libraries that should be both linked and embedded into the resulting iOS application.
+
+                -   **system**: contains a list of iOS system frameworks that are required for plugin.
+
+                -   **capabilities**: contains a list of iOS capabilities that is required for plugin. A 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 useful for data files or images.
+
+            -   **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"``