Readme

README.md

@@ -1,21 +1,128 @@
 # cairo-profiler
-Profiler for cairo programming language & starknet
 
-## Setup for development
+Profiler for Cairo programming language & Starknet.
 
-You need to install: rust, go, protobuf, pprof, graphviz 
+## Installation
 
-## Building protobufs
-Protocol buffers are built with [prost-build](https://github.com/tokio-rs/prost/tree/master/prost-build)
-
-## Run profiling
+To install the latest version of `cairo-profiler`, run:
 
+```shell
+curl -L https://raw.githubusercontent.com/software-mansion/cairo-profiler/main/scripts/install.sh | sh
 ```
-cargo run
+
+If you want to install a specific a version, run the following command with the requested version:
+
+```shell
+curl -L https://raw.githubusercontent.com/software-mansion/cairo-profiler/main/scripts/install.sh | sh -s -- v0.1.0
 ```
 
-## Reading the profiling results
+## External tools integration
+
+`cairo-profiler` is a tool-agnostic profiler which means that it accepts input from any tool. Those tools need to generate
+trace in the [expected](https://github.com/software-mansion/cairo-profiler/blob/main/src/trace_data.rs) format.
+
+### Integrated tools
+
+- [x] [Starknet Foundry](https://github.com/foundry-rs/starknet-foundry) - check how to generate the input file [here](https://foundry-rs.github.io/starknet-foundry/testing/profiling.html)
+
+## Usage
+
+Usage flow consists of two steps:
+
+- generating the output file,
+- running `pprof` tool.
+
+### Generating output file
+
+To generate the file run `cairo-profiler` with the `<PATH_TO_TRACE_DATA>` argument containing
+the path to the json file with the trace to be profiled. You can also specify the `--output-path <OUTPUT_PATH>` -
+by default the output file will be saved as `profile.pb.gz`
+
+#### Example
 
+```shell
+cairo-profiler path/to/trace.json
 ```
+
+> 📝 **Note**
+>
+> Trace needs to be in the correct format. See [trace.json](./tests/data/trace.json) as an example.
+
+### Running pprof
+
+To see results from the generated file you will need to install:
+
+- [Go](https://go.dev/doc/install)
+- [Graphviz](https://www.graphviz.org/download/)
+- [pprof](https://github.com/google/pprof?tab=readme-ov-file#building-pprof)
+
+and run:
+
+```shell
 go tool pprof -http=":8000" profile.pb.gz
 ```
+
+This command will start a web server at the specified port that provides an interactive interface.
+You can learn more about pprof usage options [here](https://github.com/google/pprof?tab=readme-ov-file#basic-usage).
+
+## Roadmap
+
+`cairo-profiler` is under active development! Expect a lot of new features to appear soon! 🔥
+
+- [ ] Starknet calls profiling:
+ - [x] L2 resources - steps, memory holes, builtins, syscalls 
+ - [ ] L1 resources - contract updates, L2 -> L1 messages
+- [ ] Function level profiling
+- [ ] Exposing `cairo-profiler` library to allow other tools to integrate
+
+## Development
+
+### Environment setup
+You need to install: [Rust](https://www.rust-lang.org/tools/install), [Go](https://go.dev/doc/install), 
+[protoc](https://grpc.io/docs/protoc-installation), [pprof](https://github.com/google/pprof?tab=readme-ov-file#building-pprof) and [Graphviz](https://graphviz.org/download). 
+
+### Running the binary
+
+The binary can be run with:
+
+```shell
+cargo run <PATH_TO_TRACE_DATA>
+```
+
+### Running tests
+
+Tests can be run with:
+
+```shell
+cargo test
+```
+
+### Formatting and lints
+
+`cairo-profiler` uses [rustfmt](https://github.com/rust-lang/rustfmt) for formatting. You can run the formatter with:
+
+```shell
+cargo fmt
+```
+
+For linting, it uses [clippy](https://github.com/rust-lang/rust-clippy). You can run it using our defined alias:
+
+```shell
+cargo lint
+```
+
+### Spelling
+
+`cairo-profiler` uses [typos](https://github.com/marketplace/actions/typos-action) for spelling checks.
+
+You can run the checker with
+
+```shell
+typos
+```
+
+Some typos can be automatically fixed by running
+
+```shell
+typos -w
+```