From 42c6dd5b47cc2fde253d8150d414a63432d19faa Mon Sep 17 00:00:00 2001
From: Rodrigo <rodrodpino@gmail.com>
Date: Mon, 25 Sep 2023 15:17:58 -0400
Subject: [PATCH] Docs: Update the readme to reflect the latest project update
 (#64)

* Update readme

* Minor readability improvements
---
 Makefile                            | 18 ++++++++++-----
 README.md                           | 34 ++++++++++++++++++++++++++++-
 cmd/cli/main.go                     |  6 ++---
 integration_tests/cairozero_test.go |  7 +++---
 4 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/Makefile b/Makefile
index 5a48fca5..4bd05e05 100644
--- a/Makefile
+++ b/Makefile
@@ -7,10 +7,12 @@ default: help
 
 help:
 	@echo "This makefile allos the following commands"
-	@echo "  make build       - compile the source code"
-	@echo "  make clean       - remove binary files"
-	@echo "  make test        - run tests"
-	@echo "  make help        - show this help message"
+	@echo "  make build           - compile the source code"
+	@echo "  make clean           - remove binary files"
+	@echo "  make unit            - run unit tests"
+	@echo "  make integration     - run integration tests"
+	@echo "  make testall         - run all tests"
+	@echo "  make help            - show this help message"
 
 build:
 	@echo "Building..."
@@ -33,7 +35,13 @@ unit:
 
 integration:
 	@echo "Running integration tests..."
-	@go test ./integration_tests/...
+	@$(MAKE) build
+	@if [ $$? -eq 0 ]; then \
+		go test ./integration_tests/... -v; \
+	else \
+		echo "Integration tests were not run"; \
+		exit 1; \
+	fi
 
 testall:
 	@echo "Running all tests..."
diff --git a/README.md b/README.md
index 720b3d58..2abcdee5 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,39 @@ Currently, it is only possible to use it by building it from source by following
 3. Execute on the root folder of the repo: `make build`.
 4. Make sure everything is running smoothly by executing: `make test`.
 
-After completing these steps, you can find the compiled VM in `bin/cairo-vm`. It is worth noting that this binary, in the current state of the project, is still non-functional.
+After completing these steps, you can find the compiled VM in `bin/cairo-vm`.
+
+### Run The VM
+
+To run the VM you need first compile the cairo file using [cairo-lang](https://github.com/starkware-libs/cairo-lang).
+Install it with the following command:
+
+```bash
+pip install cairo-lang==0.11
+```
+
+The next step is to compile a cairo file, an example would be:
+
+```bash
+cairo-compile ./integration_tests/cairo_files/factorial.cairo --proof_mode --output ./factorial_compiled.json
+```
+
+This will compile `factorial.cairo` and store the compilation result in `factorial_compiled.json`. The `--proof_mode` flag makes the compilation output special identifiers that allow to get proof of execution later on. Finally, let's execute `factorial_compiled.json` with the next command:
+
+```bash
+./bin/cairo-vm run factorial_compiled.json --proofmode --tracefile factorial_trace --memoryfile factorial_memory
+```
+
+When this command finishes, `factorial.cairo` has run correctly starting from the `main` function. The `--proofmode` flag indicates that a proof of execution should be generated. The location where this proof is stored is determined by both `--tracefile` and `memoryfile` flags accordingly.
+
+To test the correct output of the VM compared to the result of the Python VM, you just have to run:
+
+```bash
+make integration
+```
+
+This will take all Cairo files inside _./integration_tests/cairo_files/_ and run both VMs comparing that both proofs of executions are equal.
+
 
 ### Useful Commands
 
diff --git a/cmd/cli/main.go b/cmd/cli/main.go
index 1e1827cf..63c9e931 100644
--- a/cmd/cli/main.go
+++ b/cmd/cli/main.go
@@ -22,7 +22,7 @@ func main() {
 		Commands: []*cli.Command{
 			{
 				Name:  "run",
-				Usage: "runs a cairo file",
+				Usage: "runs a cairo zero compiled file",
 				Flags: []cli.Flag{
 					&cli.BoolFlag{
 						Name:        "proofmode",
@@ -31,13 +31,13 @@ func main() {
 						Destination: &proofmode,
 					},
 					&cli.StringFlag{
-						Name:        "tracelocation",
+						Name:        "tracefile",
 						Usage:       "location to store the relocated trace",
 						Required:    false,
 						Destination: &traceLocation,
 					},
 					&cli.StringFlag{
-						Name:        "memorylocation",
+						Name:        "memoryfile",
 						Usage:       "location to store the relocated memory",
 						Required:    false,
 						Destination: &memoryLocation,
diff --git a/integration_tests/cairozero_test.go b/integration_tests/cairozero_test.go
index d68e4a6e..993a59c0 100644
--- a/integration_tests/cairozero_test.go
+++ b/integration_tests/cairozero_test.go
@@ -34,8 +34,7 @@ func TestCairoZeroFiles(t *testing.T) {
 		if !strings.Contains(path, filter) {
 			continue
 		}
-
-		t.Logf("============== testing: %s ==============\n", path)
+		t.Logf("testing: %s\n", path)
 
 		compiledOutput, err := compileZeroCode(path)
 		if err != nil {
@@ -157,9 +156,9 @@ func runVm(path string) (string, string, error) {
 		"../bin/cairo-vm",
 		"run",
 		"--proofmode",
-		"--tracelocation",
+		"--tracefile",
 		traceOutput,
-		"--memorylocation",
+		"--memoryfile",
 		memoryOutput,
 		path,
 	)