readcon-core 0.14.8

An oxidized single and multiple CON file reader and writer with FFI bindings for ergonomic C/C++ usage. Implements CON spec v3.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# ReadCon.jl

Thin `ccall` bindings over `libreadcon_core` (same ABI as `include/readcon-core.h`).

## Library search order

1. `READCON_CORE_LIB` (CI and this README)
2. `READCON_LIB_PATH` (alias used in older docs)
3. A filled `Artifacts.toml` `readcon_core` artifact (from the
   `readcon-core-clib-$VER-$target.tar.gz` GitHub Release asset)
4. In-tree `target/{release,debug}/libreadcon_core.{so,dylib}`

## Prebuilt C ABI (no local cargo)

Dispatch `.github/workflows/c_lib_tarball.yml` with `tag=vX.Y.Z` (or wait
for the `release` hook) and unpack the matching asset:

```bash
VER=0.14.8
TARGET=x86_64-unknown-linux-gnu   # or aarch64-unknown-linux-gnu, *-apple-darwin
curl -fsSL -O "https://github.com/lode-org/readcon-core/releases/download/v${VER}/readcon-core-clib-${VER}-${TARGET}.tar.gz"
tar -xzf "readcon-core-clib-${VER}-${TARGET}.tar.gz"
export READCON_CORE_LIB="$PWD/readcon-core-clib-${VER}-${TARGET}/lib/libreadcon_core.so"
export JULIA_LOAD_PATH="$PWD/julia/ReadCon:${JULIA_LOAD_PATH:-}"
```

Windows + chemfiles is **not** a clib asset. Use the `readcon-chemfiles`
wheel, or a Linux/macOS tarball.

`Artifacts.toml.in` is the template; `scripts/package-clib.sh` writes
`Artifacts-$target.toml` next to the tarball.

## Run tests locally

1. Build the shared library from the **repository root**, or point at a
   prebuilt clib tarball:

   ```bash
   cargo build --release --features chemfiles
   # optional fat matrix: chemfiles,zstd,metatensor
   export READCON_CORE_LIB="$PWD/target/release/libreadcon_core.so"
   export JULIA_LOAD_PATH="$PWD/julia/ReadCon:$JULIA_LOAD_PATH"
   ```

2. From `julia/ReadCon` (or with `JULIA_PROJECT` set):

   ```bash
   julia --project=. -e 'using Pkg; Pkg.test()'
   # test/test_conformance_goldens.jl locks resources/conformance against golden/*.json
   ```

If `libreadcon_core` is not on `LD_LIBRARY_PATH` / `READCON_CORE_LIB`, tests that
touch the FFI **fail fast** with a clear load error (they do not silently skip
ABI checks). Pure Julia struct layout tests in `test/runtests.jl` still run.

## General registry

This package is not on Julia General yet. The `uuid` in `Project.toml` is
the package identity for a future Registrator.jl submission from a
`vX.Y.Z` tag (comment `@JuliaRegistrator register()` on that commit).
Do not change the uuid after the first General registration.

## CI

Workflow `.github/workflows/ci_julia.yml` runs when Julia is available on the
runner: builds `libreadcon_core` with `chemfiles`, exports `READCON_CORE_LIB`,
then `Pkg.test()`. Agents without Julia should treat missing `julia` as an
environment limit, not an API gap—the package sources and tests remain in-tree.