{"id":31363841,"url":"https://github.com/esri/link-what-you-include","last_synced_at":"2025-09-27T05:23:23.019Z","repository":{"id":315671249,"uuid":"1059719622","full_name":"Esri/link-what-you-include","owner":"Esri","description":"A tool to help maintain a coherent build system target model","archived":false,"fork":false,"pushed_at":"2025-09-19T23:47:19.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T01:35:03.185Z","etag":null,"topics":["build-system","code-quality","cpp","tool"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Esri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-18T21:00:29.000Z","updated_at":"2025-09-19T23:47:22.000Z","dependencies_parsed_at":"2025-09-20T15:17:03.760Z","dependency_job_id":null,"html_url":"https://github.com/Esri/link-what-you-include","commit_stats":null,"previous_names":["esri/link-what-you-include"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Esri/link-what-you-include","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Flink-what-you-include","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Flink-what-you-include/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Flink-what-you-include/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Flink-what-you-include/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Esri","download_url":"https://codeload.github.com/Esri/link-what-you-include/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Flink-what-you-include/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277184144,"owners_count":25775286,"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-09-27T02:00:08.978Z","response_time":73,"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":["build-system","code-quality","cpp","tool"],"created_at":"2025-09-27T05:23:20.711Z","updated_at":"2025-09-27T05:23:23.011Z","avatar_url":"https://github.com/Esri.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nCopyright (c) 2025 Environmental Systems Research Institute, Inc.\nSPDX-License-Identifier: Apache-2.0\n--\u003e\n\n# link-what-you-include\n\n\u003e Maintain a coherent build system target model.\n\nThis is a tool that can be used to check that a C++ build system has correctly\nspecified the dependencies between targets based on what files the source code\nincludes. It is analogous to\n[Include What You Use (IWYU)](https://github.com/include-what-you-use/include-what-you-use)\nbut targeting inter-library dependencies rather than inter-file dependencies.\n\nA core organizing principle of modern build systems is the target model, which\nis a graph of interconnected targets representing libraries, executables, and\nother artifacts. Each target specifies the requirements needed to build itself\nand also the requirements needed to be used by another target. When performing\na build, the usage requirements of targets are propagated down the graph to\ndependent targets. This target model is a concise and powerful way to specify\nthe relationships between the components but it can be difficult to maintain\nit's accuracy over the lifetime of a project. For example it is easy to make a\nchange to the source that removes the last remaining dependency on a library\nbut neglects to remove that dependency from the target model. The compile\ncommands will then have unnecessary include directories, and the link command\nwill list an unnecessary library but the build will succeed. Similarly, it is\neasy to start using an external library that one of your existing dependencies\nuses in it's interface and neglect to add that library to the target model.\nSince the include directories and libraries are already present in the build\ncommands because of the transitive dependency, again the build will still\nsucceed. Over time, mistakes like this accumulate and the effectiveness of the\ntarget model is diminished.\n\nBoth of the common mistakes mentioned above can be caught by\nlink-what-you-include. The tool works by reading a JSON file containing target\ninformation acquired from the build system, scanning the source code for each\ntarget, mapping the set of included headers to the set of dependent libraries,\nand comparing these dependencies to what is reported in the JSON file.\nCurrently, the JSON file is in a bespoke format and can only be generated for a\ncompatible cmake based buildsytem with the provided cmake module. The eventual\ngoal is to use [CPS](https://github.com/cps-org/cps) files instead.\n\n### Status\n\nThis tool is under development and may not be ready for production use. It is\nbeing used internally against itself and in one reasonably large project at\nEsri.\n\n### How to build\n\nConan can be used to get all the dependencies except for Clang.\n\n```\n$ conan install . -s build_type=Debug --build=missing -of build\n$ cmake -GNinja -S. -Bbuild \\\n    -DCMAKE_TOOLCHAIN_FILE=./build/conan_build/generators/conan_toolchain.cmake \\\n    -DCMAKE_BUILD_TYPE=Debug \\\n    -DClang_ROOT=/path/to/your/clang/install\n$ cmake --build build\n```\n\n### How to use with a cmake based build system\n\nThe tool works best if targets define\n[`INTERFACE_HEADER_SETS`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_HEADER_SETS.html)\nand\n[`VERIFY_INTERFACE_HEADER_SETS`](https://cmake.org/cmake/help/latest/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.html#prop_tgt:VERIFY_INTERFACE_HEADER_SETS)\nis used. The former makes it easy to associate an included header to its\ncorresponding target and the latter makes it easy to scan interface headers with\nthe correct preprocessor flags. If a target does not define the\n`INTERFACE_HEADER_SETS` property, included headers will still be associated if\nthe header is located in one of its\n[`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html).\nSince multiple targets could use the same include directory, one or more\ninclude prefix strings can be provided to disambiguate.\n\nUpdate your cmake logic to include\n[link_what_you_include.cmake](cmake/link_what_you_include.cmake) and call\n`link_what_you_include(target ...)` for every target you want to participate in\nthe verification process. Configure the build system with a single-config\ngenerator and set the CMAKE_EXPORT_COMPILE_COMMANDS cache variable. Then run\nthe lwyi executable and point it at the configured build directory.\n\n```\n$ lwyi -d /path/to/the/build/dir\n```\n\n### Contributing\n\nEsri welcomes contributions from anyone and everyone. Please see our\n[guidelines for contributing](https://github.com/esri/contributing).\n\n### License\n\nCopyright 2025 Esri\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n\u003e http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nA copy of the license is available in the repository's\n[LICENSE.txt](./LICENSE.txt) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Flink-what-you-include","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesri%2Flink-what-you-include","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Flink-what-you-include/lists"}