A more complete C example

c/.gitignore

@@ -1,3 +1,6 @@
 main
 deltachat-db
-.clangd
+.clangd
+deltachat_c_echo_bot
+*.db
+*.db-blobs

c/Makefile

@@ -0,0 +1,32 @@
+CC = gcc
+DELTACHAT_PKG_CONFIG = /usr/local/lib64/pkgconfig
+DELTACHAT_INCLUDE = /usr/local/include
+DELTACHAT_LIB = /usr/local/lib64
+
+.PHONY = all manual pkgconfig 
+
+all:
+	@echo if you know the directory of deltachat.pc, do:
+	@echo make DELTACHAT_PKG_CONFIG="<directory of deltachat.pc>" pkgconfig
+	@echo or if you know the directories of deltachat.h and libdeltachat.*, do:
+	@echo make DELTACHAT_INCLUDE="<directory of deltachat.h>" DELTACHAT_LIB="<directory of libdeltachat.*>" manual
+	@echo
+	@echo if they are in /usr/local/{include,lib64}, you can do either:
+	@echo make manual
+	@echo or
+	@echo make pkgconfig
+
+pkgconfig:
+	$(CC) -g -O2 -Wextra -Wconversion -Werror \
+  $(shell PKG_CONFIG_PATH="$(DELTACHAT_PKG_CONFIG)" \
+    pkg-config --cflags --libs deltachat) \
+  -Wl,-rpath,$(shell PKG_CONFIG_PATH=$(DELTACHAT_PKG_CONFIG) pkg-config \
+               --libs-only-L deltachat) \
+  -lpthread main.c -o deltachat_c_echo_bot
+
+manual:
+	$(CC) -g -O2 -Wextra -Wconversion -Werror \
+  -I"$(DELTACHAT_INCLUDE)" -L"$(DELTACHAT_LIB)" -ldeltachat \
+  -Wl,-rpath,"$(DELTACHAT_LIB)" \
+  -lpthread main.c -o deltachat_c_echo_bot
+

c/README.md

@@ -1,50 +1,131 @@
-# Echo Bot - C
+# C Echo Bot
 
-## Requirements
+- This describes a process for compiling a C echo bot, on a *POSIX*-like system, assuming you have installed `libdeltachat.{a.so}` from [DeltaChat Core Rust](https://github.com/deltachat/deltachat-core-rust).
+  - It will typically install the `deltachat.h` and `libdeltachat.{a,so}` into `/usr/local/{include,lib,lib64}`.
+- If you are on another platform, your steps might vary.
+  - Please feel free to submit a PR for platform-specific instructions.
 
-- This readme describes the process for compiling on **linux**, if you are on another platform your steps might vary. If you figgured out how to do it on your platform feel free to sumbit a pr to add your method to this readme.
-- You need `libdeltachat`,`git`, `cmake`, `gcc` and `pkg-config` also `rustup` if you compile `libdeltachat` on your own
+## API Documentation
 
-### Installing libdeltachat from source
+<https://c.delta.chat/>
+
+## Prerequisites
+
+- `git`
+- a C compiler that allows for passing the linker flag `-Wl,-rpath`, e.g., `gcc`
+- GNU `make`
+- optionally, `pkg-config`
+- CMake
+- a Rust tool suite for *DeltaChat Core Rust*
+- an installed `libdeltachat.{a.so}` from the *Core*, with:
+
+*either*
+
+- the directory containing `deltachat.pc`
+  - usually in `/usr/local/lib/pkgconfig` or `/usr/local/lib64/pkgconfig`
+
+*or*
+
+- the directory containing `deltachat.h`
+  - usually in `/usr/local/include`
+- the directory of `libdeltachat.*`
+  - usually in `/usr/local/lib` or `/usr/local/lib64`
+
+## Installing *DeltaChat Core Rust* from source
+
+
+### Assuming root access (requires Rust), defaulting to `/usr/local`:
+
+```sh
+git clone https://github.com/deltachat/deltachat-core-rust
+cd deltachat-core-rust
+cmake -B build
+cmake --build build
+sudo cmake --install build
+```
+
+#### To uninstall
+
+```sh
+cd deltachat-core-rust
+sudo xargs -d\\n rm -i < build/install_manifest.txt
+```
+
+### No root access or to change the install location
+
+Use `-DCMAKE_INSTALL_PREFIX="<install path>"` with `cmake -B build`:
 
 ```sh
 git clone https://github.com/deltachat/deltachat-core-rust
 cd deltachat-core-rust
-cmake -B build . && cmake --build build && sudo cmake --install build
+cmake -B build -DCMAKE_INSTALL_PREFIX="<install path>"
+cmake --build build
+cmake --install build
+# or `sudo cmake --install build` if it is a write-protected path
 ```
 
-> Info: To uninstall, run `sudo xargs -d\\n rm -f <build/install_manifest.txt` in the same directory
+#### To uninstall
+
+```sh
+cd deltachat-core-rust
+rm -i < build/install_manifest.txt
+# or `sudo xargs -d\\n rm -i < build/install_manifest.txt` if it is a write-protected path
+```
+
+## Compiling the echo bot
+
+### If you know the path to `deltachat.pc` and have `pkg-config`
 
-## Usage
+```sh
+git clone https://github.com/deltachat/deltachat-bot/echo
+cd echo/c
+make PKG_CONFIG_PATH="<path to deltachat.pc>" pkgconfig
+```
 
-### Compile
+### Otherwise
 
 ```sh
-export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
-gcc main.c -o main $(pkg-config --cflags --libs deltachat) -lpthread
+git clone https://github.com/deltachat/deltachat-bot/echo
+cd echo/c
+make DELTACHAT_INCLUDE="<path to deltachat.h>" \
+DELTACHAT_LIB="<path to libdeltachat.*>" manual
 ```
 
-### Run
+### If they are in `/usr/local/include` and `/usr/local/lib64`
 
 ```sh
-LD_LIBRARY_PATH=/usr/local/lib addr=$yourEmail mailpw=$yourPassword ./main
+make manual
+# or `make pkgconfig`
 ```
 
-### Format code
+## Run
+
+### First time, if you have an email and password for the bot
 
 ```sh
-clang-format -i main.c
+cd echo/c
+DELTACHAT_C_ECHO_EMAIL="<email>" \
+DELTACHAT_C_ECHO_PASSWORD="<password>" \
+./deltachat_c_echo_bot
 ```
 
-You might need to install `clang-format` first.
+This will place the `bot.db` and blob directory in the same 
+directory as `deltachat_c_echo_bot`.
 
-### Quirks
+### In subsequent runs, assuming `bot.db` is in the same directory as `deltachat_c_echo_bot`
 
-> There is no way to terminate it currently. I wanted to propose a SIGTERM handler, but realized doing it properly is more difficult than it should be: deltachat/deltachat-core-rust#2280
-> So for the purpose of example it's easier to assume the bot will be running forever.
->
-> ~ link2xt on https://github.com/deltachat-bot/echo/pull/13#issuecomment-790594993
+```sh
+cd echo/c
+./deltachat_c_echo_bot
+```
+
+### If you have an existing state database, i.e., `dc.db` or one from a backup
+
+```sh
+cd echo/c
+mv "<name of existing db, like dc.db>" bot.db
+mv "<name of blob directory, like dc.db-blobs>" ./bot.db-blobs
+./deltachat_c_echo_bot
+```
 
-### Useful Links
 
-- Documentation https://c.delta.chat/