| ... | ... | @@ -4745,36 +4745,36 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val |
| 4745 | 4745 | <pre>{#syntax#}@deprecated(value: anytype) @TypeOf(value){#endsyntax#}</pre> |
| 4746 | 4746 | <pre>{#syntax#}@deprecated() void{#endsyntax#}</pre> |
| 4747 | 4747 | <p> |
| 4748 | | Used to mark a given code path as deprecated. It evaluates to the same value |
| 4749 | | passed in as argument, or the void value when given none. |
| 4748 | Marks a given code path as scheduled for removal. Evaluates to the same |
| 4749 | value passed in as argument, or the {#syntax#}void{#endsyntax#} value |
| 4750 | when given none. |
| 4750 | 4751 | </p> |
| 4751 | 4752 | <p> |
| 4752 | | As an example, a library that wishes to move or rename a declaration, while |
| 4753 | | deprecating usage of the old name can use {#syntax#}@deprecated{#endsyntax#} like so: |
| 4753 | When a public declaration has been moved to a new location, the old |
| 4754 | location can be marked {#syntax#}@deprecated{#endsyntax#}: |
| 4754 | 4755 | </p> |
| 4755 | 4756 | {#syntax_block|zig|root.zig#} |
| 4756 | 4757 | pub const fooToBar = @deprecated(bar.fromFoo); // moved |
| 4757 | 4758 | {#end_syntax_block#} |
| 4758 | | |
| 4759 | 4759 | <p> |
| 4760 | | By default it is a <b>compile error</b> to reference deprecated code in |
| 4761 | | a module defined by the root package, while it is not in modules defined |
| 4762 | | by dependencies. This behavior can be overridden for the entire dependency |
| 4763 | | tree by passing {#syntax#}-fallow-deprecated{#endsyntax#} or |
| 4764 | | {#syntax#}-fno-allow-deprecated{#endsyntax#} to {#syntax#}zig build{#endsyntax#}. |
| 4760 | By default deprecated code paths are disallowed in a module defined by |
| 4761 | the root package but allowed in modules defined by the rest of the |
| 4762 | dependency tree. This behavior can be overridden by passing |
| 4763 | <code>-fallow-deprecated</code> or <code>-fno-allow-deprecated</code> to |
| 4764 | <code>zig build</code>. |
| 4765 | 4765 | </p> |
| 4766 | 4766 | <p> |
| 4767 | | Usage of this builtin is meant to help <i>direct</i> consumers discover (and remove) |
| 4768 | | their dependance on deprecated code during the grace period before a deprecated |
| 4769 | | functionality is turned into a {#syntax#}@compileError{#endsyntax#} or |
| 4770 | | removed entirely. |
| 4767 | The purpose of {#syntax#}@deprecated{#endsyntax#} is to provide at least |
| 4768 | one version (a "grace period") of a package that supports both old and new APIs |
| 4769 | simultaneously, while providing tooling for programmers to discover what needs |
| 4770 | to be upgraded to migrate to the new API. Such a grace period has the key property |
| 4771 | that it allows a project's dependency tree to be upgraded <em>one package at a time</em>. |
| 4771 | 4772 | </p> |
| 4772 | | |
| 4773 | 4773 | <p> |
| 4774 | | Using {#syntax#}@deprecated{#endsyntax#} without an argument can be useful inside of blocks: |
| 4774 | Using {#syntax#}@deprecated{#endsyntax#} without an argument can be |
| 4775 | useful inside of conditionally compiled blocks: |
| 4775 | 4776 | </p> |
| 4776 | 4777 | {#code|test_deprecated_builtin.zig#} |
| 4777 | | |
| 4778 | 4778 | {#header_close#} |
| 4779 | 4779 | |
| 4780 | 4780 | {#header_open|@divExact#} |
Andrew Kelley <andrew@ziglang.org> 2025-02-25 23:02:24-08:00