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