| ... | @@ -798,7 +798,7 @@ | ... | @@ -798,7 +798,7 @@ |
| 798 | value. Using this value would be a bug. The value will be unused, or overwritten before being used." | 798 | value. Using this value would be a bug. The value will be unused, or overwritten before being used." |
| 799 | </p> | 799 | </p> |
| 800 | <p> | 800 | <p> |
| 801 | In {#link|Debug#} and {#link|ReleaseSafe#} mode, Zig writes {#syntax#}0xaa{#endsyntax#} bytes to undefined memory. This is to catch | 801 | In {#link|debug#} and {#link|safe#} mode, Zig writes {#syntax#}0xaa{#endsyntax#} bytes to undefined memory. This is to catch |
| 802 | bugs early, and to help detect use of undefined memory in a debugger. However, this behavior is only an | 802 | bugs early, and to help detect use of undefined memory in a debugger. However, this behavior is only an |
| 803 | implementation feature, not a language semantic, so it is not guaranteed to be observable to code. | 803 | implementation feature, not a language semantic, so it is not guaranteed to be observable to code. |
| 804 | </p> | 804 | </p> |
| ... | @@ -2854,11 +2854,11 @@ or | ... | @@ -2854,11 +2854,11 @@ or |
| 2854 | {#header_close#} | 2854 | {#header_close#} |
| 2855 | {#header_open|unreachable#} | 2855 | {#header_open|unreachable#} |
| 2856 | <p> | 2856 | <p> |
| 2857 | In {#link|Debug#} and {#link|ReleaseSafe#} mode | 2857 | In {#link|debug#} and {#link|safe#} mode |
| 2858 | {#syntax#}unreachable{#endsyntax#} emits a call to {#syntax#}panic{#endsyntax#} with the message <code>reached unreachable code</code>. | 2858 | {#syntax#}unreachable{#endsyntax#} emits a call to {#syntax#}panic{#endsyntax#} with the message <code>reached unreachable code</code>. |
| 2859 | </p> | 2859 | </p> |
| 2860 | <p> | 2860 | <p> |
| 2861 | In {#link|ReleaseFast#} and {#link|ReleaseSmall#} mode, the optimizer uses the assumption that {#syntax#}unreachable{#endsyntax#} code | 2861 | In {#link|fast#} and {#link|small#} mode, the optimizer uses the assumption that {#syntax#}unreachable{#endsyntax#} code |
| 2862 | will never be hit to perform optimizations. | 2862 | will never be hit to perform optimizations. |
| 2863 | </p> | 2863 | </p> |
| 2864 | {#header_open|Basics#} | 2864 | {#header_open|Basics#} |
| ... | @@ -2871,7 +2871,7 @@ or | ... | @@ -2871,7 +2871,7 @@ or |
| 2871 | {#header_open|At Compile-Time#} | 2871 | {#header_open|At Compile-Time#} |
| 2872 | {#code|test_comptime_unreachable.zig#} | 2872 | {#code|test_comptime_unreachable.zig#} |
| 2873 | | 2873 | |
| 2874 | {#see_also|Zig Test|Build Mode|comptime#} | 2874 | {#see_also|Zig Test|Optimization Mode|comptime#} |
| 2875 | {#header_close#} | 2875 | {#header_close#} |
| 2876 | {#header_close#} | 2876 | {#header_close#} |
| 2877 | {#header_open|noreturn#} | 2877 | {#header_open|noreturn#} |
| ... | @@ -3094,7 +3094,7 @@ or | ... | @@ -3094,7 +3094,7 @@ or |
| 3094 | Here we know for sure that "1234" will parse successfully. So we put the | 3094 | Here we know for sure that "1234" will parse successfully. So we put the |
| 3095 | {#syntax#}unreachable{#endsyntax#} value on the right hand side. | 3095 | {#syntax#}unreachable{#endsyntax#} value on the right hand side. |
| 3096 | {#syntax#}unreachable{#endsyntax#} invokes safety-checked {#link|Illegal Behavior#}, so | 3096 | {#syntax#}unreachable{#endsyntax#} invokes safety-checked {#link|Illegal Behavior#}, so |
| 3097 | in {#link|Debug#} and {#link|ReleaseSafe#}, triggers a safety panic by default. So, while | 3097 | in {#link|debug#} and {#link|safe#}, triggers a safety panic by default. So, while |
| 3098 | we're debugging the application, if there <em>was</em> a surprise error here, the application | 3098 | we're debugging the application, if there <em>was</em> a surprise error here, the application |
| 3099 | would crash appropriately. | 3099 | would crash appropriately. |
| 3100 | </p> | 3100 | </p> |
| ... | @@ -3187,7 +3187,7 @@ fn createFoo(param: i32) !Foo { | ... | @@ -3187,7 +3187,7 @@ fn createFoo(param: i32) !Foo { |
| 3187 | <li>These primitives give enough expressiveness that it's completely practical | 3187 | <li>These primitives give enough expressiveness that it's completely practical |
| 3188 | to have failing to check for an error be a compile error. If you really want | 3188 | to have failing to check for an error be a compile error. If you really want |
| 3189 | to ignore the error, you can add {#syntax#}catch unreachable{#endsyntax#} and | 3189 | to ignore the error, you can add {#syntax#}catch unreachable{#endsyntax#} and |
| 3190 | get the added benefit of crashing in Debug and ReleaseSafe modes if your assumption was wrong. | 3190 | get the added benefit of crashing in {#link|debug#} and {#link|safe#} modes if your assumption was wrong. |
| 3191 | </li> | 3191 | </li> |
| 3192 | <li> | 3192 | <li> |
| 3193 | Since Zig understands error types, it can pre-weight branches in favor of | 3193 | Since Zig understands error types, it can pre-weight branches in favor of |
| ... | @@ -3269,7 +3269,7 @@ fn createFoo(param: i32) !Foo { | ... | @@ -3269,7 +3269,7 @@ fn createFoo(param: i32) !Foo { |
| 3269 | to increase their development pace. | 3269 | to increase their development pace. |
| 3270 | </p> | 3270 | </p> |
| 3271 | <p> | 3271 | <p> |
| 3272 | Error Return Traces are enabled by default in {#link|Debug#} builds and disabled by default in {#link|ReleaseFast#}, {#link|ReleaseSafe#} and {#link|ReleaseSmall#} builds. | 3272 | Error Return Traces are enabled by default in {#link|debug#} builds and disabled by default in {#link|fast#}, {#link|safe#} and {#link|small#} builds. |
| 3273 | </p> | 3273 | </p> |
| 3274 | <p> | 3274 | <p> |
| 3275 | There are a few ways to activate this error return tracing feature: | 3275 | There are a few ways to activate this error return tracing feature: |
| ... | @@ -3657,7 +3657,7 @@ void do_a_thing(struct Foo *foo) { | ... | @@ -3657,7 +3657,7 @@ void do_a_thing(struct Foo *foo) { |
| 3657 | {#code|zero_bit_types.zig#} | 3657 | {#code|zero_bit_types.zig#} |
| 3658 | | 3658 | |
| 3659 | <p>When this turns into machine code, there is no code generated in the | 3659 | <p>When this turns into machine code, there is no code generated in the |
| 3660 | body of {#syntax#}entry{#endsyntax#}, even in {#link|Debug#} mode. For example, on x86_64:</p> | 3660 | body of {#syntax#}entry{#endsyntax#}, even in {#link|debug#} mode. For example, on x86_64:</p> |
| 3661 | <pre><code>0000000000000010 <entry>: | 3661 | <pre><code>0000000000000010 <entry>: |
| 3662 | 10: 55 push %rbp | 3662 | 10: 55 push %rbp |
| 3663 | 11: 48 89 e5 mov %rsp,%rbp | 3663 | 11: 48 89 e5 mov %rsp,%rbp |
| ... | @@ -6022,15 +6022,15 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6022,15 +6022,15 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6022 | | 6022 | |
| 6023 | {#header_close#} | 6023 | {#header_close#} |
| 6024 | | 6024 | |
| 6025 | {#header_open|Build Mode#} | 6025 | {#header_open|Optimization Mode#} |
| 6026 | <p> | 6026 | <p> |
| 6027 | Zig has four build modes: | 6027 | Zig has four optimization modes: |
| 6028 | </p> | 6028 | </p> |
| 6029 | <ul> | 6029 | <ul> |
| 6030 | <li>{#link|Debug#} (default)</li> | 6030 | <li>{#link|debug#} (default)</li> |
| 6031 | <li>{#link|ReleaseFast#}</li> | 6031 | <li>{#link|fast#}</li> |
| 6032 | <li>{#link|ReleaseSafe#}</li> | 6032 | <li>{#link|safe#}</li> |
| 6033 | <li>{#link|ReleaseSmall#}</li> | 6033 | <li>{#link|small#}</li> |
| 6034 | </ul> | 6034 | </ul> |
| 6035 | <p> | 6035 | <p> |
| 6036 | To add standard build options to a <code class="file">build.zig</code> file: | 6036 | To add standard build options to a <code class="file">build.zig</code> file: |
| ... | @@ -6041,12 +6041,12 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6041,12 +6041,12 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6041 | This causes these options to be available: | 6041 | This causes these options to be available: |
| 6042 | </p> | 6042 | </p> |
| 6043 | <dl> | 6043 | <dl> |
| 6044 | <dt><kbd>-Doptimize=Debug</kbd></dt><dd>Optimizations off and safety on (default)</dd> | 6044 | <dt><kbd>-Doptimize=debug</kbd></dt><dd>Optimizations off and safety on (default)</dd> |
| 6045 | <dt><kbd>-Doptimize=ReleaseSafe</kbd></dt><dd>Optimizations on and safety on</dd> | 6045 | <dt><kbd>-Doptimize=safe</kbd></dt><dd>Optimizations on and safety on</dd> |
| 6046 | <dt><kbd>-Doptimize=ReleaseFast</kbd></dt><dd>Optimizations on and safety off</dd> | 6046 | <dt><kbd>-Doptimize=fast</kbd></dt><dd>Optimizations on and safety off</dd> |
| 6047 | <dt><kbd>-Doptimize=ReleaseSmall</kbd></dt><dd>Size optimizations on and safety off</dd> | 6047 | <dt><kbd>-Doptimize=small</kbd></dt><dd>Size optimizations on and safety off</dd> |
| 6048 | </dl> | 6048 | </dl> |
| 6049 | {#header_open|Debug#} | 6049 | {#header_open|debug#} |
| 6050 | {#shell_samp#}$ zig build-exe example.zig{#end_shell_samp#} | 6050 | {#shell_samp#}$ zig build-exe example.zig{#end_shell_samp#} |
| 6051 | <ul> | 6051 | <ul> |
| 6052 | <li>Fast compilation speed</li> | 6052 | <li>Fast compilation speed</li> |
| ... | @@ -6056,8 +6056,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6056,8 +6056,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6056 | <li>No reproducible build requirement</li> | 6056 | <li>No reproducible build requirement</li> |
| 6057 | </ul> | 6057 | </ul> |
| 6058 | {#header_close#} | 6058 | {#header_close#} |
| 6059 | {#header_open|ReleaseFast#} | 6059 | {#header_open|fast#} |
| 6060 | {#shell_samp#}$ zig build-exe example.zig -O ReleaseFast{#end_shell_samp#} | 6060 | {#shell_samp#}$ zig build-exe example.zig -Ofast{#end_shell_samp#} |
| 6061 | <ul> | 6061 | <ul> |
| 6062 | <li>Fast runtime performance</li> | 6062 | <li>Fast runtime performance</li> |
| 6063 | <li>Safety checks disabled</li> | 6063 | <li>Safety checks disabled</li> |
| ... | @@ -6066,8 +6066,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6066,8 +6066,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6066 | <li>Reproducible build</li> | 6066 | <li>Reproducible build</li> |
| 6067 | </ul> | 6067 | </ul> |
| 6068 | {#header_close#} | 6068 | {#header_close#} |
| 6069 | {#header_open|ReleaseSafe#} | 6069 | {#header_open|safe#} |
| 6070 | {#shell_samp#}$ zig build-exe example.zig -O ReleaseSafe{#end_shell_samp#} | 6070 | {#shell_samp#}$ zig build-exe example.zig -Osafe{#end_shell_samp#} |
| 6071 | <ul> | 6071 | <ul> |
| 6072 | <li>Medium runtime performance</li> | 6072 | <li>Medium runtime performance</li> |
| 6073 | <li>Safety checks enabled</li> | 6073 | <li>Safety checks enabled</li> |
| ... | @@ -6076,8 +6076,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6076,8 +6076,8 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6076 | <li>Reproducible build</li> | 6076 | <li>Reproducible build</li> |
| 6077 | </ul> | 6077 | </ul> |
| 6078 | {#header_close#} | 6078 | {#header_close#} |
| 6079 | {#header_open|ReleaseSmall#} | 6079 | {#header_open|small#} |
| 6080 | {#shell_samp#}$ zig build-exe example.zig -O ReleaseSmall{#end_shell_samp#} | 6080 | {#shell_samp#}$ zig build-exe example.zig -Osmall{#end_shell_samp#} |
| 6081 | <ul> | 6081 | <ul> |
| 6082 | <li>Medium runtime performance</li> | 6082 | <li>Medium runtime performance</li> |
| 6083 | <li>Safety checks disabled</li> | 6083 | <li>Safety checks disabled</li> |
| ... | @@ -6122,7 +6122,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6122,7 +6122,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6122 | </p> | 6122 | </p> |
| 6123 | <p> | 6123 | <p> |
| 6124 | Most Illegal Behavior is safety-checked. However, to facilitate optimizations, safety checks are disabled by default | 6124 | Most Illegal Behavior is safety-checked. However, to facilitate optimizations, safety checks are disabled by default |
| 6125 | in the {#link|ReleaseFast#} and {#link|ReleaseSmall#} optimization modes. Safety checks can also be enabled or disabled | 6125 | in the {#link|fast#} and {#link|small#} optimization modes. Safety checks can also be enabled or disabled |
| 6126 | on a per-block basis, overriding the default for the current optimization mode, using {#link|@setRuntimeSafety#}. When | 6126 | on a per-block basis, overriding the default for the current optimization mode, using {#link|@setRuntimeSafety#}. When |
| 6127 | safety checks are disabled, Safety-Checked Illegal Behavior behaves like Unchecked Illegal Behavior; that is, any behavior | 6127 | safety checks are disabled, Safety-Checked Illegal Behavior behaves like Unchecked Illegal Behavior; that is, any behavior |
| 6128 | may result from invoking it. | 6128 | may result from invoking it. |
| ... | @@ -6464,14 +6464,14 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6464,14 +6464,14 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6464 | </li> | 6464 | </li> |
| 6465 | <li> | 6465 | <li> |
| 6466 | Finally, if none of the above apply, you need a general purpose allocator. | 6466 | Finally, if none of the above apply, you need a general purpose allocator. |
| 6467 | If you are in Debug mode, {#syntax#}std.heap.DebugAllocator{#endsyntax#} is available as a | 6467 | If you are in {#link|debug#} mode, {#syntax#}std.heap.DebugAllocator{#endsyntax#} is available as a |
| 6468 | function that takes a {#link|comptime#} {#link|struct#} of configuration options and returns a type. | 6468 | function that takes a {#link|comptime#} {#link|struct#} of configuration options and returns a type. |
| 6469 | Generally, you will set up exactly one in your main function, and | 6469 | Generally, you will set up exactly one in your main function, and |
| 6470 | then pass it or sub-allocators around to various parts of your | 6470 | then pass it or sub-allocators around to various parts of your |
| 6471 | application. | 6471 | application. |
| 6472 | </li> | 6472 | </li> |
| 6473 | <li> | 6473 | <li> |
| 6474 | If you are compiling in ReleaseFast mode, {#syntax#}std.heap.smp_allocator{#endsyntax#} is | 6474 | If you are compiling in {#link|fast#} mode, {#syntax#}std.heap.smp_allocator{#endsyntax#} is |
| 6475 | a solid choice for a general purpose allocator. | 6475 | a solid choice for a general purpose allocator. |
| 6476 | </li> | 6476 | </li> |
| 6477 | <li> | 6477 | <li> |
| ... | @@ -6611,7 +6611,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val | ... | @@ -6611,7 +6611,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 6611 | Example of what is imported with {#syntax#}@import("builtin"){#endsyntax#}: | 6611 | Example of what is imported with {#syntax#}@import("builtin"){#endsyntax#}: |
| 6612 | </p> | 6612 | </p> |
| 6613 | {#builtin#} | 6613 | {#builtin#} |
| 6614 | {#see_also|Build Mode#} | 6614 | {#see_also|Optimization Mode#} |
| 6615 | {#header_close#} | 6615 | {#header_close#} |
| 6616 | {#header_open|Compilation Model#} | 6616 | {#header_open|Compilation Model#} |
| 6617 | <p> | 6617 | <p> |
| ... | @@ -7803,8 +7803,8 @@ fn readU32Be() u32 {} | ... | @@ -7803,8 +7803,8 @@ fn readU32Be() u32 {} |
| 7803 | {#syntax#}unreachable{#endsyntax#} can be used to assert that control flow will never happen upon a particular location. | 7803 | {#syntax#}unreachable{#endsyntax#} can be used to assert that control flow will never happen upon a particular location. |
| 7804 | Depending on the build mode, {#syntax#}unreachable{#endsyntax#} may emit a panic. | 7804 | Depending on the build mode, {#syntax#}unreachable{#endsyntax#} may emit a panic. |
| 7805 | <ul> | 7805 | <ul> |
| 7806 | <li>Emits a panic in {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, or when using <kbd>zig test</kbd>.</li> | 7806 | <li>Emits a panic in {#link|debug#} and {#link|safe#} mode, or when using <kbd>zig test</kbd>.</li> |
| 7807 | <li>Does not emit a panic in {#syntax#}ReleaseFast{#endsyntax#} and {#syntax#}ReleaseSmall{#endsyntax#} mode.</li> | 7807 | <li>Does not emit a panic in {#link|fast#} and {#link|small#} mode.</li> |
| 7808 | <li>See also {#link|unreachable#}</li> | 7808 | <li>See also {#link|unreachable#}</li> |
| 7809 | </ul> | 7809 | </ul> |
| 7810 | </td> | 7810 | </td> |
Andrew Kelley <andrew@ziglang.org> 2026-09-14 15:05:24-07:00