Proposal: restructure examples/ directory

[sdwoodbury]

When considering where to put the files needed for issue #641, it became apparent that the examples/ folder would benefit from reorganization.

I'm willing to take on this ticket.

Needs:

• to have various examples with:
  • a CLI program for demonstration purposes, and to collect profiling/traces. (ex: ceno_zkvm/benches/riscv_opcode.rs)
  • integration tests to verify that the end to end functionality works
  • benchmarks for preventing regressions
• a way to turn a program into a riscv binary (currently done by examples/ and examples-builder/)

Current limitations:

• multiple meanings of "example" but only one "examples" folder.
  • example can mean a CLI, for demonstration purposes and for collecting profiling/traces
  • example can mean a program to be compiled to an elf file and then proved (ex: examples/examples/ceno_rt_io.rs)
• benchmarks and integrations tests probably would benefit from sharing code
• there isn't an obvious destination within ceno_zkvm for programs which get compiled to riscv elf files

Proposed solution:

• move examples/examples into examples/ceno_rt
• make examples/ a cargo workspace with one subproject per example (ceno_rt, fibonacci, is_prime, etc)
• subproject structure as follows:
  • bin/ for CLI programs
  • lib.rs for code shared between bin/, tests/, or benches/
  • benches/ for the benchmarks
  • tests/ for integration tests, which would be similar to a benchmark but include extra checks.
  • riscv/ for the code to be compiled to a riscv elf file
  • build.rs to turn the programs in riscv/ into elf files

Also, if one desires for rust-analyzer to check the programs in riscv/ the same way it would in a folder named examples/, one could add this to the Cargo.toml file:

[[example]]
name = "<example_name>"
path = "riscv/<example_name>.rs"

potentially related issues
#606
#602
#353

[sdwoodbury]

also potentially related:
#694
#656

the examples can be structured to make it easy to run them from CI.

[matthiasgoergens]

The overall proposal seems fairly reasonable. Thanks! (Not sure about every last detail.)

See #631 and especially its associated standalone example in its own cargo workspace for something going in a similar direction.

[matthiasgoergens]

See also #719