From bd37f7e1543de4d861b1212bdf689204569db5db Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Oct 2024 16:18:52 -0400 Subject: [PATCH 01/11] DOCSP-43368: Cleanup --- source/connect.txt | 2 +- source/connect/connection-targets.txt | 9 +- source/connect/mongoclient.txt | 12 +- source/get-started/connect-to-mongodb.txt | 26 +- .../create-a-connection-string.txt | 5 +- source/get-started/download-and-install.txt | 8 +- source/includes/aggregation/aggregation.c | 7 +- .../databases-collections.c | 3 +- source/includes/get-started/quickstart.c | 3 +- source/includes/indexes/indexes.c | 8 +- source/includes/read/change-streams.c | 7 +- source/includes/read/count.c | 8 +- source/includes/read/cursors.c | 7 +- source/includes/read/distinct.c | 8 +- source/includes/read/project.c | 9 +- source/includes/read/retrieve.c | 8 +- source/includes/read/specify-a-query.c | 7 +- .../read/specify-documents-to-return.c | 8 +- .../usage-examples/index-code-examples.c | 12 +- .../usage-examples/retrieve-code-examples.c | 5 +- .../usage-examples/sample-indexes-app.c | 8 +- .../includes/usage-examples/sample-read-app.c | 8 +- source/index.txt | 26 +- source/indexes.txt | 4 +- source/install-from-source.txt | 381 ++++++++++++++++++ source/read.txt | 7 +- source/upgrade.txt | 6 +- source/work-with-indexes.txt | 2 + 28 files changed, 488 insertions(+), 116 deletions(-) create mode 100644 source/install-from-source.txt diff --git a/source/connect.txt b/source/connect.txt index 4c847adc..ed562513 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -1,4 +1,4 @@ -.. _c-sync-connect: +.. _c-connect: ================== Connect to MongoDB diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index 415712b3..e28b897a 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -40,9 +40,6 @@ Then, pass your connection string to the ``mongoc_client_new()`` function. Follow the :atlas:`Atlas driver connection guide ` to retrieve your connection string. -.. TODO, uncomment this and link to correct Stable API page for C, once written. -.. To learn more about the {+stable-api+} feature, see the :ref:``guide. - The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The code also uses the ``mongoc_server_api_new()`` function to specify a {+stable-api+} version. @@ -52,13 +49,11 @@ code also uses the ``mongoc_server_api_new()`` function to specify a {+stable-ap :end-before: end-connect-stable-api :dedent: - -.. TODO, add link to Stable API page for C Driver once created - .. tip:: When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid - breaking changes when Atlas upgrades to a new version of {+mdb-server+}. + breaking changes when Atlas upgrades to a new version of {+mdb-server+}. To learn more + about the {+stable-api+}, see the :ref:`c-stable-api` guide. Local Deployments ----------------- diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt index 59a43f89..04dc5d00 100644 --- a/source/connect/mongoclient.txt +++ b/source/connect/mongoclient.txt @@ -37,9 +37,6 @@ Connection URI A standard connection string includes the following components: -.. TODO, add this as last sentence for ``username:password`` description once a c auth page is made: -.. For more information about the ``authSource`` connection option, see :ref:`c-auth`. - .. list-table:: :widths: 20 80 :header-rows: 1 @@ -56,6 +53,8 @@ A standard connection string includes the following components: - Optional. Authentication credentials. If you include these, the client authenticates the user against the database specified in ``authSource``. + For more information about the ``authSource`` connection option, see the + :ref:`c-auth` guide. * - ``host[:port]`` @@ -96,9 +95,10 @@ to connect to a MongoDB instance: You can set the Stable API version client option to avoid breaking changes when you upgrade to a new server version. -.. TODO, uncomment these once the Stable API for C Driver page is made. -.. To learn more about the Stable API feature, -.. see the :ref:`Stable API page `. +.. tip:: + + To learn more about the {+stable-api+} feature, see the :ref:`c-stable-api` + guide. The following code shows how you can specify the connection string and the Stable API client option when connecting to a MongoDB deployment on Atlas diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt index 72c7e75f..0ab8aaa1 100644 --- a/source/get-started/connect-to-mongodb.txt +++ b/source/get-started/connect-to-mongodb.txt @@ -24,17 +24,31 @@ Connect to MongoDB mkdir c-quickstart - Run the following commands to create a ``quickstart.c`` application file in the ``c-quickstart`` - directory: + Select the tab corresponding to your operating system and run the + following commands to create a ``quickstart.c`` application file + in the ``c-quickstart`` directory: - .. code-block:: bash + .. tabs:: + + .. tab:: macOS / Linux + :tabid: create-file-mac-linux + + .. code-block:: bash + + cd c-quickstart + touch quickstart.c + + .. tab:: Windows + :tabid: create-file-windows + + .. code-block:: bash - cd c-quickstart - touch quickstart.c + cd c-quickstart + type nul > quickstart.c .. step:: Create your {+driver-short+} application - Copy and paste the following code into the ``quickstart.cpp`` file, which queries + Copy and paste the following code into the ``quickstart.c`` file, which queries the ``movies`` collection in the ``sample_mflix`` database: .. literalinclude:: /includes/get-started/quickstart.c diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt index ac013199..5fb6cabe 100644 --- a/source/get-started/create-a-connection-string.txt +++ b/source/get-started/create-a-connection-string.txt @@ -13,9 +13,8 @@ The connection string includes the hostname or IP address and port of your deployment, the authentication mechanism, user credentials when applicable, and connection options. -.. TODO -.. To connect to an instance or deployment not hosted on Atlas, see the -.. :ref:`c-connection-targets` guide. +To connect to an instance or deployment not hosted on Atlas, see the +:ref:`c-connection-targets` guide. .. procedure:: :style: connected diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt index 2631ee60..f0489042 100644 --- a/source/get-started/download-and-install.txt +++ b/source/get-started/download-and-install.txt @@ -32,8 +32,8 @@ following command in your shell: apt-cache policy libmongoc-dev If the version of the driver that is available is not the version you want, you -can install the driver from source. -.. TODO: To learn how to install the driver from source, see the c-install-from-source guide. +can install the driver from source. To learn how to install the driver from source, +see the :ref:`c-install-from-source` guide. To learn how to install the driver by using a package manager, select the tab corresponding to your operating system: @@ -205,10 +205,6 @@ your operating system: brew install mongo-c-driver -.. TODO: - .. To learn how to install the driver libraries from source, see the - .. :ref:`c-install-from-source`` guide. - After you complete these steps, you have the {+driver-short+} installed on your machine. diff --git a/source/includes/aggregation/aggregation.c b/source/includes/aggregation/aggregation.c index 7ebbafd1..5d131178 100644 --- a/source/includes/aggregation/aggregation.c +++ b/source/includes/aggregation/aggregation.c @@ -1,16 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/databases-collections/databases-collections.c b/source/includes/databases-collections/databases-collections.c index 165a1b16..98a5d10f 100644 --- a/source/includes/databases-collections/databases-collections.c +++ b/source/includes/databases-collections/databases-collections.c @@ -2,7 +2,8 @@ #include #include -int main(int argc, char *argv[]) +int +main (void) { bson_error_t error; diff --git a/source/includes/get-started/quickstart.c b/source/includes/get-started/quickstart.c index 0b3b3b68..7f650ddd 100644 --- a/source/includes/get-started/quickstart.c +++ b/source/includes/get-started/quickstart.c @@ -2,7 +2,8 @@ #include #include -int main (int argc, char *argv[]) +int +main (void) { const bson_t *doc; diff --git a/source/includes/indexes/indexes.c b/source/includes/indexes/indexes.c index 577f803d..317acf8d 100644 --- a/source/includes/indexes/indexes.c +++ b/source/includes/indexes/indexes.c @@ -3,17 +3,15 @@ #include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; mongoc_init (); - client = - mongoc_client_new (""); - collection = - mongoc_client_get_collection (client, "sample_mflix", "movies"); + client = mongoc_client_new (""); + collection = mongoc_client_get_collection (client, "sample_mflix", "movies"); { // start-remove-index diff --git a/source/includes/read/change-streams.c b/source/includes/read/change-streams.c index 4d271526..74c9ef49 100644 --- a/source/includes/read/change-streams.c +++ b/source/includes/read/change-streams.c @@ -1,16 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/read/count.c b/source/includes/read/count.c index 8c8bc381..2fc99107 100644 --- a/source/includes/read/count.c +++ b/source/includes/read/count.c @@ -1,17 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_mflix", "movies"); { diff --git a/source/includes/read/cursors.c b/source/includes/read/cursors.c index 1f46fda7..50acc333 100644 --- a/source/includes/read/cursors.c +++ b/source/includes/read/cursors.c @@ -1,16 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/read/distinct.c b/source/includes/read/distinct.c index 82c66faf..c7447fc8 100644 --- a/source/includes/read/distinct.c +++ b/source/includes/read/distinct.c @@ -1,17 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/read/project.c b/source/includes/read/project.c index e7c3931f..ae003739 100644 --- a/source/includes/read/project.c +++ b/source/includes/read/project.c @@ -1,18 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - bson_error_t error; - mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/read/retrieve.c b/source/includes/read/retrieve.c index ee0e3fdd..419481d1 100644 --- a/source/includes/read/retrieve.c +++ b/source/includes/read/retrieve.c @@ -1,17 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/read/specify-a-query.c b/source/includes/read/specify-a-query.c index fbdcdb16..eebe8b2d 100644 --- a/source/includes/read/specify-a-query.c +++ b/source/includes/read/specify-a-query.c @@ -1,16 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_fruit", "fruits"); { diff --git a/source/includes/read/specify-documents-to-return.c b/source/includes/read/specify-documents-to-return.c index 597c9729..59756e03 100644 --- a/source/includes/read/specify-documents-to-return.c +++ b/source/includes/read/specify-documents-to-return.c @@ -1,17 +1,15 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants"); { diff --git a/source/includes/usage-examples/index-code-examples.c b/source/includes/usage-examples/index-code-examples.c index 7f34bdb3..67042fbe 100644 --- a/source/includes/usage-examples/index-code-examples.c +++ b/source/includes/usage-examples/index-code-examples.c @@ -1,20 +1,16 @@ +#include #include #include -#include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; - bson_error_t error; - mongoc_init (); - client = - mongoc_client_new (""); - collection = - mongoc_client_get_collection (client, "sample_mflix", "movies"); + client = mongoc_client_new (""); + collection = mongoc_client_get_collection (client, "sample_mflix", "movies"); // Start example code here { diff --git a/source/includes/usage-examples/retrieve-code-examples.c b/source/includes/usage-examples/retrieve-code-examples.c index 3127752d..8f9a32f4 100644 --- a/source/includes/usage-examples/retrieve-code-examples.c +++ b/source/includes/usage-examples/retrieve-code-examples.c @@ -3,7 +3,7 @@ #include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; @@ -12,8 +12,7 @@ main (int argc, char *argv[]) mongoc_init (); - client = - mongoc_client_new (""); + client = mongoc_client_new (""); collection = mongoc_client_get_collection (client, "", "collection name"); { diff --git a/source/includes/usage-examples/sample-indexes-app.c b/source/includes/usage-examples/sample-indexes-app.c index 13747e17..bb230392 100644 --- a/source/includes/usage-examples/sample-indexes-app.c +++ b/source/includes/usage-examples/sample-indexes-app.c @@ -3,7 +3,7 @@ #include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; @@ -11,10 +11,8 @@ main (int argc, char *argv[]) mongoc_init (); - client = - mongoc_client_new (""); - collection = - mongoc_client_get_collection (client, "", "collection name"); + client = mongoc_client_new (""); + collection = mongoc_client_get_collection (client, "", "collection name"); // Start example code here diff --git a/source/includes/usage-examples/sample-read-app.c b/source/includes/usage-examples/sample-read-app.c index f1391346..97325a42 100644 --- a/source/includes/usage-examples/sample-read-app.c +++ b/source/includes/usage-examples/sample-read-app.c @@ -3,7 +3,7 @@ #include int -main (int argc, char *argv[]) +main (void) { mongoc_client_t *client; mongoc_collection_t *collection; @@ -12,10 +12,8 @@ main (int argc, char *argv[]) mongoc_init (); - client = - mongoc_client_new (""); - collection = - mongoc_client_get_collection (client, "", "collection name"); + client = mongoc_client_new (""); + collection = mongoc_client_get_collection (client, "", "collection name"); // Start example code here diff --git a/source/index.txt b/source/index.txt index ba2c33ee..89730b66 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,6 +12,7 @@ /read /indexes /aggregation + /install-from-source /whats-new /compatibility /upgrade @@ -34,12 +35,11 @@ Get Started Learn how to install the driver, establish a connection to MongoDB, and begin working with data in the :ref:`c-get-started` tutorial. -.. TODO -.. Connect to MongoDB -.. ------------------ +Connect to MongoDB +------------------ -.. Learn how to create and configure a connection to a MongoDB deployment -.. in the :ref:`c-connect` section. +Learn how to create and configure a connection to a MongoDB deployment +in the :ref:`c-connect` section. Databases and Collections ------------------------- @@ -52,11 +52,10 @@ What's New For a list of new features and changes in each version, see the :ref:`What's New ` section. -.. TODO -.. Write Data to MongoDB -.. --------------------- +Write Data to MongoDB +--------------------- -.. Learn how you can write data to MongoDB in the :ref:`c-write` section. +Learn how you can write data to MongoDB in the :ref:`c-write` section. Read Data from MongoDB ---------------------- @@ -75,6 +74,12 @@ Transform Your Data with Aggregation Learn how to use the {+driver-short+} to perform aggregation operations in the :ref:`c-aggregation` section. +Install From Source +------------------- + +Learn how to build the ``libmongoc`` and ``libbson`` libraries from their source +code in the :ref:`c-install-from-source` section. + .. TODO: .. FAQ .. --- @@ -97,9 +102,8 @@ Learn how to use the {+driver-short+} to perform aggregation operations in the .. Learn how to report bugs, contribute to the driver, and find more resources for .. asking questions and receiving help in the :ref:`Issues & Help ` section. - Compatibility ------------- +------------- To learn about the versions of the {+mdb-server+} and the C language that are compatible with each version of the {+driver-short+}, see the :ref:`Compatibility ` section. diff --git a/source/indexes.txt b/source/indexes.txt index cd9ec214..c65cb9fa 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -186,8 +186,8 @@ The following example deletes an index with the specified name: :copyable: :dedent: -.. TODO: To learn more about removing indexes, see :ref:`c-indexes-remove` -.. in the Work with Indexes guide. +To learn more about removing indexes, see :ref:`c-indexes-remove` +in the Work with Indexes guide. Atlas Search Index Management ----------------------------- diff --git a/source/install-from-source.txt b/source/install-from-source.txt new file mode 100644 index 00000000..531f1d92 --- /dev/null +++ b/source/install-from-source.txt @@ -0,0 +1,381 @@ +.. _c-install-from-source: + +=========================================== +Building the C Driver Libraries from Source +=========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page details how to download, unpack, configure, and build ``libbson`` and +``libmongoc`` from their original source-code form. + +.. tip:: Extra information + + Dropdowns (like this one) contain extra information and explanatory details + that are not required to complete the tutorial, but may be helpful for curious + readers, and more advanced users that want an explanation of the meaning of + certain tutorial steps. + +The following page uses a few named "variables" that you must decide up-front. +When you see such a value referenced in a tutorial step, you should substitute +the value into that step. + +.. seealso:: + + Before building, you may want to check that you are running on a supported + platform. For the list of supported platforms, refer to the + :ref:`platform-support` page. + + +Choose a Version +---------------- + +Before we begin, know what version of ``mongo-c-driver`` you will be downloading. +A list of available versions can be found on +`the GitHub repository tags page `__. +(The current version written for this documentation is {+full-version+}.) + +For the remainder of this page, ``$VERSION`` will refer to the version number of +``mongo-c-driver`` that you will be building for this tutorial. + + +.. _get-src: + +Obtaining the Source +-------------------- + +There are two primary recommended methods of obtaining the ``mongo-c-driver`` +source code: + +1. Clone the repository using ``git`` (recommended). + `(See below) `__ + +2. Download a source archive at a specific version. + `(See below) `__ + +.. important:: + + It is **highly recommended** that new users use a stable released version of + the driver, rather than building from a development branch. When you + ``git clone`` or download an archive of the repository, be sure to specify a + release tag (e.g. with Git's ``--branch`` argument). + +.. _learn.obtaining.git: + +Downloading Using Git +~~~~~~~~~~~~~~~~~~~~~ + +Using Git, the C driver repository can be cloned from the GitHub URL +https://github.com/mongodb/mongo-c-driver.git. Git tags for released versions +are named after the version for which they correspond (e.g. "{+full-version+}"). To +clone the repository using the command line, the following command may be used: + +.. code-block:: bash + + $ git clone https://github.com/mongodb/mongo-c-driver.git --branch="$VERSION" "$SOURCE" + +.. tip:: + + Despite the name, ``git-clone``'s ``--branch`` argument may also be used to + clone from repository *tags*. + +.. _learn.obtaining.archive: + +Downloading a Release Archive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An archived snapshot of the repository can be obtained from the +`GitHub Releases Page `__. +The ``mongo-c-driver-x.y.z.tar.gz`` archive attached to any release contains the +minimal set of files that you'll need for the build. + +.. tabs:: + + .. tab:: Using ``wget`` + ``tar`` + :tabid: wget-tar + + .. code-block:: none + + ## Download using wget: + $ wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \ + --output-document="mongo-c-driver-$VERSION.tar.gz" + ## Extract using tar: + $ tar xf "mongo-c-driver-$VERSION.tar.gz" + + .. tab:: Using ``curl`` + ``tar`` + :tabid: curl-tar + + .. code-block:: none + + ## Using curl: + $ curl "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \ + --output="mongo-c-driver-$VERSION.tar.gz" + ## Extract using tar: + $ tar xf "mongo-c-driver-$VERSION.tar.gz" + + .. tab:: PowerShell + :tabid: powershell + + .. code-block:: none + + ## Use Invoke-WebRequest: + PS> $url = "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.zip" + PS> $file = "mongo-c-driver-$VERSION.zip" + PS> Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file + ## Extract using Expand-Archive: + PS> Expand-Archive mongo-c-driver-$VERSION.zip + +The above commands will create a new directory ``mongo-c-driver-$VERSION`` within +the directory in which you ran the ``tar`` / ``Expand-Archive`` command (**note**: +PowerShell will create an additional intermediate subdirectory of the same +name). This directory is the root of the driver source tree (which we refer to +as ``$SOURCE`` in these documents). The ``$SOURCE`` directory should contain the +top-level ``CMakeLists.txt`` file. + + +Obtaining Prerequisites +----------------------- + +In order to build the project, a few prerequisites need to be available. + +Both ``libmongoc`` and ``libbson`` projects use `CMake `__ for build configuration. + +.. note:: + + It is *highly recommended* -- but not *required* -- that you download the + latest stable CMake available for your platform. + +.. tip:: Getting the Latest CMake + + A new stable release of CMake can be obtained from + `the CMake downloads page `__. + + For Windows and macOS, simply download the CMake ``.msi`` / ``.dmg`` (not the + ``.zip`` / ``.tar.gz``) and use it to install CMake. + + On Linux, download the self-extracting shell script (ending with ``.sh``) and + execute it using the ``sh`` utility, passing the appropriate arguments to + perform the install. For example, with the CMake 3.27.0 on the ``x86_64`` + platform, the following command can be used on the + ``cmake-3.27.0-linux-x86_64.sh`` script: + + .. code-block:: none + + $ sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license + + Assuming that ``$HOME/.local/bin`` is on your ``$PATH`` list, the ``cmake`` command + for 3.27.0 will then become available. + + The ``--help`` option can be passed to the shell script for more information. + +For the remainder of this page, it will be assumed that ``cmake`` is available as +a command on your ``PATH`` environment variable and can be executed as "``cmake``" +from a shell. You can test this by requesting the ``--version`` from CMake from +the command line: + +.. code-block:: none + + $ cmake --version + cmake version 3.21.4 + + CMake suite maintained and supported by Kitware (kitware.com/cmake). + +.. note:: + + If you intend to build ``libbson`` *only*, then CMake is sufficient for the + build. Additional C driver features may require additional external + dependencies be installed, but we will not worry about them here. + +.. XXX: Additional note for installing dependencies + + The Linux dependencies of sufficient version are likely available using the + system package manager. For example, on **Debian**/**Ubuntu** based systems, + they can be installed using APT: + + .. code-block:: none + + # apt install libssl-dev libsasl2-dev + + On **RedHat** based systems (**Fedora**, **CentOS**, **RockyLinux**, + **AlmaLinux**, etc.): + + .. code-block:: none + + # dnf install openssl-devel cyrus-sasl-devel + + Package names may vary between distributions. + +.. _learn.get.configure: + +Configuring for libbson +----------------------- + +.. important:: + + If you are building with Xcode [1]_ or Visual Studio [2]_, you + may need to execute CMake from within a special environment in which the + respective toolchain is available. + +Let the name ``$BUILD`` be the path ``$SOURCE/_build``. This will be the directory +where our built files will be written by CMake. + +With the source directory for ``mongo-c-driver`` at ``$SOURCE`` and build directory +``$BUILD``, the following command can be executed from a command-line to configure +the project with both ``libbson`` and ``libmongoc``: + +.. code-block:: none + + $ cmake -S $SOURCE -B $BUILD \ + -D ENABLE_EXTRA_ALIGNMENT=OFF \ + -D ENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \ + -D CMAKE_BUILD_TYPE=RelWithDebInfo \ + -D BUILD_VERSION="$VERSION" \ + -D ENABLE_MONGOC=OFF + + +If all dependencies are satisfied, the above command should succeed and end +with: + +.. code-block:: none + + $ cmake … + ## … (Lines of output) … + -- Generating done + -- Build files have been written to: $BUILD + +If configuration failed with an error, refer to the CMake output for error +messages and information. Ensure that configuration succeeds before proceeding. + +.. tip:: What do these CMake arguments mean? + + The ``BUILD_VERSION`` sets the version number that will be included in the build + results. This should be set to the same value as the version of the source + driver that was downloaded in :ref:`get-src`. + + The ``ENABLE_EXTRA_ALIGNMENT`` and ``ENABLE_AUTOMATIC_INIT_AND_CLEANUP`` are part + of ``mongo-c-driver``, and correspond to deprecated features that are only + enabled by default for ABI compatibility purposes. It is highly recommended to + disable these features whenever possible. + + The ``ENABLE_MONGOC=OFF`` argument disabled building ``libmongoc``. We'll build + that in the next section. + + The ``CMAKE_BUILD_TYPE`` setting tells CMake what variant of code will be + generated. In the case of ``RelWithDebInfo``, optimized binaries will be + produced, but still include debug information. The `CMAKE_BUILD_TYPE `__ + has no effect on Multi-Config generators (i.e. Visual Studio), which instead rely on + the ``--config`` option when building/installing. + +.. _learn.get.build: + +Building the Project +-------------------- + +After successfully configuring the project, the build can be executed by using +CMake: + +.. code-block:: none + + $ cmake --build $BUILD --config RelWithDebInfo --parallel + +If configured properly and all dependencies are satisfied, then the above +command should proceed to compile and link the configured components. If the +above command fails, then there is likely an error with your environment, or you +are using an unsupported/untested platform. Refer to the build tool output for +more information. + +.. tip:: The ``--config`` option + + The ``--config`` option is used to set the build configuration to use in the case of + Multi-Config generators (i.e. Visual Studio). It has no effect on other generators, + which instead use ``CMAKE_BUILD_TYPE``. + +.. _learn.get.install: + +Installing the Built Results +---------------------------- + +Let ``$PREFIX`` be the path ``$SOURCE/_install``. We can use CMake to install the +built results: + +.. code-block:: none + + $ cmake --install "$BUILD" --prefix "$PREFIX" --config RelWithDebInfo + +This command will install the ``mongo-c-driver`` build results into the ``$PREFIX`` +directory. + +.. tip:: The ``--config`` option + + The ``--config`` option is only used for Multi-Config generators (i.e. Visual Studio) + and is otherwise ignored. The value given for ``--config`` must be the same as was given for + ``--config`` with ``cmake --build``. + +.. seealso:: + + The above snippet simply installs ``mongo-c-driver`` in a subdirectory of the + source directory itself, but this is not a normal workflow. Once you feel + compfortable about configuring and building ``mongo-c-driver``, the page + :ref:`how-to-install` will do a deeper dive on from-source + installation options. + + +Configuring with libmongoc +-------------------------- + +If you followed the above steps starting from :ref:`learn.get.configure`, your +final result with only contain ``libbson`` and not the full C database driver +library. Building of ``libmongoc`` is enabled/disabled using the ``ENABLE_MONGOC`` +CMake variable. Re-run CMake again, but set ``ENABLE_MONGOC`` to ``TRUE``: + +.. code-block:: none + + $ cmake -D ENABLE_MONGOC=ON $BUILD + +If the above command succeeds, then the project has been reconfigured to build +with ``libmongoc``. Follow the process at :ref:`learn.get.build` and +:ref:`learn.get.install` again to build and install ``libmongoc``. + +.. TODO: + Add a guide on installing with the additional option features, which requires + additional packages be available for the build. + +Footnotes +~~~~~~~~~ + +.. [1] If you wish to configure and build the project with Xcode, the Xcode + command-line tools need to be installed and made available in the environment. + From within a command-line environment, run: + + .. code-block:: none + + $ xcode-select --install + + This will ensure that the compilers and linkers are available on your ``$PATH``. + +.. [2] If you wish to configure and build the project using Microsoft Visual C++, + then the Visual C++ tools and environment variables may need to be set when + running any CMake or build command. + + In many cases, CMake will detect a Visual Studio installation and + automatically load the environment itself when it is executed. This automatic + detection can be controlled with CMake's ``-G``, ``-T``, and ``-A`` options. The ``-G`` option + is the most significant, as it selects which Visual Studio version will be + used. The versions of Visual Studio supported depends on the version of CMake + that you have installed. + `A list of supported Visual Studio versions can be found here + `__. + + For greater control and more tooling options, it is recommended to run + commands from within a Visual Studio *Developer PowerShell* (preferred) or + *Developer Command Prompt* (legacy). + + For more information, refer to: + `Visual Studio Developer Command Prompt and Developer PowerShell + `__ + and `Use the Microsoft C++ toolset from the command line `__ + on the Microsoft Visual Studio documentation pages. \ No newline at end of file diff --git a/source/read.txt b/source/read.txt index 64c69a40..6c6503b9 100644 --- a/source/read.txt +++ b/source/read.txt @@ -57,10 +57,11 @@ the relevant values for your MongoDB deployment. :linenos: :emphasize-lines: 20-22 -.. TODO: uncomment when installation guide is complete -.. .. tip:: -.. For instructions about how to install the {+driver-short+}, see :ref:``. +.. tip:: + + For instructions about how to install the {+driver-short+}, see :ref:`` + in the Get Started guide. Find Documents -------------- diff --git a/source/upgrade.txt b/source/upgrade.txt index d291a3e8..37ca0fdb 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -36,7 +36,11 @@ Before you upgrade, perform the following actions: {+mdb-server+} release compatibility changes, see the :ref:`Server Release Compatibility Changes ` section. -.. TODO: Add a tip to use the stable API and link to corresponding page. +.. tip:: + + To minimize the number of changes your application requires when upgrading driver + versions in the future, use the {+stable-api+}. To learn more, see the :ref:`c-stable-api` + guide. .. _c-breaking-changes: diff --git a/source/work-with-indexes.txt b/source/work-with-indexes.txt index 875e7e7d..36071fa7 100644 --- a/source/work-with-indexes.txt +++ b/source/work-with-indexes.txt @@ -74,6 +74,8 @@ code for creating each index type. - :ref:`c-multikey-index` - :ref:`c-atlas-search-index` +.. _c-indexes-remove: + Remove an Index --------------- From 1e7fd7236237ece7ab7984c9fc313607cc511ffd Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Oct 2024 16:51:34 -0400 Subject: [PATCH 02/11] edits, add platform compat --- source/compatibility.txt | 96 +++++++++++++++++++++++++++++++++- source/install-from-source.txt | 12 +---- source/upgrade.txt | 1 - source/whats-new.txt | 2 +- 4 files changed, 98 insertions(+), 13 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index cb81fecb..4d72c48f 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -42,4 +42,98 @@ The first column lists the driver version. .. include:: /includes/compatibility/language-compatibility-table-c.rst For more information on how to read the compatibility tables, see our guide on -:ref:`MongoDB Compatibility Tables. ` \ No newline at end of file +:ref:`MongoDB Compatibility Tables. ` + +.. _platform-support: + +Platform Compatibility +---------------------- + +This section includes version compatibility information about platforms and +toolchains that are supported by the {+driver-short+}. + +Operating Systems +~~~~~~~~~~~~~~~~~ + +The following operating systems are continually tested with the {+driver-short+}: + +.. list-table:: + :header-rows: 1 + :align: left + + * - Operating System + - Notes + + * - Debian + - Versions **9.2**, **10.0**, and **11.0** + * - RHEL + - Versions **7.0**, **7.1**, **8.1**, **8.2**, and **8.3**. RHEL derivatives + (e.g. CentOS, Rocky Linux, AlmaLinux) of the same release version are + supported. Fedora is also supported, but not continually tested. + * - Ubuntu + - Versions **16.04**, **18.04**, and **20.04**. Subsequent minor releases + are also supported. Ubuntu **22.04** and newer is not yet tested. Ubuntu + derivatives based on supported Ubuntu versions are also supported. + * - Arch Linux + - + * - macOS + - Version **11.0** + * - Windows Server 2008 and Windows Server 2016 + - Windows variants of the same generation are supported + + +Compilers +~~~~~~~~~ + +The following compilers are continually tested with the {+driver-short+}: + +.. list-table:: + :header-rows: 1 + :align: left + + * - Compiler + - Notes + * - Clang + - Versions **3.7**, **3.8**, and **6.0**. Newer versions + are also supported, as well as the corresponding Apple Clang releases. + * - GCC + - Versions **4.8**, **5.4**, **6.3**, **7.5**, **8.2**, **8.3**, + **9.4**, and **10.2**. The MinGW-w64 GCC is also tested and supported. + * - Microsoft Visual C++ (MSVC) + - Tested with MSVC **14.x** (Visual Studio **2015**) and **15.x** (Visual Studio + **2017**). Newer MSVC versions are supported but not yet tested. + +Architectures +~~~~~~~~~~~~~ + +The following CPU architectures are continually tested with the {+driver-short+}: + +.. list-table:: + :align: left + :header-rows: 1 + + * - Architecture + - Notes + * - x86 (32-bit) + - Only tested on Windows + * - x86_64 (64-bit x86) + - Tested on Linux, macOS, and Windows + * - ARM / aarch64 + - Tested on macOS and Linux + * - Power8 (ppc64le) + - Only tested on Linux + * - zSeries (s390x) + - Only tested on Linux + +Additional Platforms +~~~~~~~~~~~~~~~~~~~~ + +Other platforms and toolchains are not tested, but similar versions of the above +platforms *should work*. If you encounter a platform or toolchain that you +expect to work and find that it does not, please open an issue describing the +problem, and/or open a `GitHub Pull Request `__ to fix it. + +Simple pull requests to fix unsupported platforms are welcome, but will be +considered on a case-by-case basis. The acceptance of a pull request to fix the +libraries on an unsupported platform does not imply full support of that +platform. \ No newline at end of file diff --git a/source/install-from-source.txt b/source/install-from-source.txt index 531f1d92..6e9e739c 100644 --- a/source/install-from-source.txt +++ b/source/install-from-source.txt @@ -27,8 +27,8 @@ the value into that step. .. seealso:: Before building, you may want to check that you are running on a supported - platform. For the list of supported platforms, refer to the - :ref:`platform-support` page. + platform. For the list of supported platforms, refer to :ref:`platform-support` + on the Compatibility page. Choose a Version @@ -315,14 +315,6 @@ directory. and is otherwise ignored. The value given for ``--config`` must be the same as was given for ``--config`` with ``cmake --build``. -.. seealso:: - - The above snippet simply installs ``mongo-c-driver`` in a subdirectory of the - source directory itself, but this is not a normal workflow. Once you feel - compfortable about configuring and building ``mongo-c-driver``, the page - :ref:`how-to-install` will do a deeper dive on from-source - installation options. - Configuring with libmongoc -------------------------- diff --git a/source/upgrade.txt b/source/upgrade.txt index 37ca0fdb..27c8eecb 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -25,7 +25,6 @@ when you upgrade to a new version of the {+driver-short+}. Before you upgrade, perform the following actions: -.. TODO: Link to platform support page - Ensure the new {+driver-short+} version is compatible with the {+mdb-server+} versions your application connects to and the platform your application runs on. For version compatibility information, see the :ref:`{+driver-short+} Compatibility ` diff --git a/source/whats-new.txt b/source/whats-new.txt index a8660967..aaae946b 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -62,7 +62,7 @@ Fixes - Fixes C23 compile Improvements -``````````` +```````````` - Documents expected behavior of command errors in a transaction From 6a1c38b8c6b4ea0cf87f0f4e9f0a0971655831f4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 15 Oct 2024 13:40:27 -0400 Subject: [PATCH 03/11] build log fixes --- source/connect/tls.txt | 6 +++--- source/write.txt | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 8f33cae0..b1d51df8 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -91,9 +91,9 @@ trusted by the native certificate store in use on the server. You can provide the client certificate in the following ways: -- Setting the ``tlscertificatekeyfile`` parameter in your connection string to a `.pem` file containing the root certificate chain -- Using the `mongoc_uri_set_option_as_utf8()` function to set the `MONGOC_URI_TLSCERTIFICATEKEYFILE` option - to a `.pem` file containing the root certificate chain +- Setting the ``tlscertificatekeyfile`` parameter in your connection string to a ``.pem`` file containing the root certificate chain +- Using the ``mongoc_uri_set_option_as_utf8()`` function to set the ``MONGOC_URI_TLSCERTIFICATEKEYFILE`` option + to a ``.pem`` file containing the root certificate chain .. tabs:: diff --git a/source/write.txt b/source/write.txt index 91b0d314..61453b63 100644 --- a/source/write.txt +++ b/source/write.txt @@ -28,6 +28,7 @@ Write Data to MongoDB /write/delete /write/bulk-write /write/transactions + /write/gridfs Overview -------- From 123a18e887a3d9971a6869203350fbcf65a32b85 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 15 Oct 2024 13:44:46 -0400 Subject: [PATCH 04/11] code highlight --- source/monitoring/cluster-monitoring.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt index eec99d94..3b262d89 100644 --- a/source/monitoring/cluster-monitoring.txt +++ b/source/monitoring/cluster-monitoring.txt @@ -57,7 +57,7 @@ actions: :language: c :copyable: :linenos: - :emphasize-lines: 10, 30-32 + :emphasize-lines: 10, 28-30 When you perform a database operation, the driver establishes a new connection to the server and your subscriber records the server opening event. The code outputs From ee3eb81023ab5a9d8d1e9aaf3bc9a95373d12570 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 15 Oct 2024 13:51:48 -0400 Subject: [PATCH 05/11] toc fix --- source/databases-collections.txt | 1 + source/index.txt | 1 - source/run-command.txt | 183 ------------------------------- 3 files changed, 1 insertion(+), 184 deletions(-) delete mode 100644 source/run-command.txt diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 0728965a..cc1e85bb 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -22,6 +22,7 @@ Databases and Collections :maxdepth: 1 /databases-collections/time-series + /databases-collections/run-command Overview -------- diff --git a/source/index.txt b/source/index.txt index d45e8e18..ddb8f407 100644 --- a/source/index.txt +++ b/source/index.txt @@ -9,7 +9,6 @@ Get Started /connect /databases-collections - /run-command /write /read /indexes diff --git a/source/run-command.txt b/source/run-command.txt deleted file mode 100644 index 75e3c124..00000000 --- a/source/run-command.txt +++ /dev/null @@ -1,183 +0,0 @@ -.. _c-run-command: - -====================== -Run a Database Command -====================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :description: Learn how to use the C Driver to run a database command. - :keywords: command, server, usage, code example - -Overview --------- - -In this guide, you can learn how to run a database command with the -{+driver-short+}. You can use database commands to perform a variety of -administrative and diagnostic tasks, such as fetching server statistics, -initializing a replica set, or running an aggregation pipeline. - -.. important:: Prefer Driver Functions to Database Commands - - The driver provides wrapper functions for many database commands. We recommend - using driver functions instead of executing database commands when possible. - - To perform administrative tasks, use the :mongosh:`MongoDB Shell ` instead - of the {+driver-short+}. Calling the ``db.runCommand()`` method inside the - shell is the preferred method to issue database commands, as it provides a - consistent interface between the shell and drivers. - -Execute a Command ------------------ - -To run a database command, you must specify the command and any relevant -parameters in a BSON document, then pass this BSON document to a command -execution function. The {+driver-short+} provides the following functions to run -database commands: - -- ``mongoc_client_command_simple()``, which runs a specified command on the - server and stores the first document from the result in the ``reply`` BSON - document. This function provides a simplified way to send a command directly - to the server. -- ``mongoc_client_command_with_opts()``, which runs a specified command on the - server and interprets ``opts`` according to the MongoDB server version. This - function offers flexibilty by allowing additional options. - -The following code shows how you can use the ``mongoc_client_command_simple()`` -function to run the ``hello`` command, which returns information about the current -member's role in the replica set, on a database: - -.. literalinclude:: /includes/usage-examples/run-command.c - :language: c - :dedent: - :start-after: start-execute-command - :end-before: end-execute-command - -For a full list of database commands and corresponding parameters, see the -:ref:`Additional Information ` section. - -Command Options ---------------- - -You can specify optional command behavior for the -``mongoc_client_command_with_opts()`` function. This function accepts a BSON -document for the ``opts`` parameter. - -You can pass a BSON document that specifies the following options: - -- ``readConcern`` -- ``writeConcern`` -- ``sessionId`` -- ``collation`` -- ``serverId`` - -To learn more about a command and the options that it accepts, locate the -command and follow the link in the :manual:`Database Commands -` section of the Server manual. - -The following code shows how to specify a ``grantRolesToUsers`` command with a -``majority`` write concern: - -.. literalinclude:: /includes/usage-examples/run-command.c - :language: c - :dedent: - :start-after: start-execute-command-with-options - :end-before: end-execute-command-with-options - -.. note:: Read Preference - - The ``mongoc_client_command_simple()`` and - ``mongoc_client_command_with_opts()`` functions ignore the read preference - setting you might have set on your client. By default, these functions use - the ``primary`` read preference. - - To specify a read preference other than the primary read preference, you must - explicity pass it as an argument. The following code demonstrates how to - specify a read preference and use it with the - ``mongoc_client_command_simple()`` function: - - .. code-block:: c - - read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY); - - command = BCON_NEW("hello", BCON_INT32(1)); - - retval = mongoc_client_command_simple(client, "admin", command, - read_prefs, &reply, &error); - - For more information on read preference options, see :manual:`Read Preference - ` in the Server manual. - -Response --------- - -Each function returns either a BSON document or a cursor containing the response -from the database after the command runs. Each database command performs a -different function, so the response content can vary across commands. However, -every response contains documents with the following fields: - -- ````: Provides fields specific to the database command. For - example, ``count`` returns the ``n`` field and ``explain`` returns the - ``queryPlanner`` field. -- ``ok``: Indicates whether the command succeeded (``1``) or failed (``0``). - -Example -------- - -The following code shows how you can use the -``mongoc_client_write_command_with_opts()`` function to run the -``cloneCollectionAsCapped`` command with the ``writeConcern`` option. It then -uses the ``mongoc_client_read_command_with_opts()`` function to run the -``distinct`` command with the ``collation`` and ``readConcern`` options. - -.. literalinclude:: /includes/usage-examples/run-command.c - :language: c - :dedent: - :linenos: - :emphasize-lines: 17-20, 30, 46, 53-56 - :start-after: start-run-command-example - :end-before: end-run-command-example - -Output -~~~~~~ - -The ``cloneCollectionAsCapped`` command clones a collection as a capped -collection. Then, the ``distinct`` command gets the distinct values of a field -with a given filter and collation. The example outputs the following result: - -.. code-block:: c - - cloneCollectionAsCapped: { "ok": 1, ... } distinct: { "values": ["value1", - "value2", "value3"], "ok": 1, ... } - -.. _c-addl-info-runcommand: - -Additional Information ----------------------- - -For more information about the concepts in this guide, see the following -documentation: - -- :manual:`db.runCommand() ` -- :manual:`Database Commands ` -- :manual:`hello Command ` -- :manual:`cloneCollectionAsCapped Command - ` -- :manual:`distinct Command ` - -API Documentation -~~~~~~~~~~~~~~~~~ - -- `mongoc_client_command_simple() <{+api-libmongoc+}/mongoc_client_command_simple>`__ -- `mongoc_client_command_with_opts() <{+api-libmongoc+}/mongoc_client_command_with_opts>`__ -- `mongoc_client_write_command_with_opts() <{+api-libmongoc+}/mongoc_client_write_command_with_opts>`__ -- `mongoc_client_read_command_with_opts() <{+api-libmongoc+}/mongoc_client_read_command_with_opts>`__ \ No newline at end of file From 6bac982f9194dec35c60cb03222505fbf182a8ea Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 15 Oct 2024 13:52:52 -0400 Subject: [PATCH 06/11] run command --- source/databases-collections/run-command.txt | 183 +++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 source/databases-collections/run-command.txt diff --git a/source/databases-collections/run-command.txt b/source/databases-collections/run-command.txt new file mode 100644 index 00000000..75e3c124 --- /dev/null +++ b/source/databases-collections/run-command.txt @@ -0,0 +1,183 @@ +.. _c-run-command: + +====================== +Run a Database Command +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the C Driver to run a database command. + :keywords: command, server, usage, code example + +Overview +-------- + +In this guide, you can learn how to run a database command with the +{+driver-short+}. You can use database commands to perform a variety of +administrative and diagnostic tasks, such as fetching server statistics, +initializing a replica set, or running an aggregation pipeline. + +.. important:: Prefer Driver Functions to Database Commands + + The driver provides wrapper functions for many database commands. We recommend + using driver functions instead of executing database commands when possible. + + To perform administrative tasks, use the :mongosh:`MongoDB Shell ` instead + of the {+driver-short+}. Calling the ``db.runCommand()`` method inside the + shell is the preferred method to issue database commands, as it provides a + consistent interface between the shell and drivers. + +Execute a Command +----------------- + +To run a database command, you must specify the command and any relevant +parameters in a BSON document, then pass this BSON document to a command +execution function. The {+driver-short+} provides the following functions to run +database commands: + +- ``mongoc_client_command_simple()``, which runs a specified command on the + server and stores the first document from the result in the ``reply`` BSON + document. This function provides a simplified way to send a command directly + to the server. +- ``mongoc_client_command_with_opts()``, which runs a specified command on the + server and interprets ``opts`` according to the MongoDB server version. This + function offers flexibilty by allowing additional options. + +The following code shows how you can use the ``mongoc_client_command_simple()`` +function to run the ``hello`` command, which returns information about the current +member's role in the replica set, on a database: + +.. literalinclude:: /includes/usage-examples/run-command.c + :language: c + :dedent: + :start-after: start-execute-command + :end-before: end-execute-command + +For a full list of database commands and corresponding parameters, see the +:ref:`Additional Information ` section. + +Command Options +--------------- + +You can specify optional command behavior for the +``mongoc_client_command_with_opts()`` function. This function accepts a BSON +document for the ``opts`` parameter. + +You can pass a BSON document that specifies the following options: + +- ``readConcern`` +- ``writeConcern`` +- ``sessionId`` +- ``collation`` +- ``serverId`` + +To learn more about a command and the options that it accepts, locate the +command and follow the link in the :manual:`Database Commands +` section of the Server manual. + +The following code shows how to specify a ``grantRolesToUsers`` command with a +``majority`` write concern: + +.. literalinclude:: /includes/usage-examples/run-command.c + :language: c + :dedent: + :start-after: start-execute-command-with-options + :end-before: end-execute-command-with-options + +.. note:: Read Preference + + The ``mongoc_client_command_simple()`` and + ``mongoc_client_command_with_opts()`` functions ignore the read preference + setting you might have set on your client. By default, these functions use + the ``primary`` read preference. + + To specify a read preference other than the primary read preference, you must + explicity pass it as an argument. The following code demonstrates how to + specify a read preference and use it with the + ``mongoc_client_command_simple()`` function: + + .. code-block:: c + + read_prefs = mongoc_read_prefs_new(MONGOC_READ_SECONDARY); + + command = BCON_NEW("hello", BCON_INT32(1)); + + retval = mongoc_client_command_simple(client, "admin", command, + read_prefs, &reply, &error); + + For more information on read preference options, see :manual:`Read Preference + ` in the Server manual. + +Response +-------- + +Each function returns either a BSON document or a cursor containing the response +from the database after the command runs. Each database command performs a +different function, so the response content can vary across commands. However, +every response contains documents with the following fields: + +- ````: Provides fields specific to the database command. For + example, ``count`` returns the ``n`` field and ``explain`` returns the + ``queryPlanner`` field. +- ``ok``: Indicates whether the command succeeded (``1``) or failed (``0``). + +Example +------- + +The following code shows how you can use the +``mongoc_client_write_command_with_opts()`` function to run the +``cloneCollectionAsCapped`` command with the ``writeConcern`` option. It then +uses the ``mongoc_client_read_command_with_opts()`` function to run the +``distinct`` command with the ``collation`` and ``readConcern`` options. + +.. literalinclude:: /includes/usage-examples/run-command.c + :language: c + :dedent: + :linenos: + :emphasize-lines: 17-20, 30, 46, 53-56 + :start-after: start-run-command-example + :end-before: end-run-command-example + +Output +~~~~~~ + +The ``cloneCollectionAsCapped`` command clones a collection as a capped +collection. Then, the ``distinct`` command gets the distinct values of a field +with a given filter and collation. The example outputs the following result: + +.. code-block:: c + + cloneCollectionAsCapped: { "ok": 1, ... } distinct: { "values": ["value1", + "value2", "value3"], "ok": 1, ... } + +.. _c-addl-info-runcommand: + +Additional Information +---------------------- + +For more information about the concepts in this guide, see the following +documentation: + +- :manual:`db.runCommand() ` +- :manual:`Database Commands ` +- :manual:`hello Command ` +- :manual:`cloneCollectionAsCapped Command + ` +- :manual:`distinct Command ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +- `mongoc_client_command_simple() <{+api-libmongoc+}/mongoc_client_command_simple>`__ +- `mongoc_client_command_with_opts() <{+api-libmongoc+}/mongoc_client_command_with_opts>`__ +- `mongoc_client_write_command_with_opts() <{+api-libmongoc+}/mongoc_client_write_command_with_opts>`__ +- `mongoc_client_read_command_with_opts() <{+api-libmongoc+}/mongoc_client_read_command_with_opts>`__ \ No newline at end of file From 3d609d513601dee29251519da266b9ac84aad6c8 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 15 Oct 2024 16:37:44 -0400 Subject: [PATCH 07/11] MM feedback --- source/databases-collections/time-series.txt | 4 ++-- source/index.txt | 2 +- source/indexes.txt | 2 +- source/read.txt | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt index 3d09ca77..1ff79d3e 100644 --- a/source/databases-collections/time-series.txt +++ b/source/databases-collections/time-series.txt @@ -81,7 +81,7 @@ The following example creates a time series collection named ``october2024`` in :start-after: start-create-time-series :end-before: end-create-time-series :dedent: - :emphasize-lines: 13-19 + :emphasize-lines: 12-18 To verify that you successfully created the time series collection, run the ``mongoc_database_find_collections_with_opts()`` function on the @@ -95,7 +95,7 @@ the ``mongoc_database_find_collections_with_opts()`` function on the :start-after: start-list-collections :end-before: end-list-collections :dedent: - :emphasize-lines: 4-11 + :emphasize-lines: 2-9 .. output:: diff --git a/source/index.txt b/source/index.txt index ddb8f407..8c837e67 100644 --- a/source/index.txt +++ b/source/index.txt @@ -137,7 +137,7 @@ Learn what changes you might need to make to your application to upgrade driver :ref:`Upgrade Driver Versions ` section. Learn ------- +----- Visit the Developer Hub to learn more about the {+driver-long+}. diff --git a/source/indexes.txt b/source/indexes.txt index c65cb9fa..64ef4d22 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -49,7 +49,7 @@ the relevant values for your MongoDB deployment. :language: c :copyable: :linenos: - :emphasize-lines: 19-21 + :emphasize-lines: 17-19 Single Field Index ------------------ diff --git a/source/read.txt b/source/read.txt index 6c6503b9..191b88e3 100644 --- a/source/read.txt +++ b/source/read.txt @@ -55,7 +55,7 @@ the relevant values for your MongoDB deployment. :language: c :copyable: :linenos: - :emphasize-lines: 20-22 + :emphasize-lines: 18-20 .. tip:: From b7dd96a3aa1392ec9def1cd6ed2416fe5d958d00 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 16 Oct 2024 11:00:55 -0400 Subject: [PATCH 08/11] MW feedback --- source/compatibility.txt | 48 ++++++------ source/install-from-source.txt | 136 ++++++++++++++++++--------------- 2 files changed, 99 insertions(+), 85 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index 4d72c48f..7ddbfd19 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -65,19 +65,19 @@ The following operating systems are continually tested with the {+driver-short+} - Notes * - Debian - - Versions **9.2**, **10.0**, and **11.0** + - Versions 9.2, 10.0, and 11.0 * - RHEL - - Versions **7.0**, **7.1**, **8.1**, **8.2**, and **8.3**. RHEL derivatives - (e.g. CentOS, Rocky Linux, AlmaLinux) of the same release version are + - Versions 7.0, 7.1, 8.1, 8.2, and 8.3. RHEL derivatives + (for example, CentOS, Rocky Linux, or AlmaLinux) of the same release version are supported. Fedora is also supported, but not continually tested. * - Ubuntu - - Versions **16.04**, **18.04**, and **20.04**. Subsequent minor releases - are also supported. Ubuntu **22.04** and newer is not yet tested. Ubuntu + - Versions 16.04, 18.04, and 20.04. Subsequent minor releases + are also supported. Ubuntu 22.04 and newer is not yet tested. Ubuntu derivatives based on supported Ubuntu versions are also supported. * - Arch Linux - * - macOS - - Version **11.0** + - Version 11.0 * - Windows Server 2008 and Windows Server 2016 - Windows variants of the same generation are supported @@ -94,14 +94,14 @@ The following compilers are continually tested with the {+driver-short+}: * - Compiler - Notes * - Clang - - Versions **3.7**, **3.8**, and **6.0**. Newer versions + - Versions 3.7, 3.8, and 6.0. Newer versions are also supported, as well as the corresponding Apple Clang releases. - * - GCC - - Versions **4.8**, **5.4**, **6.3**, **7.5**, **8.2**, **8.3**, - **9.4**, and **10.2**. The MinGW-w64 GCC is also tested and supported. + * - Gnu Compiler Collection (GCC) + - Versions 4.8, 5.4, 6.3, 7.5, 8.2, 8.3, + 9.4, and 10.2. The MinGW-w64 GCC is also tested and supported. * - Microsoft Visual C++ (MSVC) - - Tested with MSVC **14.x** (Visual Studio **2015**) and **15.x** (Visual Studio - **2017**). Newer MSVC versions are supported but not yet tested. + - Tested with MSVC 14.x (Visual Studio 2015) and 15.x (Visual Studio + 2017). Newer MSVC versions are supported but not yet tested. Architectures ~~~~~~~~~~~~~ @@ -115,25 +115,27 @@ The following CPU architectures are continually tested with the {+driver-short+} * - Architecture - Notes * - x86 (32-bit) - - Only tested on Windows + - Tested only on Windows * - x86_64 (64-bit x86) - Tested on Linux, macOS, and Windows * - ARM / aarch64 - Tested on macOS and Linux * - Power8 (ppc64le) - - Only tested on Linux + - Tested only on Linux * - zSeries (s390x) - - Only tested on Linux + - Tested only on Linux Additional Platforms ~~~~~~~~~~~~~~~~~~~~ -Other platforms and toolchains are not tested, but similar versions of the above -platforms *should work*. If you encounter a platform or toolchain that you +Other platforms and toolchains are not tested, but we expect similar versions +of the preceding platforms to work. If you encounter a platform or toolchain that you expect to work and find that it does not, please open an issue describing the -problem, and/or open a `GitHub Pull Request `__ to fix it. - -Simple pull requests to fix unsupported platforms are welcome, but will be -considered on a case-by-case basis. The acceptance of a pull request to fix the -libraries on an unsupported platform does not imply full support of that -platform. \ No newline at end of file +problem, or open a `GitHub Pull Request `__ to fix it. + +.. important:: + + Simple pull requests to fix unsupported platforms are welcome, but will be + considered on a case-by-case basis. The acceptance of a pull request to fix the + libraries on an unsupported platform does not imply full support of that + platform. \ No newline at end of file diff --git a/source/install-from-source.txt b/source/install-from-source.txt index 6e9e739c..8dae2ae0 100644 --- a/source/install-from-source.txt +++ b/source/install-from-source.txt @@ -10,34 +10,34 @@ Building the C Driver Libraries from Source :depth: 2 :class: singlecol -This page details how to download, unpack, configure, and build ``libbson`` and -``libmongoc`` from their original source-code form. +This page details how to download, unpack, configure, and build the ``libbson`` and +``libmongoc`` libraries from their source code. .. tip:: Extra information - Dropdowns (like this one) contain extra information and explanatory details + Admonitions (like this one) contain extra information and explanatory details that are not required to complete the tutorial, but may be helpful for curious - readers, and more advanced users that want an explanation of the meaning of + readersx and more advanced users that want an explanation of the meaning of certain tutorial steps. -The following page uses a few named "variables" that you must decide up-front. -When you see such a value referenced in a tutorial step, you should substitute -the value into that step. +The following page uses a few named variables to represent configuration +information, such as $VERSION. You must choose values for these variables +before you start the tutorial. When you see a variable referenced in a +tutorial step, substitute your value in its place. .. seealso:: - Before building, you may want to check that you are running on a supported - platform. For the list of supported platforms, refer to :ref:`platform-support` - on the Compatibility page. - + Before you build the libraries, check that you are running on a supported + platform. For the list of supported platforms, refer to :ref:`platform-support` + on the Compatibility page. Choose a Version ---------------- -Before we begin, know what version of ``mongo-c-driver`` you will be downloading. +Before you begin, know what version of ``mongo-c-driver`` you will be downloading. A list of available versions can be found on `the GitHub repository tags page `__. -(The current version written for this documentation is {+full-version+}.) +(This tutorial documents the current driver version, v{+full-version+}.) For the remainder of this page, ``$VERSION`` will refer to the version number of ``mongo-c-driver`` that you will be building for this tutorial. @@ -48,14 +48,13 @@ For the remainder of this page, ``$VERSION`` will refer to the version number of Obtaining the Source -------------------- -There are two primary recommended methods of obtaining the ``mongo-c-driver`` -source code: +Obtain the ``mongo-c-driver`` source code in one of the following ways: -1. Clone the repository using ``git`` (recommended). - `(See below) `__ +- Clone the repository by using ``git`` (recommended). + `(See below) `__ -2. Download a source archive at a specific version. - `(See below) `__ +- Download a source archive at a specific version. + `(See below) `__ .. important:: @@ -69,10 +68,10 @@ source code: Downloading Using Git ~~~~~~~~~~~~~~~~~~~~~ -Using Git, the C driver repository can be cloned from the GitHub URL -https://github.com/mongodb/mongo-c-driver.git. Git tags for released versions -are named after the version for which they correspond (e.g. "{+full-version+}"). To -clone the repository using the command line, the following command may be used: +You can clone the C driver repository from :github:`GitHub ` +by using Git. Git tags for released versions are named after the version for which they +correspond (e.g. "{+full-version+}"). To clone the repository from the command line, +use the following command: .. code-block:: bash @@ -80,18 +79,18 @@ clone the repository using the command line, the following command may be used: .. tip:: - Despite the name, ``git-clone``'s ``--branch`` argument may also be used to - clone from repository *tags*. + Despite its name, you can use the ``--branch`` option of the ``git-clone`` command to + clone from repository tags. .. _learn.obtaining.archive: Downloading a Release Archive ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -An archived snapshot of the repository can be obtained from the -`GitHub Releases Page `__. -The ``mongo-c-driver-x.y.z.tar.gz`` archive attached to any release contains the -minimal set of files that you'll need for the build. +You can obtain an archived snapshot of the C driver repository from the repository's +:github:`Releases ` page. Every release includes a +``mongo-c-driver-x.y.z.tar.gz`` archive, which contains contains the minimal set of +files that you'll need for the build. .. tabs:: @@ -106,6 +105,11 @@ minimal set of files that you'll need for the build. ## Extract using tar: $ tar xf "mongo-c-driver-$VERSION.tar.gz" + The preceding commands create the ``mongo-c-driver-$VERSION`` directory + within the directory in which you ran them, which is the root of the driver + source tree. This documentation refers to this directory as ``$SOURCE``. + The ``$SOURCE`` directory contains the top-level ``CMakeLists.txt`` file. + .. tab:: Using ``curl`` + ``tar`` :tabid: curl-tar @@ -117,6 +121,11 @@ minimal set of files that you'll need for the build. ## Extract using tar: $ tar xf "mongo-c-driver-$VERSION.tar.gz" + The preceding commands create the ``mongo-c-driver-$VERSION`` directory + within the directory in which you ran them, which is the root of the driver + source tree. This documentation refers to this directory as ``$SOURCE``. + The ``$SOURCE`` directory contains the top-level ``CMakeLists.txt`` file. + .. tab:: PowerShell :tabid: powershell @@ -129,53 +138,56 @@ minimal set of files that you'll need for the build. ## Extract using Expand-Archive: PS> Expand-Archive mongo-c-driver-$VERSION.zip -The above commands will create a new directory ``mongo-c-driver-$VERSION`` within -the directory in which you ran the ``tar`` / ``Expand-Archive`` command (**note**: -PowerShell will create an additional intermediate subdirectory of the same -name). This directory is the root of the driver source tree (which we refer to -as ``$SOURCE`` in these documents). The ``$SOURCE`` directory should contain the -top-level ``CMakeLists.txt`` file. - + The preceding commands create the ``mongo-c-driver-$VERSION`` directory + within the directory in which you ran them. The ``mongo-c-driver-$VERSION`` directory + contains a second ``mongo-c-driver-$VERSION`` directory, which is the root of the driver + source tree. This documentation refers to this directory as ``$SOURCE``. + The ``$SOURCE`` directory contains the top-level ``CMakeLists.txt`` file. Obtaining Prerequisites ----------------------- -In order to build the project, a few prerequisites need to be available. +You must install `CMake `__ to configure the ``libmongoc`` and +``libbson`` projects. We highly recommended that you download the latest stable version of +CMake that is available for your platform. To download a new stable release of CMake, +visit the . -Both ``libmongoc`` and ``libbson`` projects use `CMake `__ for build configuration. +Select the tab corresponding to your operating system and follow the instructions +to download CMake: -.. note:: +.. tabs:: - It is *highly recommended* -- but not *required* -- that you download the - latest stable CMake available for your platform. + .. tab:: Windows or macOS + :tabid: windows-macos -.. tip:: Getting the Latest CMake - - A new stable release of CMake can be obtained from - `the CMake downloads page `__. + 1. Visit the `CMake downloads page `__. + + #. Download the CMake ``.msi`` or ``.dmg`` file and use it + to install CMake. - For Windows and macOS, simply download the CMake ``.msi`` / ``.dmg`` (not the - ``.zip`` / ``.tar.gz``) and use it to install CMake. + .. tab:: Linux + :tabid: linux - On Linux, download the self-extracting shell script (ending with ``.sh``) and - execute it using the ``sh`` utility, passing the appropriate arguments to - perform the install. For example, with the CMake 3.27.0 on the ``x86_64`` - platform, the following command can be used on the - ``cmake-3.27.0-linux-x86_64.sh`` script: + 1. Visit the `CMake downloads page `__ - .. code-block:: none + #. Download the self-extracting shell script, which ends with ``.sh``. + + #. Execute the script by using the ``sh`` utility and passing the appropriate + arguments to perform the install. For example, with the CMake 3.27.0 on the ``x86_64`` + platform, run the following command: - $ sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license + .. code-block:: none - Assuming that ``$HOME/.local/bin`` is on your ``$PATH`` list, the ``cmake`` command - for 3.27.0 will then become available. - - The ``--help`` option can be passed to the shell script for more information. + sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license + + Assuming that ``$HOME/.local/bin`` is on your ``$PATH`` list, the ``cmake`` command + for 3.27.0 will then become available. + + The ``--help`` option can be passed to the shell script for more information. -For the remainder of this page, it will be assumed that ``cmake`` is available as -a command on your ``PATH`` environment variable and can be executed as "``cmake``" -from a shell. You can test this by requesting the ``--version`` from CMake from -the command line: +This page assumes that ``cmake`` is available as a command on your ``PATH`` environment +variable and can be executed as "``cmake``" from a shell. You can test this by requesting +the ``--version`` from CMake from the command line: .. code-block:: none From 0b1714a459b1fe1692dc33e58bcd54fab8cd1f71 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 16 Oct 2024 11:08:45 -0400 Subject: [PATCH 09/11] edits --- source/install-from-source.txt | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/source/install-from-source.txt b/source/install-from-source.txt index 8dae2ae0..21c8b57a 100644 --- a/source/install-from-source.txt +++ b/source/install-from-source.txt @@ -21,7 +21,7 @@ This page details how to download, unpack, configure, and build the ``libbson`` certain tutorial steps. The following page uses a few named variables to represent configuration -information, such as $VERSION. You must choose values for these variables +information, such as ``$VERSION``. You must choose values for these variables before you start the tutorial. When you see a variable referenced in a tutorial step, substitute your value in its place. @@ -37,7 +37,7 @@ Choose a Version Before you begin, know what version of ``mongo-c-driver`` you will be downloading. A list of available versions can be found on `the GitHub repository tags page `__. -(This tutorial documents the current driver version, v{+full-version+}.) +This tutorial documents the current driver version, v{+full-version+}. For the remainder of this page, ``$VERSION`` will refer to the version number of ``mongo-c-driver`` that you will be building for this tutorial. @@ -51,10 +51,10 @@ Obtaining the Source Obtain the ``mongo-c-driver`` source code in one of the following ways: - Clone the repository by using ``git`` (recommended). - `(See below) `__ + For more information, see :ref:`learn.obtaining.git`. - Download a source archive at a specific version. - `(See below) `__ + For more information, see :ref:`learn.obtaining.archive`. .. important:: @@ -149,8 +149,7 @@ Obtaining Prerequisites You must install `CMake `__ to configure the ``libmongoc`` and ``libbson`` projects. We highly recommended that you download the latest stable version of -CMake that is available for your platform. To download a new stable release of CMake, -visit the . +CMake that is available for your platform. Select the tab corresponding to your operating system and follow the instructions to download CMake: @@ -187,11 +186,11 @@ to download CMake: This page assumes that ``cmake`` is available as a command on your ``PATH`` environment variable and can be executed as "``cmake``" from a shell. You can test this by requesting -the ``--version`` from CMake from the command line: +the ``--version`` from CMake from the command line, as shown in the following code: .. code-block:: none - $ cmake --version + cmake --version cmake version 3.21.4 CMake suite maintained and supported by Kitware (kitware.com/cmake). From 4ad54cdc9dc7afa7227d1cd5a231ff4626c56674 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 16 Oct 2024 13:09:23 -0400 Subject: [PATCH 10/11] MW feedback 2 --- source/compatibility.txt | 2 +- source/install-from-source.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/compatibility.txt b/source/compatibility.txt index 7ddbfd19..c73aae55 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -96,7 +96,7 @@ The following compilers are continually tested with the {+driver-short+}: * - Clang - Versions 3.7, 3.8, and 6.0. Newer versions are also supported, as well as the corresponding Apple Clang releases. - * - Gnu Compiler Collection (GCC) + * - GNU Compiler Collection (GCC) - Versions 4.8, 5.4, 6.3, 7.5, 8.2, 8.3, 9.4, and 10.2. The MinGW-w64 GCC is also tested and supported. * - Microsoft Visual C++ (MSVC) diff --git a/source/install-from-source.txt b/source/install-from-source.txt index 21c8b57a..ecdd01b1 100644 --- a/source/install-from-source.txt +++ b/source/install-from-source.txt @@ -17,7 +17,7 @@ This page details how to download, unpack, configure, and build the ``libbson`` Admonitions (like this one) contain extra information and explanatory details that are not required to complete the tutorial, but may be helpful for curious - readersx and more advanced users that want an explanation of the meaning of + readers and more advanced users that want an explanation of the meaning of certain tutorial steps. The following page uses a few named variables to represent configuration From e1de10704031f11e260faebcfe24766faffc55a7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 16 Oct 2024 13:10:53 -0400 Subject: [PATCH 11/11] landing page --- source/index.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/index.txt b/source/index.txt index 8c837e67..a487e2cf 100644 --- a/source/index.txt +++ b/source/index.txt @@ -50,12 +50,6 @@ Databases and Collections Learn how to use the {+driver-short+} to work with MongoDB databases and collections in the :ref:`c-databases-collections` section. -What's New ----------- - -For a list of new features and changes in each version, see the :ref:`What's New ` -section. - Write Data to MongoDB --------------------- @@ -124,6 +118,12 @@ Learn how to configure read and write operations on a replica set in the .. Learn how to report bugs, contribute to the driver, and find more resources for .. asking questions and receiving help in the :ref:`Issues & Help ` section. +What's New +---------- + +For a list of new features and changes in each version, see the :ref:`What's New ` +section. + Compatibility -------------