Updated README.md file

LICENSE.txt

@@ -1,26 +1,31 @@
-Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+"""
+Copyright (c) 2021, Qualcomm Innovation Center, Inc. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-* Redistributions of source code must retain the above copyright
-  notice, this list of conditions and the following disclaimer.
-* Redistributions in binary form must reproduce the above
-  copyright notice, this list of conditions and the following
-  disclaimer in the documentation and/or other materials provided
-  with the distribution.
-* Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived
-  from this software without specific prior written permission.
+modification, are permitted provided that the following conditions are met:
 
-THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
-ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
-BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+SPDX-License-Identifier: BSD-3-Clause
+"""

README.md

@@ -38,15 +38,155 @@ Install
 Usage
 -----
 
-Clone the repository and run the build_binary.sh script with two header files as input:
+### Basic Usage
+
+Clone the repository and run the build_binary.sh script to build the armor tool:
+
+```bash
+bash build_binary.sh --build
+```
+
+This will build armor.
+
+**Important:** All header files and include paths must exist in both `project_root1` and `project_root2`.
+
+### ARMOR Command-Line Interface
+
+The tool is invoked directly using the `armor` binary:
+
+```bash
+./build/src/armor/armor [OPTIONS] projectroot1 projectroot2 [headers...]
+```
+
+#### Positional Arguments
+
+* **projectroot1** (REQUIRED)  
+  Path to the project root directory of the older version
+
+* **projectroot2** (REQUIRED)  
+  Path to the project root directory of the newer version
+
+* **headers** (optional)  
+  List of header files to compare between the two versions.  
+  **Note:** Headers must exist in both project roots.
+
+  Header path interpretation depends on whether `--header-dir` is provided:
+
+  - **With `--header-dir`:**  
+    Headers are treated as basenames (e.g., `foo.h`) under the specified subdirectory.  
+    Example:
+    ```bash
+    --header-dir include/api foo.h bar.hpp
+    ```
+    This will compare:  
+    - `projectroot1/include/api/foo.h` with `projectroot2/include/api/foo.h`  
+    - `projectroot1/include/api/bar.hpp` with `projectroot2/include/api/bar.hpp`
+
+  - **Without `--header-dir`:**  
+    Headers must be relative paths from the project root.  
+    Example:
+    ```bash
+    include/api/foo.h include/api/bar.hpp
+    ```
+    This will compare:  
+    - `projectroot1/include/api/foo.h` with `projectroot2/include/api/foo.h`  
+    - `projectroot1/include/api/bar.hpp` with `projectroot2/include/api/bar.hpp`
+
+#### Options
+
+* **-h, --help**  
+  Print help message and exit
+
+* **--header-dir TEXT**  
+  Subdirectory under each project root containing headers
+
+* **-r, --report-format TEXT:{html,json}**  
+  Report format: `html` (default).  
+  If `json` is provided, both HTML and JSON reports will be generated.
+
+* **--dump-ast-diff**  
+  Dump AST diff JSON files for debugging
+
+* **-v, --version**  
+  Display program version information and exit
+
+* **--log-level TEXT:{ERROR,LOG,INFO,DEBUG}**  
+  Set debug log level: ERROR, LOG, INFO (default), DEBUG
+
+* **-I, --include-paths TEXT ...**  
+  Include paths for header dependencies (relative to project roots).  
+  **Note:** Include paths must exist in both project roots.  
+  Example:
+  ```bash
+  -I path/to/include1 -I path/to/include2
+  ```
+  This will add:  
+  - `projectroot1/path/to/include1` and `projectroot2/path/to/include1`  
+  - `projectroot1/path/to/include2` and `projectroot2/path/to/include2`
+
+* **-m, --macro-flags TEXT**  
+  Macro flags to be passed for headers
+
+#### Usage Examples
+
+1. **Basic comparison with header directory:**
+   ```bash
+   ./build/src/armor/armor /path/to/old/project /path/to/new/project --header-dir include foo.h bar.h
+   ```
+
+2. **Comparison with relative header paths:**
+   ```bash
+   ./build/src/armor/armor /path/to/old/project /path/to/new/project include/api/foo.h include/api/bar.h
+   ```
+
+3. **Generate JSON report with include paths:**
+   ```bash
+   ./build/src/armor/armor /path/to/old/project /path/to/new/project \
+     --header-dir include \
+     --report-format json \
+     -I dependencies/include \
+     -I third_party/headers \
+     foo.h
+   ```
+   This assumes both projects have `dependencies/include` and `third_party/headers` directories.
+
+4. **Debug mode with AST diff dump:**
+   ```bash
+   ./build/src/armor/armor /path/to/old/project /path/to/new/project \
+     --header-dir include \
+     --dump-ast-diff \
+     --log-level DEBUG \
+     foo.h
+   ```
 
+Test suite
+----------
 
-    bash build_binary.sh <header_file1> <heder_file2>
+All tests are located in the `src/tests` folder. The test suite uses pytest for test execution and validation.
 
-This will build and run the compatibility checker on the provided headers.
+### Running Tests
 
-Test suite
-----------
+To run all tests, use the following command from the project root:
+
+```bash
+pytest
+```
+
+### Running Specific Tests
+
+You can also run specific test files:
+
+```bash
+pytest src/tests/test_example.py
+```
+
+### Test Requirements
+
+Ensure pytest and deepdiff packages are installed before running tests:
+
+```bash
+pip install pytest==8.4.1 deepdiff==8.5.0
+```
 
 Troubleshooting & Environment Setup
 -----------------------------------