automerge-rb 0.1.1

data/vendor/automerge-rust/automerge-c/CMakeLists.txt

@@ -0,0 +1,439 @@
+cmake_minimum_required(VERSION 3.25 FATAL_ERROR)
+
+project(automerge-c VERSION 0.3.0
+                    LANGUAGES C
+                    DESCRIPTION "C bindings for the Automerge Rust library.")
+
+include(CTest)
+
+include(CMakePackageConfigHelpers)
+
+include(GNUInstallDirs)
+
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
+
+set(DEFAULT_LIBRARY_NAME "automerge")
+
+if(NOT DEFINED LIBRARY_NAME)
+    set(LIBRARY_NAME "${DEFAULT_LIBRARY_NAME}")
+endif()
+
+set(DEFAULT_BINDINGS_NAME "${DEFAULT_LIBRARY_NAME}_core")
+
+if(NOT DEFINED BINDINGS_NAME)
+    set(BINDINGS_NAME "${DEFAULT_BINDINGS_NAME}")
+endif()
+
+if(NOT DEFINED STATIC_LIBRARY_PREFIX)
+    set(STATIC_LIBRARY_PREFIX "${CMAKE_STATIC_LIBRARY_PREFIX}")
+endif()
+
+if(NOT DEFINED STATIC_LIBRARY_SUFFIX)
+    set(STATIC_LIBRARY_SUFFIX "${CMAKE_STATIC_LIBRARY_SUFFIX}")
+endif()
+
+IF(NOT DEFINED SHARED_LIBRARY_PREFIX)
+    set(SHARED_LIBRARY_PREFIX "${CMAKE_SHARED_LIBRARY_PREFIX}")
+endif()
+
+if(NOT DEFINED SHARED_LIBRARY_SUFFIX)
+    set(SHARED_LIBRARY_SUFFIX "${CMAKE_SHARED_LIBRARY_SUFFIX}")
+endif()
+
+option(BUILD_SHARED_LIBS "Enable the choice of a shared or static library.")
+
+option(UTF32_INDEXING "Enable UTF-32 indexing.")
+
+string(MAKE_C_IDENTIFIER ${PROJECT_NAME} SYMBOL_PREFIX)
+
+string(TOUPPER ${SYMBOL_PREFIX} SYMBOL_PREFIX)
+
+set(CARGO_TARGET_DIR "${PROJECT_BINARY_DIR}/Cargo/target")
+
+set(CBINDGEN_INCLUDEDIR "${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_INCLUDEDIR}")
+
+set(CBINDGEN_TARGET_DIR "${CBINDGEN_INCLUDEDIR}/${PROJECT_NAME}")
+
+find_program (CARGO_CMD
+              "cargo"
+              PATHS "$ENV{CARGO_HOME}/bin"
+              DOC "The Rust package manager"
+)
+
+if(NOT CARGO_CMD)
+    message(FATAL_ERROR "Cargo (Rust package manager) not found! "
+                        "Please install it and/or set the CARGO_HOME "
+                        "environment variable to its path.")
+endif()
+
+find_program(RUSTC_CMD
+             "rustc"
+             PATHS "$ENV{CARGO_HOME}/bin"
+             DOC "The Rust compiler"
+)
+
+if(NOT RUSTC_CMD)
+    message(FATAL_ERROR "Rustc (Rust compiler) not found! "
+                        "Please install it and/or set the CARGO_HOME "
+                        "environment variable to its path.")
+endif()
+
+# In order to build with -Z build-std, we need to pass target explicitly.
+# https://doc.rust-lang.org/cargo/reference/unstable.html#build-std
+execute_process (
+    COMMAND ${RUSTC_CMD} -vV
+    OUTPUT_VARIABLE RUSTC_VERSION
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+)
+string(REGEX REPLACE ".*host: ([^ \n]*).*" "\\1"
+    CARGO_TARGET
+    ${RUSTC_VERSION}
+)
+
+set(CARGO_FLAGS --target=${CARGO_TARGET})
+
+set(RUSTFLAGS "")
+
+if(CMAKE_BUILD_TYPE MATCHES Debug)
+    set(CARGO_BUILD_TYPE "debug")
+else()
+    set(CARGO_BUILD_TYPE "release")
+
+    if (NOT RUSTC_VERSION MATCHES "nightly")
+        set(RUSTUP_TOOLCHAIN nightly)
+    endif()
+
+    set(RUSTFLAGS "${RUSTFLAGS} -C panic=abort")
+
+    set(CARGO_FLAGS -Z build-std=std,panic_abort --release ${CARGO_FLAGS})
+endif()
+
+if(UTF32_INDEXING)
+    set(CARGO_FEATURES "")
+    set(TEXT_INDEXING_ENCODING "UTF32")
+else()
+    set(CARGO_FEATURES "-F automerge/utf8-indexing")
+    set(TEXT_INDEXING_ENCODING "UTF8")
+endif()
+
+set(CARGO_BINARY_DIR "${CARGO_TARGET_DIR}/${CARGO_TARGET}/${CARGO_BUILD_TYPE}")
+
+configure_file(
+    ${PROJECT_SOURCE_DIR}/cmake/Cargo.toml.in
+    ${PROJECT_SOURCE_DIR}/Cargo.toml
+    NEWLINE_STYLE LF
+)
+
+set(INCLUDE_GUARD_PREFIX "${SYMBOL_PREFIX}")
+
+configure_file(
+    ${PROJECT_SOURCE_DIR}/cmake/cbindgen.toml.in
+    ${PROJECT_SOURCE_DIR}/cbindgen.toml
+    @ONLY
+    NEWLINE_STYLE LF
+)
+
+set(CARGO_OUTPUT
+    ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h
+    ${CARGO_BINARY_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}${BINDINGS_NAME}${CMAKE_STATIC_LIBRARY_SUFFIX}
+)
+
+# \note cbindgen's naming behavior isn't fully configurable and it ignores
+#       `const fn` calls (https://github.com/eqrion/cbindgen/issues/252).
+add_custom_command(
+    OUTPUT
+        ${CARGO_OUTPUT}
+    COMMAND
+        # Force cbindgen to regenerate the header file by updating its configuration file; removing the header won't.
+        ${CMAKE_COMMAND} -DCONDITION=NOT_EXISTS -P ${PROJECT_SOURCE_DIR}/cmake/file-touch.cmake -- ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h ${PROJECT_SOURCE_DIR}/cbindgen.toml
+    COMMAND
+        ${CMAKE_COMMAND} -E env CARGO_TARGET_DIR=${CARGO_TARGET_DIR} CBINDGEN_TARGET_DIR=${CBINDGEN_TARGET_DIR} RUSTUP_TOOLCHAIN=${RUSTUP_TOOLCHAIN} RUSTFLAGS=${RUSTFLAGS} ${CARGO_CMD} build ${CARGO_FLAGS} ${CARGO_FEATURES}
+    COMMAND
+        # Compensate for cbindgen's translation of consecutive uppercase letters to "ScreamingSnakeCase".
+        ${CMAKE_COMMAND} -DMATCH_REGEX=A_M\([^_]+\)_ -DREPLACE_EXPR=AM_\\1_ -P ${PROJECT_SOURCE_DIR}/cmake/file-regex-replace.cmake -- ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h
+    COMMAND
+        # Compensate for cbindgen ignoring `std::mem::size_of<usize>()` calls.
+        ${CMAKE_COMMAND} -DMATCH_REGEX=USIZE_ -DREPLACE_EXPR=\+${CMAKE_SIZEOF_VOID_P} -P ${PROJECT_SOURCE_DIR}/cmake/file-regex-replace.cmake -- ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h
+    MAIN_DEPENDENCY
+        src/lib.rs
+    DEPENDS
+        src/actor_id.rs
+        src/byte_span.rs
+        src/change.rs
+        src/cursor.rs
+        src/doc.rs
+        src/doc/list.rs
+        src/doc/map.rs
+        src/doc/mark.rs
+        src/doc/utils.rs
+        src/index.rs
+        src/item.rs
+        src/items.rs
+        src/obj.rs
+        src/result.rs
+        src/sync.rs
+        src/sync/have.rs
+        src/sync/message.rs
+        src/sync/state.rs
+        ${PROJECT_SOURCE_DIR}/build.rs
+        ${PROJECT_SOURCE_DIR}/cmake/Cargo.toml.in
+        ${PROJECT_SOURCE_DIR}/cmake/cbindgen.toml.in
+    WORKING_DIRECTORY
+        ${PROJECT_SOURCE_DIR}
+    COMMENT
+        "Producing the bindings' artifacts with Cargo..."
+    VERBATIM
+)
+
+add_custom_target(${BINDINGS_NAME}_artifacts ALL
+    DEPENDS ${CARGO_OUTPUT}
+)
+
+add_library(${BINDINGS_NAME} STATIC IMPORTED GLOBAL)
+
+target_include_directories(${BINDINGS_NAME} INTERFACE "${CBINDGEN_INCLUDEDIR}")
+
+set_target_properties(
+    ${BINDINGS_NAME}
+    PROPERTIES
+        # \note Cargo writes a debug build into a nested directory instead of
+        #       decorating its name.
+        DEBUG_POSTFIX ""
+        DEFINE_SYMBOL ""
+        IMPORTED_IMPLIB ""
+        IMPORTED_LOCATION "${CARGO_BINARY_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}${BINDINGS_NAME}${CMAKE_STATIC_LIBRARY_SUFFIX}"
+        IMPORTED_NO_SONAME "TRUE"
+        IMPORTED_SONAME ""
+        LINKER_LANGUAGE C
+        PUBLIC_HEADER "${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h"
+        SOVERSION "${PROJECT_VERSION_MAJOR}"
+        VERSION "${PROJECT_VERSION}"
+        # \note Cargo exports all of the symbols automatically.
+        WINDOWS_EXPORT_ALL_SYMBOLS "TRUE"
+)
+
+target_compile_definitions(${BINDINGS_NAME} INTERFACE $<TARGET_PROPERTY:${BINDINGS_NAME},DEFINE_SYMBOL>)
+
+set(UTILS_SUBDIR "utils")
+
+add_custom_command(
+    OUTPUT
+        ${CBINDGEN_TARGET_DIR}/${UTILS_SUBDIR}/enum_string.h
+        ${PROJECT_BINARY_DIR}/src/${UTILS_SUBDIR}/enum_string.c
+    COMMAND
+        ${CMAKE_COMMAND} -DPROJECT_NAME=${PROJECT_NAME} -DLIBRARY_NAME=${LIBRARY_NAME} -DSUBDIR=${UTILS_SUBDIR} -P ${PROJECT_SOURCE_DIR}/cmake/enum-string-functions-gen.cmake -- ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h ${CBINDGEN_TARGET_DIR}/${UTILS_SUBDIR}/enum_string.h ${PROJECT_BINARY_DIR}/src/${UTILS_SUBDIR}/enum_string.c
+    MAIN_DEPENDENCY
+        ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h
+    DEPENDS
+        ${PROJECT_SOURCE_DIR}/cmake/enum-string-functions-gen.cmake
+    WORKING_DIRECTORY
+        ${PROJECT_SOURCE_DIR}
+    COMMENT
+        "Generating the enum string functions with CMake..."
+    VERBATIM
+)
+
+add_custom_target(${LIBRARY_NAME}_utilities
+    DEPENDS ${CBINDGEN_TARGET_DIR}/${UTILS_SUBDIR}/enum_string.h
+            ${PROJECT_BINARY_DIR}/src/${UTILS_SUBDIR}/enum_string.c
+)
+
+add_library(${LIBRARY_NAME})
+
+target_compile_features(${LIBRARY_NAME} PRIVATE c_std_99)
+
+set(CMAKE_THREAD_PREFER_PTHREAD TRUE)
+
+set(THREADS_PREFER_PTHREAD_FLAG TRUE)
+
+find_package(Threads REQUIRED)
+
+set(LIBRARY_DEPENDENCIES Threads::Threads ${CMAKE_DL_LIBS})
+
+if(WIN32)
+    list(APPEND LIBRARY_DEPENDENCIES Bcrypt ntdll userenv ws2_32)
+else()
+    list(APPEND LIBRARY_DEPENDENCIES m)
+endif()
+
+set_target_properties(${LIBRARY_NAME} PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS "TRUE")
+
+# \note An imported library's INTERFACE_INCLUDE_DIRECTORIES property can't
+#       contain a non-existent path so its build-time include directory
+#       must be specified for all of its dependent targets instead.
+target_include_directories(${LIBRARY_NAME}
+    PUBLIC "$<BUILD_INTERFACE:${CBINDGEN_INCLUDEDIR};${PROJECT_SOURCE_DIR}/${CMAKE_INSTALL_INCLUDEDIR}>"
+           "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
+)
+
+add_dependencies(${LIBRARY_NAME} ${BINDINGS_NAME}_artifacts)
+
+if(BUILD_SHARED_LIBS)
+    target_link_libraries(${LIBRARY_NAME} PUBLIC "$<LINK_LIBRARY:WHOLE_ARCHIVE,${BINDINGS_NAME}>" ${LIBRARY_DEPENDENCIES})
+
+    # Enable an external build tool to find the shared library in the root of the
+    # out-of-source build directory when it has overridden an aspect of its name.
+    if(NOT (("${SHARED_LIBRARY_PREFIX}" STREQUAL "${CMAKE_SHARED_LIBRARY_PREFIX}") AND
+            ("${LIBRARY_NAME}" STREQUAL "${DEFAULT_LIBRARY_NAME}") AND
+            ("${SHARED_LIBRARY_SUFFIX}" STREQUAL "${CMAKE_SHARED_LIBRARY_SUFFIX}")))
+        add_custom_command(
+            TARGET ${LIBRARY_NAME}
+            POST_BUILD
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "Copying \"${CMAKE_SHARED_LIBRARY_PREFIX}${LIBRARY_NAME}${CMAKE_SHARED_LIBRARY_SUFFIX}\" to \"${PROJECT_BINARY_DIR}/${SHARED_LIBRARY_PREFIX}${LIBRARY_NAME}${SHARED_LIBRARY_SUFFIX}\"..."
+            COMMAND
+                ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/${CMAKE_SHARED_LIBRARY_PREFIX}${LIBRARY_NAME}${CMAKE_SHARED_LIBRARY_SUFFIX} ${PROJECT_BINARY_DIR}/${SHARED_LIBRARY_PREFIX}${LIBRARY_NAME}${SHARED_LIBRARY_SUFFIX}
+            WORKING_DIRECTORY
+                ${PROJECT_SOURCE_DIR}
+            COMMENT
+                "Aliasing the library for the external build tool..."
+            VERBATIM
+        )
+    endif()
+else()
+    target_link_libraries(${LIBRARY_NAME} PUBLIC ${BINDINGS_NAME} ${LIBRARY_DEPENDENCIES})
+
+    if(WIN32)
+        find_program(LIB_TOOL "lib" REQUIRED)
+
+        add_custom_command(
+            TARGET ${LIBRARY_NAME}
+            POST_BUILD
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "Merging its dependent libraries into \"$<TARGET_FILE:${LIBRARY_NAME}>\"..."
+            COMMAND
+                ${LIB_TOOL} /OUT:$<TARGET_FILE_NAME:${LIBRARY_NAME}> $<TARGET_FILE_NAME:${LIBRARY_NAME}> $<TARGET_FILE:${BINDINGS_NAME}>
+            WORKING_DIRECTORY
+                ${PROJECT_BINARY_DIR}
+            COMMENT
+                "Merging the libraries..."
+            VERBATIM
+        )
+    else()
+        set(OBJECTS_DIR objects)
+
+        set(BINDINGS_OBJECTS_DIR ${OBJECTS_DIR}/$<TARGET_NAME:${BINDINGS_NAME}>)
+
+        add_custom_command(
+            TARGET "${LIBRARY_NAME}"
+            POST_BUILD
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "Merging its dependent libraries into \"$<TARGET_FILE:${LIBRARY_NAME}>\"..."
+            COMMAND
+                ${CMAKE_COMMAND} -E rm -rf ${OBJECTS_DIR}
+            COMMAND
+                ${CMAKE_COMMAND} -E make_directory ${BINDINGS_OBJECTS_DIR}
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "${CMAKE_AR} -x  $<TARGET_FILE:${BINDINGS_NAME}>"
+            COMMAND
+                ${CMAKE_COMMAND} -E chdir ${BINDINGS_OBJECTS_DIR} ${CMAKE_AR} -x $<TARGET_FILE:${BINDINGS_NAME}>
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "${CMAKE_AR} -rs $<TARGET_FILE_NAME:${LIBRARY_NAME}> ${BINDINGS_OBJECTS_DIR}/*.o"
+            COMMAND
+                ${CMAKE_AR} -rs $<TARGET_FILE_NAME:${LIBRARY_NAME}> ${BINDINGS_OBJECTS_DIR}/*.o
+            WORKING_DIRECTORY
+                ${PROJECT_BINARY_DIR}
+            COMMENT
+                "Merging the libraries' constituent object files..."
+        )
+    endif()
+endif()
+
+if(NOT BUILD_SHARED_LIBS OR WIN32)
+    # Enable an external build tool to find the static/import library in the
+    # root of the out-of-source build directory when it has overridden an aspect
+    # of its name.
+    if(NOT (("${STATIC_LIBRARY_PREFIX}" STREQUAL "${CMAKE_STATIC_LIBRARY_PREFIX}") AND
+            ("${LIBRARY_NAME}" STREQUAL "${DEFAULT_LIBRARY_NAME}") AND
+            ("${STATIC_LIBRARY_SUFFIX}" STREQUAL "${CMAKE_STATIC_LIBRARY_SUFFIX}")))
+        add_custom_command(
+            TARGET ${LIBRARY_NAME}
+            POST_BUILD
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "(STATIC_LIBRARY_PREFIX, LIBRARY_NAME, STATIC_LIBRARY_SUFFIX) == (${STATIC_LIBRARY_PREFIX}, ${LIBRARY_NAME}, ${STATIC_LIBRARY_SUFFIX})"
+            COMMAND
+                ${CMAKE_COMMAND} -E echo "Copying \"${PROJECT_BINARY_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}${LIBRARY_NAME}${CMAKE_STATIC_LIBRARY_SUFFIX}\" to \"${PROJECT_BINARY_DIR}/${STATIC_LIBRARY_PREFIX}${LIBRARY_NAME}${STATIC_LIBRARY_SUFFIX}\"..."
+            COMMAND
+                ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}${LIBRARY_NAME}${CMAKE_STATIC_LIBRARY_SUFFIX} ${PROJECT_BINARY_DIR}/${STATIC_LIBRARY_PREFIX}${LIBRARY_NAME}${STATIC_LIBRARY_SUFFIX}
+            WORKING_DIRECTORY
+                ${PROJECT_SOURCE_DIR}
+            COMMENT
+                "Aliasing the static/import library for the external build tool..."
+            VERBATIM
+        )
+    endif()
+endif()
+
+# Generate the configuration header.
+math(EXPR INTEGER_PROJECT_VERSION_MAJOR "${PROJECT_VERSION_MAJOR} * 100000")
+
+math(EXPR INTEGER_PROJECT_VERSION_MINOR "${PROJECT_VERSION_MINOR} * 100")
+
+math(EXPR INTEGER_PROJECT_VERSION_PATCH "${PROJECT_VERSION_PATCH}")
+
+math(EXPR INTEGER_PROJECT_VERSION "${INTEGER_PROJECT_VERSION_MAJOR} + \
+                                   ${INTEGER_PROJECT_VERSION_MINOR} + \
+                                   ${INTEGER_PROJECT_VERSION_PATCH}")
+
+configure_file(
+    ${PROJECT_SOURCE_DIR}/cmake/config.h.in
+    ${CBINDGEN_TARGET_DIR}/config.h
+    @ONLY
+    NEWLINE_STYLE LF
+)
+
+target_sources(${LIBRARY_NAME}
+    PRIVATE
+        src/${UTILS_SUBDIR}/result.c
+        src/${UTILS_SUBDIR}/stack_callback_data.c
+        src/${UTILS_SUBDIR}/stack.c
+        src/${UTILS_SUBDIR}/string.c
+        ${PROJECT_BINARY_DIR}/src/${UTILS_SUBDIR}/enum_string.c
+    PUBLIC
+        FILE_SET api TYPE HEADERS
+            BASE_DIRS
+                ${CBINDGEN_INCLUDEDIR}
+                ${CMAKE_INSTALL_INCLUDEDIR}
+            FILES
+                ${CBINDGEN_TARGET_DIR}/${LIBRARY_NAME}.h
+                ${CBINDGEN_TARGET_DIR}/${UTILS_SUBDIR}/enum_string.h
+                ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}/${UTILS_SUBDIR}/result.h
+                ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}/${UTILS_SUBDIR}/stack_callback_data.h
+                ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}/${UTILS_SUBDIR}/stack.h
+                ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}/${UTILS_SUBDIR}/string.h
+    INTERFACE
+        FILE_SET config TYPE HEADERS
+            BASE_DIRS
+                ${CBINDGEN_INCLUDEDIR}
+            FILES
+                ${CBINDGEN_TARGET_DIR}/config.h
+)
+
+install(
+    TARGETS ${LIBRARY_NAME}
+    EXPORT ${PROJECT_NAME}-config
+    FILE_SET api
+    FILE_SET config
+)
+
+# \note Install the Cargo-built core bindings to enable direct linkage.
+install(
+    FILES $<TARGET_PROPERTY:${BINDINGS_NAME},IMPORTED_LOCATION>
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}
+)
+
+install(EXPORT ${PROJECT_NAME}-config
+        FILE ${PROJECT_NAME}-config.cmake
+        NAMESPACE "${PROJECT_NAME}::"
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${LIB}
+)
+
+if(BUILD_TESTING)
+    add_subdirectory(test EXCLUDE_FROM_ALL)
+
+    enable_testing()
+endif()
+
+add_subdirectory(docs)
+
+add_subdirectory(examples EXCLUDE_FROM_ALL)

data/vendor/automerge-rust/automerge-c/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "automerge-c"
+version = "0.2.2"
+authors = ["Orion Henry <orion.henry@gmail.com>", "Jason Kankiewicz <jason.kankiewicz@gmail.com>"]
+edition = "2021"
+license = "MIT"
+rust-version = "1.80.0"
+
+[lib]
+name = "automerge_core"
+crate-type = ["staticlib"]
+bench = false
+doc = false
+
+[dependencies]
+automerge = { path = "../automerge" }
+hex = "^0.4.3"
+libc = "^0.2"
+smol_str = "0.3"
+
+[build-dependencies]
+cbindgen = "^0.29"

data/vendor/automerge-rust/automerge-c/README.md

@@ -0,0 +1,233 @@
+# Overview
+
+automerge-c exposes a C API that can either be used directly or as the basis
+for other language bindings that have good support for calling C functions.
+
+# Installing
+
+## Prerequisites
+
+* Cargo >= 1.71.0
+* CMake >= 3.25
+* CMocka >= 1.1.5
+* Doxygen >= 1.9.1
+* Ninja >= 1.10.1
+
+See the main README for instructions on getting your environment set up and then
+you can build the automerge-c library and install its constituent files within
+a root directory of your choosing (e.g. "/usr/local") like so:
+
+```shell
+cmake -E make_directory automerge-c/build
+cmake -S automerge-c -B automerge-c/build
+cmake --build automerge-c/build
+cmake --install automerge-c/build --prefix "/usr/local"
+```
+
+Installation is important because the name, location and structure of CMake's
+out-of-source build subdirectory is subject to change based on the platform and
+the release version; generated headers like `automerge-c/config.h` and
+`automerge-c/utils/enum_string.h` are only sure to be found within their
+installed locations.
+
+It's not obvious because they are versioned but the `Cargo.toml` and
+`cbindgen.toml` configuration files are also generated in order to ensure that
+the project name, project version and library name that they contain match those
+specified within the top-level `CMakeLists.txt` file.
+
+If you'd like to cross compile the library for different platforms you can do so
+using [cross](https://github.com/cross-rs/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](https://github.com/cross-rs/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, CMake generates the `automerge.h` header file in terms of the
+processor architecture of the computer on which it was built so, for example,
+don't use a header generated for a 64-bit processor if your target is a 32-bit
+processor.
+
+# Unicode indexing
+
+By default automerge-c expects string indices to be given in terms of UTF-8 byte
+offsets so, for example, the length of "😀" (U+1F600) is 4.
+
+If instead you need string indices to be given in terms of Unicode code point
+offsets such that the length of "😀" (U+1F600) will be 1, build it like so:
+
+`cmake -S automerge-c -B automerge-c/build -DUTF32_INDEXING=true`
+
+Regardless of the specified encoding for character indices, automerge-c always
+requires a string to be provided as an `AMbyteSpan` struct that references an
+array of valid UTF-8 code points.
+
+# Usage
+
+You can build and view the C API's HTML reference documentation like so:
+
+```shell
+cmake -E make_directory automerge-c/build
+cmake -S automerge-c -B automerge-c/build
+cmake --build automerge-c/build --target automerge_docs
+firefox automerge-c/build/docs/html/index.html
+```
+
+To get started quickly, look at the
+[examples](https://github.com/automerge/automerge/tree/main/rust/automerge-c/examples).
+
+Almost all operations in automerge-c act on an Automerge document
+(`AMdoc` struct) which is structurally similar to a JSON document.
+
+You can get a document by calling either `AMcreate()` or `AMload()`. Operations
+on a given document are not thread-safe so you must use a mutex or similar to
+avoid calling more than one function on the same one concurrently.
+
+A C API function that could succeed or fail returns a result (`AMresult` struct)
+containing a status code (`AMstatus` enum) and either a sequence of at least one
+item (`AMitem` struct) or a read-only view onto a UTF-8 error message string
+(`AMbyteSpan` struct).
+An item contains up to three components: an index within its parent object
+(`AMbyteSpan` struct or `size_t`), a unique identifier (`AMobjId` struct) and a
+value.
+The result of a successful function call that doesn't produce any values will
+contain a single item that is void (`AM_VAL_TYPE_VOID`).
+A returned result **must** be passed to `AMresultFree()` once the item(s) or
+error message it contains is no longer needed in order to avoid a memory leak.
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <automerge-c/automerge.h>
+#include <automerge-c/utils/string.h>
+
+int main(int argc, char** argv) {
+  AMresult *docResult = AMcreate(NULL);
+
+  if (AMresultStatus(docResult) != AM_STATUS_OK) {
+    char* const err_msg = AMstrdup(AMresultError(docResult), NULL);
+    printf("failed to create doc: %s", err_msg);
+    free(err_msg);
+    goto cleanup;
+  }
+
+  AMdoc *doc;
+  AMitemToDoc(AMresultItem(docResult), &doc);
+
+  // useful code goes here!
+
+cleanup:
+  AMresultFree(docResult);
+}
+```
+
+If you are writing an application in C, the `AMstackItem()`, `AMstackItems()`
+and `AMstackResult()` functions enable the lifetimes of anonymous results to be
+centrally managed and allow the same validation logic to be reused without
+relying upon the `goto` statement (see examples/quickstart.c).
+
+If you are wrapping automerge-c in another language, particularly one that has a
+garbage collector, you can call the `AMresultFree()` function within a finalizer
+to ensure that memory is reclaimed when it is no longer needed.
+
+An Automerge document consists of a mutable root which is always a map from
+string keys to values. A value can be one of the following types:
+
+- A number of type double / int64_t / uint64_t
+- An explicit true / false / null
+- An immutable UTF-8 string (`AMbyteSpan` struct).
+- An immutable array of arbitrary bytes (`AMbyteSpan` struct).
+- A mutable map from string keys to values.
+- A mutable list of values.
+- A mutable UTF-8 string.
+
+If you read from a location in the document with no value, an item with type
+`AM_VAL_TYPE_VOID` will be returned, but you cannot write such a value
+explicitly.
+
+Under the hood, automerge references a mutable object by its object identifier
+where `AM_ROOT` signifies a document's root map object.
+
+There are functions to put each type of value into either a map or a list, and
+functions to read the current or a historical value from a map or 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 `AMitem` struct
+that you can inspect to determine the type of value that it contains.
+
+Strings in automerge-c are represented using an `AMbyteSpan` struct which
+contains a pointer and a length. Strings must be valid UTF-8 and may contain
+NUL (`0`) characters.
+For your convenience, you can call `AMstr()` to get an `AMbyteSpan` struct
+referencing a null-terminated byte string or `AMstrdup()` to get the
+representation of an `AMbyteSpan` struct as a null-terminated byte string
+wherein its NUL characters have been removed/replaced as you choose.
+
+Putting all of that together, to read and write from the root of the document
+you can do this:
+
+```
+#include <stdio.h>
+#include <stdlib.h>
+#include <automerge-c/automerge.h>
+#include <automerge-c/utils/string.h>
+
+int main(int argc, char** argv) {
+  // ...previous example...
+  AMdoc *doc;
+  AMitemToDoc(AMresultItem(docResult), &doc);
+
+  AMresult *putResult = AMmapPutStr(doc, AM_ROOT, AMstr("key"), AMstr("value"));
+  if (AMresultStatus(putResult) != AM_STATUS_OK) {
+    char* const err_msg = AMstrdup(AMresultError(putResult), NULL);
+    printf("failed to put: %s", err_msg);
+    free(err_msg);
+    goto cleanup;
+  }
+
+  AMresult *getResult = AMmapGet(doc, AM_ROOT, AMstr("key"), NULL);
+  if (AMresultStatus(getResult) != AM_STATUS_OK) {
+    char* const err_msg = AMstrdup(AMresultError(getResult), NULL);
+    printf("failed to get: %s", err_msg);
+    free(err_msg);
+    goto cleanup;
+  }
+
+  AMbyteSpan got;
+  if (AMitemToStr(AMresultItem(getResult), &got)) {
+    char* const c_str = AMstrdup(got, NULL);
+    printf("Got %zu-character string \"%s\"", got.count, c_str);
+    free(c_str);
+  } else {
+    printf("expected to read a string!");
+    goto cleanup;
+  }
+
+
+cleanup:
+  AMresultFree(getResult);
+  AMresultFree(putResult);
+  AMresultFree(docResult);
+}
+```
+
+Functions that do not return an `AMresult` (for example `AMitemKey()`) do
+not allocate memory but rather reference memory that was previously
+allocated. It's therefore important to keep the original `AMresult` alive (in
+this case the one returned by `AMmapRange()`) until after you are finished with
+the items that it contains. However, the memory for an individual `AMitem` can
+be shared with a new `AMresult` by calling `AMitemResult()` on it. In other
+words, a select group of items can be filtered out of a collection and only each
+one's corresponding `AMresult` must be kept alive from that point forward; the
+originating collection's `AMresult` can be safely freed.
+
+Beyond that, good luck!