Install
=======

Rust (crates.io)
----------------

.. code:: bash

   cargo add readcon-db
   # library + CLI binary from the same crate:
   cargo install readcon-db --locked

Requires `readcon-core <https://crates.io/crates/readcon-core>`__ **0.14** (pulled automatically).

Python (PyPI)
-------------

.. code:: bash

   pip install readcon-db
   python -c "import readcon_db"

Install `readcon <https://pypi.org/project/readcon/>`__ (core) as well when you need CON parse/write outside the corpus API.

From source (developers)
------------------------

.. code:: bash

   git clone https://github.com/lode-org/readcon-db
   cd readcon-db
   cargo test --locked
   cargo build --release   # libreadcon_db + CLI readcon-db

``readcon-core`` comes from crates.io (``^0.14``). To develop against a local core tree, add an **untracked** ``.cargo/config.toml``:

.. code:: toml

   [patch.crates-io]
   readcon-core = { path = "../readcon-core" }

Python extension from a checkout:

.. code:: bash

   pip install maturin
   maturin develop --release --features python --manifest-path python/pyproject.toml

C / C++ (no cbindgen)
---------------------

``include/readcon-db.h`` is hand-written and shipped. Optional ``include/readcon-db-mpi.h`` takes the caller's ``MPI_Comm`` (not linked into the library). CMake FetchContent, Meson wrap, and ``pkg-config`` do **not** run cbindgen.

CMake:

.. code:: cmake

   include(FetchContent)
   FetchContent_Declare(
     readcon-db
     URL https://github.com/lode-org/readcon-db/releases/download/v0.1.8/readcon-db-cxx-0.1.8.tar.gz
     URL_HASH SHA256=<sha256 from the .sha256 sidecar on the GitHub Release>
   )
   FetchContent_MakeAvailable(readcon-db)
   target_link_libraries(app PRIVATE readcon-db::shared)

From a checkout:

.. code:: bash

   cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$PWD/prefix
   cmake --build build && cmake --install build
   export PKG_CONFIG_PATH=$PWD/prefix/lib/pkgconfig
   pkg-config --cflags --libs readcon-db

Meson: ``dependency('readcon-db')`` with a wrap pointing at ``readcon-db-cxx-$VERSION.tar.gz`` (see ``packaging/wrapdb/``).

A process that uses both C APIs must link the **shared** objects (``libreadcon_db.so`` and ``libreadcon_core.so``). Do not static-link ``libreadcon_db.a`` together with ``libreadcon_core.a``: the db archive already contains the Rust core and rust-std, and the duplicate symbols fail at link.

Prebuilt C ABI (no local cargo)
-------------------------------

Unpack ``readcon-db-clib-$VERSION-$target.tar.gz`` from the GitHub Release, then ``export READCON_DB_LIB`` / ``PKG_CONFIG_PATH``. Attach assets to an already-published tag with Actions → **C ABI library tarball** → ``tag=vX.Y.Z``.

.. code:: bash

   VER=0.1.8
   TARGET=x86_64-unknown-linux-gnu
   curl -fsSL -O "https://github.com/lode-org/readcon-db/releases/download/v${VER}/readcon-db-clib-${VER}-${TARGET}.tar.gz"
   tar -xzf "readcon-db-clib-${VER}-${TARGET}.tar.gz"
   PREFIX="$PWD/readcon-db-clib-${VER}-${TARGET}"
   export PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig:${PKG_CONFIG_PATH:-}"
   export LD_LIBRARY_PATH="$PREFIX/lib:${LD_LIBRARY_PATH:-}"
   export READCON_DB_LIB="$PREFIX/lib/libreadcon_db.so"
   pkg-config --cflags --libs readcon-db

The cxx tarball still needs rustc/cargo. The clib tarball is the Fortran / C path that does not.

Fortran
-------

``fortran/ReadConDb`` (``bind(C)`` against the C ABI). Notes: ``fortran/README.md``. Smoke after unpacking the clib prefix:

.. code:: bash

   cd fortran/ReadConDb
   fpm build --flag "$(pkg-config --cflags readcon-db)" \
     --link-flag "$(pkg-config --libs readcon-db) -ldl -lpthread -lm"

From a checkout (after a release build of the cdylib):

.. code:: bash

   cd fortran/ReadConDb && fpm build --flag "-I../../include" \
     --link-flag "-L../../target/release -lreadcon_db -ldl -lpthread -lm"

Campaign shard/drain/join is the ``readcon-db`` CLI (in ``bin/`` of the clib tarball when the Release build produced it). See :doc:`/howto/campaign`.

Documentation
-------------

-  Landing page: https://lode-org.github.io/readcon-db/
-  Full docs: https://lode-org.github.io/readcon-db/docs/
-  Design notes: :doc:`/explanation/design`

.. code:: bash

   pixi r -e docs docbld

``pixi.lock`` pins Sphinx, Furo, and MyST to the same set Pages publishes. Refresh with ``pixi lock`` after editing ``pixi.toml`` ``[feature.docs]``.

Static marketing page
---------------------

Open ``website/index.html`` (or serve ``website/``). Logos under ``assets/logo/``.