motiejus/zig
1
Fork 0
Code Releases Activity

langref: improve @import documentation

Browse Source 
Rewrite to be more clear and correct. Also, explain ZON imports.

Resolves: #23314
This commit is contained in:
mlugg
2025-07-30 11:17:45 +01:00
committed by Matthew Lugg
parent e941ce3e68
commit bce6a7c215
1 changed files with 17 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
doc/langref.html.in
View File

@@ -4952,34 +4952,25 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
{#header_close#} {#header_close#}
{#header_open|@import#} {#header_open|@import#}
<pre>{#syntax#}@import(comptime path: []const u8) type{#endsyntax#}</pre> <pre>{#syntax#}@import(comptime target: []const u8) anytype{#endsyntax#}</pre>
<p> <p>Imports the file at {#syntax#}target{#endsyntax#}, adding it to the compilation if it is not already
This function finds a zig file corresponding to {#syntax#}path{#endsyntax#} and adds it to the build, added. {#syntax#}target{#endsyntax#} is either a relative path to another file from the file containing
if it is not already added. the {#syntax#}@import{#endsyntax#} call, or it is the name of a {#link|module|Compilation Model#}, with
</p> the import referring to the root source file of that module. Either way, the file path must end in
<p> either <code>.zig</code> (for a Zig source file) or <code>.zon</code> (for a ZON data file).</p>
Zig source files are implicitly structs, with a name equal to the file's basename with the extension <p>If {#syntax#}target{#endsyntax#} refers to a Zig source file, then {#syntax#}@import{#endsyntax#} returns
truncated. {#syntax#}@import{#endsyntax#} returns the struct type corresponding to the file. that file's {#link|corresponding struct type|Source File Structs#}, essentially as if the builtin call was
</p> replaced by {#syntax#}struct { FILE_CONTENTS }{#endsyntax#}. The return type is {#syntax#}type{#endsyntax#}.</p>
<p> <p>If {#syntax#}target{#endsyntax#} refers to a ZON file, then {#syntax#}@import{#endsyntax#} returns the value
Declarations which have the {#syntax#}pub{#endsyntax#} keyword may be referenced from a different of the literal in the file. If there is an inferred {#link|result type|Result Types#}, then the return type
source file than the one they are declared in. is that type, and the ZON literal is interpreted as that type ({#link|Result Types#} are propagated through
</p> the ZON expression). Otherwise, the return type is the type of the equivalent Zig expression, essentially as
<p> if the builtin call was replaced by the ZON file contents.</p>
{#syntax#}path{#endsyntax#} can be a relative path or it can be the name of a package. <p>The following modules are always available for import:</p>
If it is a relative path, it is relative to the file that contains the {#syntax#}@import{#endsyntax#}
function call.
</p>
<p>
The following packages are always available:
</p>
<ul> <ul>
<li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li> <li>{#syntax#}@import("std"){#endsyntax#} - Zig Standard Library</li>
<li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information <li>{#syntax#}@import("builtin"){#endsyntax#} - Target-specific information. The command <code>zig build-exe --show-builtin</code> outputs the source to stdout for reference.</li>
The command <code>zig build-exe --show-builtin</code> outputs the source to stdout for reference. <li>{#syntax#}@import("root"){#endsyntax#} - Alias for the root module. In typical project structures, this means it refers back to <code>src/main.zig</code>.
</li>
<li>{#syntax#}@import("root"){#endsyntax#} - Root source file
This is usually <code>src/main.zig</code> but depends on what file is built.
</li> </li>
</ul> </ul>
{#see_also|Compile Variables|@embedFile#} {#see_also|Compile Variables|@embedFile#}