build: bump version to 0.12.0; copy README.md to runtime_tracing

cargo publish requires a README for the published folder

Author: alehander92

runtime_tracing/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "runtime_tracing"
-version = "0.11.0"
+version = "0.12.0"
 edition = "2021"
 authors = ["Metacraft Labs Ltd"]
 description = "A library for the schema and tracing helpers for the CodeTracer db trace format"

runtime_tracing/README.md

@@ -0,0 +1,69 @@
+## runtime_tracing
+
+A format and helper library for [CodeTracer](https://github.com/metacraft-labs/CodeTracer.git) traces
+
+### format
+
+A CodeTracer trace for its db backend consists of record data, metadata for the recorded program and copy of the relevant source/repository files. 
+It's self contained, so one can debug a record of a version of a program from a different commit or branch. 
+The record data consists of a stream of objects, each of which describes a certain program event: call, step, return etc.
+
+A trace contains several files:
+* `trace.json` – the event data in JSON format
+* `trace.bin` – the same event stream encoded in a binary format (see
+  [docs/trace_binary_spec.md](docs/trace_binary_spec.md))
+* `trace_metadata.json` – metadata for the recorded program
+* `trace_paths.json` – a list of the recorded files
+* `files/` – a folder including all the source/repository files copied into the trace.
+
+The event stream can be stored either as JSON (`trace.json`) or in the
+binary format (`trace.bin`). Both representations correspond to the Rust
+types in `src/types.rs`.
+
+We plan on 
+* defining a more precise document or a list of examples or a specification.
+* producing a more optimized version of the format. A binary variant is now
+  available as `trace.bin`.
+
+A future goal of this format is to make it possible to stream traces: to be able to replay them while they're still being recorded. 
+This is one of the reasons for the decision to maintain a single "stream" of events currently. 
+
+### tracer library
+
+We also define a Rust tracer library in `src/tracer.rs` which can be used as a helper to instrument Rust-based language interpreters and vm-s. 
+It can make it easier to migrate to newer versions of the format, hiding many details behind its helpers. 
+There are a few examples and tests of its usage in `src/lib.rs`. 
+
+There are some actual usages of it as well which can be also used as an example:
+* in [blocksense-network/noir: their tracing support for CodeTracer](https://github.com/blocksense-network/noir/tree/blocksense/tooling/tracer)
+* in a small toy interpreter to be released as a part of the CodeTracer repo
+
+One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases!
+
+### Building the Documentation
+
+The library API docs can be built locally with:
+
+```bash
+cargo doc --all-features --no-deps
+```
+
+The generated HTML documentation will be placed under `target/doc`. Open
+`target/doc/runtime_tracing/index.html` in a browser to inspect it.
+
+### Publishing to crates.io
+
+After updating the version number in `Cargo.toml`, publish a new release with:
+
+```bash
+cargo publish
+```
+
+Documentation for released versions will be automatically hosted on
+[docs.rs](https://docs.rs/runtime_tracing).
+
+### Legal
+
+Authored and maintained by Metacraft Labs, Ltd
+
+LICENSE: MIT