add a quickstart

Author: kevinAlbs

README.md

@@ -34,6 +34,7 @@ Feedback on the interface is welcome on GitHub issues and discussions. Though fu
 ## Links
 
 - [GitHub Repository][github]
+- [Quickstart](./etc/quickstart)
 - [Documentation Home][docs]
   - [Tutorials][docs-learn]
   - [Reference: Configuring, Building, and Using][docs-building]

etc/quickstart/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.25)
+project(HelloAmongoc)
+add_executable(hello-amongoc hello-amongoc.c)
+find_package(amongoc REQUIRED)
+target_link_libraries(hello-amongoc PRIVATE amongoc::amongoc)

etc/quickstart/README.md

@@ -0,0 +1,54 @@
+# mongo-c-driver-async Quick Start
+
+The following steps use vcpkg to install mongo-c-driver-async, build a test application, and connect to a local MongoDB server.
+
+Steps were run on Debian 12.
+
+Install vcpkg (if not already installed):
+```bash
+cd $HOME
+git clone https://github.com/microsoft/vcpkg.git
+VCPKG_ROOT=$HOME/vcpkg
+cd vcpkg
+./bootstrap-vcpkg.sh
+export PATH=$VCPKG_ROOT:$PATH
+```
+
+Install amongoc:
+```bash
+cd $HOME
+AMONGOC_INSTALL="$HOME/mongo-c-driver-async-0.1.0"
+git clone https://github.com/mongodb-labs/mongo-c-driver-async/
+cd mongo-c-driver-async
+cmake -B_build 
+cmake --build _build --parallel
+cmake --install _build --prefix "$AMONGOC_INSTALL"
+```
+
+Build this test application:
+```bash
+# Run from this directory.
+cmake -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
+      -DCMAKE_PREFIX_PATH=$AMONGOC_INSTALL \
+      -Bcmake-build
+cmake --build cmake-build --target hello-amongoc
+```
+
+Start a local MongoDB server:
+```bash
+cd $HOME
+# Get download links from: https://www.mongodb.com/try/download/community
+wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-debian12-8.0.4.tgz
+tar -xf mongodb-linux-x86_64-debian12-8.0.4.tgz
+rm mongodb-linux-x86_64-debian12-8.0.4.tgz
+# Start server
+mkdir mongodb-data
+./mongodb-linux-x86_64-debian12-8.0.4/bin/mongod --dbpath ./mongodb-data
+```
+
+Run test application
+```bash
+./cmake-build/hello-amongoc
+```
+
+Expect to see `Successfully connected!`.

etc/quickstart/hello-amongoc.c

@@ -0,0 +1,49 @@
+#include <amongoc/amongoc.h> // Make all APIs visible
+
+#include <stdio.h>
+#include <stdlib.h>
+
+amongoc_box on_connect(amongoc_box userdata, amongoc_status *status, amongoc_box result);
+
+int main(void)
+{
+    amongoc_loop loop;
+    amongoc_status status = amongoc_default_loop_init(&loop);
+    amongoc_if_error(status, msg)
+    {
+        fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
+        return 2;
+    }
+
+    // Initiate a connection
+    amongoc_emitter em = amongoc_client_new(&loop, "mongodb://localhost:27017");
+    // Set the continuation
+    em = amongoc_then(em, &on_connect);
+    // Run the program
+    amongoc_detach_start(em);
+    amongoc_default_loop_run(&loop);
+    // Clean up
+    amongoc_default_loop_destroy(&loop);
+    return 0;
+}
+
+amongoc_box on_connect(amongoc_box userdata, amongoc_status *status, amongoc_box result)
+{
+    // We don't use the userdata
+    (void)userdata;
+    // Check for an error
+    amongoc_if_error(*status, msg)
+    {
+        fprintf(stderr, "Error while connecting to server: %s\n", msg);
+    }
+    else
+    {
+        printf("Successfully connected!\n");
+        amongoc_client *client;
+        amongoc_box_take(client, result);
+        // `client` now stores a valid client. We don't do anything else, so just delete it:
+        amongoc_client_delete(client);
+    }
+    amongoc_box_destroy(result);
+    return amongoc_nil;
+}

etc/quickstart/vcpkg.json

@@ -0,0 +1,8 @@
+{
+    "dependencies": [
+        "fmt",
+        "openssl",
+        "boost-container",
+        "boost-url"
+    ]
+}