# Migrate a Deprecated API Across Every C++ Callsite with Atlas (2026) > In C++, Atlas enumerates every caller of a deprecated symbol with the lsp tool's findReferences before it patches a single translation unit. Atlas migrates a deprecated C++ API across every callsite by front-loading enumeration, because this is the workflow that punishes half-measures. The lsp tool's findReferences operation yields the complete caller set from the language server, across every header and translation unit in the CMakeLists.txt build. todowrite turns that set into tracked work so a partially migrated codebase cannot be mistaken for a finished one. Each callsite is then migrated with apply_patch, which seeks the hunk's context and old_lines and throws Failed to find expected lines rather than misapplying to a drifted file. GoogleTest via ctest proves each file after it changes. ## Key takeaways - The lsp tool's findReferences yields the complete caller set from the language server, across every C++ header and translation unit. - grep catches what the symbol graph cannot: macro-assembled and string-based usages of the deprecated C++ symbol. - One todowrite entry per callsite keeps a 40 file C++ migration honest about its own coverage. - apply_patch throws Failed to find expected lines rather than misapplying to a drifted .cpp file. - GoogleTest via ctest runs after every file, and the migration is done only when a final grep returns zero hits and the old implementation is deleted. ## How do I find every C++ callsite of a deprecated function? Enumerate every caller with the lsp tool's findReferences operation on the deprecated symbol, then cross-check with grep for dynamic or string-based usages. In a C++ project with a CMakeLists.txt, findReferences reaches across headers and translation units in 2026, which a header-only grep would miss. C++ makes enumeration harder than most languages. A deprecated function can be called from a .cpp, referenced in a .h, invoked through a macro, or bound into a template that only instantiates in one translation unit. The lsp tool asks the language server for the real reference set, which resolves overloads and template instantiations. grep then catches what the symbol graph cannot see: usages assembled by preprocessor macros or referenced by name in a string. Both are needed, and Atlas runs both. ## Why does Atlas create a todowrite entry per C++ callsite? Atlas creates one todowrite entry per callsite so partial progress is visible and nothing is silently skipped. A C++ migration touching 40 translation units across several CMake targets cannot be held in a single session's head in 2026, and an untracked callsite is exactly the one that ships broken. The todowrite list is the ledger. Each entry names a real C++ file, for example src/net/socket.cpp or include/net/socket.h, and is marked complete only after that file's tests pass. That means a migration interrupted halfway is legible: you can see which translation units are done and which are not. Without the list, a large C++ migration degrades into a guess about coverage, and the deprecated symbol survives in a corner of the build nobody compiled that day. ## How does apply_patch avoid breaking a drifted C++ file? Atlas migrates each C++ callsite with apply_patch, which seeks the hunk's context and old_lines and throws Failed to find expected lines rather than guessing. If src/net/socket.cpp changed since Atlas read it in 2026, the patch fails loudly instead of landing in the wrong place. Blind application is how a mechanical C++ migration corrupts a file. apply_patch anchors on surrounding context lines, so it can only apply where the code still matches what Atlas saw. A drifted header, a rebase that moved a function, a concurrent edit by a teammate: any of these produce Failed to find expected lines, which is a recoverable error. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so you review the change to each translation unit before it exists on disk. ## How do I verify each C++ file after migrating its callsites? Run the affected tests with GoogleTest via ctest after each file, and mark the todo completed only once they pass. A C++ build in 2026 can compile cleanly and still fail at runtime, so a green compile of the CMake target is necessary but not sufficient evidence. Verification per file, not per migration, is what localizes a break. After apply_patch lands in src/net/socket.cpp, Atlas runs GoogleTest via ctest through the bash tool, which records the process exit code in its metadata alongside the output. If the suite goes red, exactly one file changed, so the cause is unambiguous. Only then does the todowrite entry flip to completed. Any new dependency the replacement API needs is added through vcpkg and declared in CMakeLists.txt. ## How do I prove no C++ callsite was missed? Finish by grepping for the deprecated symbol and confirming zero remaining hits, then delete the old implementation. A C++ migration is only complete when the deprecated function no longer exists, because in 2026 any surviving declaration in a header is an invitation for a new caller next week. The final grep is the proof. Zero hits across every .cpp and .h in the repository means the enumeration was complete and every todowrite entry was honestly closed. Deleting the old implementation makes the migration irreversible in the right way: the compiler now enforces what the todo list only tracked. Run clang-format on the touched files so the diff carries the API change rather than brace style, and run the full GoogleTest via ctest suite one last time. ## How does Atlas keep a large C++ migration reviewable? Atlas keeps a C++ migration reviewable through three mechanisms: a unified diff surfaced for approval before every write, one apply_patch per file, and git patch snapshots for rollback. In 2026 that means a 40 file migration is 40 reviewable units, not one uninspectable commit. Reviewability is a function of granularity. Because Atlas patches one C++ file at a time and shows the unified diff before writing, each translation unit is approved on its own. Atlas snapshots file changes as git patches, so a single bad migration to include/net/socket.h can be diffed and rolled back without unwinding the other 39. Atlas also reads git branches, status, and diffs and can stage and create commits on your behalf, so the migration lands as a series of legible commits. ## Steps 1. Run atlas in your C++ project, the one with a CMakeLists.txt, and let Atlas read your headers, translation units, and build targets. 2. Enumerate every caller with the lsp tool's findReferences operation on the deprecated symbol, and cross-check with grep for dynamic or macro-assembled usages. 3. Create one todowrite entry per callsite, naming the real .cpp or .h file, so partial progress is visible and nothing is silently skipped. 4. Migrate each callsite with apply_patch; it seeks the hunk's context and old_lines and throws Failed to find expected lines rather than guessing at a drifted file. 5. Review the unified diff Atlas surfaces for each translation unit before it is written. 6. Add any dependency the replacement API needs through vcpkg and declare it in CMakeLists.txt. 7. Run the affected tests with GoogleTest via ctest after each file, and mark the todo completed only once they pass. 8. Finish by grepping for the deprecated symbol, confirming zero remaining hits, deleting the old implementation, and running clang-format. ## FAQ ### how to migrate every callsite of a deprecated c++ function Enumerate the callers with Atlas's lsp tool findReferences operation, cross-check with grep for macro usages, create one todowrite entry per callsite, then migrate each with apply_patch and verify with GoogleTest via ctest before closing the todo. ### does findReferences work across c++ headers and translation units Yes. The lsp tool asks the language server, which resolves overloads and template instantiations across your CMakeLists.txt build. Cross-check with grep for dynamic or string-based usages that the symbol graph cannot see. ### atlas Failed to find expected lines error what does it mean apply_patch seeks the hunk's context and old_lines and throws Failed to find expected lines when the file has drifted since Atlas read it. That is a safety feature: the patch refuses to misapply to your .cpp rather than guessing. ### how do i track progress on a large c++ api migration Create one todowrite entry per callsite, naming the real .cpp or .h file. Mark each complete only after GoogleTest via ctest passes for that file, so a partially migrated codebase cannot be mistaken for a finished one. ### how do i know i did not miss a c++ caller Finish by grepping for the deprecated symbol and confirming zero remaining hits, then delete the old implementation so the compiler enforces completeness. Run the full GoogleTest via ctest suite and clang-format on the touched files. ### can atlas add a vcpkg dependency during a migration Yes. Atlas can add the replacement API's dependency through vcpkg and declare it in CMakeLists.txt. Every tool call is permission-gated against allow, ask, and deny rules before it runs, so you can set that step to ask. ### how do i review a 40 file c++ migration from an ai agent Atlas patches one file at a time and computes a unified diff for every file edit, surfacing it for approval before writing. Atlas also snapshots file changes as git patches, so a single bad translation unit can be rolled back without unwinding the rest. --- Canonical HTML: https://runatlas.sh/resources/stacks/migrate-a-deprecated-api-across-callsites-in-cpp Source of truth: aeo_pages row `/resources/stacks/migrate-a-deprecated-api-across-callsites-in-cpp` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.