change the default installation directory from ./zig-cache to ./

[andrewrk]

Accepted Proposal

---

If you run zig init-exe and then zig build --help you see this:

Steps:
  install (default)           Copy build artifacts to prefix path
  uninstall                   Remove build artifacts from prefix path
  run                         Run the app

General Options:
  -h, --help                  Print this help and exit
  --verbose                   Print commands before executing them
  --prefix [path]             Override default install prefix
  --search-prefix [path]      Add a path to look for binaries, libraries, headers
  --color [auto|off|on]       Enable or disable colored error messages

Project-Specific Options:
  -Dtarget=[string]           The CPU architecture, OS, and ABI to build for
  -Drelease-safe=[bool]       Optimizations on and safety on
  -Drelease-fast=[bool]       Optimizations on and safety off
  -Drelease-small=[bool]      Size optimizations on and safety off

Advanced Options:
...

As you can see, the default step is install. If you pass explicit steps on the command line, those steps are executed instead of the default. Currently, the install step has a default prefix path of zig-cache:

zig/lib/std/build.zig

Lines 194 to 210 in fd18252

	/// This function is intended to be called by std/special/build_runner.zig, not a build.zig file.
	pub fn resolveInstallPrefix(self: *Builder) void {
	if (self.dest_dir) |dest_dir| {
	const install_prefix = self.install_prefix orelse "/usr";
	self.install_path = fs.path.join(self.allocator, &[_][]const u8{ dest_dir, install_prefix }) catch unreachable;
	} else {
	const install_prefix = self.install_prefix orelse blk: {
	const p = self.cache_root;
	self.install_prefix = p;
	break :blk p;
	};
	self.install_path = install_prefix;
	}
	self.lib_dir = fs.path.join(self.allocator, &[_][]const u8{ self.install_path, "lib" }) catch unreachable;
	self.exe_dir = fs.path.join(self.allocator, &[_][]const u8{ self.install_path, "bin" }) catch unreachable;
	self.h_dir = fs.path.join(self.allocator, &[_][]const u8{ self.install_path, "include" }) catch unreachable;
	}

This proposal is to make the default installation directory named after the output mode:

zig/lib/std/builtin.zig

Lines 144 to 149 in fd18252

	pub const Mode = enum {
	Debug,
	ReleaseSafe,
	ReleaseFast,
	ReleaseSmall,
	};

So, if you were to run zig build with the defaults for init-exe, you would get:

Debug/bin/foo.exe

With zig build -Drelease-safe you would get:

ReleaseSafe/bin/foo.exe

However, I further propose that this changes when one takes advantage of setPreferredReleaseMode, in which case

Project-Specific Options:
  -Dtarget=[string]           The CPU architecture, OS, and ABI to build for
  -Drelease-safe=[bool]       Optimizations on and safety on
  -Drelease-fast=[bool]       Optimizations on and safety off
  -Drelease-small=[bool]      Size optimizations on and safety off

turns into

Project-Specific Options:
  -Dtarget=[string]           The CPU architecture, OS, and ABI to build for
  -Drelease=[bool]            Create a release build (ReleaseSafe)

where "ReleaseSafe" is whatever the preferred release mode is. In this case, zig build -Drelease would give you a default installation directory of "Release":

Release/bin/foo.exe

As a reminder, it is always possible to override the install prefix with the --prefix CLI parameter.

---

Comments / suggestions / counter proposals welcome! Nobody will be accused of doing the B-word in this thread!

[g-w1]

Is there any reason why this is not zig-cache/Release/bin/foo.exe or zig-cache/bin/Release/foo.exe, depending on if you can share things between multiple build modes (such as cached comptime values)? I would like this better because all the artifacts are in one place. (Keep in mind, i'm coming from Rust which does this so i'm probably biased). I like this proposal though, because it doesn't overwrite the zig-cache/bin/foo.exe when you change release mode.

[frmdstryr]

Maybe there should just be a .zigrc file that people can set their own defaults since getting people to agree on one way will likely never happen.

I prefer how it currently is as its easier to switch modes without having to update other commands.

[g-w1]

I also think that the default install directory should be in the same directory as build.zig and not in cwd() as I proposed in #7603, which I realized is a duplicate of this.

[andrewrk]

Here is what is accepted:

• Default install directory to be relative to build.zig and not in cwd() (change the default installation directory from ./zig-cache to ./ #7296 (comment))
• The directory will be named debug or release (lower case). All 3 release modes will map to release, whether or not setPreferredReleaseMode is used.

[andrewrk]

Reverted in fc38b42 due to a regression and pushback from the community. This issue is now open for discussion again.

[andrewrk]

One issue that this proposal does not take into account is that we currently do not have a concept of release/debug until the build.zig script creates one. However the build.zig script wants to access the installation directory. So we have a dependency cycle to resolve here if we wanted to put build mode into the install path.

[andrewrk]

Discussed during the stage2 meeting:

• build scripts should have access to the already computed install prefix (status quo)
• add a -p=foo and -p foo alias for --prefix to make it easier to type, for the use case of cwd being the build root but you want to have a build directory
• default prefix will be current working directory (instead of zig-cache)
• Follow-up proposal (separate): omit bin/ and lib/ directories when installing Windows applications, just throw everything in the top level. Let's check what other build systems such as Meson do.

[marler8997]

Why have a different convention for windows?

[marler8997]

Today we use $build_root/zig-cache as the default install prefix, what's the rationale behind changing it to $CWD? For example, why would we choose $CWD instead of $build_root?

[andrewrk]

For example, why would we choose $CWD instead of $build_root?

The main deciding factor is that it enables the use case of having a bunch of different build flags that you could mix and match so the user could name their own directories and do their own flag combos.

Why have a different convention for windows?

I'll make a follow-up proposal for that, so that won't be part of this one. The question is whether to have a convention that is consistent across different platforms, or to have a convention that is consistent across users' expectations for their own platforms (and my understanding is that Windows users expect .zip files with flat hierarchy).

[ikskuh]

Why have a different convention for windows?

Because if you build a project consisting of a shared library and an executable, you need to copy them to the same directory on windows anyway, but with FHS, the case is different

[marler8997]

Because if you build a project consisting of a shared library and an executable, you need to copy them to the same directory on windows anyway, but with FHS, the case is different

Ah that's true. On Linux ELF supports absolute path references or DT_RUNPATH and the like. I don't know of an equivalent on Windows that would allow an exe to find a dll that's not in the same directory. I quickly skimmed the docs and didn't find anything we could use either (https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order).

[ityonemo]

Just as a note, in the long run you might want release environments, that are tagged by the user, possibly as an argument to zig build. For example, a reasonable sane default set release environments would be "test", "dev", "prod" as basic environments, but someone else might want "test", "dev", "staging", "prod", or geographically segregated for compliance reasons: "prod-US"/"prod-EU". This could for example change what dependencies are loaded by the package manager, and there could be a many-to-many mapping between the release mode and the release environments, and if I had to pick I would want release environments to set the destination directory, and not the release mode. Such a thing would not preclude using the release mode as dirname in the short term.

[marler8997]

@ityonemo I think your examples further demonstrate the need for taking a "hands off" approach here. There are an endless number of strings one could put into the install directory name. build mode, datetime, language, backend, libc name, target arch/os/cpu, optimization level, the list goes on. So the proposed default of using CWD means that Zig is punting this decision to the user. Now Zig doesn't have to make the decision of a reasonable default set of strings to include in the install directory name.

[ityonemo]

I would say the only thing is that if you do have it be cwd the problem is it's easy to accidentally leave a binary artifact behind in the version control, which is not great. If you have some sort of build subdirectory, then it's an easy .gitignore.

[marler8997]

@ityonemo Yeah. If we made the default something like $CWD/install then that could have some benefits.

[KempWatson]

I've been amazed at the awkwardness of this and similar discussions. Should not one be simply able to run "zig build", and have the build system do anything relatively easily? Without needing arguments to zig build? Why is setting my own preferred target folder so hard?

[Paul-Dempsey]

@KempWatson please refrain from complaining on the issue tracker. Your comment contributes no facts or makes any specific proposal to move the issue forward. It is just a complaint. If you want to have a discussion on process or priorities, or a place to vent, one of the Zig social forums are more appropriate places for that.

[KempWatson]

@Paul-Dempsey my apologies; I'll rephrase:

I'm trying to use build.zig to script creation of a library, for a number of operating system targets, all with exactly the same name. Currently, zig build allows selection of input file paths, but not output file paths, which seems imbalanced as both are equally integral parts of building a target. The suggestion above to make the default installation directory named after the output mode will not accomplish this use case, which I think would be fairly common. I'd propose to make this simple, as in:

const libWinX64 = b.addSharedLibrary(.{
.name = "WinX64",
.root_source_file = b.path("src/main.zig"),
.dest_target_file = b.path("mycustomrelativepath/winOnX64/mylib.dll"), // PROPOSAL
.target = b.resolveTargetQuery(.{ .os_tag = .windows, .cpu_arch = .x86_64 }),
.optimize = .ReleaseSmall,
});

const libWinARM = b.addSharedLibrary(.{
.name = "WinARM",
.root_source_file = b.path("src/main.zig"),
.dest_target_file = b.path("mycustomrelativepath/winOnARM/mylib.dll"), // PROPOSAL
.target = b.resolveTargetQuery(.{ .os_tag = .windows, .cpu_arch = .aarch64 }),
.optimize = .ReleaseSmall,
});

Also, per @marler8997 above, the different output naming convention for Windows seems not to match Zig's stated goal of explicitness - it's making assumptions about output naming, also a related concern.

[marler8997]

Hey @KempWatson, Zigup had the same issue you're describing and I solved it by making a "ci" target that will build zigup for various architectures and installs them to a subdirectory based on the target (see https://github.com/marler8997/zigup/blob/master/build.zig).

So by default, running zig build will give you your 1 zigup executable in zig-out/bin/zigup, but running zig build ci will build many targets and installs them to various subdirectories like zig-out/arch64-linux/zigup. Here's a snippet for how this works in build.zig:

    for (ci_targets) |ci_target_str| {
        const target = b.resolveTargetQuery(try std.Target.Query.parse(
            .{ .arch_os_abi = ci_target_str },
        ));
        // ...
        const zigup_exe = addZigupExe(b, target, optimize);
        const zigup_exe_install = b.addInstallArtifact(zigup_exe, .{
            .dest_dir = .{ .override = .{ .custom = ci_target_str } },
        });
        ci_step.dependOn(&zigup_exe_install.step);

Further down it evens tars up all the results into a single archive that I can download after a CI run and upload to a release. build.zig is pretty powerful but it does take some time/practice to wrap your head around.