{"id":34610078,"url":"https://github.com/qualcomm/armor","last_synced_at":"2026-02-17T11:16:35.292Z","repository":{"id":326217006,"uuid":"1050903948","full_name":"qualcomm/armor","owner":"qualcomm","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-17T11:52:19.000Z","size":185,"stargazers_count":1,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-20T18:52:30.348Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qualcomm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T06:04:49.000Z","updated_at":"2025-12-17T11:52:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qualcomm/armor","commit_stats":null,"previous_names":["qualcomm/armor"],"tags_count":0,"template":false,"template_full_name":"qualcomm/qualcomm-repository-template","purl":"pkg:github/qualcomm/armor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Farmor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Farmor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Farmor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Farmor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qualcomm","download_url":"https://codeload.github.com/qualcomm/armor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Farmor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28003724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T14:05:32.816Z","updated_at":"2025-12-24T14:06:43.973Z","avatar_url":"https://github.com/qualcomm.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"ARMOR\n=========================\n\nARMOR is a tool for checking backward source-level compatibility of C/C++ software libraries using Clang AST.\n\nContents\n--------\n1. [ About      ](#about)\n2. [ Install    ](#install)\n3. [ Usage      ](#usage)\n4. [ Test suite ](#test-suite)\n5. [Troubleshooting \u0026 Environment Setup](#troubleshoot)\n\nAbout\n-----\nThis tool analyzes two versions of a C/C++ header file and detects source-level API incompatibilities. It leverages Clang's AST to perform deep structural comparisons, helping maintainers ensure backward compatibility in evolving codebases.\n\n\nInstall\n-------\n\n    sudo apt update\n    sudo apt install clang-14 make cmake\n    sudo apt install libclang-common-14-dev libclang-14-dev llvm-14-dev\n\n\n###### Requires\n\n* make\n* cmake\n* llvm-14\n* clang-14\n\n###### Platforms\n\n* Linux\n\nUsage\n-----\n\n### Basic Usage\n\nClone the repository and run the build_binary.sh script to build the armor tool:\n\n```bash\nbash build_binary.sh --build\n```\n\nThis will build armor.\n\n**Important:** All header files and include paths must exist in both `project_root1` and `project_root2`.\n\n### ARMOR Command-Line Interface\n\nThe tool is invoked directly using the `armor` binary:\n\n```bash\n./build/src/armor/armor [OPTIONS] projectroot1 projectroot2 [headers...]\n```\n\n#### Positional Arguments\n\n* **projectroot1** (REQUIRED)  \n  Path to the project root directory of the older version\n\n* **projectroot2** (REQUIRED)  \n  Path to the project root directory of the newer version\n\n* **headers** (optional)  \n  List of header files to compare between the two versions.  \n  **Note:** Headers must exist in both project roots.\n  \n  Header path interpretation depends on whether `--header-dir` is provided:\n  \n  - **With `--header-dir`:**  \n    Headers are treated as basenames (e.g., `foo.h`) under the specified subdirectory.  \n    Example:\n    ```bash\n    --header-dir include/api foo.h bar.hpp\n    ```\n    This will compare:  \n    - `projectroot1/include/api/foo.h` with `projectroot2/include/api/foo.h`  \n    - `projectroot1/include/api/bar.hpp` with `projectroot2/include/api/bar.hpp`\n  \n  - **Without `--header-dir`:**  \n    Headers must be relative paths from the project root.  \n    Example:\n    ```bash\n    include/api/foo.h include/api/bar.hpp\n    ```\n    This will compare:  \n    - `projectroot1/include/api/foo.h` with `projectroot2/include/api/foo.h`  \n    - `projectroot1/include/api/bar.hpp` with `projectroot2/include/api/bar.hpp`\n\n#### Options\n\n* **-h, --help**  \n  Print help message and exit\n\n* **--header-dir TEXT**  \n  Subdirectory under each project root containing headers\n\n* **-r, --report-format TEXT:{html,json}**  \n  Report format: `html` (default).  \n  If `json` is provided, both HTML and JSON reports will be generated.\n\n* **--dump-ast-diff**  \n  Dump AST diff JSON files for debugging\n\n* **-v, --version**  \n  Display program version information and exit\n\n* **--log-level TEXT:{ERROR,LOG,INFO,DEBUG}**  \n  Set debug log level: ERROR, LOG, INFO (default), DEBUG\n\n* **-I, --include-paths TEXT ...**  \n  Include paths for header dependencies (relative to project roots).  \n  **Note:** Include paths must exist in both project roots.  \n  Example:\n  ```bash\n  -I path/to/include1 -I path/to/include2\n  ```\n  This will add:  \n  - `projectroot1/path/to/include1` and `projectroot2/path/to/include1`  \n  - `projectroot1/path/to/include2` and `projectroot2/path/to/include2`\n\n* **-m, --macro-flags TEXT**  \n  Macro flags to be passed for headers\n\n#### Usage Examples\n\n1. **Basic comparison with header directory:**\n   ```bash\n   ./build/src/armor/armor /path/to/old/project /path/to/new/project --header-dir include foo.h bar.h\n   ```\n\n2. **Comparison with relative header paths:**\n   ```bash\n   ./build/src/armor/armor /path/to/old/project /path/to/new/project include/api/foo.h include/api/bar.h\n   ```\n\n3. **Generate JSON report with include paths:**\n   ```bash\n   ./build/src/armor/armor /path/to/old/project /path/to/new/project \\\n     --header-dir include \\\n     --report-format json \\\n     -I dependencies/include \\\n     -I third_party/headers \\\n     foo.h\n   ```\n   This assumes both projects have `dependencies/include` and `third_party/headers` directories.\n\n4. **Debug mode with AST diff dump:**\n   ```bash\n   ./build/src/armor/armor /path/to/old/project /path/to/new/project \\\n     --header-dir include \\\n     --dump-ast-diff \\\n     --log-level DEBUG \\\n     foo.h\n   ```\n\nTest suite\n----------\n\nAll tests are located in the `src/tests` folder. The test suite uses pytest for test execution and validation.\n\n### Running Tests\n\nTo run all tests, use the following command from the project root:\n\n```bash\npytest\n```\n\n### Running Specific Tests\n\nYou can also run specific test files:\n\n```bash\npytest src/tests/test_example.py\n```\n\n### Test Requirements\n\nEnsure pytest and deepdiff packages are installed before running tests:\n\n```bash\npip install pytest==8.4.1 deepdiff==8.5.0\n```\n\nTroubleshooting \u0026 Environment Setup\n-----------------------------------\nIf you encounter build errors, ensure the following environment setup:\n\n1. You have C++ version 11 or higher (e.g., 23):\n\n    ls /usr/include/c++\n\n\n2. The same C++ version is available under the platform-specific path:\n\n    ls /usr/include/x86_64-linux-gnu/c++\n\n\n3. You have Clang version 14 and subversion 14.0.0:\n\n    ls /usr/include/clang\n\n4. You only have LLVM version 14 installed (Clang 14 is only compatible with LLVM 14):\n\n    ls /usr/lib | grep llvm-\n\n\n## License\n\narmor is licensed under the [BSD-3-clause License](https://spdx.org/licenses/BSD-3-Clause.html). See [LICENSE.txt](LICENSE.txt) for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualcomm%2Farmor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqualcomm%2Farmor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualcomm%2Farmor/lists"}