diff --git a/snooty.toml b/snooty.toml index 4883edcf..8ab1a1f2 100644 --- a/snooty.toml +++ b/snooty.toml @@ -10,7 +10,6 @@ intersphinx = [ toc_landing_pages = [ "/databases-collections", "/read", - "/get-started", "/indexes", "/work-with-indexes", "/connect", diff --git a/source/get-started.txt b/source/get-started.txt index 04aeb662..686c5d10 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -18,14 +18,6 @@ Get Started with the C Driver :description: Learn how to create an app to connect to MongoDB deployment by using the C driver. :keywords: quick start, tutorial, basics -.. toctree:: - - Download & Install - Create a Deployment - Create a Connection String - Connect to MongoDB - Next Steps - Overview -------- @@ -42,4 +34,408 @@ MongoDB Atlas and query data in your cluster. Follow this guide to connect a sample {+language+} application to a MongoDB Atlas deployment. If you prefer to connect to MongoDB using a different driver or -programming language, see our :driver:`list of official drivers <>`. \ No newline at end of file +programming language, see our :driver:`list of official drivers <>`. + +.. _c-get-started-download-and-install: + +Download and Install +-------------------- + +Download the C Driver +~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} consists of two libraries: ``libbson`` and +``libmongoc``. In this guide, you will learn how to install ``libmongoc``, +which comes bundled with ``libbson``. + +You can install the {+driver-short+} by using +a package manager, or by installing the libraries from source. Different Linux +distributions install different versions of the driver when installed with a +package manager. Because of this, you should check the version your distribution +includes before installing the driver. + +On RedHat Enterprise Linux (RHEL) distributions, you can check the version by +running the following command in your shell: + +.. code-block:: bash + + sudo dnf info mongo-c-driver-devel + +On Debian-based distributions, you can check the version by running the +following command in your shell: + +.. code-block:: bash + + 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. 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: + +.. tabs:: + + .. tab:: Linux + :tabid: install-linux + + .. _c-redhat-install: + + RedHat Enterprise Linux Distributions + `````````````````````````````````````` + + You can install the driver on RedHat Enterprise Linux (RHEL) + distributions, version 7 or later, or distributions based on RHEL, + such as: + + - `CentOS `__ + - `Rocky Linux `__ + - `AlmaLinux `__ + + Before you install the driver on a RHEL distribution, not including + Fedora, you must first enable the Extra Packages for Enterprise + Linux (EPEL) repository. You can enable the EPEL repository by + installing the ``epel-release`` package, as shown in the following + example: + + .. code-block:: bash + + yum install epel-release + + Then, you can install the {+driver-short+} + by using ``yum``. To do so, run the following command in + your shell: + + .. code-block:: bash + + yum install mongo-c-driver-devel + + .. note:: Developer Packages + + The preceding code example installs the developer packages, which + are required to build applications that use the {+driver-short+}. To + install only the libraries, without development files, run the + following command: + + .. code-block:: bash + + yum install mongo-c-driver + + If you are installing on a RHEL distribution that is version 8 or + later, we recommend running the preceding code examples by using + ``dnf`` instead of ``yum``. + + Fedora + `````` + + If you are using Fedora or an enterprise Linux distribution of + version 8 or later, you can install the driver by using the same + commands as shown in the :ref:`preceding example ` + and replacing ``yum`` with ``dnf``. + + The following example shows how to install the {+driver-short+} in a + Fedora distribution: + + .. code-block:: bash + + dnf install mongo-c-driver-devel + + Debian-Based Distributions + `````````````````````````` + + In Debian-Based Linux distributions, including Ubuntu and Ubuntu + derivatives, the driver libraries are available through the Advanced + Packaging Tool (APT). You can install the driver with APT by running + the following command in your shell: + + .. code-block:: bash + + apt install libmongoc-dev + + The preceding code example installs the developer packages, which + are required to build applications that use the {+driver-short+}. To + install only the libraries, without development files, run the + following command: + + .. code-block:: bash + + apt install libmongoc-1.0-0 + + .. tab:: Windows + :tabid: install-windows + + For Windows environments, we recommend building the {+driver-short+} + libraries from source to ensure maximum compatibility with the local + toolchain. You can automate building from source by using a + from-source library package management tool, such as + `vcpkg `__. + + .. tip:: + + To learn how to get started with vcpkg, see the `vcpkg Get Started + guide `__ + in the Microsoft documentation. + + In `vcpkg manifest mode `__, add the + driver library to your project's ``vcpkg.json`` manifest file, + as shown in the following example: + + .. code-block:: js + + { + // ... + "dependencies": [ + // ... + "mongo-c-driver" + ] + } + + When you build a CMake project with vcpkg integration and have a + ``vcpkg.json`` manifest file, vcpkg automatically installs the project's + dependencies before proceeding with configuration. + + If you are using `vcpkg classic mode `__, + you can install the driver by running the following command in + your shell: + + .. code-block:: bash + + vcpkg install mongo-c-driver + + After you install the driver, the standard CMake configuration file + is available, as well as the generated ``IMPORTED`` targets. You can + create a ``CMakeLists.txt`` file as shown in the following example: + + .. code-block:: cmake + + find_package(mongoc-1.0 CONFIG REQUIRED) + target_link_libraries(my-application + PRIVATE $,mongo::mongoc_shared,mongo::mongoc_static>) + + .. note:: + + You can use the ``$:...>`` generator + expression in the preceding example to switch the link type of + ``libmongoc`` based on the form that is available from the + ``find_package()`` command. ``libmongoc`` supports building with + both *dynamic* and *static* library types, but vcpkg + installs only one type at a time. + + To configure the CMake project with vcpkg integration, set the CMake + toolchain file in the configuration command by running the following + commands in your shell: + + .. code-block:: bash + + cmake -S . -B _build -D + CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake + + .. tab:: MacOS + :tabid: install-mac + + You can download the {+driver-short+} on MacOS by using the `Homebrew + package manager `__. To do so, run the following command in + your shell: + + .. code-block:: bash + + brew install mongo-c-driver + +After you complete these steps, you have the {+driver-short+} installed +on your machine. + +.. _c-get-started-create-deployment: + +Create a MongoDB Deployment +--------------------------- + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a Free MongoDB deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your Credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +into your database. + + +.. _c-get-started-connection-string: + +Create a Connection String +-------------------------- + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +To connect to an instance or deployment not hosted on Atlas, see the +:ref:`c-connection-targets` guide. + +.. procedure:: + :style: connected + + .. step:: Find Your MongoDB Atlas Connection String + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log in to your Atlas account and navigate to the + :guilabel:`Database` section and click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_select_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Proceed to the :guilabel:`Connect your application` section and select + "C" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + Select the :guilabel:`Password (SCRAM)` authentication mechanism. + + Deselect the :guilabel:`Include full driver code example` option to view + only the connection string. + + .. step:: Copy Your Connection String + + Click the button on the right of the connection string to copy it + to your clipboard, as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_copy_c.png + :alt: The copy button next to the connection string in the Atlas UI + + .. step:: Update the Placeholders + + Paste this connection string into a file in your preferred text editor and + replace the ```` and ```` placeholders with your + database user's username and password. + + Save this file to a safe location for use in the next step. + +After completing these steps, you have a connection string that +corresponds to your Atlas cluster. + +.. _c-get-started-connect-to-mongodb: + +Run a Sample Query +------------------ + +.. step:: Create a Project Directory + + In your shell, navigate to where you want to create your + application, then run the following command to create a + directory called ``c-quickstart`` for this project: + + .. code-block:: bash + + mkdir c-quickstart + + 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: + + .. 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 + type nul > quickstart.c + +.. step:: Create Your C Driver Application + + 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 + :language: c + +.. step:: Assign the Connection String + + Replace the ```` placeholder with the + connection string that you copied from the :ref:`c-get-started-connection-string` + step of this guide. + +.. step:: Run Your C Application + + In your shell, run the following commands to compile and run this application: + + .. code-block:: none + + gcc -o quickstartc quickstart.c $(pkg-config --libs --cflags libmongoc-1.0) + ./quickstartc + + The command line output contains details about the retrieved movie + document: + + .. code-block:: none + :copyable: false + + { "_id" : { "$oid" : "..." }, + "plot" : "Two imprisoned men bond over a number of years, finding solace + and eventual redemption through acts of common decency.", + ... + "title" : "The Shawshank Redemption", + ... + + If you encounter an error or see no output, ensure that you specified the + proper connection string in the ``quickstart.c`` file and that you loaded the + sample data. + +After you complete these steps, you have a working application that +uses the driver to connect to your MongoDB deployment, runs a query on +the sample data, and prints out the result. + +.. _c-get-started-next-steps: + +Next Steps +---------- + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: learn more + +Congratulations on completing the quick start tutorial! + +.. include:: /includes/get-started/troubleshoot.rst + +In this tutorial, you created a C application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about the {+driver-short+} from the following resources: + +- Learn how to perform read operations in the :ref:`` section. + +- Learn how to perform write operations in the :ref:`` section. diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt deleted file mode 100644 index 0ab8aaa1..00000000 --- a/source/get-started/connect-to-mongodb.txt +++ /dev/null @@ -1,93 +0,0 @@ -.. _c-get-started-connect-to-mongodb: - -================== -Connect to MongoDB -================== - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: test connection, runnable, code example - -.. procedure:: - :style: connected - - .. step:: Create a project directory - - In your shell, navigate to where you want to create your - application, then run the following command to create a - directory called ``c-quickstart`` for this project: - - .. code-block:: bash - - mkdir c-quickstart - - 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: - - .. 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 - type nul > quickstart.c - - .. step:: Create your {+driver-short+} application - - 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 - :language: c - - .. step:: Assign the connection string - - Replace the ```` placeholder with the - connection string that you copied from the :ref:`c-get-started-connection-string` - step of this guide. - - .. step:: Run your C application - - In your shell, run the following commands to compile and run this application: - - .. code-block:: none - - gcc -o quickstartc quickstart.c $(pkg-config --libs --cflags libmongoc-1.0) - ./quickstartc - - The command line output contains details about the retrieved movie - document: - - .. code-block:: none - :copyable: false - - { "_id" : { "$oid" : "..." }, - "plot" : "Two imprisoned men bond over a number of years, finding solace - and eventual redemption through acts of common decency.", - ... - "title" : "The Shawshank Redemption", - ... - - If you encounter an error or see no output, ensure that you specified the - proper connection string in the ``quickstart.c`` file and that you loaded the - sample data. - -After you complete these steps, you have a working application that -uses the driver to connect to your MongoDB deployment, runs a query on -the sample data, and prints out the result. - -.. include:: /includes/get-started/troubleshoot.rst diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt deleted file mode 100644 index 5fb6cabe..00000000 --- a/source/get-started/create-a-connection-string.txt +++ /dev/null @@ -1,62 +0,0 @@ -.. _c-get-started-connection-string: - -========================== -Create a Connection String -========================== - -You can connect to your MongoDB deployment by providing a -**connection URI**, also called a *connection string*, which -instructs the driver on how to connect to a MongoDB deployment -and how to behave while connected. - -The connection string includes the hostname or IP address and -port of your deployment, the authentication mechanism, user credentials -when applicable, and connection options. - -To connect to an instance or deployment not hosted on Atlas, see the -:ref:`c-connection-targets` guide. - -.. procedure:: - :style: connected - - .. step:: Find your MongoDB Atlas Connection String - - To retrieve your connection string for the deployment that - you created in the :ref:`previous step `, - log in to your Atlas account and navigate to the - :guilabel:`Database` section and click the :guilabel:`Connect` button - for your new deployment. - - .. figure:: /includes/figures/atlas_connection_select_cluster.png - :alt: The connect button in the clusters section of the Atlas UI - - Proceed to the :guilabel:`Connect your application` section and select - "C" from the :guilabel:`Driver` selection menu and the version - that best matches the version you installed from the :guilabel:`Version` - selection menu. - - Select the :guilabel:`Password (SCRAM)` authentication mechanism. - - Deselect the :guilabel:`Include full driver code example` option to view - only the connection string. - - .. step:: Copy your Connection String - - Click the button on the right of the connection string to copy it - to your clipboard, as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_copy_c.png - :alt: The copy button next to the connection string in the Atlas UI - - .. step:: Update the Placeholders - - Paste this connection string into a file in your preferred text editor and - replace the ```` and ```` placeholders with your - database user's username and password. - - Save this file to a safe location for use in the next step. - -After completing these steps, you have a connection string that -corresponds to your Atlas cluster. - -.. include:: /includes/get-started/troubleshoot.rst diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt deleted file mode 100644 index a26a169f..00000000 --- a/source/get-started/create-a-deployment.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _c-get-started-create-deployment: - -=========================== -Create a MongoDB Deployment -=========================== - -You can create a free tier MongoDB deployment on MongoDB Atlas -to store and manage your data. MongoDB Atlas hosts and manages -your MongoDB database in the cloud. - -.. procedure:: - :style: connected - - .. step:: Create a Free MongoDB deployment on Atlas - - Complete the :atlas:`Get Started with Atlas ` - guide to set up a new Atlas account and load sample data into a new free - tier MongoDB deployment. - - .. step:: Save your Credentials - - After you create your database user, save that user's - username and password to a safe location for use in an upcoming step. - -After you complete these steps, you have a new free tier MongoDB -deployment on Atlas, database user credentials, and sample data loaded -into your database. - -.. include:: /includes/get-started/troubleshoot.rst diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt deleted file mode 100644 index f0489042..00000000 --- a/source/get-started/download-and-install.txt +++ /dev/null @@ -1,211 +0,0 @@ -.. _c-get-started-download-and-install: - -==================== -Download and Install -==================== - -Download the {+driver-short+} ----------------------- - -The {+driver-short+} consists of two libraries: ``libbson`` and -``libmongoc``. In this guide, you will learn how to install ``libmongoc``, -which comes bundled with ``libbson``. - -You can install the {+driver-short+} by using -a package manager, or by installing the libraries from source. Different Linux -distributions install different versions of the driver when installed with a -package manager. Because of this, you should check the version your distribution -includes before installing the driver. - -On RedHat Enterprise Linux (RHEL) distributions, you can check the version by -running the following command in your shell: - -.. code-block:: bash - - sudo dnf info mongo-c-driver-devel - -On Debian-based distributions, you can check the version by running the -following command in your shell: - -.. code-block:: bash - - 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. 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: - -.. tabs:: - - .. tab:: Linux - :tabid: install-linux - - .. _c-redhat-install: - - RedHat Enterprise Linux Distributions - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - You can install the driver on RedHat Enterprise Linux (RHEL) - distributions, version 7 or later, or distributions based on RHEL, - such as: - - - `CentOS `__ - - `Rocky Linux `__ - - `AlmaLinux `__ - - Before you install the driver on a RHEL distribution, not including - Fedora, you must first enable the Extra Packages for Enterprise - Linux (EPEL) repository. You can enable the EPEL repository by - installing the ``epel-release`` package, as shown in the following - example: - - .. code-block:: bash - - yum install epel-release - - Then, you can install the {+driver-short+} - by using ``yum``. To do so, run the following command in - your shell: - - .. code-block:: bash - - yum install mongo-c-driver-devel - - .. note:: Developer Packages - - The preceding code example installs the developer packages, which - are required to build applications that use the {+driver-short+}. To - install only the libraries, without development files, run the - following command: - - .. code-block:: bash - - yum install mongo-c-driver - - If you are installing on a RHEL distribution that is version 8 or - later, we recommend running the preceding code examples by using - ``dnf`` instead of ``yum``. - - Fedora - ~~~~~~ - - If you are using Fedora or an enterprise Linux distribution of - version 8 or later, you can install the driver by using the same - commands as shown in the :ref:`preceding example ` - and replacing ``yum`` with ``dnf``. - - The following example shows how to install the {+driver-short+} in a - Fedora distribution: - - .. code-block:: bash - - dnf install mongo-c-driver-devel - - Debian-Based Distributions - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - - In Debian-Based Linux distributions, including Ubuntu and Ubuntu - derivatives, the driver libraries are available through the Advanced - Packaging Tool (APT). You can install the driver with APT by running - the following command in your shell: - - .. code-block:: bash - - apt install libmongoc-dev - - The preceding code example installs the developer packages, which - are required to build applications that use the {+driver-short+}. To - install only the libraries, without development files, run the - following command: - - .. code-block:: bash - - apt install libmongoc-1.0-0 - - .. tab:: Windows - :tabid: install-windows - - For Windows environments, we recommend building the {+driver-short+} - libraries from source to ensure maximum compatibility with the local - toolchain. You can automate building from source by using a - from-source library package management tool, such as - `vcpkg `__. - - .. tip:: - - To learn how to get started with vcpkg, see the `vcpkg Get Started - guide `__ - in the Microsoft documentation. - - In `vcpkg manifest mode `__, add the - driver library to your project's ``vcpkg.json`` manifest file, - as shown in the following example: - - .. code-block:: js - - { - // ... - "dependencies": [ - // ... - "mongo-c-driver" - ] - } - - When you build a CMake project with vcpkg integration and have a - ``vcpkg.json`` manifest file, vcpkg automatically installs the project's - dependencies before proceeding with configuration. - - If you are using `vcpkg classic mode `__, - you can install the driver by running the following command in - your shell: - - .. code-block:: bash - - vcpkg install mongo-c-driver - - After you install the driver, the standard CMake configuration file - is available, as well as the generated ``IMPORTED`` targets. You can - create a ``CMakeLists.txt`` file as shown in the following example: - - .. code-block:: cmake - - find_package(mongoc-1.0 CONFIG REQUIRED) - target_link_libraries(my-application - PRIVATE $,mongo::mongoc_shared,mongo::mongoc_static>) - - .. note:: - - You can use the ``$:...>`` generator - expression in the preceding example to switch the link type of - ``libmongoc`` based on the form that is available from the - ``find_package()`` command. ``libmongoc`` supports building with - both *dynamic* and *static* library types, but vcpkg - installs only one type at a time. - - To configure the CMake project with vcpkg integration, set the CMake - toolchain file in the configuration command by running the following - commands in your shell: - - .. code-block:: bash - - cmake -S . -B _build -D - CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake - - .. tab:: MacOS - :tabid: install-mac - - You can download the {+driver-short+} on MacOS by using the `Homebrew - package manager `__. To do so, run the following command in - your shell: - - .. code-block:: bash - - brew install mongo-c-driver - -After you complete these steps, you have the {+driver-short+} installed -on your machine. - -.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/next-steps.txt b/source/get-started/next-steps.txt deleted file mode 100644 index 0391efa6..00000000 --- a/source/get-started/next-steps.txt +++ /dev/null @@ -1,24 +0,0 @@ -.. _c-get-started-next-steps: - -========== -Next Steps -========== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: learn more - -Congratulations on completing the quick start tutorial! - -In this tutorial, you created a C application that -connects to a MongoDB deployment hosted on MongoDB Atlas -and retrieves a document that matches a query. - -Learn more about the {+driver-short+} from the following resources: - -- Learn how to perform read operations in the :ref:`` section. - -.. - Learn how to perform write operations in the :ref:`` section. diff --git a/source/includes/get-started/troubleshoot.rst b/source/includes/get-started/troubleshoot.rst index 14980b3d..e44cbbc8 100644 --- a/source/includes/get-started/troubleshoot.rst +++ b/source/includes/get-started/troubleshoot.rst @@ -1,6 +1,6 @@ .. note:: - If you run into issues on this step, ask for help in the + If you run into issues in this tutorial, ask for help in the :community-forum:`MongoDB Community Forums ` or submit feedback by using the :guilabel:`Rate this page` tab on the right or bottom right side of this page. \ No newline at end of file