Go 1.26 Introduces Source-Level Inliner for Automatic API Upgrades
Introduction
The release of Go 1.26 brings a completely reimagined go fix subcommand, aimed at helping developers keep their codebases current and efficient. Among its new features, the source-level inliner stands out as a foundational component that enables package authors to define their own migrations and code modernizations. This article explores how the source-level inliner works, how it differs from traditional compiler inlining, and how it is already being used by tools like gopls and go fix to simplify API transitions.
What Is Source-Level Inlining?
Inlining is a transformation that replaces a function call with the body of the called function, after substituting actual arguments for formal parameters. While compiler inlining performs this substitution on an ephemeral intermediate representation to generate more efficient machine code, source-level inlining modifies the source code itself, producing durable changes that persist across builds.
Go’s source-level inliner was developed in 2023 and has been quietly available through gopls’ interactive refactoring tools. For instance, the “Inline call” code action (accessible via the “Source Action…” menu in VS Code) uses this inliner to replace a function call with its definition. This refactoring handles many subtle correctness issues, such as variable shadowing, renames, and side effect evaluation, making it safe and reliable for real-world code.
The Inliner’s Role in go fix
The new go fix command in Go 1.26 includes several bespoke modernizers for language and library features, but the source-level inliner is the first general-purpose “self-service” modernizer. This means that any package author can write simple migration rules to automate API upgrades across their projects. The inliner’s correctness guarantees ensure that these migrations do not introduce subtle bugs.
Before Go 1.26, go fix was limited to a fixed set of transformations defined by the Go team. Now, with the source-level inliner as a building block, the community can contribute migrations for their own libraries. For example, if a library deprecates a function in favor of a new one, the author can define an inline replacement that automatically updates all call sites.
Technical Deep Dive
How Source-Level Inlining Works
The inliner operates by parsing the Go source code, identifying the call to be inlined, and then substituting the function body into the call site. Key challenges include:
- Variable name conflicts: The inliner must rename identifiers in the inlined code to avoid shadowing variables in the calling scope.
- Side effects: Arguments are evaluated exactly once, preserving order and preventing duplicate evaluation.
- Return statements: The inliner transforms
returnstatements into assignments to the result variable(s) and appropriate control flow.
These challenges are similar to those faced by compilers, but the source-level approach demands additional care to produce readable, idiomatic Go code.
The Role of gopls
The Go language server (gopls) was the first consumer of the source-level inliner. It uses the inliner not only for the “Inline call” action but also for other refactorings such as “Change signature” and “Remove unused parameter.” In these cases, the inliner is invoked internally to eliminate function calls after parameter changes, ensuring that the resulting code is correct and clean.
Correctness and Safety
One of the primary design goals of the source-level inliner is correctness. It carefully tracks scopes and aliasing rules defined by the Go specification. For example, when inlining a function with multiple returns, the inliner creates a new block scope to avoid leaking variables. It also handles defer statements and closures correctly, a notoriously tricky area.
Using the Source-Level Inliner in Practice
To use the source-level inliner directly through gopls, place your cursor on a function call and invoke the “Inline call” refactoring (e.g., Ctrl+. in VS Code then select “Source Action…”). The inliner will replace the call with the body of the function, adjusting the code as needed.
For automated migrations via go fix, package authors can define inline rules as part of their library’s upgrade guide. For instance, a rule could specify that calls to oldpkg.Foo(x) should be replaced with newpkg.Bar(x, true). The inliner applies these rules across all Go files in the project, creating a diff that developers can review and commit.
Example: Before and After
Consider a function sum(a, b int) int { return a + b }. Inlining the call sum(3, 4) in a function six() would produce { return 3 + 4 }, which the compiler can then further optimize. The inliner ensures that any side effects of arguments are preserved and that the result is assigned correctly.
Conclusion
The source-level inliner is a powerful addition to the Go toolchain. By providing a safe and automatic way to update source code, it empowers package authors to deliver smooth API migrations and encourages the entire Go ecosystem to stay up-to-date. As more developers adopt go fix and gopls refactorings, we can expect fewer deprecated function calls and more consistent codebases. For a deeper dive, refer to the original Go Blog post by Alan Donovan and explore the go fix documentation.