automerge/rust/automerge-c/README.md

automerge-c exposes an API to C that can either be used directly or as a basis for other language bindings that have good support for calling into C functions.

Building

See the main README for instructions on getting your environment set up, then you can use ./scripts/ci/cmake-build Release static to build automerge-c.

It will output two files:

• ./build/Cargo/target/include/automerge-c/automerge.h
• ./build/Cargo/target/release/libautomerge.a

To use these in your application you must arrange for your C compiler to find these files, either by moving them to the right location on your computer, or by configuring the compiler to reference these directories.

• export LDFLAGS=-L./build/Cargo/target/release -lautomerge
• export CFLAGS=-I./build/Cargo/target/include

If you'd like to cross compile the library for different platforms you can do so using cross. For example:

• cross build --manifest-path rust/automerge-c/Cargo.toml -r --target aarch64-unknown-linux-gnu

This will output a shared library in the directory rust/target/aarch64-unknown-linux-gnu/release/.

You can replace aarch64-unknown-linux-gnu with any cross supported targets. The targets below are known to work, though other targets are expected to work too:

• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu

As a caveat, the header file is currently 32/64-bit dependant. You can re-use it for all 64-bit architectures, but you must generate a specific header for 32-bit targets.

Usage

For full reference, read through automerge.h, or to get started quickly look at the examples.

Almost all operations in automerge-c act on an AMdoc struct which you can get from AMcreate() or AMload(). Operations on a given doc are not thread safe so you must use a mutex or similar to avoid calling more than one function with the same AMdoc pointer concurrently.

As with all functions that either allocate memory, or could fail if given invalid input, AMcreate() returns an AMresult. The AMresult contains the returned doc (or error message), and must be freed with AMfree() after you are done to avoid leaking memory.

#include <automerge-c/automerge.h>
#include <stdio.h>

int main(int argc, char** argv) {
  AMresult *docResult = AMcreate(NULL);

  if (AMresultStatus(docResult) != AM_STATUS_OK) {
    printf("failed to create doc: %s", AMerrorMessage(docResult).src);
    goto cleanup;
  }

  AMdoc *doc = AMresultValue(docResult).doc;

  // useful code goes here!

cleanup:
  AMfree(docResult);
}

If you are writing code in C directly, you can use the AMpush() helper function to reduce the boilerplate of error handling and freeing for you (see examples/quickstart.c).

If you are wrapping automerge-c in another language, particularly one that has a garbage collector, you can call AMfree within a finalizer to ensure that memory is reclaimed when it is no longer needed.

An AMdoc wraps an automerge document which are very similar to JSON documents. Automerge documents consist of a mutable root, which is always a map from string keys to values. Values can have the following types:

• A number of type double / int64_t / uint64_t
• An explicit true / false / nul
• An immutable utf-8 string (AMbyteSpan)
• An immutable array of arbitrary bytes (AMbyteSpan)
• A mutable map from string keys to values (AMmap)
• A mutable list of values (AMlist)
• A mutable string (AMtext)

If you read from a location in the document with no value a value with .tag == AM_VALUE_VOID will be returned, but you cannot write such a value explicitly.

Under the hood, automerge references mutable objects by the internal object id, and AM_ROOT is always the object id of the root value.

There is a function to put each type of value into either a map or a list, and a function to read the current value from a list. As (in general) collaborators may edit the document at any time, you cannot guarantee that the type of the value at a given part of the document will stay the same. As a result reading from the document will return an AMvalue union that you can inspect to determine its type.

Strings in automerge-c are represented using an AMbyteSpan which contains a pointer and a length. Strings must be valid utf-8 and may contain null bytes. As a convenience you can use AMstr() to get the representation of a null-terminated C string as an AMbyteSpan.

Putting all of that together, to read and write from the root of the document you can do this:

#include <automerge-c/automerge.h>
#include <stdio.h>

int main(int argc, char** argv) {
  // ...previous example...
  AMdoc *doc = AMresultValue(docResult).doc;

  AMresult *putResult = AMmapPutStr(doc, AM_ROOT, AMstr("key"), AMstr("value"));
  if (AMresultStatus(putResult) != AM_STATUS_OK) {
    printf("failed to put: %s", AMerrorMessage(putResult).src);
    goto cleanup;
  }

  AMresult *getResult = AMmapGet(doc, AM_ROOT, AMstr("key"), NULL);
  if (AMresultStatus(getResult) != AM_STATUS_OK) {
    printf("failed to get: %s", AMerrorMessage(getResult).src);
    goto cleanup;
  }

  AMvalue got = AMresultValue(getResult);
  if (got.tag != AM_VALUE_STR) {
    printf("expected to read a string!");
    goto cleanup;
  }

  printf("Got %zu-character string `%s`", got.str.count, got.str.src);

cleanup:
  AMfree(getResult);
  AMfree(putResult);
  AMfree(docResult);
}

Functions that do not return an AMresult (for example AMmapItemValue()) do not allocate memory, but continue to reference memory that was previously allocated. It's thus important to keep the original AMresult alive (in this case the one returned by AMmapRange()) until after you are done with the return values of these functions.

Beyond that, good luck!