From 285c9a57ad7a556e58405a5f73169a76f198cfd7 Mon Sep 17 00:00:00 2001 From: Ziyang Hu Date: Tue, 3 Jan 2023 20:06:08 +0800 Subject: [PATCH] update docs --- README-zh.md | 26 ++--- cozo-core/src/lib.rs | 5 +- cozo-lib-c/README.md | 4 +- cozo-lib-java/README-zh.md | 6 +- cozo-lib-nodejs/README-zh.md | 93 +++++++++-------- cozo-lib-nodejs/README.md | 8 +- cozo-lib-python/README-zh.md | 13 +-- cozo-lib-python/README.md | 2 +- cozo-lib-swift/README-zh.md | 110 ++++++++------------- cozo-lib-swift/README.md | 8 +- cozo-lib-wasm/README-zh.md | 51 +++------- cozo-lib-wasm/README.md | 4 +- cozo-lib-wasm/wasm-react-demo/README-zh.md | 3 + cozoserver/README-zh.md | 90 ++++++----------- cozoserver/README.md | 6 +- 15 files changed, 168 insertions(+), 261 deletions(-) create mode 100644 cozo-lib-wasm/wasm-react-demo/README-zh.md diff --git a/README-zh.md b/README-zh.md index 772c4a7e..3a52c0c4 100644 --- a/README-zh.md +++ b/README-zh.md @@ -168,19 +168,19 @@ end[] <- [['YPO]] Cozo 可以安装在一大堆不同的语言与环境中： -| 语言/环境 | 官方支持的平台 | 存储引擎 | -|-------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------| -| [Python](https://github.com/cozodb/pycozo) | Linux (x86_64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [NodeJS](./cozo-lib-nodejs) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [浏览器](./cozo-lib-wasm) | 支持[WASM](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility)的浏览器（较新的浏览器全都支持） | M | -| [Java (JVM)](https://github.com/cozodb/cozo-lib-java) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [Clojure (JVM)](https://github.com/cozodb/cozo-clj) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [安卓](https://github.com/cozodb/cozo-lib-android) | Android (ARM64, ARMv7, x86_64, x86) | MQ | -| [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ | -| [Rust](https://docs.rs/cozo/) | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)（源代码编译） | MQRST | -| [Go](https://github.com/cozodb/cozo-lib-go) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [C/C++/支持C FFI的语言](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | -| [独立的HTTP服务](./cozoserver) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST | +| 语言/环境 | 官方支持的平台 | 存储引擎 | +|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-------| +| [Python](https://github.com/cozodb/pycozo)（[国内镜像](https://gitee.com/cozodb/pycozo)） | Linux (x86_64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [NodeJS](./cozo-lib-nodejs) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [浏览器](./cozo-lib-wasm) | 支持[WASM](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility)的浏览器（较新的浏览器全都支持） | M | +| [Java (JVM)](https://github.com/cozodb/cozo-lib-java)（[国内镜像](https://gitee.com/cozodb/cozo-lib-java)） | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [Clojure (JVM)](https://github.com/cozodb/cozo-clj)（[国内镜像](https://gitee.com/cozodb/cozo-clj)） | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [安卓](https://github.com/cozodb/cozo-lib-android)（[国内镜像](https://gitee.com/cozodb/cozo-lib-android)） | Android (ARM64, ARMv7, x86_64, x86) | MQ | +| [iOS/macOS (Swift)](./cozo-lib-swift) | iOS (ARM64, 模拟器), Mac (ARM64, x86_64) | MQ | +| [Rust](https://docs.rs/cozo/) | 任何支持`std`的[平台](https://doc.rust-lang.org/nightly/rustc/platform-support.html)（源代码编译） | MQRST | +| [Go](https://github.com/cozodb/cozo-lib-go)（[国内镜像](https://gitee.com/cozodb/cozo-lib-go)） | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [C/C++/支持 C FFI 的语言](./cozo-lib-c) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQR | +| [独立的 HTTP 服务](./cozoserver) | Linux (x86_64, ARM64), Mac (ARM64, x86_64), Windows (x86_64) | MQRST | “存储引擎”列中各个字母的含义： diff --git a/cozo-core/src/lib.rs b/cozo-core/src/lib.rs index be296054..4fcff6b8 100644 --- a/cozo-core/src/lib.rs +++ b/cozo-core/src/lib.rs @@ -11,10 +11,7 @@ //! //! This doc describes the Rust API. To learn how to use CozoDB to query (CozoScript), see: //! -//! * [CozoScript Manual](https://docs.cozodb.org) -//! -//! You can run all the queries described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/) -//! without installing anything. +//! * [The CozoDB documentation](https://docs.cozodb.org) //! //! Rust API usage: //! ``` diff --git a/cozo-lib-c/README.md b/cozo-lib-c/README.md index f9665a6e..3cfc0570 100644 --- a/cozo-lib-c/README.md +++ b/cozo-lib-c/README.md @@ -5,9 +5,7 @@ This directory contains the source of the Cozo C API. This document describes how to set up the C library. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html). You can download pre-built libraries from the [release page](https://github.com/cozodb/cozo/releases), look for those starting with `libcozo_c`. diff --git a/cozo-lib-java/README-zh.md b/cozo-lib-java/README-zh.md index 0c12bacf..0a0b669a 100644 --- a/cozo-lib-java/README-zh.md +++ b/cozo-lib-java/README-zh.md @@ -4,9 +4,9 @@ 一般情况下，这个库不是直接使用的。用于应当使用以下调用此库的库： -* [Cozo Java](https://github.com/cozodb/cozo-lib-java)：在 JVM Java 中使用 -* [Cozo Clojure](https://github.com/cozodb/cozo-clj)：在 JVM Clojure 中使用 -* [Cozo Android](https://github.com/cozodb/cozo-lib-android)：在安卓中使用 +* [Cozo Java](https://github.com/cozodb/cozo-lib-java) （[镜像](https://gitee.com/cozodb/cozo-lib-java)）：在 JVM Java 中使用 +* [Cozo Clojure](https://github.com/cozodb/cozo-clj) （[镜像](https://gitee.com/cozodb/cozo-clj)）：在 JVM Clojure 中使用 +* [Cozo Android](https://github.com/cozodb/cozo-lib-android) （[镜像](https://gitee.com/cozodb/cozo-lib-android)）：在安卓中使用 下面几个小节介绍在上面几个库不支持你的平台时如何从源码编译此库。 diff --git a/cozo-lib-nodejs/README-zh.md b/cozo-lib-nodejs/README-zh.md index b79bf53b..fc849473 100644 --- a/cozo-lib-nodejs/README-zh.md +++ b/cozo-lib-nodejs/README-zh.md @@ -2,23 +2,27 @@ [![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node) -Embedded [CozoDB](https://github.com/cozodb/cozo) for NodeJS. +NodeJS 的嵌入式 [CozoDB](https://www.cozodb.org) 库。 -This document describes how to set up the Cozo module for use in NodeJS. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +本文叙述的是如何安装设置库本身。有关如何使用 CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。 -## Installation +## 安装 ```bash npm install --save cozo-node ``` -If that doesn't work because there are no precompiled binaries for your platform, -scroll below to the building section. +安装过程中需要从 [GitHub 发布页](https://github.com/cozodb/cozo-lib-nodejs/releases/tag/0.4.0) 下载二进制文件。如果因为网络问题失败，可以使用此 [镜像](https://github.com/cozodb/cozo-lib-nodejs/releases/tag/0.4.0) ，使用方法为 -## Usage +```bash +npm install --save cozo-node --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/ +``` + +注意：如果你用的是 Yarn 而不是 NPM，类似的命令 [可能不奏效](https://github.com/mapbox/node-pre-gyp/issues/514) 。 + +如果你的操作系统、平台不是常见的平台，可能会报错说找不到预编译库。这种情况下可以参见后面关于如何从源码编译的内容。 + +## 用法 ```javascript const {CozoDb} = require('cozo-node') @@ -41,93 +45,84 @@ printQuery("?[a] <- [[1, 2]]") ```ts class CozoDb { /** - * Constructor + * 构造函数 * - * @param engine: defaults to 'mem', the in-memory non-persistent engine. - * 'sqlite', 'rocksdb' and maybe others are available, - * depending on compile time flags. - * @param path: path to store the data on disk, defaults to 'data.db', - * may not be applicable for some engines such as 'mem' - * @param options: defaults to {}, ignored by all the engines in the published NodeJS artefact + * @param engine: 默认为 'mem'，即纯内存的非持久化存储。其他值可以是 'sqlite'、'rocksdb' 等 + * @param path: 存储文件或文件夹的路径，默认为 'data.db'。在 'mem' 引擎下无用。 + * @param options: 默认为 {}，在 NodeJS 支持的引擎中无用。 */ constructor(engine: string, path: string, options: object): CozoDb; /** - * You must call this method for any database you no longer want to use: - * otherwise the native resources associated with it may linger for as - * long as your program runs. Simply `delete` the variable is not enough. + * 关闭数据库，并释放其原生资源。如果不调用此方法而直接删除数据库的变量，则会造成原生资源泄漏。 */ close(): void; /** - * Runs a query + * 执行查询文本 * - * @param script: the query - * @param params: the parameters as key-value pairs, defaults to {} + * @param script: 查询文本 + * @param params: 传入的参数，默认为 {} */ async run(script: string, params: object): object; /** - * Export several relations + * 导出存储表 * - * @param relations: names of relations to export, in an array. + * @param relations: 需要导出的存储表名称 */ async exportRelations(relations: Array): object; /** - * Import several relations. + * 导入数据至存储表 * - * Note that triggers are _not_ run for the relations, if any exists. - * If you need to activate triggers, use queries with parameters. + * 注意：以此方法导入数据不会激活存储表上任何的触发器。 * - * @param data: in the same form as returned by `exportRelations`. The relations - * must already exist in the database. + * @param data: 导入的表以及数据，格式与 `exportRelations` 返回的相同 */ async importRelations(data: object): object; /** - * Backup database + * 备份数据库 * - * @param path: path to file to store the backup. + * @param path: 备份文件路径 */ async backup(path: string): object; /** - * Restore from a backup. Will fail if the current database already contains data. + * 从备份文件恢复数据至当前数据库。若当前数据库非空，则报错。 * - * @param path: path to the backup file. + * @param path: 备份文件路径 */ async restore(path: string): object; /** - * Import several relations from a backup. The relations must already exist in the database. - * - * Note that triggers are _not_ run for the relations, if any exists. - * If you need to activate triggers, use queries with parameters. - * - * @param path: path to the backup file. - * @param rels: the relations to import. + * 将备份文件中指定存储表里的数据插入当前数据库中同名表里。 + * + * 注意：以此方法导入数据不会激活存储表上任何的触发器。 + * + * @param path: 备份文件路径 + * @param rels: 需导入数据的表名 */ async importRelationsFromBackup(path: string, rels: Array): object; } ``` -## Building +更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。 + +## 编译 -Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run +编译 `cozo-node` 需要 [Rust 工具链](https://rustup.rs)。运行 ```bash cargo build --release -p cozo-node -F compact -F storage-rocksdb ``` -and then find the dynamic library (names can vary a lot, the file extension is `.so` on Linux, `.dylib` on Mac, -and `.dll` on Windows) under the `../target/` folder (you may need to search for it). -Copy it to the file `native/6/cozo_node_prebuilt.node` under this directory (create intermediate directories if they don't exist). +完成后，动态链接库可以在 `../target/` 文件夹中找到（具体文件名根据平台与操作系统会有差异，一般来说 Linux 上 扩展名为 `.so`，Mac 上为 `.dylib`，Windows 上为 `.dll`）。 +将找到的动态库拷贝为此目录下的 `native/6/cozo_node_prebuilt.node` 文件（中间目录若不存在，则需建立）。 -If you did everything correctly, you should get the hello world message printed out when you run +如果一切操作正确，在此目录下执行下列命令则会正常返回： ```bash node example.js -``` - -under this directory. \ No newline at end of file +``` \ No newline at end of file diff --git a/cozo-lib-nodejs/README.md b/cozo-lib-nodejs/README.md index e4b0db16..6032f499 100644 --- a/cozo-lib-nodejs/README.md +++ b/cozo-lib-nodejs/README.md @@ -2,12 +2,10 @@ [![cozo-node](https://img.shields.io/npm/v/cozo-node)](https://www.npmjs.com/package/cozo-node) -Embedded [CozoDB](https://github.com/cozodb/cozo) for NodeJS. +Embedded [CozoDB](https://www.cozodb.org) for NodeJS. This document describes how to set up the Cozo module for use in NodeJS. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html). ## Installation @@ -112,6 +110,8 @@ class CozoDb { } ``` +More information are [here](https://docs.cozodb.org/en/latest/nonscript.html). + ## Building Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run diff --git a/cozo-lib-python/README-zh.md b/cozo-lib-python/README-zh.md index cd967b42..9198be8e 100644 --- a/cozo-lib-python/README-zh.md +++ b/cozo-lib-python/README-zh.md @@ -2,19 +2,14 @@ [![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/) -Native bindings for embedding [CozoDB](https://github.com/cozodb/cozo) in Python, providing the -`cozo_embedded` package. +[CozoDB](https://www.cozodb.org) 的 Python 嵌入式库 `cozo_embedded` 的源代码。 -You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo), -which depends on this package. +一般来说你应该使用 [PyCozo](https://github.com/cozodb/pycozo) 库（ [Gitee 镜像](https://gitee.com/cozodb/pycozo) ），而不是直接使用此库。 -To build this package, you need to install the Rust toolchain -as well as the [maturin](https://github.com/PyO3/maturin) python package. -Then run +编译此库需要安装 Rust 工具链以及 [maturin](https://github.com/PyO3/maturin) 。安装好后运行 ```bash maturin build -F compact -F storage-rocksdb --release ``` -Refer maturin's docs for more information about how to [develop](https://www.maturin.rs/develop.html) -and [build](https://www.maturin.rs/distribution.html) this package. \ No newline at end of file +更多选项参见 maturin 的 [文档](https://www.maturin.rs/) 。 \ No newline at end of file diff --git a/cozo-lib-python/README.md b/cozo-lib-python/README.md index 447564e1..165c45d4 100644 --- a/cozo-lib-python/README.md +++ b/cozo-lib-python/README.md @@ -2,7 +2,7 @@ [![pypi](https://img.shields.io/pypi/v/cozo_embedded)](https://pypi.org/project/cozo_embedded/) -Native bindings for embedding [CozoDB](https://github.com/cozodb/cozo) in Python, providing the +Native bindings for embedding [CozoDB](https://www.cozodb.org) in Python, providing the `cozo_embedded` package. You are not supposed to be using this package directly in your code. Use [PyCozo](https://github.com/cozodb/pycozo), diff --git a/cozo-lib-swift/README-zh.md b/cozo-lib-swift/README-zh.md index decf2bb3..75124a4f 100644 --- a/cozo-lib-swift/README-zh.md +++ b/cozo-lib-swift/README-zh.md @@ -2,18 +2,13 @@ [![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift) -This document describes how to set up the Cozo module for use in Swift on Apple hardware. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +本文叙述的是如何安装设置库本身。有关如何使用 CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。 -This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators). +本库可在 macOS（苹果 ARM 或 Intel 芯片）以及 iOS（iPad、iPhone、模拟器）中使用。 -Only the `storage-sqlite` engine is enabled for the Swift prebuilt binaries, as using -other storage engines on desktop or mobile does not make too much sense. If you disagree, -see the Building section below. +预编译的二进制包里，持久化引擎中，只有 `storage-sqlite` 在此库中可用。如果需要其他引擎请从源码编译。 -## Installation +## 安装 ### CocoaPods @@ -27,28 +22,9 @@ end ### Swift Package Manager (SPM) -The package is published as an archive containing a Swift package. -Download it from the [release page](https://github.com/cozodb/cozo/releases) (look for `CozoSwiftBridge.tgz`). -Uncompress. +从 [GitHub 发布页面](https://github.com/cozodb/cozo/releases) 下载名为 `CozoSwiftBridge.tgz` 的包，然后手动导入至 XCode 中。详见 [英文文档](./README.md)。 -In XCode of your project, select from the menu `File > Add Packages`, -select `Add Local ...` on the bottom, choose the folder you just decompressed -(the one containing a `Package.swift` at the root), then click `Add Package`. - -Then click your project on the left pane, and go to -`General > Frameworks, Libraries, and Embedded Content`, -click on the plus sign, and add `Workspace > CozoSwiftBridge > CozoSwiftBridge` -(with a library icon). - -If you did everything right, you should also see `CozoSwiftBridge` under -`Build Phases > Link Binary With Libraries`. - -> You cannot download swift packages directly from GitHub repo, since -in order to support that we would need to check the binaries -into version control, and GitHub does not like it (we tried to work -this around with Git LFS, but no luck). - -## Using the library +## 基本使用 ```swift import CozoSwiftBridge @@ -60,7 +36,9 @@ import CozoSwiftBridge let res = try! db.run("?[] <- [[1,2,3]]").toString() } ``` -Above we created an SQLite-based database. For memory-based ones: + +上例中创建了一个 SQLite 引擎支持的数据库。如果要用纯内存引擎： + ```swift let db = CozoDB() ``` @@ -72,101 +50,93 @@ public class CozoDB { public let db: DbInstance /** - * Constructs an in-memory database. + * 构造一个纯内存引擎的数据库 */ public init(); /** - * Constructs a database. + * 构造一个数据库 * - * `kind`: the engine kind, can be `mem` or `sqlite`. - * `path`: specifies the path to the storage file, only used for `sqlite` engine + * `kind`: 引擎类型，`mem` 或 `sqlite`。 + * `path`: 存储文件的路径，仅在 `sqlite` 引擎下有效。 */ public init(kind: String, path: String) throws; /** - * Run query against the database. + * 执行查询文本 * - * `query`: the CozoScript to execute. + * `query`: 查询文本 */ public func run(_ query: String) throws -> [NamedRow]; /** - * Run query against the database. + * 执行查询文本 * - * `query`: the CozoScript to execute. - * `params`: the params of the query in JSON format. + * `query`: 查询文本 + * `params`: 文本中可用的参数 */ public func run(_ query: String, params: JSON) throws -> [NamedRow]; /** - * Export relations as JSON + * 导出纯出表至 JSON * - * `relations`: the stored relations to export + * `relations`: 需导出的表名 */ public func exportRelations(relations: [String]) throws -> JSON; /** - * Import data into relations + * 导入数据至存储表中 * - * Note that triggers are _not_ run for the relations, if any exists. - * If you need to activate triggers, use queries with parameters. + * 注意此方法不会激活任何触发器。 * - * `data`: the payload, in the same format as returned by `exportRelations`. + * `data`: 导入内容，与 `exportRelations` 返回的格式相同 */ public func importRelations(data: JSON) throws; /** - * Backup the database. + * 备份数据库 * - * `path`: path of the output file. + * `path`: 备份路径 */ public func backup(path: String) throws; /** - * Restore the database from a backup. + * 将备份恢复到当前数据库 * - * `path`: path of the input file. + * `path`: 备份路径 */ public func restore(path: String) throws; /** - * Import data into a relation from a backup. + * 将备份中表里的数据插入当前数据库中选定的同名表中 * - * Note that triggers are _not_ run for the relations, if any exists. - * If you need to activate triggers, use queries with parameters. + * 注意此方法不会激活任何触发器。 * - * `path`: path of the input file. - * `relations`: the stored relations to import into. + * `path`: 备份路径 + * `relations`: 需要导入数据的表名 */ public func importRelationsFromBackup(path: String, relations: [String]) throws; } ``` -## Building the Swift Package +更多信息 [见此](https://docs.cozodb.org/zh_CN/latest/nonscript.html) 。 -First, install the [Rust toolchain](https://rustup.rs). -Then run the [build script](build-rust.sh) in this directory. -It is recommended to also set the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`: -this makes the building process much longer, but in turn the library runs a little bit faster. +## 编译 -When everything goes well, you should find the compiled Swift package in a directory called -`CozoSwiftBridge`. +首先安装 [Rust 工具链](https://rustup.rs)。然后执行 [此批处理文件](build-rust.sh) 。建议执行时设置环境变量`CARGO_PROFILE_RELEASE_LTO=fat`：编译时间会变长，但是生成的库更快。 -If you want to use the RocksDB engine on Desktop, in the build script change the two lines +如果一切都没问题，则 `CozoSwiftBridge` 文件夹里会有编译好的文件。 + +如果想使用 RocksDB 引擎，则在批处理文件中，将以下两行 ```bash cargo build -p cozo-swift -F compact --target x86_64-apple-darwin --release cargo build -p cozo-swift -F compact --target aarch64-apple-darwin --release ``` -to +改为 ```bash cargo build -p cozo-swift -F compact -F storage-rocksdb --target x86_64-apple-darwin --release cargo build -p cozo-swift -F compact -F storage-rocksdb --target aarch64-apple-darwin --release ``` +注意，给 iOS 编译 RocksDB 不是一件简单的事情。 -Then you also need to link your executable with `libc++`: in XCode, click on your project -in the left drawer, then on the right go to `Build phases > Link Binary With Libraries`, -click the plus sign, search for `libc++`, then add `libc++.tbd` found under Apple SDKs. - -Similar same process goes if you want to enable other features. Note that building the -RocksDB engine for mobile is a very demanding task! +在使用生成的库时，需要在 XCode 中选择链接至 `libc++` 动态库。 \ No newline at end of file diff --git a/cozo-lib-swift/README.md b/cozo-lib-swift/README.md index d2370200..22ae2edb 100644 --- a/cozo-lib-swift/README.md +++ b/cozo-lib-swift/README.md @@ -3,13 +3,11 @@ [![pod](https://img.shields.io/cocoapods/v/CozoSwiftBridge)](https://github.com/cozodb/cozo/tree/main/cozo-lib-swift) This document describes how to set up the Cozo module for use in Swift on Apple hardware. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html). This package can be used for MacOS (both Apple ARM and Intel) and iOS (iPad, iPhone and simulators). -Only the `storage-sqlite` engine is enabled for the Swift prebuilt binaries, as using +Only the `storage-sqlite` persistent engine is enabled for the Swift prebuilt binaries, as using other storage engines on desktop or mobile does not make too much sense. If you disagree, see the Building section below. @@ -143,6 +141,8 @@ public class CozoDB { } ``` +More information are [here](https://docs.cozodb.org/en/latest/nonscript.html). + ## Building the Swift Package First, install the [Rust toolchain](https://rustup.rs). diff --git a/cozo-lib-wasm/README-zh.md b/cozo-lib-wasm/README-zh.md index f8555fb8..f7884e9e 100644 --- a/cozo-lib-wasm/README-zh.md +++ b/cozo-lib-wasm/README-zh.md @@ -1,35 +1,26 @@ # Cozo WASM 库（浏览器） -This crate provides Cozo web assembly modules for browsers. -If you are targeting NodeJS, use [this](../cozo-lib-nodejs) instead: -native code is still _much_ faster than WASM. +可以在浏览器中运行的 Cozo WASM 库。NodeJS 用户请使用 [原生库](../cozo-lib-nodejs) ：速度更快，功能也更多。 -This document describes how to set up the Cozo WASM module for use. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +本文叙述的是如何安装设置库本身。有关如何使用 CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。 -## Installation +安装 ``` npm install cozo-lib-wasm ``` -Alternatively, you can download `cozo_wasm--wasm32-unknown-unknown.zip` -from the [release page](https://github.com/cozodb/cozo/releases) and include -the JS and WASM files directly in your project: see the `index.html` example -[here](https://rustwasm.github.io/docs/wasm-bindgen/examples/without-a-bundler.html) for -what is required in your code. +你也可以直接从 [发布页面](https://github.com/cozodb/cozo/releases) 下载 `cozo_wasm--wasm32-unknown-unknown.zip` 文件，然后直接在你的网页代码中引用：见 [此处](https://rustwasm.github.io/docs/wasm-bindgen/examples/without-a-bundler.html) 的 `index.html` 范例。 -## Usage +## 使用 -See the code [here](wasm-react-demo/src/App.js). Basically, you write +参考 [此文件](wasm-react-demo/src/App.js)。简单地说： ```js import init, {CozoDb} from "cozo-lib-wasm"; ``` -and call +然后： ```js let db; @@ -51,36 +42,26 @@ export class CozoDb { export_relations(data: string): string; - // Note that triggers are _not_ run for the relations, if any exists. - // If you need to activate triggers, use queries with parameters. + // 注意：通过此接口载入数据不会激活触发器 import_relations(data: string): string; } ``` -Note that this API is synchronous. If your computation runs for a long time, -**it will block the main thread**. If you know that some of your queries are going to be heavy, -you should consider running Cozo in a web worker. However, the published module -may not work across browsers in web workers (look for the row "Support for ECMAScript -modules" [here](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#browser_compatibility)). +注意所有的 API 都是同步的。如果你的查询需要比较长的时间返回，浏览器的主线程会被阻塞。阻塞浏览器主线程不是好事，因此在这种情况下你可以考虑在 web worker 中运行 Cozo WASM 模块。不过预编译的 WASM 模块不支持在有些浏览器的 web worker 中运行：见 [此页面](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#browser_compatibility) 的 "Support for ECMAScript +modules" 信息。 -The next section contains some pointers for how to alleviate this, but expect a lot of work. +## 编译 -## Compiling +编译需要 [Rust 工具链](https://rustup.rs/)，[NodeJS 与 npm](https://nodejs.org/)，再加上 [wasm-pack](https://github.com/rustwasm/wasm-pack)。 -You will need to install [Rust](https://rustup.rs/), [NodeJS with npm](https://nodejs.org/), -and [wasm-pack](https://github.com/rustwasm/wasm-pack) first. - -The published module was built with +用以下命令来编译： ```bash wasm-pack build --target web --release ``` -and the environment variable `CARGO_PROFILE_RELEASE_LTO=fat`. +建议编译时设置环境变量 `CARGO_PROFILE_RELEASE_LTO=fat` 使生成的库更快（以增加编译时间为代价）。 -The important option is `--target web`: the above usage instructions only work for this target. -See the documentation [here](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target). +以上我们给出了参数 `--target web`：上面在浏览器中的使用例子只支持用此参数编译出的库。更多信息参见 [WASM 的文档](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target)。 -if you are interested in running Cozo in a web worker and expect it to run across browsers, -you will need to use the `--target no-modules` option, and write a lot of gluing code. -See [here](https://rustwasm.github.io/wasm-bindgen/examples/wasm-in-web-worker.html) for tips. \ No newline at end of file +使用 `--target no-modules` 编译出的库可以在更多浏览器中的 web worker 运行，但是调用方式与上面给出的例子有区别，也更麻烦。详情见 [文档](https://rustwasm.github.io/wasm-bindgen/examples/wasm-in-web-worker.html) 。 \ No newline at end of file diff --git a/cozo-lib-wasm/README.md b/cozo-lib-wasm/README.md index dc24738b..9b2f2e29 100644 --- a/cozo-lib-wasm/README.md +++ b/cozo-lib-wasm/README.md @@ -5,9 +5,7 @@ If you are targeting NodeJS, use [this](../cozo-lib-nodejs) instead: native code is still _much_ faster than WASM. This document describes how to set up the Cozo WASM module for use. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html). ## Installation diff --git a/cozo-lib-wasm/wasm-react-demo/README-zh.md b/cozo-lib-wasm/wasm-react-demo/README-zh.md new file mode 100644 index 00000000..568b9737 --- /dev/null +++ b/cozo-lib-wasm/wasm-react-demo/README-zh.md @@ -0,0 +1,3 @@ +# Cozo WASM 示例 + +此示例的展示在 https://www.cozodb.org/wasm-demo/ 。源码供参考。 \ No newline at end of file diff --git a/cozoserver/README-zh.md b/cozoserver/README-zh.md index f7783b35..a09177b2 100644 --- a/cozoserver/README-zh.md +++ b/cozoserver/README-zh.md @@ -2,84 +2,56 @@ [![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases) -This document describes how to set up cozoserver. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +本文叙述的是如何安装设置服务程序本身。有关如何使用 CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。 -## Download +## 下载 -The standalone executable for Cozo can be downloaded from the [release page](https://github.com/cozodb/cozo/releases). -Look for those with names `cozoserver-*`. -Those with names `cozoserver_all-*` supports additional storage backends -such as [TiKV](https://tikv.org/) storage, but are larger. +独立服务的程序可以从 [GitHub 发布页](https://github.com/cozodb/cozo/releases) 或 [Gitee 发布页](https://gitee.com/cozodb/cozo/releases) 下载，其中名为 `cozoserver-*` 的是独立服务程序，名为 `cozoserver_all-*` 的独立程序同时支持更多地存储引擎，比如 [TiKV](https://tikv.org/)。 -## Starting the server +## 启动服务程序 -Run the cozoserver command in a terminal: +在终端中执行： ```bash ./cozoserver ``` -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` +如此执行命令会使用纯内存的非持久化存储引擎。执行 `./cozoserver -h` 可查看如何启用其它引擎，以及其它参数。 -To stop Cozo, press `CTRL-C`, or send `SIGTERM` to the process with e.g. `kill`. +若要终止程序，按下 `CTRL-C` 按键，或向进程发送 `SIGTERM` （比如通过 `kill` 命令）。 -## The query API +## 查询 API -Queries are run by sending HTTP POST requests to the server. -By default, the API endpoint is `http://127.0.0.1:9070/text-query`. -A JSON body of the following form is expected: +查询通过向 API 发送 POST 请求来完成。默认的请求地址是 `http://127.0.0.1:9070/text-query` 。请求必须包含 JSON 格式的正文，具体内容如下： ```json { "script": "", "params": {} } ``` -params should be an object of named parameters. For example, if params is `{"num": 1}`, -then `$num` can be used anywhere in your query string where an expression is expected. -Always use params instead of concatenating strings when you need parametrized queries. - -The HTTP API always responds in JSON. If a request is successful, then its `"ok"` field will be `true`, -and the `"rows"` field will contain the data for the resulting relation, and `"headers"` will contain -the headers. If an error occurs, then `"ok"` will contain `false`, the error message will be in `"message"` -and a nicely-formatted diagnostic will be in `"display"` if available. - -> Cozo is designed to run in a trusted environment and be used by trusted clients. -> It does not come with elaborate authentication and security features. -> If you must access Cozo remotely, you are responsible for setting up firewalls, encryptions and proxies yourself. +`params` 给出了查询文本中可用的变量。例如，当 `params` 为 `{"num": 1}` 时，查询文本中可以以 `$num` 来代替常量 `1`。请善用此功能，而不是手动拼接查询字符串。 + +HTTP API 返回的结果永远是 JSON 格式的。如果请求成功，则返回结果的 `"ok"` 字段将为 `true`，且 `"rows"` 字段将含有查询结果的行，而 `"headers"` 将含有表头。如果查询报错，则 `"ok"` 字段将为 `false`，而错误信息会在 `"message"` 字段中，同时 `"display"` 字段会包含格式化好的友好的错误提示。 + +> Cozo 的设计，基于其在一个受信任的环境中运行，且其所有用户也是由受信任的这种假设。因此 Cozo 没有内置认证与复杂的安全机制。如果你需要远程访问 Cozo 服务，你必须自己设置防火墙、加密和代理等，用来保护服务器上资源的安全。 > -> As a guard against users accidentally exposing sensitive data, -> If you bind Cozo to non-loopback addresses, -> Cozo will generate a token string and require all queries from non-loopback addresses -> to provide the token string in the HTTP header field x-cozo-auth. -> The warning printed when you start Cozo with a -> 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. -* `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. - -> For `import` and `import-from-backup`, triggers are _not_ run for the relations, if any exists. -If you need to activate triggers, use queries with parameters. - - -## Building - -Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run +> 由于总是会有用户不小心将服务接口暴露于外网，Cozo 有一个补救措施：如果从非回传地址访问 Cozo，则必须在所有请求中以 HTTP 文件头 `x-cozo-auth` 的形式附上访问令牌。访问令牌的内容在启动服务的终端中有提示。注意这仅仅是一个补救措施，并不是特别可靠的安全机制，是为了尽量防止一些不由于小心而造成严重后果的悲剧。 + +## 所有 API + +* `POST /text-query`，见上。 +* `GET /export/{relations: String}`，导出指定表中的数据，其中 `relations` 是以逗号分割的表名。 +* `PUT /import`，向数据库导入数据。所导入的数据应以在正文中以 `application/json` MIME 类型传入，具体格式与 `/export` 返回值中的 `data` 字段相同。 +* `POST /backup`，备份数据库，需要传入 JSON 正文 `{"path": <路径>}`。 +* `POST /import-from-backup`，将备份中指定存储表中的数据插入当前数据库中同名存储表。需要传入 JSON 正文 `{"path": <路径>, "relations": <表名数组>}`. +* `GET /`，用浏览器打开这个地址，然后打开浏览器的调试工具，就可以使用一个简陋的 JS 客户端。 + +> 注意 `import` 与 `import-from-backup` 接口不会激活任何触发器。 + + +## 编译 + +编译 `cozoserver` 需要 [Rust 工具链](https://rustup.rs)。运行 ```bash cargo build --release -p cozoserver -F compact -F storage-rocksdb diff --git a/cozoserver/README.md b/cozoserver/README.md index 39f08070..75bdcd9e 100644 --- a/cozoserver/README.md +++ b/cozoserver/README.md @@ -3,9 +3,7 @@ [![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases) This document describes how to set up cozoserver. -To learn how to use CozoDB (CozoScript), follow -the [tutorial](https://docs.cozodb.org/en/latest/tutorial.html). You can run all the queries -described in the tutorial with an in-browser DB [here](https://www.cozodb.org/wasm-demo/). +To learn how to use CozoDB (CozoScript), read the [docs](https://docs.cozodb.org/en/latest/index.html). ## Download @@ -79,7 +77,7 @@ If you need to activate triggers, use queries with parameters. ## Building -Building `cozo-node` requires a [Rust toolchain](https://rustup.rs). Run +Building `cozoserver` requires a [Rust toolchain](https://rustup.rs). Run ```bash cargo build --release -p cozoserver -F compact -F storage-rocksdb