diff --git a/snooty.toml b/snooty.toml index e44369c119..f03ff33085 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,6 +11,9 @@ intersphinx = [ toc_landing_pages = [ # New IA "/sdk/crud/create", + "/sdk/platforms/android", + "/sdk/platforms/apple", + "/sdk/platforms/unity", # Tutorial "/tutorial", @@ -86,6 +89,8 @@ atlas = "Atlas" admin-api-page = "/admin/api/v3/#" base-url = "https://www.mongodb.com/docs/realm" cpp-prefix = "https://www.mongodb.com/docs/realm-sdks/cpp/latest" +dart-minimum-version="3.3.0" +flutter-minimum-version="3.19.0" kotlin-sdk-version = "1.16.0" kotlinx-coroutines-version = "1.7.0" kotlin-sync-prefix = "https://www.mongodb.com/docs/realm-sdks/kotlin/latest/library-sync/" diff --git a/source/frameworks/flutter.txt b/source/frameworks/flutter.txt index fe10d1acbc..a2cd360fcf 100644 --- a/source/frameworks/flutter.txt +++ b/source/frameworks/flutter.txt @@ -7,4 +7,5 @@ Build with Flutter .. toctree:: :titlesonly: + Install Quick Start diff --git a/source/frameworks/flutter/install.txt b/source/frameworks/flutter/install.txt new file mode 100644 index 0000000000..e01371658d --- /dev/null +++ b/source/frameworks/flutter/install.txt @@ -0,0 +1,154 @@ +.. _sdks-install-sdk-in-flutter-project: + +==================================== +Install Atlas Device SDK for Flutter +==================================== + +.. meta:: + :description: Install the Atlas Device SDK in a Flutter application. + :keywords: Realm, Flutter SDK, code example + +.. facet:: + :name: genre + :values: tutorial + +.. facet:: + :name: programming_language + :values: dart + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Use Atlas Device SDK in a Flutter project to build cross-platform +applications with Flutter and Dart. This guide provides instructions for +installing the SDK in a Flutter project. For details about installing the SDK +in a standalone Dart project, refer to +:ref:`sdks-install`. + +Requirements +------------ + +Install Flutter with Dart in your development environment. The Flutter +installation includes Dart. To learn how, refer to the official +`Flutter Installation Guide `__. + +When building a project with Flutter, the SDK requires the following minimum +versions: + +- Flutter version {+flutter-minimum-version+} or later. +- Dart version {+dart-minimum-version+} or later. + +Supported Platforms +~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/api-details/dart/install/install-supported-platforms-description.rst + +Install the SDK +--------------- + +.. procedure:: + + .. step:: Create a Project + + To create a Flutter project, run the following commands: + + .. code-block:: bash + + flutter create + cd + + For more information, refer to Flutter's `Get Started Guide + `__. + + .. step:: Add the SDK to the Project + + To add the Flutter SDK to your project, run the following command: + + .. code-block:: bash + + flutter pub add realm + + This downloads the `realm `__ + package, and adds it to your project. + + In your ``pubspec.yaml`` file, you should see: + + .. code-block:: yaml + :caption: pubspec.yaml + + dependencies: + realm: + + .. note:: Using Networking in your macOS App + + If you are developing with Flutter in the macOS App Sandbox and + require network access, you must enable network entitlements in your + app. By default, network requests are not allowed due to built-in + macOS security settings. + + To learn how to change your app's macOS entitlements, refer to + :ref:`Device Sync and App Sandbox Entitlements + `. + +Update the Package Version +-------------------------- + +To change the version of the SDK in your project, perform the following steps: + +.. procedure:: + + .. step:: Update the ``pubspec.yaml`` File + + Update the package version in your :file:`pubspec.yaml` file dependencies. + + .. code-block:: yaml + :caption: pubspec.yaml + + dependencies: + realm: + + .. step:: Install the Updated Package + + From the command line, run the following command to install the updated + version: + + .. code-block:: + + dart pub upgrade realm + + Then, run the following command to install the updated SDK's native + binaries: + + .. code-block:: + + dart run realm install + + .. step:: Regenerate Object Models + + Changes to the package version may affect the functionality of the object + models. From the command line, run the following command to regenerate + object models with new and updated functionality: + + .. code-block:: bash + + dart run realm generate + + .. include:: /includes/flutter-v2-breaking-change.rst + +Import the SDK +-------------- + +To use the SDK in your app, import the package into any files that use it: + +.. code-block:: dart + :caption: ExampleFile.dart + + import 'package:realm/realm.dart'; + +Platform-Specific Considerations +-------------------------------- + +.. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst diff --git a/source/hidden-pages/upgrade-to-v2.txt b/source/hidden-pages/upgrade-to-v2.txt new file mode 100644 index 0000000000..f7a339147b --- /dev/null +++ b/source/hidden-pages/upgrade-to-v2.txt @@ -0,0 +1,206 @@ +:orphan: + +.. _flutter-upgrade-v2: + +============================= +Upgrade to Flutter SDK v2.0.0 +============================= + +.. meta:: + :description: Upgrade your existing Flutter or Dart app to Flutter SDK version 2.0.0 or later. + :keywords: code example, migration, migrate + +.. facet:: + :name: genre + :values: tutorial + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Atlas Device SDK for Flutter version 2.0.0 introduces several breaking changes +that impact existing apps upgrading from an earlier version. + +Notably, this version of the SDK: + +- Changes the part builder and how the SDK generates files for + your data model classes. This change impacts all apps upgrading from an + earlier version of the SDK. Refer to the :ref:`flutter-v2-builder-breaking-changes` + section on this page for information and instructions. + +- Removes or replaces several classes and members. These changes may or may not impact your + app. Refer to the :ref:`flutter-v2-removed-classes` section + on this page for information and instructions for impacted apps. + +.. _flutter-v2-builder-breaking-changes: + +Builder Changes +--------------- + +.. important:: + + This change impacts all apps upgrading from an earlier version of the SDK. + +Flutter SDK version 2.0.0 updates the SDK's ``realm_generator`` to use a +``PartBuilder`` instead of a ``SharedPartBuilder``. +This updated builder generates ``RealmModel`` data model files with a new +``.realm.dart`` file extension: + +.. list-table:: + :header-rows: 1 + :widths: 25 25 50 + + * - Version + - File Extension + - Example Part Directive + + * - SDK v2.0.0 and later + - ``.realm.dart`` + - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-new.dart + :language: dart + + * - SDK v1.9.0 and earlier + - ``.g.dart`` + - .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.part-directive-old.dart + :language: dart + +.. tip:: + + The update from ``SharedPartBuilder`` to ``PartBuilder`` makes it easier + to use multiple builders in your app. For example, combining ``realm_dart`` + with a serialization package builder such as ``dart_mappable`` or + ``json_serializable``. + +.. _flutter-v2-what-do-i-need-to-do: + +What Do I Need to Do? +~~~~~~~~~~~~~~~~~~~~~ + +When you upgrade an existing app from an earlier version of the Flutter SDK to +version 2.0.0 or later, you *must* update any existing part declarations, then +regenerate the object models with the new ``.realm.dart`` file extension: + +.. procedure:: + + .. step:: Update Your Existing Part Declarations + + Update all of the ``RealmObject`` part declarations in your app to + use the new naming convention: + + .. literalinclude:: /examples/generated/flutter/migrate_parts.snippet.migrate-model-dart-new.dart + :language: dart + :emphasize-lines: 3-5 + + .. step:: Regenerate Your Object Models + + .. tabs:: + + .. tab:: Flutter + :tabid: flutter + + After you update all of your declarations, regenerate your + object models with the new ``.realm.dart`` file extension. + You can safely delete any ``.g.dart`` files from your project. + + .. code-block:: + + dart run realm generate + + .. tab:: Dart Standalone + :tabid: dart + + After you update all of your declarations, regenerate your + object models with the new ``.realm.dart`` file extension. + You can safely delete any ``.g.dart`` files from your project. + + .. code-block:: + + dart run realm_dart generate + +.. _flutter-v2-removed-classes: + +Removed Classes and Members +--------------------------- + +Flutter SDK version 2.0.0 also removed or replaced several classes, members, and properties +from the SDK. These changes may or may not impact your app. + +The following table outlines what was removed and why, as well as a recommended solution +when upgrading an app that used the removed class or member, if any: + +.. list-table:: + :header-rows: 1 + :widths: 33 33 33 + + * - Removed Class or Member + - Reason + - Solution + + * - ``AppConfiguration.localAppName`` and ``AppConfiguration.localAppVersion`` + - Unused in SDK. + - Remove any instances. + + * - ``ClientResetError.isFatal`` + - Not needed. Always ``true``. + - Remove any instances. + + * - ``ClientResetError.sessionErrorCode`` + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. See also the + :flutter-sdk:`SyncError ` API reference. + + * - ``Realm.logger.level`` + - Replaced by ``Realm.logger.setLogLevel``. + - Replace any instances. See also :ref:`sdks-logging`. + + * - ``RealmProperty.indexed`` + - Replaced by ``RealmProperty.indexType``. + - Replace any instances. + + * - ``RealmValue.type`` + - Changed to an enum of ``RealmValueType``. + - Replace any instances. See also :ref:`RealmValue Data Type `. + + * - ``RealmValue.uint8List`` + - Renamed to ``RealmValue.binary``. + - Replace any instances. See also :ref:`RealmValue Data Type `. + + * - ``SchemaObject.properties`` + - ``SchemaObject`` changed to an iterable collection of ``SchemaProperty``. + - Replace any instances. See also the + :flutter-sdk:`SchemaObject ` API reference. + + * - ``SyncError`` constructor and ``SyncError.create`` factory + - Sync errors should only be created internally by the SDK. + - Remove any instances. + + * - ``SyncClientError``, ``SyncConnectionError``, ``SyncSessionError``, + ``SyncResolveError``, ``SyncWebSocketError``, and ``GeneralSyncError`` + - Consolidated into ``SyncError`` in SDK v1.6.0. + - Use ``SyncError`` or its subclasses. See also the + :flutter-sdk:`SyncError ` API reference. + + * - ``SyncErrorCategory``, ``SyncClientErrorCode``, ``SyncConnectionErrorCode``, + ``SyncSessionErrorCode``, ``SyncResolveErrorCode``,``SyncWebsocketErrorCode``, + and ``GeneralSyncErrorCode`` + - Consolidated into ``SyncErrorCode`` in SDK v1.6.0. + - Use ``SyncErrorCode`` enum. See also the + :flutter-sdk:`SyncError ` API reference. + + * - ``SyncError.codeValue``, ``SyncError.category``, and ``SyncError.detailedMessage`` + - Consolidated into ``SyncError`` in SDK v1.6.0. Messages were unused. + - Remove any category or message instances. Replace ``SyncError.codeValue`` + with ``SyncError.code.code``. See also the + :flutter-sdk:`SyncError ` API reference. + + * - ``SyncProgress.transferredBytes`` and ``SyncProgress.transferableBytes`` + - Reported transferred and transferable values were incorrect. Consolidated + into a new ``SyncProgress.progressEstimate`` metric. + - Use ``SyncProgress.progressEstimate``. See also :ref:`sdks-check-upload-and-download-progress`. + + * - ``User.provider`` + - Provider is associated with each identity, so value was incorrect + for users with more than one identity. + - Remove any instances. diff --git a/source/includes/api-details/cpp/install/install-import-sdk-description.rst b/source/includes/api-details/cpp/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..7040e39c8d --- /dev/null +++ b/source/includes/api-details/cpp/install/install-import-sdk-description.rst @@ -0,0 +1,2 @@ +Make the SDK available in your code by including the +``cpprealm/sdk.hpp`` header in the translation unit where you want to use it. diff --git a/source/includes/api-details/cpp/install/install-install-sdk-procedure-cmake.rst b/source/includes/api-details/cpp/install/install-install-sdk-procedure-cmake.rst new file mode 100644 index 0000000000..440a27d7ae --- /dev/null +++ b/source/includes/api-details/cpp/install/install-install-sdk-procedure-cmake.rst @@ -0,0 +1,83 @@ +You can use CMake with the FetchContent module to manage the SDK and its +dependencies in your C++ project. + +.. procedure:: + + .. step:: Create or Modify CMakeLists.txt + + Create or modify your ``CMakeLists.txt`` in the root directory of your + project: + + 1. Add ``Include(FetchContent)`` to include the FetchContent module + in your project build. + #. Use ``FetchContent_Declare`` to locate the SDK dependency + and specify the version tag you want to use. + #. Use the ``FetchContent_MakeAvailable()`` command to check whether + the named dependencies have been populated, and if not, populate them. + #. Finally, ``target_link_libraries()`` links the SDK dependency to + your target executable. + + To get the most recent version tag, refer to the releases on GitHub: + `realm/realm-cpp `__. + + Set the minimum C++ standard to 17 with ``set(CMAKE_CXX_STANDARD 17)``. + + In a Windows install, add the required compiler flag: + + .. code-block:: + + if(MSVC) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Zc:preprocessor /bigobj") + endif() + + .. example:: + + .. code-block:: cmake + :emphasize-lines: 14, 17-21, 24, 29 + + cmake_minimum_required(VERSION 3.15) + + project(MyDeviceSDKCppProject) + + # Minimum C++ standard + set(CMAKE_CXX_STANDARD 17) + + # In a Windows install, set these compiler flags: + if(MSVC) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Zc:preprocessor /bigobj") + endif() + + # Include the FetchContent module so you can download the C++ SDK + Include(FetchContent) + + # Declare the version of the C++ SDK you want to download + FetchContent_Declare( + cpprealm + GIT_REPOSITORY https://github.com/realm/realm-cpp.git + GIT_TAG v1.0.0 + ) + + # The MakeAvailable command ensures the named dependencies have been populated + FetchContent_MakeAvailable(cpprealm) + + # Create an executable target called myApp with the source file main.cpp + add_executable(myApp main.cpp) + + target_link_libraries(myApp PRIVATE cpprealm) + + .. step:: Run CMake + + Run CMake in a gitignored directory, such as ``build``, to generate the build + configurations that you can then use to compile your app: + + .. code-block:: + + # build/ is in .gitignore + mkdir build + cd build + cmake .. # Create Makefile by reading the CMakeLists.txt in the parent directory (../) + make # Actually build the app + + You can use CMake to generate more than simple Makefiles by using the ``-G`` + flag. See the `CMake documentation `_ for more + information. diff --git a/source/includes/api-details/cpp/install/install-install-sdk-procedure-swift-package-manager.rst b/source/includes/api-details/cpp/install/install-install-sdk-procedure-swift-package-manager.rst new file mode 100644 index 0000000000..77c730b95a --- /dev/null +++ b/source/includes/api-details/cpp/install/install-install-sdk-procedure-swift-package-manager.rst @@ -0,0 +1,23 @@ +When developing with Xcode, you can use Swift Package Manager (SPM) to +install the SDK's ``realm-cpp`` library. + +.. procedure:: + + .. step:: Add Package Dependency + + In Xcode, select ``File`` > ``Add Packages...``. + + .. step:: Specify the Repository + + Copy and paste the following into the search/input box. + + .. code-block:: + + https://github.com/realm/realm-cpp + + .. step:: Select the Package Products + + Under :guilabel:`Package Product`, select ``realm-cpp-sdk``. Under + :guilabel:`Add to Target`, select the target you would like to add + the SDK to. For example, the target might be the main executable of + your app. Click :guilabel:`Add Package`. diff --git a/source/includes/api-details/cpp/install/install-intro-description.rst b/source/includes/api-details/cpp/install/install-intro-description.rst new file mode 100644 index 0000000000..bf152df736 --- /dev/null +++ b/source/includes/api-details/cpp/install/install-intro-description.rst @@ -0,0 +1,3 @@ +Atlas Device SDK for C++ enables client applications written in C++ to access +data stored on devices and sync data with Atlas. This page details how to +install the C++ SDK in your project and get started. diff --git a/source/includes/api-details/cpp/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/cpp/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..f3932163ea --- /dev/null +++ b/source/includes/api-details/cpp/install/install-platform-specific-considerations-description.rst @@ -0,0 +1 @@ +- :ref:`sdks-build-for-android` diff --git a/source/includes/api-details/cpp/install/install-requirements-description.rst b/source/includes/api-details/cpp/install/install-requirements-description.rst new file mode 100644 index 0000000000..cd81052232 --- /dev/null +++ b/source/includes/api-details/cpp/install/install-requirements-description.rst @@ -0,0 +1,4 @@ +- Minimum C++ standard: C++17. +- For development on macOS: Xcode 11.x or later. +- For development on Windows: Microsoft Visual C++ (MSVC). +- Otherwise, we recommend git and `CMake `__. diff --git a/source/includes/api-details/cpp/platforms/android-build-android-app-description.rst b/source/includes/api-details/cpp/platforms/android-build-android-app-description.rst new file mode 100644 index 0000000000..284ccfff38 --- /dev/null +++ b/source/includes/api-details/cpp/platforms/android-build-android-app-description.rst @@ -0,0 +1,32 @@ +The SDK supports building Android apps with C++. To build an Android app: + +- :ref:`sdks-install` +- Add ```` to + your ``AndroidManifest.xml`` +- Add the SDK's subdirectory to your native library's ``CMakeLists.txt`` + and link it as a target library: + + .. code-block:: text + + set(CMAKE_CXX_STANDARD 17) + add_subdirectory("realm-cpp") + ... + target_link_libraries( + # Specifies the target library. + myapplication + # make sure to link the C++ SDK. + cpprealm + ) + +- Ensure that the git submodules are initialized inside of the ``realm-cpp`` + folder before building. +- When instantiating the database or the SDK App, you must pass the + ``filesDir.path`` as the ``path`` parameter in the respective constructor or + database open template. + +For an example of how to use the SDK in an Android app, refer to +the :github:`Android RealmExample App ` +in the ``realm-cpp`` GitHub repository. + +Specifically, refer to the ``MainActivity.kt`` & ``native-lib.cpp`` files +in the Android example app for code examples. diff --git a/source/includes/api-details/csharp/install/install-import-sdk-description.rst b/source/includes/api-details/csharp/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..3bff9b4832 --- /dev/null +++ b/source/includes/api-details/csharp/install/install-import-sdk-description.rst @@ -0,0 +1 @@ +Add the following line to the top of your source files to use the SDK: diff --git a/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-mac.rst b/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-mac.rst new file mode 100644 index 0000000000..2a363f28aa --- /dev/null +++ b/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-mac.rst @@ -0,0 +1,23 @@ +.. procedure:: + + .. step:: Open the NuGet Package Manager + + In the Solution Explorer, right-click your solution and select + :guilabel:`Manage NuGet Packages...` to open the NuGet + Package management window. + + .. figure:: /images/vs-mac-nuget.png + :alt: Open the NuGet Package management window. + :lightbox: + + .. note:: + + Adding the package at the Solution level allows you to add + it to every project in one step. + + .. step:: Add the Realm Package + + In the search bar, search for **Realm**. Select the + result and click :guilabel:`Add Package`. If you are using Xamarin, + you may be prompted to select which projects use the Realm + package. Select all of the projects, and then click :guilabel:`Ok`. diff --git a/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-windows.rst b/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-windows.rst new file mode 100644 index 0000000000..c7abe55167 --- /dev/null +++ b/source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-windows.rst @@ -0,0 +1,27 @@ +.. procedure:: + + .. step:: Open the NuGet Package Manager + + In the Solution Explorer, right-click your solution and + select :guilabel:`Manage NuGet Packages for Solution...` + to open the NuGet Package management window. + + .. figure:: /images/vs-win-nuget.png + :alt: Open the NuGet Package management window. + :lightbox: + + .. step:: Add the Realm Package + + + In the search bar, search for **Realm**. Select the + result and click :guilabel:`Install`. When prompted, + select all projects and click :guilabel:`Ok`. + + .. figure:: /images/vs-win-nuget-search.png + :alt: Search for Realm and add it to your project(s). + :lightbox: + +.. step:: Add the Realm Weaver to FodyWeavers.xml + + .. include:: /includes/add-realm-fody-weaver.rst + \ No newline at end of file diff --git a/source/includes/api-details/csharp/install/install-intro-description.rst b/source/includes/api-details/csharp/install/install-intro-description.rst new file mode 100644 index 0000000000..fb1e5943bc --- /dev/null +++ b/source/includes/api-details/csharp/install/install-intro-description.rst @@ -0,0 +1,7 @@ +You can use the Atlas Device SDK for .NET to develop apps in C# .NET with +several frameworks, including +`.NET MAUI `__, +`Xamarin `__, +`Avalonia UI `__, +`UWP `__, +`Unity `__, and others. diff --git a/source/includes/api-details/csharp/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/csharp/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..90ecae307a --- /dev/null +++ b/source/includes/api-details/csharp/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,18 @@ +- :ref:`sdks-unity` + +Apple Privacy Manifest +~~~~~~~~~~~~~~~~~~~~~~ + +When building for Apple platforms, Apple requires any apps or third-party SDKs +that use *required reasons APIs* to provide a privacy manifest. The manifest +contains details about the app's or SDK's data collection and use practices, +and it must be included when submitting new apps or app updates to the Apple +App Store. + +Some of the SDK language and framework libraries provide a privacy manifest to +streamline this process. The .NET library does not provide a privacy manifest. +If your application is a cross-platform app that you intend to submit to the +Apple App Store, you may be required to provide your own version of this +privacy manifest. + +For details, refer to :ref:`sdks-apple-privacy-manifest`. diff --git a/source/includes/api-details/csharp/install/install-requirements-description.rst b/source/includes/api-details/csharp/install/install-requirements-description.rst new file mode 100644 index 0000000000..16ab598807 --- /dev/null +++ b/source/includes/api-details/csharp/install/install-requirements-description.rst @@ -0,0 +1,4 @@ +Before getting started, ensure you have installed Visual Studio: + +- `Visual Studio `__ 2015 Update 2 or later. +- `Visual Studio for Mac `__ 7.0 or later. diff --git a/source/includes/api-details/dart/install/install-import-sdk-description.rst b/source/includes/api-details/dart/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..3bff9b4832 --- /dev/null +++ b/source/includes/api-details/dart/install/install-import-sdk-description.rst @@ -0,0 +1 @@ +Add the following line to the top of your source files to use the SDK: diff --git a/source/includes/api-details/dart/install/install-install-sdk-procedure.rst b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst new file mode 100644 index 0000000000..ad8029ec28 --- /dev/null +++ b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst @@ -0,0 +1,45 @@ +.. procedure:: + + .. step:: Create a Project + + To create a Dart project, run the following commands: + + .. code-block:: + + dart create + cd + + For more information, refer to Dart's `Get Started Guide + `__ for standalone + Dart command-line and server applications. + + .. step:: Add the SDK to the Project + + To add the SDK to your project, run the following command: + + .. code-block:: + + dart pub add realm_dart + + This downloads the `realm_dart + `__ package, and adds it to + your project. + + In your ``pubspec.yaml`` file, you should see: + + .. code-block:: + :caption: pubspec.yaml + + dependencies: + realm_dart: + + After the package is added, run the following command to install it: + + .. code-block:: + + dart run realm_dart install + + This downloads and copies the required native binaries to the app + directory. + +.. include:: /includes/api-details/dart/install/install-update-package-version-description.rst diff --git a/source/includes/api-details/dart/install/install-intro-description.rst b/source/includes/api-details/dart/install/install-intro-description.rst new file mode 100644 index 0000000000..874a9997d1 --- /dev/null +++ b/source/includes/api-details/dart/install/install-intro-description.rst @@ -0,0 +1,4 @@ +Use Atlas Device SDK to build a Flutter project or a standalone Dart project. +This guide provides instructions for installing the SDK in a standalone Dart +project. For details about installing the SDK in a Flutter project, refer to +:ref:`sdks-install-sdk-in-flutter-project`. diff --git a/source/includes/api-details/dart/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/dart/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..54785221d1 --- /dev/null +++ b/source/includes/api-details/dart/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,16 @@ +- :ref:`macOS: Device Sync and App Sandbox Entitlements ` + +Apple Privacy Manifest +~~~~~~~~~~~~~~~~~~~~~~ + +When building for Apple platforms, Apple requires any apps or third-party SDKs +that use *required reasons APIs* to provide a privacy manifest. The manifest +contains details about the app's or SDK's data collection and use practices, +and it must be included when submitting new apps or app updates to the Apple +App Store. + +Some of the SDK language and framework libraries provide a privacy manifest to +streamline this process. Starting in version 2.2.0, the Dart and Flutter +libraries provide a privacy manifest. + +For details, refer to :ref:`sdks-apple-privacy-manifest`. diff --git a/source/includes/api-details/dart/install/install-requirements-description.rst b/source/includes/api-details/dart/install/install-requirements-description.rst new file mode 100644 index 0000000000..bee3848a35 --- /dev/null +++ b/source/includes/api-details/dart/install/install-requirements-description.rst @@ -0,0 +1,11 @@ +For standalone Dart apps, you can install Dart in your development +environment without Flutter. To learn how, refer to the official +`Dart Installation Guide `__. + +The latest version of Atlas Device SDK requires Dart version +{+dart-minimum-version+} or later. + +Supported Platforms +~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/api-details/dart/install/install-supported-platforms-description.rst diff --git a/source/includes/api-details/dart/install/install-supported-platforms-description.rst b/source/includes/api-details/dart/install/install-supported-platforms-description.rst new file mode 100644 index 0000000000..92ce207c3e --- /dev/null +++ b/source/includes/api-details/dart/install/install-supported-platforms-description.rst @@ -0,0 +1,24 @@ +When using the SDK in a Flutter or standalone Dart project, you can build for +the following platforms: + +- iOS +- Android +- macOS +- Windows running on 64-bit architecture +- Linux running on 64-bit architecture + +.. important:: Unsupported Platforms + + The SDK does *not* currently support the following platforms through the + Dart or Flutter libraries: + + - Web + - Windows running on ARM64 or 32-bit architectures + - Linux running on ARM64 or 32-bit architectures + + Visit the respective "Build for Platforms" page for more details about + library and language support: + + - :ref:`sdks-build-for-web` + - :ref:`sdks-build-for-windows` + - :ref:`sdks-build-for-linux` diff --git a/source/includes/api-details/dart/install/install-update-package-version-description.rst b/source/includes/api-details/dart/install/install-update-package-version-description.rst new file mode 100644 index 0000000000..c5a14b1c95 --- /dev/null +++ b/source/includes/api-details/dart/install/install-update-package-version-description.rst @@ -0,0 +1,44 @@ +Update the Package Version +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To change the version of the SDK in your project, perform the following steps: + +.. procedure:: + + .. step:: Update the ``pubspec.yaml`` File + + Update the package version in your :file:`pubspec.yaml` file dependencies. + + .. code-block:: + :caption: pubspec.yaml + + dependencies: + realm_dart: + + .. step:: Install the Updated Package + + From the command line, run the following command to install the updated + version: + + .. code-block:: + + dart pub upgrade realm_dart + + Then, run the following command to install the updated SDK's native + binaries: + + .. code-block:: + + dart run realm_dart install + + .. step:: Regenerate Object Models + + Changes to the package version may affect the functionality of the object + models. From the command line, run the following command to regenerate + object models with new and updated functionality: + + .. code-block:: + + dart run realm_dart generate + + .. include:: /includes/flutter-v2-breaking-change.rst diff --git a/source/includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst b/source/includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst new file mode 100644 index 0000000000..6638e9d0b3 --- /dev/null +++ b/source/includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst @@ -0,0 +1,2 @@ +Add the following line to the top of your source files (JavaScript or +TypeScript) where you want to use the SDK: diff --git a/source/includes/api-details/javascript/install/install-intro-js-ts-description.rst b/source/includes/api-details/javascript/install/install-intro-js-ts-description.rst new file mode 100644 index 0000000000..77c1eed79e --- /dev/null +++ b/source/includes/api-details/javascript/install/install-intro-js-ts-description.rst @@ -0,0 +1,6 @@ +The Atlas Device SDK for JavaScript enables development of applications using +the JavaScript and TypeScript languages. The JavaScript library is best suited +for writing server-side applications. Your application could be one +component in a wider stack that also includes iOS and Android apps. + +The JavaScript library is not suitable for front-end application development. diff --git a/source/includes/api-details/javascript/install/install-requirements-js-ts-description.rst b/source/includes/api-details/javascript/install/install-requirements-js-ts-description.rst new file mode 100644 index 0000000000..d9fd9166da --- /dev/null +++ b/source/includes/api-details/javascript/install/install-requirements-js-ts-description.rst @@ -0,0 +1,5 @@ +Before getting started, ensure your environment meets the +following requirements: + +- `Node.js `__ version 12.x or later (including Node.js version 14) +- Linux, macOS 10.8 (or later), or Windows 8 (or later) diff --git a/source/includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst b/source/includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst new file mode 100644 index 0000000000..a624e081f2 --- /dev/null +++ b/source/includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst @@ -0,0 +1,33 @@ +.. procedure:: + + .. step:: Create a Node.js Project + + Create your Node.js project by creating a new directory + for your project and running ``npm init`` in that + directory. In the example below, replace ``MyApp`` + with your desired project name. Answer all of the prompts + to fill out the details of your project. + + .. code-block:: + + mkdir MyApp && cd MyApp && npm init + + .. step:: Install the SDK with NPM + + In your Node.js project directory, use the following command + to add the SDK to your project: + + .. code-block:: + + npm install realm + + .. step:: Enable TypeScript (optional) + + TypeScript is a superset of JavaScript that adds static + type checking and other features intended to make + application-scale development more robust. If you'd like + to use TypeScript, follow the TypeScript team's official + `Node Starter guide + `__. + The SDK supports TypeScript natively and integrates easily + into a TypeScript project. diff --git a/source/includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst b/source/includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst new file mode 100644 index 0000000000..8bd5d9cb2d --- /dev/null +++ b/source/includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst @@ -0,0 +1,16 @@ +Supported Platforms +~~~~~~~~~~~~~~~~~~~ + +The installation instructions on this page assume you're using the JavaScript +library in a server-side environment. For instructions installing the library +for Internet of Things (IoT) devices, refer to :ref:`sdks-build-for-iot`. + +Unsupported Platforms +~~~~~~~~~~~~~~~~~~~~~ + +- **Front-end Web Applications**: due to limitations of the browser environment, + it is not possible to build a browser-based web app with this library. For + front-end web applications, refer to :ref:`sdks-build-for-web`. + +- **Mobile App Development**: For cross-platform mobile app development, refer + to :ref:`sdks-build-with-react-native`. diff --git a/source/includes/api-details/kotlin/install/install-import-sdk-description.rst b/source/includes/api-details/kotlin/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..97d5577053 --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-import-sdk-description.rst @@ -0,0 +1,13 @@ +In the files where you use the SDK, add the appropriate imports for the APIs +you're using. + +The Kotlin library APIs are divided into two modules: + +- :kotlin-sdk:`Realm Kotlin SDK `: APIs that deal with device + database functionality, such as modeling data, reacting to changes, and type + serializers. +- :kotlin-sync-sdk:`Realm Kotlin SDK - Sync `: APIs that deal with + connecting to MongoDB for Device Sync, user authentication, calling an + Atlas Function, and accessing MongoDB Atlas. + +Refer to the API documentation for each respective module for API details. diff --git a/source/includes/api-details/kotlin/install/install-install-sdk-procedure-android.rst b/source/includes/api-details/kotlin/install/install-install-sdk-procedure-android.rst new file mode 100644 index 0000000000..fff2b48a61 --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-install-sdk-procedure-android.rst @@ -0,0 +1,54 @@ +.. procedure:: + + .. step:: Add the SDK to the Project + + Add :file:`io.realm.kotlin`, specifying the library version and + :file:`apply false`, to the list of plugins in your project-level Gradle + build file, typically found at :file:`/build.gradle`: + + .. code-block:: + :caption: Global build.gradle + + plugins { + id 'io.realm.kotlin' version '{+kotlin-sdk-version+}' apply false + } + + Add the following to your app-level Gradle build file, typically + found at :file:`/app/build.gradle`: + + - Add :file:`io.realm.kotlin` to the list of plugins. + - Add the following to the list of dependencies: + + - Add :file:`io.realm.kotlin:library-base` to the dependencies block. + - If using Device Sync in your application, add :file:`io.realm.kotlin:library-sync` to the dependencies block. + + - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies. + + .. code-block:: + :caption: Module build.gradle + :emphasize-lines: 4, 12-16 + + plugins { + id 'com.android.application' + id 'org.jetbrains.kotlin.android' + id 'io.realm.kotlin' + } + + android { + // ... build configuration settings + } + + dependencies { + implementation 'io.realm.kotlin:library-base:{+kotlin-sdk-version+}' + // If using Device Sync + implementation 'io.realm.kotlin:library-sync:{+kotlin-sdk-version+}' + // If using coroutines with the SDK + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:{+kotlinx-coroutines-version+}' + } + + .. step:: Sync Gradle Files + + After updating the Gradle configuration, + resolve the dependencies by clicking :guilabel:`File` > + :guilabel:`Sync Project with Gradle Files` in the Android Studio menu bar. + You can now use the SDK in your application. \ No newline at end of file diff --git a/source/includes/api-details/kotlin/install/install-install-sdk-procedure-kotlin-multiplatform.rst b/source/includes/api-details/kotlin/install/install-install-sdk-procedure-kotlin-multiplatform.rst new file mode 100644 index 0000000000..b1da4a7e7c --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-install-sdk-procedure-kotlin-multiplatform.rst @@ -0,0 +1,64 @@ +.. procedure:: + + .. step:: Add the SDK to the Project + + 1. Add the following to your app-level Gradle build file, typically found at :file:`/app/build.gradle`: + + - Add :file:`io.realm.kotlin` to the list of plugins. + - Add the following to the list of dependencies: + + - Add :file:`io.realm.kotlin:library-base` to the dependencies block. + - If using Device Sync in your application, add :file:`io.realm.kotlin:library-sync` to the dependencies block. + + - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies. + + .. code-block:: + :caption: App build.gradle + :emphasize-lines: 5, 18-22 + + plugins { + kotlin("multiplatform") + kotlin("native.cocoapods") + id("com.android.library") + id("io.realm.kotlin") version "{+kotlin-sdk-version+}" + } + + version = "1.0" + + kotlin { + android() + iosX64() + iosArm64() + + sourceSets { + val commonMain by getting { + dependencies { + implementation("io.realm.kotlin:library-base:{+kotlin-sdk-version+}") + // If using Device Sync + implementation("io.realm.kotlin:library-sync:{+kotlin-sdk-version+}") + // If using coroutines with the SDK + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:{+kotlinx-coroutines-version+}") + } + } + } + } + + 2. If you use any part of the SDK inside the Android module, add the following compile-time dependencies to your module-level Gradle build file, typically found at :file:`/module/build.gradle`: + + .. code-block:: + :caption: Android Module build.gradle + + dependencies { + compileOnly("io.realm.kotlin:library-base:{+kotlin-sdk-version+}") + } + // If using Device Sync + dependencies { + compileOnly("io.realm.kotlin:library-sync:{+kotlin-sdk-version+}") + } + + .. step:: Sync Gradle Files + + After updating the Gradle configuration, + resolve the dependencies by clicking :guilabel:`File` > + :guilabel:`Sync Project with Gradle Files` in the Android Studio menu bar. + You can now use the SDK in your application. diff --git a/source/includes/api-details/kotlin/install/install-intro-description.rst b/source/includes/api-details/kotlin/install/install-intro-description.rst new file mode 100644 index 0000000000..c93469558e --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-intro-description.rst @@ -0,0 +1,5 @@ +The Atlas Device SDK for Kotlin supports the following platforms. Each has its +own installation method and requirements: + +- Android +- Kotlin Multiplatform (KMP) diff --git a/source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..e6147d3924 --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,19 @@ +- :ref:`sdks-build-for-android` +- :ref:`sdks-build-for-apple` + +Apple Privacy Manifest +~~~~~~~~~~~~~~~~~~~~~~ + +When building for Apple platforms, Apple requires any apps or third-party SDKs +that use *required reasons APIs* to provide a privacy manifest. The manifest +contains details about the app's or SDK's data collection and use practices, +and it must be included when submitting new apps or app updates to the Apple +App Store. + +Some of the SDK language and framework libraries provide a privacy manifest to +streamline this process. The Kotlin library does not provide a privacy +manifest. If your application is a cross-platform app that you intend to +submit to the Apple App Store, you may be required to provide your own version +of this privacy manifest. + +For details, refer to :ref:`sdks-apple-privacy-manifest`. diff --git a/source/includes/api-details/kotlin/install/install-requirements-description.rst b/source/includes/api-details/kotlin/install/install-requirements-description.rst new file mode 100644 index 0000000000..9c7bbde8bb --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-requirements-description.rst @@ -0,0 +1,34 @@ +Before getting started, ensure your development environment +meets the following prerequisites: + +- :android:`Android Studio ` Bumblebee 2021.1.1 or higher. +- JDK 11 or higher. +- Kotlin Plugin for Android Studio, version 1.6.10 or higher. +- An Android Virtual Device (AVD) using a supported CPU architecture. + +Additionally, Kotlin Multiplatform (KMP) for mobile projects require the following: + +- `Kotlin Multiplatform Mobile (KMM) Plugin + `__ + for Android Studio, version 0.3.1 or higher. +- A Kotlin Multiplatform (KMP) App created using the "Kotlin Multiplatform App" + template in Android Studio. Follow the instructions in the + `Kotlin Multiplatform documentation + `__. + +For more details on setting up your KMP environment, refer to the `official +Kotlin Multiplatform for mobile +`__ documentation. To verify your +environment setup, follow Kotlin's `guide to checking your +environment +`__. + +.. tip:: Kotlin Plugin Version + + The Kotlin Multiplatform (KMP) ecosystem frequently changes. If you experience + any issues installing the SDK, check your Kotlin Plugin version, since + outdated plugins can lead to difficult to debug errors. To see which + versions of the Kotlin Plugin are compatible with the SDK, refer to the + `Kotlin SDK changelog `__. + +.. include:: /includes/api-details/kotlin/install/install-supported-target-environments-description.rst diff --git a/source/includes/api-details/kotlin/install/install-supported-target-environments-description.rst b/source/includes/api-details/kotlin/install/install-supported-target-environments-description.rst new file mode 100644 index 0000000000..4eecaeb249 --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-supported-target-environments-description.rst @@ -0,0 +1,67 @@ +Supported Target Environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kotlin Multiplatform (KMP) supports a wide range of application environments +Refer also to Kotlin's `Multiplatform Gradle DSL reference: Targets +`__ documentation. + +.. tabs:: + + .. tab:: Supported Environments + :tabid: kmp-supported-environments + + The Kotlin library supports the following environments: + + - :file:`android` + + - :file:`iosArm64` + - :file:`iosSimulatorArm64` + - :file:`iosX64` + + - :file:`jvm` + + - :file:`macosArm64` + - :file:`macosX64` + + .. tab:: Unsupported Environments + :tabid: kmp-unsupported-environments + + The Kotlin library does *not* support the following environments: + + - :file:`androidNativeArm32` + - :file:`androidNativeArm64` + - :file:`androidNativeX86` + - :file:`androidNativeX64` + + - :file:`iosArm32` + + - :file:`js` + + - :file:`linuxArm32Hfp` + - :file:`linuxArm64` + - :file:`linuxMips32` + - :file:`linuxMipsel32` + - :file:`linuxX64` + + - :file:`mingwX64` + - :file:`mingwX86` + + - :file:`tvosArm64` + - :file:`tvosSimulatorArm64` + - :file:`tvosX64` + + - :file:`wasm32` + + - :file:`watchosArm32` + - :file:`watchosArm64` + - :file:`watchosSimulatorArm64` + - :file:`watchosX86` + - :file:`watchosX64` + +If you want to build for an environment that the Kotlin library does not +support, consider using one of the other libraries. For more information, +refer to these "Build for Platform" pages: + +- :ref:`sdks-build-for-apple` +- :ref:`sdks-build-for-linux` +- :ref:`sdks-build-for-web` diff --git a/source/includes/api-details/objectivec/install/install-import-sdk-description.rst b/source/includes/api-details/objectivec/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..fb34b4cd0f --- /dev/null +++ b/source/includes/api-details/objectivec/install/install-import-sdk-description.rst @@ -0,0 +1 @@ +Add the following line at the top of your source files to use the SDK: diff --git a/source/includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..33b5b15cfe --- /dev/null +++ b/source/includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,20 @@ +- :ref:`sdks-build-for-apple` +- :ref:`sdks-tvos` + +Apple Privacy Manifest +~~~~~~~~~~~~~~~~~~~~~~ + +Apple requires any apps or third-party SDKs that use *required reasons APIs* +to provide a privacy manifest. The manifest contains details about the app's +or SDK's data collection and use practices, and it must be included when +submitting new apps or app updates to the Apple App Store. + +The Swift and Objective-C libraries provide a privacy manifest to streamline +this process. + +To include these manifests in a build target that uses the ``Realm`` library, +you must build ``Realm`` as a dynamic framework. For details, refer to the +Swift Package Manager Installation instructions step +**(Optional) Build RealmSwift as a Dynamic Framework**. + +For additional details, refer to :ref:`sdks-apple-privacy-manifest`. diff --git a/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst b/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst new file mode 100644 index 0000000000..31112af4e2 --- /dev/null +++ b/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst @@ -0,0 +1,62 @@ +If you are installing with `CocoaPods +`__, you need +CocoaPods 1.10.1 or later. + +.. procedure:: + + .. step:: Update the CocoaPods repositories + + On the command line, run ``pod repo update`` to ensure + CocoaPods can access the latest available ``Realm`` library versions. + + .. step:: Initialize CocoaPods for Your Project + + If you do not already have a Podfile for your project, + run ``pod init`` in the root directory of your project to + create a Podfile for your project. A Podfile allows you + to specify project dependencies to CocoaPods. + + .. step:: Add the SDK as a Dependency in Your Podfile + + Add a ``use_frameworks!`` line to your Podfile if it is not + already there. + + Add the line ``pod 'Realm', '~>10'`` to your main and test + targets. + + When done, your Podfile should look similar to this: + + .. code-block:: + :emphasize-lines: 8 + + platform :ios, '12.0' + + target 'MyDeviceSDKProject' do + # Comment the next line if you don't want to use dynamic frameworks + use_frameworks! + + # Pods for MyDeviceSDKProject + pod 'Realm', '~>10' + + target 'MyRealmProjectTests' do + inherit! :search_paths + # Pods for testing + pod 'Realm', '~>10' + end + + .. step:: Install the Dependencies + + From the command line, run ``pod install`` to fetch the + dependencies. + + .. step:: Use the CocoaPods-Generated ``.xcworkspace`` File + + CocoaPods generates an ``.xcworkspace`` file for you. This + file has all of the dependencies configured. From now on, + open this file -- not the ``.xcodeproj`` file -- to work + on your project. + +Resolve Build Issues +~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst diff --git a/source/includes/api-details/objectivec/install/install-sdk-procedure-swift-package-manager.rst b/source/includes/api-details/objectivec/install/install-sdk-procedure-swift-package-manager.rst new file mode 100644 index 0000000000..ca0a784b7a --- /dev/null +++ b/source/includes/api-details/objectivec/install/install-sdk-procedure-swift-package-manager.rst @@ -0,0 +1,48 @@ +.. procedure:: + + .. step:: Add Package Dependency + + In Xcode, select ``File`` > ``Add Packages...``. + + .. step:: Specify the Repository + + Copy and paste the following into the search/input box. + + .. code-block:: + + https://github.com/realm/realm-swift.git + + .. step:: Specify Options + + In the options for the ``realm-swift`` package, we recommend setting + the ``Dependency Rule`` to ``Up to Next Major Version``, + and enter the `current Swift library version + `__ . Then, click + ``Add Package``. + + .. step:: Select the Package Products + + .. versionchanged:: 10.49.3 + Instead of adding both, only add one package. + + Select either ``RealmSwift`` or ``Realm``, then click ``Add Package``. + + - If you use *only* Objective-C APIs, add ``Realm``. + - If you use Swift or Swift and Objective-C APIs, add ``RealmSwift``. + + .. step:: (Optional) Build Realm as a Dynamic Framework + + To use the Privacy Manifest supplied by the SDK, build ``Realm`` or + ``RealmSwift`` as a dynamic framework. If you build the library as a + static framework, you must supply your own Privacy Manifest. + + To build the library as a dynamic framework: + + 1. In your project :guilabel:`Targets`, select your build target. + 2. Go to the :guilabel:`General` tab. + 3. Expand the :guilabel:`Frameworks and Libraries` element. + 4. For the ``Realm`` framework, change the + :guilabel:`Embed` option from "Do Not Embed" to "Embed & Sign." + + Now, Xcode builds ``Realm`` dynamically, and can provide the + SDK-supplied Privacy Manifest. diff --git a/source/includes/api-details/swift/install/install-import-sdk-description.rst b/source/includes/api-details/swift/install/install-import-sdk-description.rst new file mode 100644 index 0000000000..7e6ec91e75 --- /dev/null +++ b/source/includes/api-details/swift/install/install-import-sdk-description.rst @@ -0,0 +1,9 @@ +Within your Swift files, you can access the Swift APIs and all required +wrappers. The vast majority of ``RealmSwift`` types are directly aliased from +their Objective-C counterparts. + +In some cases, the :swift-sdk:`Swift API reference <>` documentation does not +include details for the underlying Objective-C counterparts. You may need to +drop down to the :objc-sdk:`Objective-C API reference <>` for more details. + +Add the following line at the top of your source files to use the SDK: diff --git a/source/includes/api-details/swift/install/install-intro-description.rst b/source/includes/api-details/swift/install/install-intro-description.rst new file mode 100644 index 0000000000..20df889cd8 --- /dev/null +++ b/source/includes/api-details/swift/install/install-intro-description.rst @@ -0,0 +1,4 @@ +Atlas Device SDK for Swift enables you to build iOS, macOS, tvOS, +and watchOS applications using either the Swift or Objective-C programming +languages. This page details how to install the SDK in your project and get +started. diff --git a/source/includes/api-details/swift/install/install-platform-specific-considerations-description.rst b/source/includes/api-details/swift/install/install-platform-specific-considerations-description.rst new file mode 100644 index 0000000000..5049b6137e --- /dev/null +++ b/source/includes/api-details/swift/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,41 @@ +- :ref:`sdks-build-for-apple` +- :ref:`sdks-tvos` + +Swift Concurrency Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Swift SDK supports Swift's concurrency-related language features. +For best practices on using the Swift SDK's concurrency features, refer +to the documentation below. + +Async/Await Support +``````````````````` + +.. include:: /includes/swift-async-await-support.rst + +For more information about async/await support in the Swift SDK, refer +to :ref:`Swift Concurrency: Async/Await APIs `. + +Actor Support +````````````` + +The Swift SDK supports actor-isolated realm instances. For more information, +refer to :ref:`swift-actor-isolated-realm`. + +Apple Privacy Manifest +~~~~~~~~~~~~~~~~~~~~~~ + +Apple requires any apps or third-party SDKs that use *required reasons APIs* +to provide a privacy manifest. The manifest contains details about the app's +or SDK's data collection and use practices, and it must be included when +submitting new apps or app updates to the Apple App Store. + +The Swift and Objective-C libraries provide a privacy manifest to streamline +this process. + +To include these manifests in a build target that uses ``RealmSwift``, you must +build ``RealmSwift`` as a dynamic framework. For details, refer to the Swift +Package Manager Installation instructions step +**(Optional) Build RealmSwift as a Dynamic Framework**. + +For additional details, refer to :ref:`sdks-apple-privacy-manifest`. diff --git a/source/includes/api-details/swift/install/install-requirements-description.rst b/source/includes/api-details/swift/install/install-requirements-description.rst new file mode 100644 index 0000000000..fa2e7c4c7f --- /dev/null +++ b/source/includes/api-details/swift/install/install-requirements-description.rst @@ -0,0 +1,22 @@ +Before getting started, ensure your development environment +meets the following prerequisites: + +- Your project uses an Xcode version and minimum OS version that the library + supports. Refer to **Supported Target Environments** on this page for more + details. +- Reflection is enabled in your project. The Swift SDK uses reflection to + determine your model's properties. Your project must not set + ``SWIFT_REFLECTION_METADATA_LEVEL = none``, or the SDK cannot see properties + in your model. Reflection is enabled by default if your project does + not specifically set a level for this setting. + +.. include:: /includes/api-details/swift/install/install-supported-os-and-xcode-description.rst + +App Download File Size +~~~~~~~~~~~~~~~~~~~~~~ + +The SDK should only add around 5 to 8 MB to your app's download +size. The releases we distribute are significantly larger because they +include support for the iOS, watchOS and tvOS simulators, some debug symbols, +and bitcode, all of which are stripped by the App Store automatically when +apps are downloaded. diff --git a/source/includes/api-details/swift/install/install-resolve-build-issues-carthage.rst b/source/includes/api-details/swift/install/install-resolve-build-issues-carthage.rst new file mode 100644 index 0000000000..958ec15081 --- /dev/null +++ b/source/includes/api-details/swift/install/install-resolve-build-issues-carthage.rst @@ -0,0 +1,47 @@ +Some developers experience build issues after installing the SDK via +CocoaPods or Carthage. Common causes of these issues include: + +- Installation issues: + + - Initial install failed + - Using an unsupported version of the dependency manager + +- Build tool issues: + + - Build tools have stale caches + - Updating build tool versions + +- Making changes to your project setup, such as: + + - Adding a new target + - Sharing dependencies across targets + +A fix that often clears these issues is to delete derived data +and clean the Xcode build folder. + +.. procedure:: + + .. step:: Reset Carthage-managed Dependency State + + Run these commands in the terminal, in the root of your project: + + .. code-block:: + + rm -rf Carthage + # Assumes default DerivedData location: + rm -rf ~/Library/Developer/Xcode/DerivedData + carthage update + + .. important:: + + This will update **all** of your Carthage-managed dependencies, not + just Atlas Device SDK. + + .. step:: Clean the Xcode Build Folder + + With your project open in Xcode, go to the Product drop-down menu, + and select Clean Build Folder. + + .. figure:: /images/xcode-clean-build-folder.png + :alt: Select Product, then Clean Build Folder. + :lightbox: diff --git a/source/includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst b/source/includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst new file mode 100644 index 0000000000..ebd4753665 --- /dev/null +++ b/source/includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst @@ -0,0 +1,44 @@ +Some developers experience build issues after installing the SDK via +CocoaPods or Carthage. Common causes of these issues include: + +- Installation issues: + + - Initial install failed + - Using an unsupported version of the dependency manager + +- Build tool issues: + + - Build tools have stale caches + - Updating build tool versions + +- Making changes to your project setup, such as: + + - Adding a new target + - Sharing dependencies across targets + +A fix that often clears these issues is to delete derived data +and clean the Xcode build folder. + +.. procedure:: + + .. step:: Reset the Cocoapods Integration State + + Run these commands in the terminal, in the root of your project: + + .. code-block:: + + pod cache clean Realm + pod cache clean RealmSwift + pod deintegrate || rm -rf Pods + pod install --repo-update --verbose + # Assumes the default DerivedData location: + rm -rf ~/Library/Developer/Xcode/DerivedData + + .. step:: Clean the Xcode Build Folder + + With your project open in Xcode, go to the Product drop-down menu, + and select Clean Build Folder. + + .. figure:: /images/xcode-clean-build-folder.png + :alt: Select Product, then Clean Build Folder. + :lightbox: diff --git a/source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst b/source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst new file mode 100644 index 0000000000..5f36d494a8 --- /dev/null +++ b/source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst @@ -0,0 +1,47 @@ +If you are installing with `Carthage +`__, you need +Carthage 0.33 or later. + +.. procedure:: + + .. step:: Add the SDK as a Dependency in Your Cartfile + + Add the SDK as a dependency by appending the line ``github + "realm/realm-swift"`` to your Cartfile. + + You can create a Cartfile or append to an existing one by + running the following command in your project directory: + + .. code-block:: + + echo 'github "realm/realm-swift"' >> Cartfile + + .. step:: Install the Dependencies + + From the command line, run ``carthage update --use-xcframeworks`` + to fetch the dependencies. + + .. step:: Add the Frameworks to Your Project + + Carthage places the built dependencies in the ``Carthage/Build`` + directory. + + Open your project's ``xcodeproj`` file in Xcode. Go to + the Project Navigator panel and click your application + name to open the project settings editor. Select the + :guilabel:`General` tab. + + In Finder, open the ``Carthage/Build/`` directory. Drag the + ``RealmSwift.xcframework`` and ``Realm.xcframework`` files + found in that directory to the :guilabel:`Frameworks, + Libraries, and Embedded Content` section of your + project's :guilabel:`General` settings. + + .. figure:: /images/carthage-add-frameworks.png + :alt: Drag the xcframework files into the Xcode project. + :lightbox: + +Resolve Build Issues +~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/api-details/swift/install/install-resolve-build-issues-carthage.rst diff --git a/source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst b/source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst new file mode 100644 index 0000000000..0506e7bf17 --- /dev/null +++ b/source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst @@ -0,0 +1,58 @@ +If you are installing with `CocoaPods +`__, you need +CocoaPods 1.10.1 or later. + +.. procedure:: + + .. step:: Update the CocoaPods repositories + + On the command line, run ``pod repo update`` to ensure + CocoaPods can access the latest available ``RealmSwift`` package versions. + + .. step:: Initialize CocoaPods for Your Project + + If you do not already have a Podfile for your project, + run ``pod init`` in the root directory of your project to + create a Podfile for your project. A Podfile allows you + to specify project dependencies to CocoaPods. + + .. step:: Add the SDK as a Dependency in Your Podfile + + Add a ``use_frameworks!`` line to your Podfile if it is not + already there. + + Add the line ``pod 'RealmSwift', '~>10'`` to your main and test + targets. + + When done, your Podfile should look similar to this: + + .. code-block:: + :emphasize-lines: 8 + + platform :ios, '12.0' + + target 'MyDeviceSDKProject' do + # Comment the next line if you don't want to use dynamic frameworks + use_frameworks! + + # Pods for MyDeviceSDKProject + pod 'RealmSwift', '~>10' + + end + + .. step:: Install the Dependencies + + From the command line, run ``pod install`` to fetch the + dependencies. + + .. step:: Use the CocoaPods-Generated ``.xcworkspace`` File + + CocoaPods generates an ``.xcworkspace`` file for you. This + file has all of the dependencies configured. From now on, + open this file -- not the ``.xcodeproj`` file -- to work + on your project. + +Resolve Build Issues +~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst diff --git a/source/includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst b/source/includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst new file mode 100644 index 0000000000..b329df293f --- /dev/null +++ b/source/includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst @@ -0,0 +1,22 @@ +.. procedure:: + + .. step:: Download and Extract the Framework + + Download the `latest release of the Swift library + `__ and extract the zip. + + .. step:: Copy Framework(s) Into Your Project + + Drag ``Realm.xcframework`` and ``RealmSwift.xcframework`` (if using) + to the File Navigator of your Xcode project. Select the + :guilabel:`Copy items if needed` checkbox and press :guilabel:`Finish`. + + .. tip:: + + If using the Objective-C API within a Swift project, we + recommend you include both Realm Swift and Realm Objective-C in your + project. Within your Swift files, you can access the Swift API and + all required wrappers. Using the RealmSwift API in mixed + Swift/Objective-C projects is possible because the vast majority of + RealmSwift types are directly aliased from their Objective-C + counterparts. diff --git a/source/includes/api-details/swift/install/install-sdk-procedure-swift-package-manager.rst b/source/includes/api-details/swift/install/install-sdk-procedure-swift-package-manager.rst new file mode 100644 index 0000000000..bb84f0686d --- /dev/null +++ b/source/includes/api-details/swift/install/install-sdk-procedure-swift-package-manager.rst @@ -0,0 +1,48 @@ +.. procedure:: + + .. step:: Add Package Dependency + + In Xcode, select ``File`` > ``Add Packages...``. + + .. step:: Specify the Repository + + Copy and paste the following into the search/input box. + + .. code-block:: + + https://github.com/realm/realm-swift.git + + .. step:: Specify Options + + In the options for the ``realm-swift`` package, we recommend setting + the ``Dependency Rule`` to ``Up to Next Major Version``, + and enter the `current Swift library version + `__ . Then, click + ``Add Package``. + + .. step:: Select the Package Products + + .. versionchanged:: 10.49.3 + Instead of adding both, only add one package. + + Select either ``RealmSwift`` or ``Realm``, then click ``Add Package``. + + - If you use Swift or Swift and Objective-C APIs, add ``RealmSwift``. + - If you use *only* Objective-C APIs, add ``Realm``. + + .. step:: (Optional) Build RealmSwift as a Dynamic Framework + + To use the Privacy Manifest supplied by the SDK, build the library + as a dynamic framework. If you build the library as a static + framework, you must supply your own Privacy Manifest. + + To build the library as a dynamic framework: + + 1. In your project :guilabel:`Targets`, select your build target. + 2. Go to the :guilabel:`General` tab. + 3. Expand the :guilabel:`Frameworks and Libraries` element. + 4. For the ``RealmSwift`` framework, change the + :guilabel:`Embed` option from "Do Not Embed" to "Embed & Sign." + + Now, Xcode builds ``RealmSwift`` dynamically, and can provide the + SDK-supplied Privacy Manifest. diff --git a/source/includes/api-details/swift/install/install-supported-os-and-xcode-description.rst b/source/includes/api-details/swift/install/install-supported-os-and-xcode-description.rst new file mode 100644 index 0000000000..11f9d7e2e9 --- /dev/null +++ b/source/includes/api-details/swift/install/install-supported-os-and-xcode-description.rst @@ -0,0 +1,42 @@ +Supported Target Environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + There are special considerations when using the SDK with + tvOS. See :ref:`sdks-tvos` for more information. + +Xcode 15 +```````` + +.. versionchanged:: 10.50.0 + Minimum required Xcode version is 15.1 + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: index-table + + * - Supported OS + - Realm Database + - Atlas App Services + + * - iOS 12.0+ + - X + - X + + * - macOS 10.14+ + - X + - X + + * - tvOS 12.0+ + - X + - X + + * - watchOS 4.0+ + - X + - + + * - visionOS 1.0+ + - X + - X diff --git a/source/includes/flutter-v2-breaking-change.rst b/source/includes/flutter-v2-breaking-change.rst index 0edd624533..d8505b67cb 100644 --- a/source/includes/flutter-v2-breaking-change.rst +++ b/source/includes/flutter-v2-breaking-change.rst @@ -1,8 +1,9 @@ -.. important:: Flutter SDK v2.0.0 Breaking Change to Generated Files +.. important:: SDK v2.0.0 Breaking Change to Generated Files - Flutter SDK version 2.0.0 introduces an update to the - builder, which impacts how files generate. In v2.0.0 and later, all - generated files use the ``.realm.dart`` naming convention instead of ``.g.dart``. + SDK version 2.0.0 introduces an update to the + builder, which impacts how files generate. In v2.0.0 and later, all + generated files use the ``.realm.dart`` naming convention instead of ``.g.dart``. - This is a breaking change for existing apps. For information on how to upgrade an existing app from an earlier SDK version to v2.0.0 or later, - refer to :ref:`flutter-upgrade-v2`. + This is a breaking change for existing apps. For information on how to + upgrade an existing app from an earlier SDK version to v2.0.0 or later, + refer to :ref:`flutter-upgrade-v2`. diff --git a/source/includes/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst new file mode 100644 index 0000000000..f9b0856eae --- /dev/null +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -0,0 +1,55 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.include-header.cpp + :language: cpp + + - id: csharp + content: | + + .. code-block:: csharp + + using Realms; + + - id: dart + content: | + + .. code-block:: dart + :caption: ExampleFile.dart + + import 'package:realm_dart/realm.dart'; + + - id: javascript + content: | + + .. code-block:: javascript + + import Realm from "realm"; + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/MyRealmApp.snippet.import-realm.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/RealmApp.snippet.import-realm.swift + :language: swift + + - id: typescript + content: | + + .. code-block:: typescript + + import Realm from "realm"; diff --git a/source/platforms.txt b/source/platforms.txt index 8da0a2109c..519247049a 100644 --- a/source/platforms.txt +++ b/source/platforms.txt @@ -28,6 +28,6 @@ with Atlas Device SDK: - :ref:`sdks-build-for-apple` - :ref:`sdks-build-for-iot` - :ref:`sdks-build-for-linux` -- :ref:`dotnet-unity` +- :ref:`sdks-unity` - :ref:`sdks-build-for-web` - :ref:`sdks-build-for-windows` diff --git a/source/platforms/android.txt b/source/platforms/android.txt index 07e511aebf..8f771c7f35 100644 --- a/source/platforms/android.txt +++ b/source/platforms/android.txt @@ -4,13 +4,82 @@ Build for Android ================= +.. meta:: + :description: Provide a short description of the consolidated page. This is critical for SEO. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol +.. tabs-selector:: drivers + Placeholder page for information about building for Android. Include info about which frameworks we support building for Android, plus any specific version or compatibility info worth calling out? + +Build an Android App +-------------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/platforms/android-build-android-app-description.rst + + .. tab:: + :tabid: csharp + + + + .. tab:: + :tabid: dart + + + + .. tab:: + :tabid: java + + + + .. tab:: + :tabid: java-kotlin + + + + .. tab:: + :tabid: javascript + + + + .. tab:: + :tabid: kotlin + + + + .. tab:: + :tabid: objectivec + + + + .. tab:: + :tabid: swift + + + + .. tab:: + :tabid: typescript + + diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index cb469465eb..338cd797a1 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -13,8 +13,10 @@ Build for Apple .. toctree:: :titlesonly: + Apple Privacy Manifest Swift Concurrency Swift Actor Support + Build for tvOS Placeholder page for information about building for Apple. @@ -23,3 +25,41 @@ any specific version or compatibility info worth calling out? Maybe make this a directory with Apple-specific content (Apple Privacy Manifest, build for tvOS, etc.?) + +Build for macOS +--------------- + +Device Sync and App Sandbox Entitlements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are developing for macOS and require network access, you must enable +network entitlements in your application. By default, Apple's App Sandbox +does not allow network requests due to built-in security settings. + +Enable network entitlements to use these SDK features: + +- :ref:`Device Sync ` +- :ref:`Call an Atlas Function ` +- :ref:`Access MongoDB Atlas ` + +.. _sdks-macos-flutter-app-sandbox-entitlements: + +With Flutter +~~~~~~~~~~~~ + +To enable network requests in a Flutter application, add the following code +to **both** the files :file:`macos/Runner/DebugProfile.entitlements` and +:file:`macos/Runner/Release.entitlements`: + +.. code-block:: xml + :emphasize-lines: 2-3 + + + com.apple.security.network.client + + + +For more information about Flutter development for macOS, refer to +`Building macOS apps with Flutter +`__ +in the Flutter documentation. diff --git a/source/platforms/apple/privacy-manifest.txt b/source/platforms/apple/privacy-manifest.txt new file mode 100644 index 0000000000..3f00f65c76 --- /dev/null +++ b/source/platforms/apple/privacy-manifest.txt @@ -0,0 +1,71 @@ +.. _sdks-apple-privacy-manifest: + +=========================================== +The Atlas Device SDK Apple Privacy Manifest +=========================================== + +.. meta:: + :description: Learn about the SDK-provided Privacy Manifest when building for the Apple App Store, and any additional details you may be required to supply. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Apple may require apps that use Atlas Device SDK to provide a privacy manifest +containing details about the SDK's data collection and use practices. The +bundled manifest file must be included when submitting new apps or app updates +to the App Store. For more details about Apple's requirements, refer to +:apple:`Upcoming third-party SDK requirements ` +on the Apple Developer website. + +Some of the SDK libraries provide a privacy manifest to comply with Apple's +required API disclosures and the reasons for using those APIs. You can view +the privacy manifests in each package, or in the relevant GitHub repository: + +- Dart + + - ``realm-dart``/iOS: + `https://github.com/realm/realm-dart/blob/main/packages/realm/ios/Resources/PrivacyInfo.xcprivacy + `__ + - ``realm-dart``/macOS: + `https://github.com/realm/realm-dart/blob/main/packages/realm/macos/Resources/PrivacyInfo.xcprivacy + `__ + +- Swift: ``RealmSwift``: `https://github.com/realm/realm-swift/blob/master/RealmSwift/PrivacyInfo.xcprivacy `_ +- ObjectiveC: ``Realm``: `https://github.com/realm/realm-swift/blob/master/Realm/PrivacyInfo.xcprivacy `_ + +The SDK does not include analytics code in builds for the App Store. +The SDK does not log into Atlas on its own behalf. + +If you write an app that uses any App Services functionality, such as +:ref:`connecting to Atlas ` to: + +- :ref:`Call an Atlas Function ` +- :ref:`Authenticate and manage users ` +- :ref:`Access MongoDB Atlas ` +- :ref:`Open a synced database ` + +You may need to add additional disclosures to your app's privacy manifest +detailing your data collection and use practices when using these APIs. + +For more information, refer to Apple's +:apple:`Privacy manifest files documentation `. + +Special Build Instructions +-------------------------- + +To include these manifests in a build target that uses ``RealmSwift``, you must +build ``RealmSwift`` as a dynamic framework. For details, refer to the Swift +Package Manager Installation instructions step +**(Optional) Build RealmSwift as a Dynamic Framework**. diff --git a/source/platforms/apple/swift-concurrency.txt b/source/platforms/apple/swift-concurrency.txt index bb64760b16..f181ca42bb 100644 --- a/source/platforms/apple/swift-concurrency.txt +++ b/source/platforms/apple/swift-concurrency.txt @@ -139,7 +139,8 @@ Tasks and TaskGroups Swift concurrency provides APIs to manage :apple:`Tasks ` and :apple:`TaskGroups `. The `Swift concurrency -documentation `__ +documentation +`__ defines a task as a unit of work that can be run asynchronously as part of your program. Task allows you to specifically define a unit of asynchronous work. TaskGroup lets you define a collection of Tasks to execute as a unit @@ -230,6 +231,6 @@ To avoid threading-related issues in code that uses Swift concurrency features: .. _concurrency-page-sendable-thread-confined-reference: Sendable, Non-Sendable, and Thread-Confined Types ------------------------------------------------- +------------------------------------------------- .. include:: /includes/swift-api-sendable-thread-confined-reference.rst diff --git a/source/platforms/apple/tvos.txt b/source/platforms/apple/tvos.txt new file mode 100644 index 0000000000..849f626755 --- /dev/null +++ b/source/platforms/apple/tvos.txt @@ -0,0 +1,70 @@ +.. _sdks-tvos: + +============== +Build for tvOS +============== + +.. meta:: + :description: When you're using Atlas Device SDK to build for Apple's tvOS, keep these important considerations in mind. + :keywords: Realm, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: swift + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +When you're using Atlas Device SDK to build for Apple's tvOS, keep these +important considerations in mind. + +.. seealso:: + + :ref:`sdks-install` + +Avoid Storing Important User Data +--------------------------------- + +Avoid storing important user data in the database on tvOS. Instead, it's +best to treat the SDK as a rebuildable cache. + +.. note:: + + The reason for this has to do with where the SDK writes its + :ref:`database files `. On other Apple + platforms, the SDK writes its database files to the "Documents" + directory. Because tvOS restricts writes to that directory, the + default database file location on tvOS is instead ``NSCachesDirectory``. + tvOS can purge files in that directory at any time, so reliable + long-term persistence is not possible. For cloud-backed persistence + on tvOS, consider using :ref:`Device Sync `. + +You can also use the SDK as an initial data source by +:ref:`bundling prebuilt database files ` in your app. +Note that the :apple:`App Store guidelines ` limit your +app size to 4GB. + +.. tip:: + + Browse our :github:`tvOS examples + ` for sample tvOS apps + that demonstrate how to use the SDK as an offline cache. + +Share Database Files with TV Services Extensions +------------------------------------------------ + +To share a :ref:`database file ` between a +tvOS app and a TV services extension such as :apple:`Top Shelf +`, use the +``Library/Caches/`` directory in the shared container for the +application group: + +.. literalinclude:: /examples/generated/code/start/OpenCloseRealm.snippet.tvos-share-path.swift + :language: swift diff --git a/source/platforms/iot.txt b/source/platforms/iot.txt index 58cc1384fa..aee33e6e5f 100644 --- a/source/platforms/iot.txt +++ b/source/platforms/iot.txt @@ -14,3 +14,59 @@ Placeholder page for information about building for IoT. Include info about which frameworks we support building for IoT, plus any specific version or compatibility info worth calling out? + +Install the SDK for IoT +----------------------- + +.. TODO: Should also add details about C++ here + +JavaScript Library +~~~~~~~~~~~~~~~~~~ + +To create a Node.js project and add the Node.js SDK on an +Internet of Things (IoT) platform such as the Raspberry Pi 2, 3, or 4 +running Raspberry Pi OS (formerly Raspbian), follow the steps below: + +.. procedure:: + + .. step:: Install a C++ Compiler + + The Node.js SDK's IoT library is not distributed as a binary, so you + must build it from source. To do this, you'll need a working C++ compiler. + To install such a compiler on your IoT device, run the following command: + + .. code-block:: bash + + sudo apt install build-essential g++ libssl-dev + + .. step:: Create a Node.js Project + + Create your Node.js project by creating a new directory + for your project and running ``npm init`` in that + directory. In the example below, replace ``MyApp`` + with your desired project name. Answer all of the prompts + to fill out the details of your project. + + .. code-block:: bash + + mkdir MyApp && cd MyApp && npm init + + .. step:: Install the SDK with NPM + + In your Node.js project directory, use the following command + to add the SDK to your project: + + .. code-block:: bash + + npm install realm + + .. step:: Enable TypeScript (optional) + + TypeScript is a superset of JavaScript that adds static + type checking and other features intended to make + application-scale development more robust. If you'd like + to use TypeScript, follow the TypeScript team's official + `Node Starter guide + `__. + The SDK supports TypeScript natively and integrates easily + into a TypeScript project. diff --git a/source/platforms/unity.txt b/source/platforms/unity.txt index 8caa8f1e94..88283956a9 100644 --- a/source/platforms/unity.txt +++ b/source/platforms/unity.txt @@ -1,8 +1,8 @@ -.. _dotnet-unity: +.. _sdks-unity: -================================ -Quick Start for Unity - .NET SDK -================================ +========================= +Build for Unity with .NET +========================= .. meta:: :description: Get started using Atlas Device SDK for .NET with a Unity project. @@ -243,7 +243,7 @@ away. For examples of when you may perform BSON deserialization, check out the ` documentation. Using the SDK While the Application is Quitting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The .NET SDK cannot be accessed within the `AppDomain.DomainUnload Event `_ or diff --git a/source/sdk/install.txt b/source/sdk/install.txt index b575168178..91cb0aaae0 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -6,15 +6,333 @@ Install Atlas Device SDK .. meta:: :description: Install Atlas Device SDK for your preferred language or framework using popular package managers and build tools. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre :values: tutorial +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, javascript/typescript, kotlin, objective-c, swift + .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol -Placeholder page for Install content. +.. tabs-selector:: drivers + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-intro-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/install/install-intro-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/install/install-intro-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/install/install-intro-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/install/install-intro-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/swift/install/install-intro-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/install/install-intro-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/install/install-intro-js-ts-description.rst + +Requirements +------------ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-requirements-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/install/install-requirements-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/install/install-requirements-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/install/install-requirements-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/install/install-requirements-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/swift/install/install-requirements-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/install/install-requirements-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/install/install-requirements-js-ts-description.rst + +Install the SDK +--------------- + +.. tip:: Atlas Device SDK and Realm + + The SDK uses Realm Core database for data persistence on the device. When + you install the SDK, the package names reflect Realm naming. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tabs:: + + .. tab:: Swift Package Manager + :tabid: cpp-spm + + .. include:: /includes/api-details/cpp/install/install-install-sdk-procedure-swift-package-manager.rst + + .. tab:: CMake + :tabid: cpp-cmake + + .. include:: /includes/api-details/cpp/install/install-install-sdk-procedure-cmake.rst + + .. tab:: + :tabid: csharp + + .. important:: Install the SDK for all projects + + If you have a multi-platform solution, be sure to install the SDK for + **all of the platform projects**, even if the given project doesn't contain + any SDK-specific code. + + .. tabs:: + + .. tab:: Visual Studio for Mac + :tabid: vs-mac + + .. include:: /includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-mac.rst + + .. tab:: Visual Studio for Windows + :tabid: vs-windows + + .. include:: /includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-windows.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/install/install-install-sdk-procedure.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst + + .. tab:: + :tabid: kotlin + + .. tabs:: + + .. tab:: Android + :tabid: kotlin-android + + .. include:: /includes/api-details/kotlin/install/install-install-sdk-procedure-android.rst + + .. tab:: Kotlin Multiplatform (KMP) + :tabid: kotlin-multiplatform + + .. include:: /includes/api-details/kotlin/install/install-install-sdk-procedure-kotlin-multiplatform.rst + + .. tab:: + :tabid: objectivec + + .. tabs:: + + .. tab:: SwiftPM + :tabid: objc-swiftpm + + .. include:: /includes/api-details/objectivec/install/install-sdk-procedure-swift-package-manager.rst + + .. tab:: CocoaPods + :tabid: objc-cocoapods + + .. include:: /includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst + + .. tab:: Carthage + :tabid: objc-carthage + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-carthage.rst + + .. tab:: Dynamic Framework + :tabid: objct-dynamic-framework + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst + + .. tab:: + :tabid: swift + + .. tabs:: + + .. tab:: SwiftPM + :tabid: swift-swiftpm + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-swift-package-manager.rst + + .. tab:: CocoaPods + :tabid: swift-cocoapods + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst + + .. tab:: Carthage + :tabid: swift-carthage + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-carthage.rst + + .. tab:: Dynamic Framework + :tabid: swift-dynamic-framework + + .. include:: /includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst + +Import the SDK +-------------- + +.. tip:: Atlas Device SDK and Realm + + The SDK uses Realm Core database for data persistence on the device. When + you import the SDK, the package names reflect Realm naming. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-import-sdk-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/install/install-import-sdk-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/install/install-import-sdk-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/install/install-import-sdk-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/install/install-import-sdk-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/install/install-import-sdk-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst + +.. include:: /includes/sdk-examples/install/install-import-sdk.rst + +Platform-Specific Considerations +-------------------------------- + +For details about installing the SDK and building for a specific platform, +refer to the relevant platform pages: + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/install/install-platform-specific-considerations-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst