(DOCSP-39500): Consolidate Install page

snooty.toml

@@ -11,6 +11,9 @@ intersphinx = [
 toc_landing_pages = [
  # New IA
  "/sdk/crud/create",
+ "/sdk/platforms/android",
+ "/sdk/platforms/apple",
+ "/sdk/platforms/unity",
 
  # Tutorial
  "/tutorial",
@@ -86,6 +89,8 @@ atlas = "Atlas"
 admin-api-page = "/admin/api/v3/#"
 base-url = "https://www.mongodb.com/docs/realm"
 cpp-prefix = "https://www.mongodb.com/docs/realm-sdks/cpp/latest"
+dart-minimum-version="3.3.0"
+flutter-minimum-version="3.19.0"
 kotlin-sdk-version = "1.16.0"
 kotlinx-coroutines-version = "1.7.0"
 kotlin-sync-prefix = "https://www.mongodb.com/docs/realm-sdks/kotlin/latest/library-sync/"

source/frameworks/flutter.txt

@@ -7,4 +7,5 @@ Build with Flutter
 .. toctree::
  :titlesonly:
 
+ Install </frameworks/flutter/install>
  Quick Start </frameworks/flutter/quick-start>

source/frameworks/flutter/install.txt

@@ -0,0 +1,154 @@
+.. _sdks-install-sdk-in-flutter-project:
+
+====================================
+Install Atlas Device SDK for Flutter
+====================================
+
+.. meta::
+ :description: Install the Atlas Device SDK in a Flutter application.
+ :keywords: Realm, Flutter SDK, code example
+
+.. facet::
+ :name: genre
+ :values: tutorial
+
+.. facet::
+ :name: programming_language
+ :values: dart
+
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 2
+ :class: singlecol
+
+Use Atlas Device SDK in a Flutter project to build cross-platform
+applications with Flutter and Dart. This guide provides instructions for
+installing the SDK in a Flutter project. For details about installing the SDK
+in a standalone Dart project, refer to
+:ref:`sdks-install`.
+
+Requirements
+------------
+
+Install Flutter with Dart in your development environment. The Flutter
+installation includes Dart. To learn how, refer to the official
+`Flutter Installation Guide <https://docs.flutter.dev/get-started/install>`__.
+
+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 <app_name>
+ cd <app_name>
+
+ For more information, refer to Flutter's `Get Started Guide
+ <https://docs.flutter.dev/get-started/test-drive?tab=terminal>`__.
+
+ .. 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 <https://pub.dev/packages/realm>`__
+ package, and adds it to your project.
+
+ In your ``pubspec.yaml`` file, you should see:
+
+ .. code-block:: yaml
+ :caption: pubspec.yaml
+
+ dependencies:
+ realm: <latest_version>
+
+ .. note:: Using Networking in your macOS App
+
+ If you are developing with Flutter in the macOS App Sandbox and
+ require network access, you must enable network entitlements in your
+ app. By default, network requests are not allowed due to built-in
+ macOS security settings.
+
+ To learn how to change your app's macOS entitlements, refer to
+ :ref:`Device Sync and App Sandbox Entitlements
+ <sdks-macos-flutter-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: <updated_version>
+
+ .. step:: Install the Updated Package
+
+ From the command line, run the following command to install the updated
+ version:
+
+ .. code-block::
+
+ dart pub upgrade realm
+
+ Then, run the following command to install the updated SDK's native
+ binaries:
+
+ .. code-block::
+
+ dart run realm install
+
+ .. step:: Regenerate Object Models
+
+ Changes to the package version may affect the functionality of the object
+ models. From the command line, run the following command to regenerate
+ object models with new and updated functionality:
+
+ .. code-block:: bash
+
+ dart run realm generate
+
+ .. include:: /includes/flutter-v2-breaking-change.rst
+
+Import the SDK
+--------------
+
+To use the SDK in your app, import the package into any files that use it:
+
+.. code-block:: dart
+ :caption: ExampleFile.dart
+
+ import 'package:realm/realm.dart';
+
+Platform-Specific Considerations
+--------------------------------
+
+.. include:: /includes/api-details/dart/install/install-platform-specific-considerations-description.rst

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 <realm/SyncErrorCode.html>` API reference.
+
+ * - ``Realm.logger.level``
+ - Replaced by ``Realm.logger.setLogLevel``.
+ - Replace any instances. See also :ref:`sdks-logging`.
+
+ * - ``RealmProperty.indexed``
+ - Replaced by ``RealmProperty.indexType``.
+ - Replace any instances.
+
+ * - ``RealmValue.type``
+ - Changed to an enum of ``RealmValueType``.
+ - Replace any instances. See also :ref:`RealmValue Data Type <sdks-mixed-data-type>`.
+
+ * - ``RealmValue.uint8List``
+ - Renamed to ``RealmValue.binary``.
+ - Replace any instances. See also :ref:`RealmValue Data Type <sdks-mixed-data-type>`.
+
+ * - ``SchemaObject.properties``
+ - ``SchemaObject`` changed to an iterable collection of ``SchemaProperty``.
+ - Replace any instances. See also the
+ :flutter-sdk:`SchemaObject <realm/SchemaObject-class.html>` 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 <realm/SyncErrorCode.html>` 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 <realm/SyncErrorCode.html>` 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 <realm/SyncErrorCode.html>` API reference.
+
+ * - ``SyncProgress.transferredBytes`` and ``SyncProgress.transferableBytes``
+ - Reported transferred and transferable values were incorrect. Consolidated
+ into a new ``SyncProgress.progressEstimate`` metric.
+ - Use ``SyncProgress.progressEstimate``. See also :ref:`sdks-check-upload-and-download-progress`.
+
+ * - ``User.provider``
+ - Provider is associated with each identity, so value was incorrect
+ for users with more than one identity.
+ - Remove any instances.

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.