Skip to content

Commit 3a26253

Browse files
rachel-mackrachel-mack
committed
get started
1 parent 58970c4 commit 3a26253

8 files changed

+307
-328
lines changed

‎snooty.toml

-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ intersphinx = [
99

1010
toc_landing_pages = [
1111
"/api-abi-versioning",
12-
"/get-started",
1312
"/connect",
1413
"/read",
1514
"/write",

‎source/get-started.txt

+306-9
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,6 @@ Get Started with the C++ Driver
1818
:description: Learn how to create an app to connect to MongoDB deployment by using the C++ driver.
1919
:keywords: quick start, tutorial, basics
2020

21-
.. toctree::
22-
23-
Download & Install </get-started/download-and-install/>
24-
Create a Deployment </get-started/create-a-deployment/>
25-
Create a Connection String </get-started/create-a-connection-string/>
26-
Connect to MongoDB </get-started/connect-to-mongodb/>
27-
Next Steps </get-started/next-steps/>
28-
2921
Overview
3022
--------
3123

@@ -42,4 +34,309 @@ MongoDB Atlas and query data in your cluster.
4234

4335
Follow this guide to connect a sample C++ application to a MongoDB Atlas
4436
deployment. If you prefer to connect to MongoDB using a different driver or
45-
programming language, see our :driver:`list of official drivers <>`.
37+
programming language, see our :driver:`list of official drivers <>`.
38+
39+
.. _cpp-quick-start-download-and-install:
40+
41+
Download and Install
42+
--------------------
43+
44+
.. procedure::
45+
:style: connected
46+
47+
.. step:: Install dependencies
48+
49+
Before you begin this tutorial, ensure you have the following dependencies
50+
installed in your development environment:
51+
52+
- Compiler that supports C++17, such as `GCC <https://gcc.gnu.org/install/>`__, `Clang <https://clang.llvm.org/>`__,
53+
or `Visual Studio <https://visualstudio.microsoft.com/>`__
54+
- `CMake <https://cmake.org/>`__ v3.15 or later
55+
- `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`__
56+
57+
.. note:: Pre-C++17 Configurations
58+
59+
Although C++11 is the minimum supported language version, this tutorial
60+
configures the {+driver-short+} to use the C++17 standard library
61+
as recommended by the :ref:`cpp-polyfill-config` section. If you want to install
62+
the driver for pre-C++17 configurations, set the ``CMAKE_CXX_STANDARD``
63+
configuration option to your C++ version. Then, the driver will automatically use
64+
bsoncxx library polyfill implementations for required C++17 features.
65+
66+
.. step:: Download the {+driver-short+}
67+
68+
To download the latest version of the {+driver-short+} from the ``mongo-cxx-driver`` Github
69+
repository, run the following commands in your shell from your root directory:
70+
71+
.. code-block:: bash
72+
73+
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r{+full-version+}/mongo-cxx-driver-r{+full-version+}.tar.gz
74+
tar -xzf mongo-cxx-driver-r{+full-version+}.tar.gz
75+
cd mongo-cxx-driver-r{+full-version+}/build
76+
77+
.. step:: Configure the driver for installation
78+
79+
Select the tab corresponding to your operating system and run following command from your
80+
``mongo-cxx-driver-r{+full-version+}/build`` directory:
81+
82+
.. tabs::
83+
84+
.. tab:: macOS / Linux
85+
:tabid: configure-mac-linux
86+
87+
.. code-block:: bash
88+
89+
cmake .. \
90+
-DCMAKE_BUILD_TYPE=Release \
91+
-DCMAKE_CXX_STANDARD=17
92+
93+
This command instructs CMake to install ``mongocxx`` into the ``/usr/local`` directory.
94+
95+
.. tab:: Windows
96+
:tabid: configure-windows
97+
98+
.. code-block:: bash
99+
100+
'C:\<path>\cmake.exe' .. \
101+
-G "Visual Studio <version> <year>" -A "x64" \
102+
-DCMAKE_CXX_STANDARD=17 \
103+
-DCMAKE_INSTALL_PREFIX=C:\mongo-cxx-driver \
104+
105+
This command instructs CMake to install ``mongocxx`` into the ``C:\mongo-cxx-driver``
106+
directory. Replace the following placeholder values:
107+
108+
- ``<path>``: The path to your CMake executable
109+
- ``<version>``: Your Visual Studio version number
110+
- ``<year>``: The year corresponding to your Visual Studio version
111+
112+
.. step:: Build and install the driver
113+
114+
Select the tab corresponding to your operating system and run following commands to install
115+
the driver:
116+
117+
.. tabs::
118+
119+
.. tab:: macOS / Linux
120+
:tabid: configure-mac-linux
121+
122+
.. code-block:: bash
123+
124+
cmake --build .
125+
sudo cmake --build . --target install
126+
127+
.. tab:: Windows
128+
:tabid: configure-windows
129+
130+
.. code-block:: bash
131+
132+
cmake --build . --config RelWithDebInfo
133+
cmake --build . --target install --config RelWithDebInfo
134+
135+
After you complete these steps, you have the {+driver-short+} installed
136+
on your machine.
137+
138+
.. _cpp-quick-start-create-deployment:
139+
140+
Create a MongoDB Deployment
141+
---------------------------
142+
143+
You can create a free tier MongoDB deployment on MongoDB Atlas
144+
to store and manage your data. MongoDB Atlas hosts and manages
145+
your MongoDB database in the cloud.
146+
147+
.. procedure::
148+
:style: connected
149+
150+
.. step:: Create a Free MongoDB deployment on Atlas
151+
152+
Complete the :atlas:`Get Started with Atlas </getting-started>`
153+
guide to set up a new Atlas account and load sample data into a new free
154+
tier MongoDB deployment.
155+
156+
.. step:: Save your Credentials
157+
158+
After you create your database user, save that user's
159+
username and password to a safe location for use in an upcoming step.
160+
161+
After you complete these steps, you have a new free tier MongoDB
162+
deployment on Atlas, database user credentials, and sample data loaded
163+
into your database.
164+
165+
.. _cpp-quick-start-connection-string:
166+
167+
Create a Connection String
168+
--------------------------
169+
170+
You can connect to your MongoDB deployment by providing a
171+
**connection URI**, also called a *connection string*, which
172+
instructs the driver on how to connect to a MongoDB deployment
173+
and how to behave while connected.
174+
175+
The connection string includes the hostname or IP address and
176+
port of your deployment, the authentication mechanism, user credentials
177+
when applicable, and connection options.
178+
179+
To connect to an instance or deployment not hosted on Atlas, see the
180+
:ref:`cpp-connection-targets` guide.
181+
182+
.. procedure::
183+
:style: connected
184+
185+
.. step:: Find your MongoDB Atlas Connection String
186+
187+
To retrieve your connection string for the deployment that
188+
you created in the :ref:`previous step <cpp-quick-start-create-deployment>`,
189+
log in to your Atlas account and navigate to the
190+
:guilabel:`Database` section and click the :guilabel:`Connect` button
191+
for your new deployment.
192+
193+
.. figure:: /includes/figures/atlas_connection_select_cluster.png
194+
:alt: The connect button in the clusters section of the Atlas UI
195+
196+
Proceed to the :guilabel:`Connect your application` section and select
197+
"C++" from the :guilabel:`Driver` selection menu and the version
198+
that best matches the version you installed from the :guilabel:`Version`
199+
selection menu.
200+
201+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
202+
203+
Deselect the :guilabel:`Include full driver code example` option to view
204+
only the connection string.
205+
206+
.. step:: Copy your Connection String
207+
208+
Click the button on the right of the connection string to copy it
209+
to your clipboard, as shown in the following screenshot:
210+
211+
.. figure:: /includes/figures/atlas_connection_copy_string_cpp.png
212+
:alt: The copy button next to the connection string in the Atlas UI
213+
214+
.. step:: Update the Placeholders
215+
216+
Paste this connection string into a file in your preferred text editor
217+
and replace the ``<username>`` and ``<password>`` placeholders with
218+
your database user's username and password.
219+
220+
Save this file to a safe location for use in the next step.
221+
222+
After completing these steps, you have a connection string that
223+
corresponds to your Atlas cluster.
224+
225+
.. _cpp-quick-start-connect-to-mongodb:
226+
227+
Connect to MongoDB
228+
------------------
229+
230+
.. facet::
231+
:name: genre
232+
:values: tutorial
233+
234+
.. meta::
235+
:keywords: test connection, runnable, code example
236+
237+
.. procedure::
238+
:style: connected
239+
240+
.. step:: Create a project directory
241+
242+
From your root directory, run the following command in your shell to create a directory called
243+
``cpp-quickstart`` for this project:
244+
245+
.. code-block:: bash
246+
247+
mkdir cpp-quickstart
248+
249+
Run the following commands to create a ``quickstart.cpp`` application file in the ``cpp-quickstart``
250+
directory:
251+
252+
.. code-block:: bash
253+
254+
cd cpp-quickstart
255+
touch quickstart.cpp
256+
257+
.. step:: Create your {+driver-short+} application
258+
259+
Copy and paste the following code into the ``quickstart.cpp`` file, which queries
260+
the ``movies`` collection in the ``sample_mflix`` database:
261+
262+
.. literalinclude:: /includes/get-started/quickstart.cpp
263+
264+
.. step:: Assign the connection string
265+
266+
Replace the ``<connection string>`` placeholder with the
267+
connection string that you copied from the :ref:`cpp-quick-start-connection-string`
268+
step of this guide.
269+
270+
.. step:: Run your C++ application
271+
272+
In your shell, run the following commands to compile and run this application:
273+
274+
.. code-block:: none
275+
276+
c++ --std=c++17 quickstart.cpp $(pkg-config --cflags --libs libmongocxx) -o ./app.out
277+
./app.out
278+
279+
.. tip::
280+
281+
MacOS users might see the following error after running the preceding commands:
282+
283+
.. code-block:: bash
284+
:copyable: false
285+
286+
dyld[54430]: Library not loaded: @rpath/libmongocxx._noabi.dylib
287+
288+
To resolve this error, use the ``-Wl,-rpath`` linker option to set the ``@rpath``, as shown
289+
in the following code:
290+
291+
.. code-block:: none
292+
293+
c++ --std=c++17 quickstart.cpp -Wl,-rpath,/usr/local/lib/ $(pkg-config --cflags --libs libmongocxx) -o ./app.out
294+
./app.out
295+
296+
The command line output contains details about the retrieved movie
297+
document:
298+
299+
.. code-block:: none
300+
:copyable: false
301+
302+
{ "_id" : { "$oid" : "573a1399f29313caabceeb20" },
303+
"plot" : "Two imprisoned men bond over a number of years, finding solace
304+
and eventual redemption through acts of common decency.",
305+
...
306+
"title" : "The Shawshank Redemption",
307+
...
308+
309+
If you encounter an error or see no output, ensure that you specified the
310+
proper connection string in the ``quickstart.cpp`` file and that you loaded the
311+
sample data.
312+
313+
After you complete these steps, you have a working application that
314+
uses the driver to connect to your MongoDB deployment, runs a query on
315+
the sample data, and prints out the result.
316+
317+
.. _cpp-quick-start-next-steps:
318+
319+
==========
320+
Next Steps
321+
==========
322+
323+
.. facet::
324+
:name: genre
325+
:values: reference
326+
327+
.. meta::
328+
:keywords: learn more
329+
330+
Congratulations on completing the quick start tutorial!
331+
332+
.. include:: /includes/get-started/troubleshoot.rst
333+
334+
In this tutorial, you created a C++ application that
335+
connects to a MongoDB deployment hosted on MongoDB Atlas
336+
and retrieves a document that matches a query.
337+
338+
Learn more about {+driver-short+} from the following resources:
339+
340+
- Learn how to perform read operations in the :ref:`<cpp-read>` section.
341+
342+
- Learn how to perform write operations in the :ref:`<cpp-write>` section.

0 commit comments

Comments
 (0)