Update documentation #1254

DiegoCivi · 2025-06-13T23:00:53Z

Tidy up and update documentation

Checklist

Linked to Github Issue
Unit tests added
Integration tests added.
This change requires new documentation.
- Documentation has been added/updated.

github-actions · 2025-06-14T01:27:59Z

Benchmark results Main vs HEAD.

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base dict_insert.cairo (JIT)`	2.589 ± 0.023	2.556	2.639	1.03 ± 0.02
`base dict_insert.cairo (AOT)`	2.513 ± 0.030	2.475	2.555	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head dict_insert.cairo (JIT)`	2.503 ± 0.014	2.479	2.524	1.03 ± 0.01
`head dict_insert.cairo (AOT)`	2.427 ± 0.014	2.411	2.450	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base dict_snapshot.cairo (JIT)`	2.288 ± 0.015	2.265	2.307	1.04 ± 0.01
`base dict_snapshot.cairo (AOT)`	2.196 ± 0.018	2.175	2.238	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head dict_snapshot.cairo (JIT)`	2.223 ± 0.015	2.207	2.248	1.05 ± 0.01
`head dict_snapshot.cairo (AOT)`	2.123 ± 0.013	2.111	2.153	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base factorial_2M.cairo (JIT)`	2.762 ± 0.062	2.716	2.897	1.06 ± 0.02
`base factorial_2M.cairo (AOT)`	2.598 ± 0.014	2.576	2.613	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head factorial_2M.cairo (JIT)`	2.593 ± 0.015	2.580	2.630	1.02 ± 0.01
`head factorial_2M.cairo (AOT)`	2.547 ± 0.016	2.514	2.567	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base fib_2M.cairo (JIT)`	2.200 ± 0.029	2.143	2.240	1.00 ± 0.03
`base fib_2M.cairo (AOT)`	2.195 ± 0.064	2.140	2.347	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head fib_2M.cairo (JIT)`	2.138 ± 0.012	2.124	2.158	1.02 ± 0.02
`head fib_2M.cairo (AOT)`	2.090 ± 0.030	2.062	2.168	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base linear_search.cairo (JIT)`	2.435 ± 0.086	2.364	2.596	1.09 ± 0.04
`base linear_search.cairo (AOT)`	2.237 ± 0.029	2.205	2.288	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head linear_search.cairo (JIT)`	2.306 ± 0.010	2.293	2.325	1.05 ± 0.01
`head linear_search.cairo (AOT)`	2.186 ± 0.013	2.169	2.211	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
`base logistic_map.cairo (JIT)`	2.529 ± 0.018	2.497	2.549	1.07 ± 0.02
`base logistic_map.cairo (AOT)`	2.374 ± 0.033	2.324	2.431	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
`head logistic_map.cairo (JIT)`	2.429 ± 0.019	2.404	2.462	1.08 ± 0.01
`head logistic_map.cairo (AOT)`	2.252 ± 0.016	2.226	2.270	1.00

github-actions · 2025-06-14T01:33:17Z

Benchmarking results

Benchmark for program `dict_insert`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	11.038 ± 0.076	10.955	11.238	4.49 ± 0.05
`cairo-native (embedded AOT)`	2.458 ± 0.023	2.416	2.496	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2.644 ± 0.060	2.579	2.721	1.08 ± 0.03

Benchmark for program `dict_snapshot`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	511.3 ± 4.6	503.9	520.5	1.00
`cairo-native (embedded AOT)`	2092.2 ± 9.7	2080.1	2108.8	4.09 ± 0.04
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2207.7 ± 8.5	2194.1	2223.3	4.32 ± 0.04

Benchmark for program `factorial_2M`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	4.898 ± 0.027	4.856	4.941	1.85 ± 0.04
`cairo-native (embedded AOT)`	2.644 ± 0.052	2.565	2.709	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2.667 ± 0.026	2.621	2.701	1.01 ± 0.02

Benchmark for program `fib_2M`

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
`Cairo-vm (Rust, Cairo 1)`	4.801 ± 0.013	4.786	4.820	2.32 ± 0.02
`cairo-native (embedded AOT)`	2.072 ± 0.013	2.056	2.093	1.00
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2.124 ± 0.010	2.105	2.140	1.03 ± 0.01

Benchmark for program `linear_search`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	550.6 ± 3.7	545.4	558.0	1.00
`cairo-native (embedded AOT)`	2200.8 ± 65.7	2144.2	2338.3	4.00 ± 0.12
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2382.7 ± 50.5	2306.6	2473.2	4.33 ± 0.10

Benchmark for program `logistic_map`

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`Cairo-vm (Rust, Cairo 1)`	383.2 ± 7.9	372.1	393.7	1.00
`cairo-native (embedded AOT)`	2320.9 ± 42.4	2257.7	2401.1	6.06 ± 0.17
`cairo-native (embedded JIT using LLVM's ORC Engine)`	2446.2 ± 52.0	2401.0	2583.2	6.38 ± 0.19

codecov-commenter · 2025-06-14T01:43:16Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.27%. Comparing base (ac3e1a4) to head (dc471bb).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1254   +/-   ##
=======================================
  Coverage   76.27%   76.27%           
=======================================
  Files         111      111           
  Lines       26602    26602           
=======================================
  Hits        20291    20291           
  Misses       6311     6311

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

README.md

JulianGCalderon

Nice work. I left some minor comments. Also, please update the PR description

JulianGCalderon · 2025-06-19T13:55:01Z

README.md

-Example: `echo '1' | cairo-native-run 'program.cairo' 'program::program::main' --inputs - --outputs -`
+Example: `cairo-native-run --available-gas 5000 './programs/program.cairo'`


Does this example file exist? (./programs/program.cairo)

Nope, it was just as an example. Changed it to one that exists here 5b18317

JulianGCalderon · 2025-06-19T13:55:40Z

cairo-tests/src/integer_test.cairo

Why was this file removed?

JulianGCalderon · 2025-06-19T13:57:52Z

src/compiler.rs

I feel like this changes are unrelated, and should be moved to another pull request.

The changes were undone in c42454d

JulianGCalderon · 2025-06-19T14:05:49Z

docs/execution_walkthrough.md

+When using the JIT it'll be automatically linked (if compiled with support for
+it, which is enabled by default). If using the AOT, the
+`CAIRO_NATIVE_RUNTIME_LIBRARY` environment variable will have to be modified to
+point to the `libcairo_native_runtime.a` file, which is built and placed in said
+folder by `make build`.


This paragraph is outdated. We no longer have a runtime library. This PR #1051 may have more details on how the new runtime mechanism works.

I changed it and tried to explain how it is done now. I didn't mention how it was done before, I don´t know if that is necessary or not. Let me know what you think

JulianGCalderon · 2025-06-19T14:06:36Z

docs/execution_walkthrough.md

+The syscall handler is similar to the runtime in the sense that we have
+C-compatible functions called from MLIR, but it's different in that they're
+built into Cairo Native itself rather than an external library, and that their
+implementation is user-dependent.


Idem. We don't have an external library for the runtime anymore.

JulianGCalderon · 2025-06-19T14:19:53Z

Also, there are some things that could be done, but I'm not sure that this PR is the right place:

Update cairo-native tools usages (--help).
Update trace-dump Replay documentation (or link to the replay documentation).
Remove the ignore on the rust examples, to ensure that they don't get outdated.

docs/overview.md

docs/execution_walkthrough.md

Co-authored-by: Julian Gonzalez Calderon <gonzalezcalderonjulian@gmail.com>

README.md

docs/compilation_walkthrough.md

JulianGCalderon

LGTM!

Co-authored-by: Franco Giachetta <francogiachetta27@gmail.com>

docs/execution_walkthrough.md

JulianGCalderon

LGTM!

azteca1998 and others added 9 commits June 13, 2025 20:00

Add some docs. Fix some issues.

a282628

More docs.

6b8f6d0

Minor changes

03bce62

More minor changes

655d438

Refactor on src layout

5fc6372

Update examples on overview.md

b6ada90

Minor changes on overview.md example

6cd39dd

Minor change

f36784d

Remove wrong enum explanation

107ee68

DiegoCivi requested review from Oppen, azteca1998, edg-l, entropidelic, fmoletta, gabrielbosio, igaray, jrchatruc and pefontana as code owners June 13, 2025 23:00

gabrielbosio mentioned this pull request Jun 13, 2025

Update docs. #961

Closed

5 tasks

Fix merge mistake

b2cfadb

Remove JitValue references

a465209

gabrielbosio requested changes Jun 17, 2025

View reviewed changes

README.md Show resolved Hide resolved

DiegoCivi added 2 commits June 18, 2025 11:23

Apply comments

34e5c6a

Remove outdated link

722ea69

JulianGCalderon requested changes Jun 19, 2025

View reviewed changes

Change cairo-native-run example file

5b18317

DiegoCivi and others added 5 commits July 17, 2025 10:06

Refactor of project layout

580521a

Add tool info

da5c08d

Merge branch 'main' into update-documentation

286c666

Refactor of runtime explanation

ee28e90

Minor changes

2822583

JulianGCalderon reviewed Jul 17, 2025

View reviewed changes

docs/overview.md Outdated Show resolved Hide resolved

docs/execution_walkthrough.md Outdated Show resolved Hide resolved

docs/execution_walkthrough.md Outdated Show resolved Hide resolved

DiegoCivi and others added 4 commits July 18, 2025 09:28

Update docs/overview.md

717935e

Co-authored-by: Julian Gonzalez Calderon <gonzalezcalderonjulian@gmail.com>

Update docs/execution_walkthrough.md

663b5c5

Co-authored-by: Julian Gonzalez Calderon <gonzalezcalderonjulian@gmail.com>

Update docs/execution_walkthrough.md

da4c780

Co-authored-by: Julian Gonzalez Calderon <gonzalezcalderonjulian@gmail.com>

Merge branch 'main' into update-documentation

ffb66ad

FrancoGiachetta reviewed Jul 18, 2025

View reviewed changes

JulianGCalderon previously approved these changes Jul 18, 2025

View reviewed changes

DiegoCivi added 2 commits July 22, 2025 16:04

Refactor of starknet-native-compile description

a6858ab

cairo -> sierra

567fc74

DiegoCivi dismissed JulianGCalderon’s stale review via 567fc74 July 22, 2025 19:07

DiegoCivi and others added 4 commits July 22, 2025 16:09

Update docs/compilation_walkthrough.md

753f850

Co-authored-by: Franco Giachetta <francogiachetta27@gmail.com>

Update docs/compilation_walkthrough.md

82022da

Co-authored-by: Franco Giachetta <francogiachetta27@gmail.com>

Update docs/compilation_walkthrough.md

ab53ab1

Co-authored-by: Franco Giachetta <francogiachetta27@gmail.com>

Update docs/compilation_walkthrough.md

aea8b7e

Co-authored-by: Franco Giachetta <francogiachetta27@gmail.com>

FrancoGiachetta previously approved these changes Jul 24, 2025

View reviewed changes

docs/execution_walkthrough.md Outdated Show resolved Hide resolved

Minor changes

76a7235

DiegoCivi dismissed FrancoGiachetta’s stale review via 76a7235 July 28, 2025 14:11

JulianGCalderon previously approved these changes Jul 28, 2025

View reviewed changes

Merge branch 'main' into update-documentation

3e9307d

DiegoCivi dismissed JulianGCalderon’s stale review via 3e9307d August 25, 2025 19:40

JulianGCalderon previously approved these changes Aug 25, 2025

View reviewed changes

FrancoGiachetta previously approved these changes Aug 25, 2025

View reviewed changes

Merge branch 'main' into update-documentation

dc471bb

DiegoCivi dismissed stale reviews from FrancoGiachetta and JulianGCalderon via dc471bb September 16, 2025 13:33

		Example: `echo '1' \| cairo-native-run 'program.cairo' 'program::program::main' --inputs - --outputs -`
		Example: `cairo-native-run --available-gas 5000 './programs/program.cairo'`

Update documentation #1254

Are you sure you want to change the base?

Update documentation #1254

Uh oh!

Conversation

DiegoCivi commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

github-actions bot commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark results Main vs HEAD.

Base

Head

Base

Head

Base

Head

Base

Head

Base

Head

Base

Head

Uh oh!

github-actions bot commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarking results

Benchmark for program dict_insert

Benchmark for program dict_snapshot

Benchmark for program factorial_2M

Benchmark for program fib_2M

Benchmark for program linear_search

Benchmark for program logistic_map

Uh oh!

codecov-commenter commented Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

JulianGCalderon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JulianGCalderon commented Jun 19, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JulianGCalderon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JulianGCalderon left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

DiegoCivi commented Jun 13, 2025 •

edited

Loading

github-actions bot commented Jun 14, 2025 •

edited

Loading

github-actions bot commented Jun 14, 2025 •

edited

Loading

Benchmark for program `dict_insert`

Benchmark for program `dict_snapshot`

Benchmark for program `factorial_2M`

Benchmark for program `fib_2M`

Benchmark for program `linear_search`

Benchmark for program `logistic_map`

codecov-commenter commented Jun 14, 2025 •

edited

Loading