From 12e2677af6f761140a6e959672b8057146d1b12b Mon Sep 17 00:00:00 2001 From: Ziyang Hu Date: Sat, 26 Nov 2022 22:53:00 +0800 Subject: [PATCH] update docs --- BUILDING.md | 35 ------------------------------- cozo-lib-c/README.md | 34 +++++++++++------------------- cozo-lib-c/example.c | 2 +- cozo-lib-java/CozoJavaBridge.java | 8 ------- cozo-lib-java/README.md | 16 ++++++++++++++ cozo-lib-java/build.sh | 8 ------- cozoserver/README.md | 35 +++++++++++++++++++++++++++---- 7 files changed, 60 insertions(+), 78 deletions(-) delete mode 100644 BUILDING.md create mode 100644 cozo-lib-java/README.md delete mode 100755 cozo-lib-java/build.sh diff --git a/BUILDING.md b/BUILDING.md deleted file mode 100644 index 743b16ad..00000000 --- a/BUILDING.md +++ /dev/null @@ -1,35 +0,0 @@ -# Building Cozo from source - -You need to install the [Rust toolchain](https://www.rust-lang.org/tools/install) on your system. -You also need a C++17 compiler. - -Clone the Cozo git repo: - -```bash -git clone https://github.com/cozodb/cozo.git --recursive -``` - -You need to pass the `--recursive` flag so that submodules are also cloned. -Next, run in the root of the cloned repo: - -```bash -cargo build --release -``` - -Wait for potentially a long time, and you will find the compiled binary in `target/release`. - -You can run `cargo build --release -F jemalloc` instead -to indicate that you want to compile and use jemalloc as the memory allocator for the RocksDB storage backend, -which can make a difference in performance depending on your workload. - -To build the C library: - -```bash -cargo build --release --manifest-path=cozo-lib-c/Cargo.toml -``` - -To build the Java library used by [cozo-lib-java](https://github.com/cozodb/cozo-lib-java): - -```bash -cargo build --release --manifest-path=cozo-lib-java/Cargo.toml -``` \ No newline at end of file diff --git a/cozo-lib-c/README.md b/cozo-lib-c/README.md index 26e9987f..9b72cb7f 100644 --- a/cozo-lib-c/README.md +++ b/cozo-lib-c/README.md @@ -2,39 +2,29 @@ This directory contains the source of the Cozo C API. -For building, refer [here](../BUILDING.md). +This document describes how to set up the C library. +To learn how to use CozoDB (CozoScript), follow +the [tutorial](https://nbviewer.org/github/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb) +first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries +described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/). + +You can download pre-built libraries from the [release page](https://github.com/cozodb/cozo/releases), +look for those starting with `libcozo_c`. The API is contained in this single [header file](./cozo_c.h). An example for using the API is [here](./example.c). To build and run the example: + ```bash gcc -L../target/release/ -lcozo_c example.c -o example && ./example ``` -## Building for iOS - -See [this guide](https://blog.mozilla.org/data/2022/01/31/this-week-in-glean-building-and-deploying-a-rust-library-on-ios/) -for detailed instructions on compilation for iOS. +# Building Cozo from source -All scripts are run from this directory. - -For iOS devices: +You need to install the [Rust toolchain](https://www.rust-lang.org/tools/install) on your system. Then: ```bash -ARCHS=arm64 ./comiple-ios.sh cozo_c release +cargo build --release -p cozo_c -F compact -F storage-rocksdb ``` - -For simulator on Apple ARM: -```bash -IS_SIMULATOR=1 ARCHS=arm64 ./comiple-ios.sh cozo_c release -``` - -For simulator on x86-64: -```bash -IS_SIMULATOR=1 ARCHS=x86_64 ./comiple-ios.sh cozo_c release -``` - -The libraries are then found in `../target` subdirectories. The static libraries can then be linked into -your iOS applications. \ No newline at end of file diff --git a/cozo-lib-c/example.c b/cozo-lib-c/example.c index 17942d1a..7c11c7f8 100644 --- a/cozo-lib-c/example.c +++ b/cozo-lib-c/example.c @@ -19,7 +19,7 @@ void run_query(int32_t db_id, const char *query) { int main() { int32_t db_id; - char *err = cozo_open_db("_test_db", &db_id); + char *err = cozo_open_db("mem", "", "{}", &db_id); if (err) { printf("%s", err); diff --git a/cozo-lib-java/CozoJavaBridge.java b/cozo-lib-java/CozoJavaBridge.java index 47b2c203..0b0f71cd 100644 --- a/cozo-lib-java/CozoJavaBridge.java +++ b/cozo-lib-java/CozoJavaBridge.java @@ -9,12 +9,4 @@ public class CozoJavaBridge { private static native String backup(int id, String file); private static native String restore(int id, String file); private static native String importFromBackup(int id, String data); - - static { - System.loadLibrary("cozo_java"); - } - - public static void main(String[] args) { - System.out.println("OK"); - } } \ No newline at end of file diff --git a/cozo-lib-java/README.md b/cozo-lib-java/README.md new file mode 100644 index 00000000..281a864b --- /dev/null +++ b/cozo-lib-java/README.md @@ -0,0 +1,16 @@ +# Cozo-lib-java + +This crate provides the JNI bindings for using Cozo in Java/JVM languages/Android. + +You do not use this crate directly. Instead, use: + +* ... for Android +* ... for Java or other JVM languages +* ... for Clojure on JVM (you can also use the Java library, but this one is nicer) + +## Building + +With the Rust toolchain installed, +```bash +cargo build --release -p cozo_java -F compact -F storage-rocksdb +``` \ No newline at end of file diff --git a/cozo-lib-java/build.sh b/cozo-lib-java/build.sh deleted file mode 100755 index d73788a2..00000000 --- a/cozo-lib-java/build.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env bash - -cross build -p cozo_java --release --target=aarch64-linux-android -cross build -p cozo_java --release --target=armv7-linux-androideabi -cross build -p cozo_java --release --target=i686-linux-android -cross build -p cozo_java --release --target=x86_64-linux-android -cross build -p cozo_java --release -F storage-rocksdb --target=aarch64-unknown-linux-gnu -cross build -p cozo_java --release -F storage-rocksdb --target=x86_64-unknown-linux-gnu \ No newline at end of file diff --git a/cozoserver/README.md b/cozoserver/README.md index 1e5b2d27..b4131254 100644 --- a/cozoserver/README.md +++ b/cozoserver/README.md @@ -3,17 +3,23 @@ The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases) (look for those with names `cozoserver-*`). +This document describes how to set up cozoserver. +To learn how to use CozoDB (CozoScript), follow +the [tutorial](https://nbviewer.org/github/cozodb/cozo-docs/blob/main/tutorial/tutorial.ipynb) +first and then read the [manual](https://cozodb.github.io/current/manual/). You can run all the queries +described in the tutorial with an in-browser DB [here](https://cozodb.github.io/wasm-demo/). + ## Starting the server Run the cozoserver command in a terminal: ```bash -./cozoserver +./cozoserver ``` -If `` does not exist, it will be created. -Cozo will then start a web server and bind to address 127.0.0.1 and port 9070. -These two can be customized: run the executable with the -h option to learn how. +This starts an in-memory, non-persistent database. +For more options such as how to run a persistent database with other storage engines, +see `./cozoserver -h` To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`. @@ -49,3 +55,24 @@ and a nicely-formatted diagnostic will be in `"display"` if available. > non-default binding will tell you where to find the token string. > This “security measure” is not considered sufficient for any purpose > and is only intended as a last defence against carelessness. + +## API + +* `POST /text-query`, described above. +* `GET /export/{relations: String}`, where `relations` is a comma-separated list of relations to export. + The query parameter `as_objects` can change the output format. +* `PUT /import`, import data into the database. Data should be in `application/json` MIME type in the body, + in the same format as returned in the `data` field in the `/export` API. +* `POST /backup`, backup database, should supply a JSON body of the form `{"path": }` +* `POST /import-from-backup`, import data into the database from a backup. Should supply a JSON body + of the form `{"path": , "relations": }`. +* `GET /`, if you open this in your browser and open your developer tools, you will be able to use + a very simple client to query this database. + +## Building + +Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run + +```bash +cargo build --release -p cozoserver -F compact -F storage-rocksdb +```