From 08eed1166f130c397126a1c6ac5d31119e489f92 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 10:23:44 -0400 Subject: [PATCH 01/22] Scaffold Install page structure --- .../install-import-sdk-description.rst | 2 + .../install-install-sdk-procedures.rst | 101 ++++++ .../cpp/install/install-intro-description.rst | 3 + ...rm-specific-considerations-description.rst | 1 + .../install-requirements-description.rst | 4 + .../android-build-android-app-description.rst | 32 ++ .../install/install-import-sdk.rst | 63 ++++ source/platforms/android.txt | 69 +++++ source/sdk/install.txt | 289 +++++++++++++++++- 9 files changed, 563 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/cpp/install/install-install-sdk-procedures.rst create mode 100644 source/includes/api-details/cpp/install/install-intro-description.rst create mode 100644 source/includes/api-details/cpp/install/install-platform-specific-considerations-description.rst create mode 100644 source/includes/api-details/cpp/install/install-requirements-description.rst create mode 100644 source/includes/api-details/cpp/platforms/android-build-android-app-description.rst create mode 100644 source/includes/sdk-examples/install/install-import-sdk.rst 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-procedures.rst b/source/includes/api-details/cpp/install/install-install-sdk-procedures.rst new file mode 100644 index 0000000000..0c156b6fa6 --- /dev/null +++ b/source/includes/api-details/cpp/install/install-install-sdk-procedures.rst @@ -0,0 +1,101 @@ +.. tabs:: + + .. tab:: SwiftPM + :tabid: swiftpm + + 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:: sh + + 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`. + + .. tab:: CMake + :tabid: cmake + + You can use CMake with the FetchContent module to manage the SDK and its + dependencies in your C++ project. + + 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 flags listed below. + + .. 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) + + 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:: bash + + # 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. \ No newline at end of file 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/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst new file mode 100644 index 0000000000..e8ce775648 --- /dev/null +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/quick-start.snippet.include-header.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript 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/sdk/install.txt b/source/sdk/install.txt index b575168178..bedf3a9dbc 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -6,15 +6,302 @@ 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, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre :values: tutorial +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, 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/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-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/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + +Install the SDK +--------------- + +.. tip:: Atlas Device SDK and Realm + + The SDK uses Realm Core database for device data persistence. When you + install the SDK, the package names reflect Realm naming. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-sdk-procedures.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + +Import the SDK +-------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/install/install-import-sdk-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + +.. include:: /includes/sdk-examples/install/install-import.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/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst From 8a50da1d1d91376dcb32fd48ccda42cb0d37124e Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 10:40:15 -0400 Subject: [PATCH 02/22] Experiment with different include structure --- .../install-install-sdk-procedure-cmake.rst | 83 ++++++++++++++ ...ll-sdk-procedure-swift-package-manager.rst | 23 ++++ .../install-install-sdk-procedures.rst | 101 ------------------ source/sdk/install.txt | 14 ++- 4 files changed, 118 insertions(+), 103 deletions(-) create mode 100644 source/includes/api-details/cpp/install/install-install-sdk-procedure-cmake.rst create mode 100644 source/includes/api-details/cpp/install/install-install-sdk-procedure-swift-package-manager.rst delete mode 100644 source/includes/api-details/cpp/install/install-install-sdk-procedures.rst 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..b2b3140e8c --- /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:: bash + + # 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..3587877c00 --- /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:: sh + + 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-install-sdk-procedures.rst b/source/includes/api-details/cpp/install/install-install-sdk-procedures.rst deleted file mode 100644 index 0c156b6fa6..0000000000 --- a/source/includes/api-details/cpp/install/install-install-sdk-procedures.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. tabs:: - - .. tab:: SwiftPM - :tabid: swiftpm - - 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:: sh - - 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`. - - .. tab:: CMake - :tabid: cmake - - You can use CMake with the FetchContent module to manage the SDK and its - dependencies in your C++ project. - - 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 flags listed below. - - .. 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) - - 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:: bash - - # 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. \ No newline at end of file diff --git a/source/sdk/install.txt b/source/sdk/install.txt index bedf3a9dbc..f7aecf0e4e 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -144,7 +144,17 @@ Install the SDK .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/install/install-sdk-procedures.rst + .. 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 @@ -246,7 +256,7 @@ Import the SDK .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst -.. include:: /includes/sdk-examples/install/install-import.rst +.. include:: /includes/sdk-examples/install/install-import-sdk.rst Platform-Specific Considerations -------------------------------- From 3dcb4303d772a1b56d0996fced89377f393b04f9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 10:44:39 -0400 Subject: [PATCH 03/22] Tweak code blocks --- .../cpp/install/install-install-sdk-procedure-cmake.rst | 2 +- .../install-install-sdk-procedure-swift-package-manager.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index b2b3140e8c..440a27d7ae 100644 --- 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 @@ -70,7 +70,7 @@ dependencies in your C++ project. 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:: bash + .. code-block:: # build/ is in .gitignore mkdir build 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 index 3587877c00..77c730b95a 100644 --- 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 @@ -11,7 +11,7 @@ install the SDK's ``realm-cpp`` library. Copy and paste the following into the search/input box. - .. code-block:: sh + .. code-block:: https://github.com/realm/realm-cpp From 76150c56d61125da9bffcffda741fa2a02631310 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 11:04:19 -0400 Subject: [PATCH 04/22] Add C# install details --- .../install-import-sdk-description.rst | 1 + ...ll-sdk-procedure-visual-studio-for-mac.rst | 23 +++++++++++++++ ...dk-procedure-visual-studio-for-windows.rst | 27 ++++++++++++++++++ .../install/install-intro-description.rst | 7 +++++ ...rm-specific-considerations-description.rst | 1 + .../install-requirements-description.rst | 4 +++ .../install/install-import-sdk.rst | 5 ++-- source/platforms.txt | 2 +- source/platforms/unity.txt | 10 +++---- source/sdk/install.txt | 28 +++++++++++++++---- 10 files changed, 94 insertions(+), 14 deletions(-) create mode 100644 source/includes/api-details/csharp/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-mac.rst create mode 100644 source/includes/api-details/csharp/install/install-install-sdk-procedure-visual-studio-for-windows.rst create mode 100644 source/includes/api-details/csharp/install/install-intro-description.rst create mode 100644 source/includes/api-details/csharp/install/install-platform-specific-considerations-description.rst create mode 100644 source/includes/api-details/csharp/install/install-requirements-description.rst 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..b0580090a2 --- /dev/null +++ b/source/includes/api-details/csharp/install/install-platform-specific-considerations-description.rst @@ -0,0 +1 @@ +- :ref:`sdks-unity` 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/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index e8ce775648..d14eb73290 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -10,8 +10,9 @@ - id: csharp content: | - .. literalinclude:: /examples/MissingPlaceholders/example.cs - :language: csharp + .. code-block:: csharp + + using Realms; - id: dart content: | 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/unity.txt b/source/platforms/unity.txt index 8caa8f1e94..7ec9cadeae 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 -================================ +==================================== +Atlas Device SDK 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 f7aecf0e4e..2f7e935e13 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -34,7 +34,7 @@ Install Atlas Device SDK .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/csharp/install/install-intro-description.rst .. tab:: :tabid: dart @@ -89,7 +89,7 @@ Requirements .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/csharp/install/install-requirements-description.rst .. tab:: :tabid: dart @@ -159,8 +159,24 @@ Install the SDK .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - + .. 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 @@ -214,7 +230,7 @@ Import the SDK .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/csharp/install/install-import-sdk-description.rst .. tab:: :tabid: dart @@ -274,7 +290,7 @@ refer to the relevant platform pages: .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/csharp/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: dart From 03a089246183dd638d30f0ebb74d1a289b44a22d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 13:17:33 -0400 Subject: [PATCH 05/22] Add Dart install details, kinda --- snooty.toml | 2 + source/frameworks/flutter/install.txt | 108 ++++++++++++++++++ ...rm-specific-considerations-description.rst | 14 +++ .../install-import-sdk-description.rst | 1 + .../install/install-install-sdk-procedure.rst | 43 +++++++ .../install/install-intro-description.rst | 4 + ...rm-specific-considerations-description.rst | 11 ++ .../install-requirements-description.rst | 11 ++ ...nstall-supported-platforms-description.rst | 24 ++++ .../install/install-import-sdk.rst | 6 +- source/platforms/apple.txt | 39 +++++++ source/platforms/apple/privacy-manifest.txt | 71 ++++++++++++ source/platforms/unity.txt | 6 +- source/sdk/install.txt | 10 +- 14 files changed, 340 insertions(+), 10 deletions(-) create mode 100644 source/frameworks/flutter/install.txt create mode 100644 source/includes/api-details/dart/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/dart/install/install-install-sdk-procedure.rst create mode 100644 source/includes/api-details/dart/install/install-intro-description.rst create mode 100644 source/includes/api-details/dart/install/install-platform-specific-considerations-description.rst create mode 100644 source/includes/api-details/dart/install/install-requirements-description.rst create mode 100644 source/includes/api-details/dart/install/install-supported-platforms-description.rst create mode 100644 source/platforms/apple/privacy-manifest.txt diff --git a/snooty.toml b/snooty.toml index e44369c119..bb615b765d 100644 --- a/snooty.toml +++ b/snooty.toml @@ -86,6 +86,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/install.txt b/source/frameworks/flutter/install.txt new file mode 100644 index 0000000000..77436443a7 --- /dev/null +++ b/source/frameworks/flutter/install.txt @@ -0,0 +1,108 @@ +.. _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:`flutter-macos-development`. + +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/platform-specific-considerations-description.rst 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 index b0580090a2..ca63724227 100644 --- 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 @@ -1 +1,15 @@ - :ref:`sdks-unity` + +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/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..feea5b8fa2 --- /dev/null +++ b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst @@ -0,0 +1,43 @@ +.. procedure:: + + .. step:: Create a Project + + To create a Dart project, run the following commands: + + .. code-block:: bash + + 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:: bash + + 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:: yaml + :caption: pubspec.yaml + + dependencies: + realm_dart: + + After the package is added, run the following command to install it: + + .. code-block:: bash + + dart run realm_dart install + + This downloads and copies the required native binaries to the app + directory. 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..f62456f865 --- /dev/null +++ b/source/includes/api-details/dart/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,11 @@ +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..ac3ac243fe --- /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 the 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/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index d14eb73290..2af70bca20 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -17,8 +17,10 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart - :language: dart + .. code-block:: dart + :caption: ExampleFile.dart + + import 'package:realm_dart/realm.dart'; - id: java content: | diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index cb469465eb..368af4115d 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -13,6 +13,7 @@ Build for Apple .. toctree:: :titlesonly: + Apple Privacy Manifest Swift Concurrency Swift Actor Support @@ -23,3 +24,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/unity.txt b/source/platforms/unity.txt index 7ec9cadeae..88283956a9 100644 --- a/source/platforms/unity.txt +++ b/source/platforms/unity.txt @@ -1,8 +1,8 @@ .. _sdks-unity: -==================================== -Atlas Device SDK for Unity with .NET -==================================== +========================= +Build for Unity with .NET +========================= .. meta:: :description: Get started using Atlas Device SDK for .NET with a Unity project. diff --git a/source/sdk/install.txt b/source/sdk/install.txt index 2f7e935e13..a6f69e570e 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -39,7 +39,7 @@ Install Atlas Device SDK .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/dart/install/install-intro-description.rst .. tab:: :tabid: java @@ -94,7 +94,7 @@ Requirements .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/dart/install/install-requirements-description.rst .. tab:: :tabid: java @@ -180,7 +180,7 @@ Install the SDK .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/dart/install/install-install-sdk-procedure.rst .. tab:: :tabid: java @@ -235,7 +235,7 @@ Import the SDK .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/dart/install/import-sdk-description.rst .. tab:: :tabid: java @@ -295,7 +295,7 @@ refer to the relevant platform pages: .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: java From 812bc9bf82ea00e4bb787e4fc96f9c9351395c3a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 14:00:50 -0400 Subject: [PATCH 06/22] Fix build errors --- source/frameworks/flutter.txt | 1 + source/frameworks/flutter/install.txt | 5 +++-- source/sdk/install.txt | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) 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 index 77436443a7..17318d2964 100644 --- a/source/frameworks/flutter/install.txt +++ b/source/frameworks/flutter/install.txt @@ -90,7 +90,8 @@ Install the SDK macOS security settings. To learn how to change your app's macOS entitlements, refer to - :ref:`flutter-macos-development`. + :ref:`Device Sync and App Sandbox Entitlements + `. Import the SDK -------------- @@ -105,4 +106,4 @@ To use the SDK in your app, import the package into any files that use it: Platform-Specific Considerations -------------------------------- -.. include:: /includes/api-details/dart/install/platform-specific-considerations-description.rst +.. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst diff --git a/source/sdk/install.txt b/source/sdk/install.txt index a6f69e570e..90532e204a 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -235,7 +235,7 @@ Import the SDK .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/install/import-sdk-description.rst + .. include:: /includes/api-details/dart/install/install-import-sdk-description.rst .. tab:: :tabid: java From 308869ba7e4ef8cafc0b0eaa204b8a1568fec0a0 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 14:38:14 -0400 Subject: [PATCH 07/22] Add platform landing pages to snooty.toml --- snooty.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/snooty.toml b/snooty.toml index bb615b765d..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", From 20a900778aed31d849546fb6abbe7736ec841124 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 14:46:26 -0400 Subject: [PATCH 08/22] Omit Java SDK --- .../install/install-import-sdk.rst | 12 ----- source/sdk/install.txt | 54 +------------------ 2 files changed, 2 insertions(+), 64 deletions(-) diff --git a/source/includes/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index 2af70bca20..5aa144e920 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -22,18 +22,6 @@ import 'package:realm_dart/realm.dart'; - - id: java - content: | - - .. literalinclude:: /examples/MissingPlaceholders/api.java - :language: java - - - id: java-kotlin - content: | - - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt - :language: kotlin - - id: javascript content: | diff --git a/source/sdk/install.txt b/source/sdk/install.txt index 90532e204a..8cb0a8d755 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -6,7 +6,7 @@ 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, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre @@ -14,7 +14,7 @@ Install Atlas Device SDK .. facet:: :name: programming_language - :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift + :values: cpp, csharp, dart, javascript/typescript, kotlin, objective-c, swift .. contents:: On this page :local: @@ -41,16 +41,6 @@ Install Atlas Device SDK .. include:: /includes/api-details/dart/install/install-intro-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - .. tab:: :tabid: javascript @@ -96,16 +86,6 @@ Requirements .. include:: /includes/api-details/dart/install/install-requirements-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - .. tab:: :tabid: javascript @@ -182,16 +162,6 @@ Install the SDK .. include:: /includes/api-details/dart/install/install-install-sdk-procedure.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - .. tab:: :tabid: javascript @@ -237,16 +207,6 @@ Import the SDK .. include:: /includes/api-details/dart/install/install-import-sdk-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - .. tab:: :tabid: javascript @@ -297,16 +257,6 @@ refer to the relevant platform pages: .. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - .. tab:: :tabid: javascript From ed9fe044cec7e8a57e552bf303e5e93573407f43 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 16:24:43 -0400 Subject: [PATCH 09/22] Add Kotlin library details --- ...rm-specific-considerations-description.rst | 2 + .../install-import-sdk-description.rst | 13 ++++ .../install-install-sdk-procedure-android.rst | 54 ++++++++++++++++ ...all-sdk-procedure-kotlin-multiplatform.rst | 64 +++++++++++++++++++ .../install/install-intro-description.rst | 5 ++ ...rm-specific-considerations-description.rst | 16 +++++ .../install-requirements-description.rst | 34 ++++++++++ ...ported-target-environments-description.rst | 57 +++++++++++++++++ .../install/install-import-sdk.rst | 3 +- source/sdk/install.txt | 20 ++++-- 10 files changed, 261 insertions(+), 7 deletions(-) create mode 100644 source/includes/api-details/kotlin/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/kotlin/install/install-install-sdk-procedure-android.rst create mode 100644 source/includes/api-details/kotlin/install/install-install-sdk-procedure-kotlin-multiplatform.rst create mode 100644 source/includes/api-details/kotlin/install/install-intro-description.rst create mode 100644 source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst create mode 100644 source/includes/api-details/kotlin/install/install-requirements-description.rst create mode 100644 source/includes/api-details/kotlin/install/install-supported-target-environments-description.rst 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 index f62456f865..cea2264a65 100644 --- 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 @@ -1,3 +1,5 @@ +- :ref:`macOS: Device Sync and App Sandbox Entitlements ` + 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, 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..84d4ddf45d --- /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:: kotlin + :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:: kotlin + :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..6573e5724a --- /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:: kotlin + :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:: kotlin + :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..af0ec5db6f --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst @@ -0,0 +1,16 @@ +- :ref:`sdks-build-for-android` +- :ref:`sdks-build-for-apple` + +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..ec97e034ea --- /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 +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..6e9d0549a4 --- /dev/null +++ b/source/includes/api-details/kotlin/install/install-supported-target-environments-description.rst @@ -0,0 +1,57 @@ +Supported Target Environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kotlin Multiplatform (KMP) supports a wide range of application environments +Refer also to Kotlin's `Multiplatform Gradle DSL reference: Targets +`__ documentation. + +Supported Environments +`````````````````````` + +The Kotlin library supports the following environments: + +- :file:`android` + +- :file:`iosArm64` +- :file:`iosSimulatorArm64` +- :file:`iosX64` + +- :file:`jvm` + +- :file:`macosArm64` +- :file:`macosX64` + +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` diff --git a/source/includes/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index 5aa144e920..d7a2271868 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -31,9 +31,8 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/sdk/install.txt b/source/sdk/install.txt index 8cb0a8d755..c242497117 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -49,7 +49,7 @@ Install Atlas Device SDK .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/kotlin/install/install-intro-description.rst .. tab:: :tabid: objectivec @@ -94,7 +94,7 @@ Requirements .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/kotlin/install/install-requirements-description.rst .. tab:: :tabid: objectivec @@ -170,7 +170,17 @@ Install the SDK .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + .. 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 @@ -215,7 +225,7 @@ Import the SDK .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/kotlin/install/install-import-sdk-description.rst .. tab:: :tabid: objectivec @@ -265,7 +275,7 @@ refer to the relevant platform pages: .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: objectivec From e9e6a6254cc63582a4340f804436bc262e7ff1c9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 17:14:22 -0400 Subject: [PATCH 10/22] Refactor supported environments into mutually-exclusive tabs --- ...ported-target-environments-description.rst | 80 +++++++++++-------- 1 file changed, 45 insertions(+), 35 deletions(-) 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 index 6e9d0549a4..4eecaeb249 100644 --- 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 @@ -5,53 +5,63 @@ Kotlin Multiplatform (KMP) supports a wide range of application environments Refer also to Kotlin's `Multiplatform Gradle DSL reference: Targets `__ documentation. -Supported Environments -`````````````````````` +.. tabs:: -The Kotlin library supports the following environments: + .. tab:: Supported Environments + :tabid: kmp-supported-environments -- :file:`android` + The Kotlin library supports the following environments: -- :file:`iosArm64` -- :file:`iosSimulatorArm64` -- :file:`iosX64` + - :file:`android` -- :file:`jvm` + - :file:`iosArm64` + - :file:`iosSimulatorArm64` + - :file:`iosX64` -- :file:`macosArm64` -- :file:`macosX64` + - :file:`jvm` -Unsupported Environments -```````````````````````` + - :file:`macosArm64` + - :file:`macosX64` -The Kotlin library does *not* support the following environments: + .. tab:: Unsupported Environments + :tabid: kmp-unsupported-environments -- :file:`androidNativeArm32` -- :file:`androidNativeArm64` -- :file:`androidNativeX86` -- :file:`androidNativeX64` + The Kotlin library does *not* support the following environments: -- :file:`iosArm32` + - :file:`androidNativeArm32` + - :file:`androidNativeArm64` + - :file:`androidNativeX86` + - :file:`androidNativeX64` -- :file:`js` + - :file:`iosArm32` + + - :file:`js` -- :file:`linuxArm32Hfp` -- :file:`linuxArm64` -- :file:`linuxMips32` -- :file:`linuxMipsel32` -- :file:`linuxX64` + - :file:`linuxArm32Hfp` + - :file:`linuxArm64` + - :file:`linuxMips32` + - :file:`linuxMipsel32` + - :file:`linuxX64` -- :file:`mingwX64` -- :file:`mingwX86` + - :file:`mingwX64` + - :file:`mingwX86` -- :file:`tvosArm64` -- :file:`tvosSimulatorArm64` -- :file:`tvosX64` + - :file:`tvosArm64` + - :file:`tvosSimulatorArm64` + - :file:`tvosX64` -- :file:`wasm32` + - :file:`wasm32` -- :file:`watchosArm32` -- :file:`watchosArm64` -- :file:`watchosSimulatorArm64` -- :file:`watchosX86` -- :file:`watchosX64` + - :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` From 7383184ade0c79f0f7053b89e21904b93c7b97ed Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 17:54:53 -0400 Subject: [PATCH 11/22] Add JS SDK details --- .../install-import-sdk-js-ts-description.rst | 2 + .../install-intro-js-ts-description.rst | 8 +++ .../install-requirements-js-ts-dscription.rst | 5 ++ .../install/install-sdk-procedure-js-ts.rst | 33 +++++++++++ ...-supported-platforms-js-ts-description.rst | 16 ++++++ .../install/install-import-sdk.rst | 10 ++-- source/platforms/iot.txt | 56 +++++++++++++++++++ source/sdk/install.txt | 16 +++--- 8 files changed, 134 insertions(+), 12 deletions(-) create mode 100644 source/includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/install/install-intro-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.rst create mode 100644 source/includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst create mode 100644 source/includes/api-details/javascript/install/install-supported-platforms-js-ts-description.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..2be0b84702 --- /dev/null +++ b/source/includes/api-details/javascript/install/install-intro-js-ts-description.rst @@ -0,0 +1,8 @@ +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. + +.. include:: /includes/api-details/javascript/install/install-supported-platforms-description.rst diff --git a/source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.rst b/source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.rst new file mode 100644 index 0000000000..d9fd9166da --- /dev/null +++ b/source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.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..420f15f251 --- /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:: 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/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..634d3ccd5c --- /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, use + the :ref:`sdks-build-with-react-native`. diff --git a/source/includes/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index d7a2271868..8d7e946210 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -25,8 +25,9 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js - :language: javascript + .. code-block:: javascript + + import Realm from "realm"; - id: kotlin content: | @@ -49,5 +50,6 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts - :language: typescript + .. code-block:: typescript + + import Realm from "realm"; 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/sdk/install.txt b/source/sdk/install.txt index c242497117..f2ddf19d88 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -44,7 +44,7 @@ Install Atlas Device SDK .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-intro-js-ts-description.rst .. tab:: :tabid: kotlin @@ -64,7 +64,7 @@ Install Atlas Device SDK .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-intro-js-ts-description.rst Requirements ------------ @@ -89,7 +89,7 @@ Requirements .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-requirements-js-ts-description.rst .. tab:: :tabid: kotlin @@ -109,7 +109,7 @@ Requirements .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-requirements-js-ts-description.rst Install the SDK --------------- @@ -165,7 +165,7 @@ Install the SDK .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst .. tab:: :tabid: kotlin @@ -195,7 +195,7 @@ Install the SDK .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-sdk-procedure-js-ts.rst Import the SDK -------------- @@ -270,7 +270,7 @@ refer to the relevant platform pages: .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst .. tab:: :tabid: kotlin @@ -290,4 +290,4 @@ refer to the relevant platform pages: .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-supported-platforms-js-ts-description.rst From 419a785aea6e28dff0b17f1ea5fcac03f0995c38 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 17:59:23 -0400 Subject: [PATCH 12/22] Fix build error --- ...-dscription.rst => install-requirements-js-ts-description.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/api-details/javascript/install/{install-requirements-js-ts-dscription.rst => install-requirements-js-ts-description.rst} (100%) diff --git a/source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.rst b/source/includes/api-details/javascript/install/install-requirements-js-ts-description.rst similarity index 100% rename from source/includes/api-details/javascript/install/install-requirements-js-ts-dscription.rst rename to source/includes/api-details/javascript/install/install-requirements-js-ts-description.rst From a88563133309658fd153fa9457447f8ae84d8f7b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 18 Jul 2024 18:06:14 -0400 Subject: [PATCH 13/22] Fix build error --- .../javascript/install/install-intro-js-ts-description.rst | 2 -- 1 file changed, 2 deletions(-) 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 index 2be0b84702..77c1eed79e 100644 --- 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 @@ -4,5 +4,3 @@ 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. - -.. include:: /includes/api-details/javascript/install/install-supported-platforms-description.rst From 7ecfe22336c7f29cf348e1dc8d1e452f312fe872 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 10:31:17 -0400 Subject: [PATCH 14/22] Add Swift and Objective-C install details --- .../install-import-sdk-description.rst | 1 + .../install-sdk-procedure-cocoapods.rst | 62 ++++++++++++++++ ...ll-sdk-procedure-swift-package-manager.rst | 48 +++++++++++++ .../install-import-sdk-description.rst | 9 +++ .../install/install-intro-description.rst | 4 ++ ...rm-specific-considerations-description.rst | 41 +++++++++++ .../install-requirements-description.rst | 21 ++++++ .../install-resolve-build-issues-carthage.rst | 47 +++++++++++++ ...install-resolve-build-issues-cocoapods.rst | 44 ++++++++++++ .../install-sdk-procedure-carthage.rst | 47 +++++++++++++ .../install-sdk-procedure-cocoapods.rst | 58 +++++++++++++++ ...nstall-sdk-procedure-dynamic-framework.rst | 22 ++++++ ...ll-sdk-procedure-swift-package-manager.rst | 48 +++++++++++++ ...all-supported-os-and-xcode-description.rst | 42 +++++++++++ .../install/install-import-sdk.rst | 4 +- source/platforms/apple.txt | 1 + source/platforms/apple/swift-concurrency.txt | 5 +- source/platforms/apple/tvos.txt | 70 +++++++++++++++++++ source/sdk/install.txt | 69 ++++++++++++++---- 19 files changed, 627 insertions(+), 16 deletions(-) create mode 100644 source/includes/api-details/objectivec/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst create mode 100644 source/includes/api-details/objectivec/install/install-sdk-procedure-swift-package-manager.rst create mode 100644 source/includes/api-details/swift/install/install-import-sdk-description.rst create mode 100644 source/includes/api-details/swift/install/install-intro-description.rst create mode 100644 source/includes/api-details/swift/install/install-platform-specific-considerations-description.rst create mode 100644 source/includes/api-details/swift/install/install-requirements-description.rst create mode 100644 source/includes/api-details/swift/install/install-resolve-build-issues-carthage.rst create mode 100644 source/includes/api-details/swift/install/install-resolve-build-issues-cocoapods.rst create mode 100644 source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst create mode 100644 source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst create mode 100644 source/includes/api-details/swift/install/install-sdk-procedure-dynamic-framework.rst create mode 100644 source/includes/api-details/swift/install/install-sdk-procedure-swift-package-manager.rst create mode 100644 source/includes/api-details/swift/install/install-supported-os-and-xcode-description.rst create mode 100644 source/platforms/apple/tvos.txt 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-sdk-procedure-cocoapods.rst b/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst new file mode 100644 index 0000000000..e9614bd067 --- /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 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..f9fcddbc01 --- /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:: sh + + 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..234cfa73f0 --- /dev/null +++ b/source/includes/api-details/swift/install/install-requirements-description.rst @@ -0,0 +1,21 @@ +Before getting started, ensure your development environment +meets the following prerequisites: + +- Your project uses an Xcode version and minimum OS version listed in the + :ref:`swift-os-support` section of this page. +- 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..dcdfdd8214 --- /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:: bash + + 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..18cddd5140 --- /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:: bash + + 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..2ab6a4d226 --- /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:: bash + + 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..3e17534369 --- /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 Realm 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..4c2ad3d37e --- /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:: sh + + 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..27dd4dc74a --- /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:`ios-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 + - 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/sdk-examples/install/install-import-sdk.rst b/source/includes/sdk-examples/install/install-import-sdk.rst index 8d7e946210..f9b0856eae 100644 --- a/source/includes/sdk-examples/install/install-import-sdk.rst +++ b/source/includes/sdk-examples/install/install-import-sdk.rst @@ -38,13 +38,13 @@ - id: objectivec content: | - .. literalinclude:: /examples/MissingPlaceholders/example.m + .. literalinclude:: /examples/generated/code/start/MyRealmApp.snippet.import-realm.m :language: objectivec - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/RealmApp.snippet.import-realm.swift :language: swift - id: typescript diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index 368af4115d..8f4a21e7b3 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -16,6 +16,7 @@ Build for Apple Apple Privacy Manifest Swift Concurrency Swift Actor Support + Build for tvOS Placeholder page for information about building for Apple. 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/sdk/install.txt b/source/sdk/install.txt index f2ddf19d88..2310d62c6e 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -54,12 +54,12 @@ Install Atlas Device SDK .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-intro-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-intro-description.rst .. tab:: :tabid: typescript @@ -99,12 +99,12 @@ Requirements .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-requirements-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-requirements-description.rst .. tab:: :tabid: typescript @@ -185,12 +185,52 @@ Install the SDK .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. 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 - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. 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 @@ -200,6 +240,11 @@ Install the SDK Import the SDK -------------- +.. tip:: Atlas Device SDK and Realm + + The SDK uses Realm Core database for device data persistence. When you + import the SDK, the package names reflect Realm naming. + .. tabs-drivers:: .. tab:: @@ -220,7 +265,7 @@ Import the SDK .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-import-js-ts-description.rst .. tab:: :tabid: kotlin @@ -230,17 +275,17 @@ Import the SDK .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/objectivec/install/install-import-sdk-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-import-sdk-description.rst .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/javascript/install/install-import-js-ts-description.rst .. include:: /includes/sdk-examples/install/install-import-sdk.rst @@ -280,12 +325,12 @@ refer to the relevant platform pages: .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + .. include:: /includes/api-details/swift/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: typescript From 51217839411dbb7d3b09c8b1c406822b01bc531c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:00:08 -0400 Subject: [PATCH 15/22] Fix build errors --- .../swift/install/install-requirements-description.rst | 5 +++-- .../install/install-supported-os-and-xcode-description.rst | 2 +- source/sdk/install.txt | 4 ++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/includes/api-details/swift/install/install-requirements-description.rst b/source/includes/api-details/swift/install/install-requirements-description.rst index 234cfa73f0..fa2e7c4c7f 100644 --- a/source/includes/api-details/swift/install/install-requirements-description.rst +++ b/source/includes/api-details/swift/install/install-requirements-description.rst @@ -1,8 +1,9 @@ Before getting started, ensure your development environment meets the following prerequisites: -- Your project uses an Xcode version and minimum OS version listed in the - :ref:`swift-os-support` section of this page. +- 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 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 index 27dd4dc74a..28f9f09d32 100644 --- 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 @@ -4,7 +4,7 @@ Supported Target Environments .. important:: There are special considerations when using the SDK with - tvOS. See :ref:`ios-tvos` for more information. + tvOS. See :ref:`sdks-tvos` for more information. Xcode 15 ```````` diff --git a/source/sdk/install.txt b/source/sdk/install.txt index 2310d62c6e..3e8aa01628 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -265,7 +265,7 @@ Import the SDK .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/install/install-import-js-ts-description.rst + .. include:: /includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst .. tab:: :tabid: kotlin @@ -285,7 +285,7 @@ Import the SDK .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/install/install-import-js-ts-description.rst + .. include:: /includes/api-details/javascript/install/install-import-sdk-js-ts-description.rst .. include:: /includes/sdk-examples/install/install-import-sdk.rst From 766ed5b915543093c9d99a51196895d422d612a9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:06:11 -0400 Subject: [PATCH 16/22] Fix build errors --- .../install/install-sdk-procedure-swift-package-manager.rst | 2 +- .../swift/install/install-resolve-build-issues-carthage.rst | 2 +- .../swift/install/install-resolve-build-issues-cocoapods.rst | 2 +- .../swift/install/install-sdk-procedure-carthage.rst | 2 +- .../install/install-sdk-procedure-swift-package-manager.rst | 2 +- source/platforms/apple.txt | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) 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 index f9fcddbc01..ca0a784b7a 100644 --- 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 @@ -8,7 +8,7 @@ Copy and paste the following into the search/input box. - .. code-block:: sh + .. code-block:: https://github.com/realm/realm-swift.git 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 index dcdfdd8214..958ec15081 100644 --- 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 @@ -25,7 +25,7 @@ and clean the Xcode build folder. Run these commands in the terminal, in the root of your project: - .. code-block:: bash + .. code-block:: rm -rf Carthage # Assumes default DerivedData location: 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 index 18cddd5140..ebd4753665 100644 --- 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 @@ -25,7 +25,7 @@ and clean the Xcode build folder. Run these commands in the terminal, in the root of your project: - .. code-block:: bash + .. code-block:: pod cache clean Realm pod cache clean RealmSwift 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 index 2ab6a4d226..5f36d494a8 100644 --- a/source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst +++ b/source/includes/api-details/swift/install/install-sdk-procedure-carthage.rst @@ -12,7 +12,7 @@ Carthage 0.33 or later. You can create a Cartfile or append to an existing one by running the following command in your project directory: - .. code-block:: bash + .. code-block:: echo 'github "realm/realm-swift"' >> Cartfile 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 index 4c2ad3d37e..bb84f0686d 100644 --- 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 @@ -8,7 +8,7 @@ Copy and paste the following into the search/input box. - .. code-block:: sh + .. code-block:: https://github.com/realm/realm-swift.git diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index 8f4a21e7b3..338cd797a1 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -16,7 +16,7 @@ Build for Apple Apple Privacy Manifest Swift Concurrency Swift Actor Support - Build for tvOS + Build for tvOS Placeholder page for information about building for Apple. From 130f00aae24d80c1c9b30fb235c58790ec7103b2 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:10:04 -0400 Subject: [PATCH 17/22] Objective-C doesn't have actor support --- ...rm-specific-considerations-description.rst | 20 +++++++++++++++++++ source/sdk/install.txt | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst 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..0ec593b52f --- /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 ``Realm``, 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/sdk/install.txt b/source/sdk/install.txt index 3e8aa01628..ca34cfb046 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -325,7 +325,7 @@ refer to the relevant platform pages: .. tab:: :tabid: objectivec - .. include:: /includes/api-details/swift/install/install-platform-specific-considerations-description.rst + .. include:: /includes/api-details/objectivec/install/install-platform-specific-considerations-description.rst .. tab:: :tabid: swift From 3bfe0fabd9fef8ba7ce0284d974c145122a62f7c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:23:24 -0400 Subject: [PATCH 18/22] Add details about upgrading Flutter package version --- source/frameworks/flutter/install.txt | 45 +++++++++++++++++++ .../install/install-install-sdk-procedure.rst | 2 + ...all-update-package-version-description.rst | 44 ++++++++++++++++++ .../includes/flutter-v2-breaking-change.rst | 13 +++--- 4 files changed, 98 insertions(+), 6 deletions(-) create mode 100644 source/includes/api-details/dart/install/install-update-package-version-description.rst diff --git a/source/frameworks/flutter/install.txt b/source/frameworks/flutter/install.txt index 17318d2964..e01371658d 100644 --- a/source/frameworks/flutter/install.txt +++ b/source/frameworks/flutter/install.txt @@ -93,6 +93,51 @@ Install the SDK :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 -------------- 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 index feea5b8fa2..ea802a32cd 100644 --- a/source/includes/api-details/dart/install/install-install-sdk-procedure.rst +++ b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst @@ -41,3 +41,5 @@ 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-update-package-version-description.rst b/source/includes/api-details/dart/install/install-update-package-version-description.rst new file mode 100644 index 0000000000..0846456f17 --- /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:: yaml + :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:: bash + + dart run realm_dart generate + + .. include:: /includes/flutter-v2-breaking-change.rst 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`. From 8c2898490f8a1b671cfee2403f4d02097aa8f72c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:28:23 -0400 Subject: [PATCH 19/22] Add the Flutter upgrade page as a 'hidden page' --- source/hidden-pages/upgrade-to-v2.txt | 206 ++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 source/hidden-pages/upgrade-to-v2.txt diff --git a/source/hidden-pages/upgrade-to-v2.txt b/source/hidden-pages/upgrade-to-v2.txt new file mode 100644 index 0000000000..fc3d08408d --- /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:`flutter-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:`flutter-monitor-sync-progress`. + + * - ``User.provider`` + - Provider is associated with each identity, so value was incorrect + for users with more than one identity. + - Remove any instances. From 1abb8602a52a67f254a4e7d1a8c4d726e533016d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:38:17 -0400 Subject: [PATCH 20/22] Remove languages from code blocks on Install page, fix build errors --- source/hidden-pages/upgrade-to-v2.txt | 8 ++++---- .../dart/install/install-install-sdk-procedure.rst | 6 +++--- .../install-update-package-version-description.rst | 2 +- .../javascript/install/install-sdk-procedure-js-ts.rst | 4 ++-- .../install/install-install-sdk-procedure-android.rst | 4 ++-- ...install-install-sdk-procedure-kotlin-multiplatform.rst | 4 ++-- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/source/hidden-pages/upgrade-to-v2.txt b/source/hidden-pages/upgrade-to-v2.txt index fc3d08408d..f7a339147b 100644 --- a/source/hidden-pages/upgrade-to-v2.txt +++ b/source/hidden-pages/upgrade-to-v2.txt @@ -153,7 +153,7 @@ when upgrading an app that used the removed class or member, if any: * - ``Realm.logger.level`` - Replaced by ``Realm.logger.setLogLevel``. - - Replace any instances. See also :ref:`flutter-logging`. + - Replace any instances. See also :ref:`sdks-logging`. * - ``RealmProperty.indexed`` - Replaced by ``RealmProperty.indexType``. @@ -161,11 +161,11 @@ when upgrading an app that used the removed class or member, if any: * - ``RealmValue.type`` - Changed to an enum of ``RealmValueType``. - - Replace any instances. See also :ref:`RealmValue Data Type `. + - Replace any instances. See also :ref:`RealmValue Data Type `. * - ``RealmValue.uint8List`` - Renamed to ``RealmValue.binary``. - - Replace any instances. See also :ref:`RealmValue Data Type `. + - Replace any instances. See also :ref:`RealmValue Data Type `. * - ``SchemaObject.properties`` - ``SchemaObject`` changed to an iterable collection of ``SchemaProperty``. @@ -198,7 +198,7 @@ when upgrading an app that used the removed class or member, if any: * - ``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:`flutter-monitor-sync-progress`. + - Use ``SyncProgress.progressEstimate``. See also :ref:`sdks-check-upload-and-download-progress`. * - ``User.provider`` - Provider is associated with each identity, so value was incorrect 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 index ea802a32cd..b81d2b1901 100644 --- a/source/includes/api-details/dart/install/install-install-sdk-procedure.rst +++ b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst @@ -4,7 +4,7 @@ To create a Dart project, run the following commands: - .. code-block:: bash + .. code-block:: dart create cd @@ -17,7 +17,7 @@ To add the SDK to your project, run the following command: - .. code-block:: bash + .. code-block:: dart pub add realm_dart @@ -35,7 +35,7 @@ After the package is added, run the following command to install it: - .. code-block:: bash + .. code-block:: dart run realm_dart install 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 index 0846456f17..f48f0f998e 100644 --- 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 @@ -37,7 +37,7 @@ To change the version of the SDK in your project, perform the following steps: models. From the command line, run the following command to regenerate object models with new and updated functionality: - .. code-block:: bash + .. code-block:: dart run realm_dart generate 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 index 420f15f251..a624e081f2 100644 --- 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 @@ -8,7 +8,7 @@ with your desired project name. Answer all of the prompts to fill out the details of your project. - .. code-block:: bash + .. code-block:: mkdir MyApp && cd MyApp && npm init @@ -17,7 +17,7 @@ In your Node.js project directory, use the following command to add the SDK to your project: - .. code-block:: bash + .. code-block:: npm install realm 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 index 84d4ddf45d..fff2b48a61 100644 --- 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 @@ -6,7 +6,7 @@ :file:`apply false`, to the list of plugins in your project-level Gradle build file, typically found at :file:`/build.gradle`: - .. code-block:: kotlin + .. code-block:: :caption: Global build.gradle plugins { @@ -24,7 +24,7 @@ - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies. - .. code-block:: kotlin + .. code-block:: :caption: Module build.gradle :emphasize-lines: 4, 12-16 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 index 6573e5724a..b1da4a7e7c 100644 --- 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 @@ -12,7 +12,7 @@ - To use coroutines with the SDK, add :file:`org.jetbrains.kotlinx:kotlinx-coroutines-core` to the list of dependencies. - .. code-block:: kotlin + .. code-block:: :caption: App build.gradle :emphasize-lines: 5, 18-22 @@ -45,7 +45,7 @@ 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:: kotlin + .. code-block:: :caption: Android Module build.gradle dependencies { From 138c738a0e8b675044fd0ea7afd2668a26639b16 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 19 Jul 2024 11:43:44 -0400 Subject: [PATCH 21/22] Apparently it can't be yaml either --- .../api-details/dart/install/install-install-sdk-procedure.rst | 2 +- .../dart/install/install-update-package-version-description.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index b81d2b1901..ad8029ec28 100644 --- a/source/includes/api-details/dart/install/install-install-sdk-procedure.rst +++ b/source/includes/api-details/dart/install/install-install-sdk-procedure.rst @@ -27,7 +27,7 @@ In your ``pubspec.yaml`` file, you should see: - .. code-block:: yaml + .. code-block:: :caption: pubspec.yaml dependencies: 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 index f48f0f998e..c5a14b1c95 100644 --- 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 @@ -9,7 +9,7 @@ To change the version of the SDK in your project, perform the following steps: Update the package version in your :file:`pubspec.yaml` file dependencies. - .. code-block:: yaml + .. code-block:: :caption: pubspec.yaml dependencies: From 889f3157da42fed74fcb9cf8d5cdf39c40716318 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 31 Jul 2024 09:08:24 -0400 Subject: [PATCH 22/22] Apply review feedback --- ...stall-platform-specific-considerations-description.rst | 3 +++ ...stall-platform-specific-considerations-description.rst | 3 +++ .../dart/install/install-requirements-description.rst | 4 ++-- .../install-supported-platforms-js-ts-description.rst | 4 ++-- ...stall-platform-specific-considerations-description.rst | 3 +++ .../kotlin/install/install-requirements-description.rst | 2 +- ...stall-platform-specific-considerations-description.rst | 6 +++--- .../install/install-sdk-procedure-cocoapods.rst | 2 +- .../swift/install/install-sdk-procedure-cocoapods.rst | 2 +- .../install-supported-os-and-xcode-description.rst | 2 +- source/sdk/install.txt | 8 ++++---- 11 files changed, 24 insertions(+), 15 deletions(-) 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 index ca63724227..90ecae307a 100644 --- 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 @@ -1,5 +1,8 @@ - :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, 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 index cea2264a65..54785221d1 100644 --- 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 @@ -1,5 +1,8 @@ - :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, diff --git a/source/includes/api-details/dart/install/install-requirements-description.rst b/source/includes/api-details/dart/install/install-requirements-description.rst index ac3ac243fe..bee3848a35 100644 --- a/source/includes/api-details/dart/install/install-requirements-description.rst +++ b/source/includes/api-details/dart/install/install-requirements-description.rst @@ -2,8 +2,8 @@ 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 the SDK requires Dart version {+dart-minimum-version+} -or later. +The latest version of Atlas Device SDK requires Dart version +{+dart-minimum-version+} or later. Supported Platforms ~~~~~~~~~~~~~~~~~~~ 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 index 634d3ccd5c..8bd5d9cb2d 100644 --- 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 @@ -12,5 +12,5 @@ Unsupported Platforms 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, use - the :ref:`sdks-build-with-react-native`. +- **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-platform-specific-considerations-description.rst b/source/includes/api-details/kotlin/install/install-platform-specific-considerations-description.rst index af0ec5db6f..e6147d3924 100644 --- 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 @@ -1,6 +1,9 @@ - :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, diff --git a/source/includes/api-details/kotlin/install/install-requirements-description.rst b/source/includes/api-details/kotlin/install/install-requirements-description.rst index ec97e034ea..9c7bbde8bb 100644 --- a/source/includes/api-details/kotlin/install/install-requirements-description.rst +++ b/source/includes/api-details/kotlin/install/install-requirements-description.rst @@ -16,7 +16,7 @@ Additionally, Kotlin Multiplatform (KMP) for mobile projects require the followi `Kotlin Multiplatform documentation `__. -For more details on setting up your KMP environment, refer to the `official Kotlin +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 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 index 0ec593b52f..33b5b15cfe 100644 --- 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 @@ -12,9 +12,9 @@ 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 ``Realm``, you must -build ``Realm`` as a dynamic framework. For details, refer to the Swift -Package Manager Installation instructions step +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 index e9614bd067..31112af4e2 100644 --- a/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst +++ b/source/includes/api-details/objectivec/install/install-sdk-procedure-cocoapods.rst @@ -7,7 +7,7 @@ CocoaPods 1.10.1 or later. .. step:: Update the CocoaPods repositories On the command line, run ``pod repo update`` to ensure - CocoaPods can access the latest available Realm versions. + CocoaPods can access the latest available ``Realm`` library versions. .. step:: Initialize CocoaPods for Your Project 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 index 3e17534369..0506e7bf17 100644 --- a/source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst +++ b/source/includes/api-details/swift/install/install-sdk-procedure-cocoapods.rst @@ -7,7 +7,7 @@ CocoaPods 1.10.1 or later. .. step:: Update the CocoaPods repositories On the command line, run ``pod repo update`` to ensure - CocoaPods can access the latest available Realm versions. + CocoaPods can access the latest available ``RealmSwift`` package versions. .. step:: Initialize CocoaPods for Your Project 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 index 28f9f09d32..11f9d7e2e9 100644 --- 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 @@ -18,7 +18,7 @@ Xcode 15 :class: index-table * - Supported OS - - Realm + - Realm Database - Atlas App Services * - iOS 12.0+ diff --git a/source/sdk/install.txt b/source/sdk/install.txt index ca34cfb046..91cb0aaae0 100644 --- a/source/sdk/install.txt +++ b/source/sdk/install.txt @@ -116,8 +116,8 @@ Install the SDK .. tip:: Atlas Device SDK and Realm - The SDK uses Realm Core database for device data persistence. When you - install the SDK, the package names reflect Realm naming. + 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:: @@ -242,8 +242,8 @@ Import the SDK .. tip:: Atlas Device SDK and Realm - The SDK uses Realm Core database for device data persistence. When you - import the SDK, the package names reflect Realm naming. + 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::