rust

Stencila Rust

Core Stencila functionality implemented in a fast, memory-safe language

🦀 Introduction

This is the stencila core Rust library. Its main purpose is to implement core functionality that can be reused in the Stencila CLI and in language bindings.

📦 Install

This library is not yet published to https://crates.io/, but you can still add it to your Cargo.toml using,

stencila = { git = "https://github.com/stencila/stencila" }

🛠️ Develop

Getting started

Get started by cloning this repository, installing Rust and using the using make setup to install necessary Cargo plugins (for formatting, linting, etc):

git clone git@github.com:stencila/stencila
cd stencila/rust
make setup

If you are contributing code please run formatting, linting and tests before submitting PRs:

make fix test

Code organization

This library is made up of many Rust crates. Splitting Rust code into small crates has advantages for compilation speed, modularization and reuse. In addition, because Rust derive macros must be in their own crate, and to avoid circular dependencies among crates it it necessary to split some crates further (e.g the codec-html, codec-html-derive, and the codec-html-trait crates).

Most of these crates are internal and are not published (those crates have version = "0.0.0" in their Cargo.toml).

The current crates include (but are not limited to):

CLI

• cli: The stencila CLI tool

• cli-gen: Generates reference documentation for the CLI

Documents and formats

• document: A document representing one of the CreativeWork types in the Stencila Schema.

• format: Provides the Format enum and utility functions for working with document formats.

Schema

• schema-gen: Generates language bindings, JSON Schema definitions and documentation from the Stencila Schema.

• schema: Rust types generated from the Stencila Schema by schema-gen

Node traits

• node-store and node-store-derive: Provides the ReadNode and WriteNode traits and derive macros for reading and writing document nodes from/to Automerge stores.

• node-strip and node-strip-derive: Provides the StripNode trait and derive macro for removing properties of document nodes.

Codecs

• codec: Provides the Codec trait for encoding/decoding between the types in the schema crate and other external formats (i.e. a 'converter').

• codec-losses: Utilities for recording encoding/decoding losses.

• codec-debug: A codec for the Rust Debug trait.

• codec-html: A codec for HTML.

• codec-jats: A codec for JATS XML.

• codec-json: A codec for JSON.

• codec-json5: A codec for JSON5.

• codec-markdown: A codec for Markdown.

• codec-text: A codec for plain text.

• codec-yaml: A codec for YAML.

Utilities

• common: Common dependencies used across crates.

• common-dev: Common development dependencies used across crates.

Using Tokio console

Turn on the console-subscriber feature to use tokio-console for debugging async tasks and locks e.g.

cargo run --bin stencila --features=console-subscriber -- serve

and in another terminal run tokio-console,

tokio-console