This is a proposal to eliminate the `usingnamespace` keyword from the Zig progra…mming language. I know this is a controversial one, but please read the whole thing before leaving any comments.
## Overview
The `usingnamespace` keyword has existed in Zig for many years. Its functionality is to import all declarations from one namespace into another.
`usingnamespace` was formerly called `use`, and was actually considered for deletion in the past -- see #2014. Ultimately, Andrew decided not to remove it from the language, with the following main justifications:
* `pub usingnamespace @cImport(@cInclude(...))` is a helpful pattern. This point is made obsolete by #20630.
* Some parts of the standard library make use of `usingnamespace`. These uses have been all but eliminated -- this is discussed below.
In recent years, the usage of `usingnamespace` in first-party ZSF code has declined. Across the entire compiler, standard library, and compiler-rt, there is now precisely one usage of `usingnamespace`:
https://github.com/ziglang/zig/blob/9d9b5a11e873cc15e3f1b6e506ecf22c8380c87d/lib/std/c.zig#L35-L48
Every other `grep` result that shows up for `usingnamespace` is simply supporting code for it across the compiler pipeline. This leads us to revisit the decision to keep it in the language.
**This is a proposal to delete `usingnamespace` from the language, with no direct replacement.**
## Why?
This proposal is not just to prune language complexity (although that is one motivation). In fact, there are three practical reasons I believe this language feature should be deleted.
### Code Readability
A core tenet of Zig's design is that readability is favored over writability, because the majority of any programmer's time is inevitably spent *reading* code rather than writing it. Unfortunately, `usingnamespace` has a tendency to significantly harm the readability of code that uses it.
Consider, as an example, the singular usage of `usingnamespace` in the standard library. If I want to call the Linux libc function `dl_iterate_phdr`, where should I look to determine if this function is in `std.c`? The obvious answer would be `std/c.zig`, but this is incorrect. The `usingnamespace` here means that the definition of this function is actually in `std/c/linux.zig`! Similarly, if I want to discover which platforms this function is defined on, and how its signature differs between platforms, I have to check each file in `std/c/*.zig`, and compare the signatures between those files.
Without `usingnamespace`, the story would be completely different. `dl_iterate_phdr` would be defined directly in `std/c.zig`, perhaps with a `switch` per-target. All of the information about this function would be *localized* to the namespace which actually contains it: I could see, in the space of perhaps 10 lines, which platforms this function was defined on, and whether/how the signatures differ.
This is one example of a more general problem with `usingnamespace`: it adds distance between the "expected" definition of a declaration and its "actual" definition. Without `usingnamespace`, discovering a declaration's definition site is incredibly simple: you find the definition of the namespace you are looking in (for instance, you determine that `std.c` is defined by `std/c.zig`), and you find the identifier being defined within that type declaration. With `usingnamespace`, however, you can be led on a wild goose chase through different types and files.
Not only does this harm readability for humans, but it is also problematic for tooling; for instance, Autodoc cannot reasonably see through non-trivial uses of `usingnamespace` (try looking for `dl_iterate_phdr` under `std.c` in the std documentation).
### Poor Namespacing
`usingnamespace` can encourage questionable namespacing. When declarations are stored in a separate file, that typically means they share something in common which is not shared with the contents of another file. As such, it is likely a very reasonable choice to actually expose the contents of that file via a separate namespace, rather than including them in a more general parent namespace. I often summarize this point as "**Namespaces are good, actually**".
For an example of this, consider `std.os.linux.IoUring`. In Zig 0.11.0, this type (at the time named `IO_Uring`) lived in a file `std/os/linux/io_uring.zig`, alongside many "sibling" types, such as `SubmissionQueue`. This file was imported into `std.os.linux` with a `pub usingnamespace`, resulting in namespacing like `std.os.linux.SubmissionQueue`. However, since `SubmissionQueue` is directly related to io_uring, this namespacing makes no sense! Instead, `SubmissionQueue` should indeed be namespaced within a namespace specific to io_uring. As it happens, this namespace is, well, the `IoUring` type. We now have `std.os.linux.IoUring.SubmissionQueue`, which is unambiguously better namespacing.
### Incremental Compilation
A key feature of the Zig compiler, which is rapidly approaching usability, is incremental compilation: the ability for the compiler to determine which parts of a Zig program have changed, and recompile only the necessary code.
As a part of this, we must model "dependencies" between declarations in Zig code. For instance, when you write an identifier which refers to a container-level declaration, a dependency is registered so that if that declaration's type or value changes, this declaration must also be recompiled.
I don't intend to explain the whole dependency model in the compiler here, but suffice to say, there are some complexities. One complexity which is currently unsolved is `usingnamespace`. The current (WIP) implementation of incremental compilation essentially assumes that `usingnamespace` is never used; it is not modeled in the dependency system. The reason for this is that it complicates the model for the reasons we identified above: without `usingnamespace`, we can know all names within a namespace purely from syntax, whereas with `usingnamespace`, semantic analysis may be required. The Zig language has some slightly subtle rules about when `usingnamespace` declarations are semantically analyzed, which aims to reduce dependency loops. Chances are you have never thought about this -- that's the goal of those rules! However, they very much exist, and modelling them correctly in incremental compilation -- especially without performing a large amount of unnecessary re-analysis -- is a difficult problem. It's absolutely a surmountable one, but it may be preferable to simplify the language so that this complexity no longer exists.
Note that changing the language to aid incremental compilation, even if the changes are not strictly necessary, is something Andrew has explicitly stated he is happy to do. There is precedent for this in, for example, the recent changes to type resolution, which changed the language (by introducing the rule that all referenced types are fully resolved by the end of compilation) to simplify the implementation of incremental compilation.
## Use Cases
This section addresses some common use cases of `usingnamespace`, and discusses alternative methods to achieve the same result without the use of this language feature.
### Conditional Inclusion
`usingnamespace` can be used to conditionally include a declaration as follows:
```zig
pub usingnamespace if (have_foo) struct {
pub const foo = 123;
} else struct {};
```
The solution here is pretty simple: usually, you can just include the declaration unconditionally. Zig's lazy compilation means that it will not be analyzed unless referenced, so there are no problems!
```zig
pub const foo = 123;
```
Occasionally, this is not a good solution, as it lacks safety. Perhaps analyzing `foo` will always work, but will only give a meaningful result if `have_foo` is true, and it would be a bug to use it in any other case. In such cases, the declaration can be conditionally made a compile error:
```zig
pub const foo = if (have_foo)
123
else
@compileError("foo not supported on this target");
```
Note that this does break feature detection with `@hasDecl`. However, feature detection through this mechanism is discouraged anyway, as it is very prone to typos and bitrotting.
### Implementation Switching
A close cousin of conditional inclusion, `usingnamespace` can also be used to select from multiple implementations of a declaration at comptime:
```zig
pub usingnamespacee switch (target) {
.windows => struct {
pub const target_name = "windows";
pub fn init() T {
// ...
}
},
else => struct {
pub const target_name = "something good";
pub fn init() T {
// ...
}
},
};
```
The alternative to this is incredibly simple, and in fact, results in obviously better code: just make the definition itself a conditional.
```zig
pub const target_name = switch (target) {
.windows => "windows",
else => "something good",
};
pub const init = switch (target) {
.windows => initWindows,
else => initOther,
};
fn initWindows() T {
// ...
}
fn initOther() T {
// ...
}
```
### Mixins
Okay, now we're getting to the big one. A very common use case for `usingnamespace` in the wild -- perhaps *the* most common use case -- is to implement mixins.
```zig
/// Mixin to provide methods to manipulate the `_counter` field.
pub fn CounterMixin(comptime T: type) type {
return struct {
pub fn incrementCounter(x: *T) void {
x._counter += 1;
}
pub fn resetCounter(x: *T) void {
x._counter = 0;
}
};
}
pub const Foo = struct {
_counter: u32 = 0,
pub usingnamespace CounterMixin(Foo);
};
```
Obviously this simple example is a little silly, but the use case is legitimate: mixins can be a useful concept and are used by some major projects such as TigerBeetle.
The alternative for this makes a key observation which I already mentioned above: **namespacing is good, actually**. The same logic can be applied to mixins. The word "counter" in `incrementCounter` and `resetCounter` already kind of *is* a namespace in spirit -- it's like how we used to have `std.ChildProcess` but have since renamed it to `std.process.Child`. The same idea can be applied here: what if instead of `foo.incrementCounter()`, you called `foo.counter.increment()`?
This can be elegantly achieved using a zero-bit field and `@fieldParentPtr`. Here is the above example ported to use this mechanism:
```zig
/// Mixin to provide methods to manipulate the `_counter` field.
pub fn CounterMixin(comptime T: type) type {
return struct {
pub fn increment(m: *@This()) void {
const x: *T = @alignCast(@fieldParentPtr("counter", m));
x._counter += 1;
}
pub fn reset(m: *@This()) void {
const x: *T = @alignCast(@fieldParentPtr("counter", m));
x._counter = 0;
}
};
}
pub const Foo = struct {
_counter: u32 = 0,
counter: CounterMixin(Foo) = .{},
};
```
This code provides identical effects, but with a usage of `foo.counter.increment()` rather than `foo.incrementCounter()`. We have applied namespacing to our mixin using zero-bit fields. In fact, this mechanism is *more* useful, because it allows you to also include fields! For instance, in this case, we could move the `_counter` field to `CounterMixin`. Of course, in this case that wouldn't be a mixin at all, but there are certainly cases where a mixin might require certain additional state, which this system allows you to avoid duplicating at the mixin's use site.
## External Projects
This section will look over uses of `usingnamespace` in some real-world projects and propose alternative schemes to achieve the same effect.
### Mach
I have discussed Mach's usages of `usingnamespace` with @slimsag in the past, and we agreed on migration mechanisms, so I won't go into too much detail here. A quick summary of a few of them:
* `math/ray.zig`: this is redundant; the error case is already caught above.
* `math/mat.zig`: this logic can be mostly generalized with some simple metaprogramming. What remains can be handled by the "implementation switching" approach discussed above or similar.
* `math/vec.zig`: same as `mat.zig`.
* `sysaudio/wasapi/win32.zig`: these are a little awkward for ABI reasons, but this is generated code so it's fine if it ends up a little verbose, and most of it is unused IIRC.
### TigerBeetle
* `node.zig`: this code uses `usingnamespace` to merge two namespaces. Probably these should just be imported separately, under `tb` and `tb_client` respectively.
* `testing/marks.zig`: re-expose the 4 functions from `std.log.scoped`, and conditionally define `mark.err` etc as needed.
* `vsr/message_header.zig`: namespaced mixins, as described above.
* `flags.zig`: define `main` conditionally, as described above.
* `ring_buffer.zig`: implementation switching, as described above.
* `tracer.zig`: implementation switching, as described above.
* `lsm/segmented_array.zig`: conditional inclusion, as described above.
* `clients/java/src/jni.zig`: replace `usingnamespace JniInterface(JavaVM)` with `const Interface = JniInterface(JavaVM)`, and replace `JavaVM.interface_call` with `Interface.call` (renaming that function).
* `clients/node/src/c.zig`: to be replaced with build system C translation, see #20630.
### ghostty
I won't explain any specific cases here, since ghostty is currently in closed beta. However, I have glanced through its usages of `usingnamespace`, and it appears most could be eliminated with a combination of (a) more namespacing and (b) occasional manual re-exports.