Docs: Update the readme to reflect the latest project update (#64)

* Update readme

* Minor readability improvements

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..."

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
 

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,

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,
 	)