From 01085abfa7227f8f4d528001af5a5f1866473c26 Mon Sep 17 00:00:00 2001
From: Linda Njau <lindanjau21@gmail.com>
Date: Sat, 14 Dec 2024 22:16:06 +0300
Subject: [PATCH] update JSON.md to require OCaml 5.1.0+ and other minor
 improvements

---
 doc/JSON.md | 83 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 70 insertions(+), 13 deletions(-)

diff --git a/doc/JSON.md b/doc/JSON.md
index fc7f9cc014..1d1ab46e0c 100644
--- a/doc/JSON.md
+++ b/doc/JSON.md
@@ -1,18 +1,75 @@
-STEPS TO BUILD AND COMPILE THE PROJECT
-=======================================
+# Building and Compiling the Project
 
-After Installing the prerequisites
+## Prerequisites
 
-1.  We first need to build the sail parser.
-    1. Find a directory to clone this repository, and make that directory your current working directory.
-    2. `git clone https://github.com/ThinkOpenly/sail`
-    3. `cd sail`
-    4. `make`
+1. **Install Sail**
+   Follow the [installation guide](https://github.com/rems-project/sail/blob/sail2/INSTALL.md).
 
-2.  Then, set up the environment for building in the RISC-V Sail repository:
-    1. `eval $(opam env)`
-    2. `export PATH=<path-to-sail-repository>:$PATH`
+2. **Check OCaml Version**
+   Ensure OCaml version 5.1.0 or higher is installed:
+   ```bash
+   ocamlc -version
+   ```
+   If the version is lower, create a new opam switch:
+   ```bash
+   opam switch create 5.1.0
+   eval $(opam env)
+   ```
 
-3.  Clone this sail-riscv repository.
+## Building the Project
 
-4.  Within that clone : `make json`
+### 1. Build the Sail Parser
+
+1. Clone the Sail repository:
+   ```bash
+   git clone https://github.com/ThinkOpenly/sail.git
+   ```
+2. Navigate into the repository:
+   ```bash
+   cd sail
+   ```
+3. Build the parser:
+   ```bash
+   make
+   ```
+
+### 2. Set Up the Environment for RISC-V Sail
+
+1. Initialize the opam environment:
+   ```bash
+   eval $(opam env)
+   ```
+2. Update the `PATH` to include the Sail repository:
+   ```bash
+   export PATH=<path-to-sail-repository>:$PATH
+   ```
+   Replace `<path-to-sail-repository>` with the actual path to your Sail repository.
+3. Clone the RISC-V Sail repository:
+   ```bash
+   git clone https://github.com/ThinkOpenly/sail-riscv.git
+   ```
+
+### 3. Build the Project
+
+Run the following command to build the project:
+```bash
+make json
+```
+
+### Optional: Debugging and Logging
+
+To enable debugging and save outputs, navigate to the `sail-riscv` folder and run the following commands:
+
+1. Change to the `sail-riscv` directory:
+   ```bash
+   cd sail-riscv
+   ```
+2. Activate debug mode:
+   ```bash
+   export SAIL_DEBUG=1
+   ```
+3. Save debug and JSON output to files:
+   ```bash
+   make json > output.json 2> debug.log
+   ```
+   Replace `output.json` and `debug.log` with your preferred filenames.