You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# Cozo for Swift on Apple Hardware
|
|
|
|
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://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/).
|
|
|
|
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
|
|
other storage engines on desktop or mobile does not make too much sense. If you disagree,
|
|
see the Building section below.
|
|
|
|
## Installation
|
|
|
|
### CocoaPods
|
|
|
|
```ruby
|
|
target 'YourApp' do
|
|
use_frameworks!
|
|
|
|
pod 'CozoSwiftBridge', '~> 0.2.1'
|
|
end
|
|
```
|
|
|
|
### Swift Package Manager (SPM)
|
|
|
|
The package is published as an archive containing a Swift package.
|
|
Download it from the [release page] (look for `CozoSwiftBridge-<VERSION>.tgz`).
|
|
Uncompress.
|
|
|
|
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`.
|
|
|
|
## Using the library
|
|
|
|
```swift
|
|
import CozoSwiftBridge
|
|
|
|
...
|
|
|
|
let path = NSHomeDirectory()
|
|
let file = path + "/cozo-data.db"
|
|
let db = new_cozo_db("sqlite", file, "");
|
|
let result: String! = db?.run_script_str("::relations", "").toString();
|
|
```
|
|
Above we created an SQLite-based database. For memory-based ones:
|
|
```swift
|
|
let db = new_cozo_db("mem", "", "");
|
|
```
|
|
|
|
## API
|
|
|
|
The function `new_cozo_db` can be used to create a database, passing in the engine type,
|
|
the storage path, and options.
|
|
The following methods are available on the returned database object:
|
|
```
|
|
extension DbInstanceRef {
|
|
/**
|
|
* Run query against a database.
|
|
*
|
|
* `payload`: a UTF-8 encoded C-string for the CozoScript to execute.
|
|
* `params`: a UTF-8 encoded C-string for the params of the query,
|
|
* in JSON format. You must always pass in a valid JSON map,
|
|
* even if you do not use params in your query
|
|
* (pass "{}" in this case).
|
|
*/
|
|
public func run_script_str(_ payload: GenericToRustStr, _ params: GenericToRustStr) -> RustString;
|
|
|
|
/**
|
|
* Import data into relations
|
|
* `data`: a UTF-8 encoded JSON payload, see the manual for the expected fields.
|
|
*/
|
|
public func import_relations_str(_ data: GenericToRustStr) -> RustString;
|
|
|
|
/**
|
|
* Export relations into JSON
|
|
*
|
|
* `data`: a UTF-8 encoded JSON payload, , in the same form as returned by exporting relations
|
|
*/
|
|
public func export_relations_str(_ data: GenericToRustStr) -> RustString;
|
|
|
|
/**
|
|
* Backup the database.
|
|
*
|
|
* `out_file`: path of the output file.
|
|
*/
|
|
public func backup_db_str(_ out_file: GenericToRustStr) -> RustString;
|
|
|
|
/**
|
|
* Restore the database from a backup.
|
|
*
|
|
* `in_file`: path of the input file.
|
|
*/
|
|
public func restore_backup_str(_ in_file: GenericToRustStr) -> RustString;
|
|
|
|
/**
|
|
* Import data into a relation
|
|
*
|
|
* `data`: a UTF-8 encoded JSON payload: `{"path": ..., "relations": [...]}`
|
|
*/
|
|
public func import_from_backup_str(_ data: GenericToRustStr) -> RustString;
|
|
}
|
|
```
|
|
You can pass Swift strings as arguments. The returned types are all `RustString`:
|
|
you need to call `.toString()` on them to convert to Swift strings, and then parse them
|
|
as JSON objects (for example, by using [SwiftyJSON](https://github.com/SwiftyJSON/SwiftyJSON).
|
|
|
|
## Building the Swift Package
|
|
|
|
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`.
|
|
|
|
If you want to use the RocksDB engine on Desktop, in the build script change the two lines
|
|
```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
|
|
```
|
|
|
|
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!
|