diff --git a/snooty.toml b/snooty.toml index 17aedb31..3b4b530c 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,14 +1,13 @@ name = "c" title = "C Driver" -intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", - "https://www.mongodb.com/docs/atlas/objects.inv", - "https://www.mongodb.com/docs/drivers/objects.inv", - ] - -toc_landing_pages = [ - "/read" +intersphinx = [ + "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/atlas/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", ] + +toc_landing_pages = ["/read", "/get-started"] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" [constants] @@ -26,3 +25,5 @@ driver-short = "C driver" language = "C" mdb-server = "MongoDB Server" stable-api = "Stable API" +libmongoc = "libmongoc" +libbson = "libbson" diff --git a/source/get-started.txt b/source/get-started.txt new file mode 100644 index 00000000..812efb9b --- /dev/null +++ b/source/get-started.txt @@ -0,0 +1,45 @@ +.. _c-get-started: + +============================= +Get Started with the {+driver-short+} +============================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. meta:: + :description: Learn how to create an app to connect to MongoDB deployment by using the C driver. + :keywords: quick start, tutorial, basics + +.. toctree:: + + /get-started/download-and-install/ + /get-started/create-a-deployment/ + /get-started/create-a-connection-string/ + /get-started/connect-to-mongodb/ + /get-started/next-steps/ + +Overview +-------- + +The {+driver-long+} is a {+language+} library that you can use to connect to MongoDB and +interact with data stored in your deployment. This guide shows you how to create an +application that uses the {+driver-short+} to connect to a MongoDB cluster hosted on +MongoDB Atlas and query data in your cluster. + +.. tip:: + + MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB + deployments. You can create your own free (no credit card required) MongoDB Atlas + deployment by following the steps in this guide. + +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 diff --git a/source/get-started/connect-to-mongodb.txt b/source/get-started/connect-to-mongodb.txt new file mode 100644 index 00000000..3cb77210 --- /dev/null +++ b/source/get-started/connect-to-mongodb.txt @@ -0,0 +1,5 @@ +.. _c-get-started-connect-to-mongodb: + +================== +Connect to MongoDB +================== \ No newline at end of file diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt new file mode 100644 index 00000000..57fbc52c --- /dev/null +++ b/source/get-started/create-a-connection-string.txt @@ -0,0 +1,5 @@ +.. _c-get-started-connection-string: + +========================== +Create a Connection String +========================== \ No newline at end of file diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt new file mode 100644 index 00000000..c0b4cfb3 --- /dev/null +++ b/source/get-started/create-a-deployment.txt @@ -0,0 +1,5 @@ +.. _c-get-started-create-deployment: + +=========================== +Create a MongoDB Deployment +=========================== \ No newline at end of file diff --git a/source/get-started/download-and-install.txt b/source/get-started/download-and-install.txt new file mode 100644 index 00000000..2631ee60 --- /dev/null +++ b/source/get-started/download-and-install.txt @@ -0,0 +1,215 @@ +.. _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. +.. TODO: To learn how to install the driver from source, see the 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 <https://www.centos.org/>`__ + - `Rocky Linux <https://rockylinux.org/>`__ + - `AlmaLinux <https://almalinux.org/>`__ + + 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 <c-redhat-install>` + 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 <https://vcpkg.io>`__. + + .. tip:: + + To learn how to get started with vcpkg, see the `vcpkg Get Started + guide <https://learn.microsoft.com/en-us/vcpkg/get_started/overview>`__ + in the Microsoft documentation. + + In `vcpkg manifest mode <https://learn.microsoft.com/en-us/vcpkg/users/manifests>`__, 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 <https://learn.microsoft.com/en-us/vcpkg/users/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 $<IF:$<TARGET_EXISTS:mongo::mongoc_shared>,mongo::mongoc_shared,mongo::mongoc_static>) + + .. note:: + + You can use the ``$<IF:$<TARGET_EXISTS...>:...>`` 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 <https://brew.sh/>`__. To do so, run the following command in + your shell: + + .. code-block:: bash + + 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. + +.. 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 new file mode 100644 index 00000000..a6adfd0f --- /dev/null +++ b/source/get-started/next-steps.txt @@ -0,0 +1,5 @@ +.. _c-get-started-next-steps: + +========== +Next Steps +========== \ No newline at end of file diff --git a/source/includes/get-started/troubleshoot.rst b/source/includes/get-started/troubleshoot.rst new file mode 100644 index 00000000..14980b3d --- /dev/null +++ b/source/includes/get-started/troubleshoot.rst @@ -0,0 +1,6 @@ +.. note:: + + If you run into issues on this step, ask for help in the + :community-forum:`MongoDB Community Forums <tag/c/>` + 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 diff --git a/source/index.txt b/source/index.txt index 51904a24..40baf7bd 100644 --- a/source/index.txt +++ b/source/index.txt @@ -6,6 +6,7 @@ :titlesonly: :maxdepth: 1 + /get-started /databases-collections /read libbson API Documentation <{+api-libbson+}> @@ -21,12 +22,11 @@ the official MongoDB driver for {+language+} applications. .. ``libmongoc`` depends on the ``libbson`` library. To learn more about ``libbson``, see .. <BSON guide link>. -.. TODO -.. Get Started -.. ----------- +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. +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