How to get it up and running

[wayjake]

I tried zig build and I ended up with this.

/Users/username/devops/zigwin32/build.zig:3:21: error: root struct of file 'std' has no member named 'Build'
pub fn build(b: *std.Build) void {
                 ~~~^~~~~~
referenced by:
    runBuild: /usr/local/Cellar/zig/0.10.1/lib/zig/build_runner.zig:231:45
    usage__anon_4562: /usr/local/Cellar/zig/0.10.1/lib/zig/build_runner.zig:242:13
    remaining reference traces hidden; use '-freference-trace' to see all reference traces

I am on a Macbook pro (Intel).

Also, this was my first time ever running zig at all. Do I need to use that generator repo first? Let me know if I am missing anything if you can, thanks!

[eddineimad0]

if u wanna add this to your project do the following:

1. create the project with zig init.
2. create a libs folder in the root of the project (this is by convention where you place the external libraries you wanna use).
3. clone the zigwin32 repo inside that libs folder (you can also use other strategies like git submodule for cloning the repo).
4. inside your project's build.zig specify the zigwin32 as a module here is an example of mine:

const std = @import("std");
const builting = @import("builtin");

pub fn build(b: *std.Build) void {

    const target = b.standardTargetOptions(.{});

    const optimize = b.standardOptimizeOption(.{});

    const lib = b.addStaticLibrary(.{
        .name = "widow",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });

    if (builting.os.tag == .windows) {
        const win32api = b.createModule(.{
            .source_file = .{ .path = "libs/zigwin32/win32.zig" },
        });
        lib.addModule("win32", win32api);
    }
    lib.install();
}

As you can see i'm building a static library in this example and depending on the os.tag i'm conditionally including the zigwin32 library, with this i can include it in any zig file in my project using @import("win32"); notice "win32" is the name i specified in the addModule function.
with this you can successfully build your project with the zig build command

[marler8997]

Thanks for providing these instructions @eddineimad0. Note that these instructions will only work for a limited window of Zig versions, for example 0.11.0-dev.2336+5b82b4004 works but 0.11.0-dev.2619+bd3e248c7 doesn't. Update the line lib.install() to b.installArtifact(lib) to work with more recent versions of Zig.

Also in most cases you'll want to add zigwin32 as zig module to whatever artifact you're building instead of wrapping it in a static library and linking it afterwards.

There's also one correction in these instructions, the line if (builtin.os.tag == .windows) should be if (target.getOs().tag == .windows), you want to verify that your compile target is windows rather than checking if the host system building the project is windows.

[marler8997]

P.S. I should also mention that soon Zig's package manager should be ready and with that you'll be able to add an entry in build.zig.zon that will cause zig to automatically download zigwin32 for you, i.e.

build.zig.zon

.{
    .name = "myexample",
    .version = "0.0.0",

    .dependencies = .{
        .zigwin32 = .{
            .url = "https://github.com/marlersoft/zigwin32/archive/b70e7f818d77a0c0f39b0bd9c549e16439ff5780.tar.gz",
            .hash = "TODO PUT CORRECT HASH HERE",
        },
    },
}

The build.zig file for this would look something like:

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const zigwin32_dep = b.dependency("zigwin32", .{
        .target = target,
        .optimize = optimize,
    });
    
    const exe = b.addExecutable(.{
        .name = "hellowindows",
        .root_source_file = .{ .path = "hellowindows.zig" },
        .target = target,
        .optimize = optimize,
    });
    exe.addModule("win32", zigwin32_dep);

    b.installArtifact(exe);
}

[yvz5]

@marler8997 would you mind putting this in the readme file ? it would also help to create releases so we can just use
zig fetch --save <url>

[sigod]

@marler8997 This is not valid:

    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const zigwin32_dep = b.dependency("zigwin32", .{
        .target = target,
        .optimize = optimize,
    });

zig build complains:

error: invalid option: -Dcpu
error: invalid option: -Dtarget
error: invalid option: -Doptimize
D:\sigod\programs\Zig\lib\std\Build.zig:2230:35: 0x7ff6854c1463 in dependency__anon_67333 (build.exe.obj)
            return dependencyInner(b, name, pkg.build_root, if (@hasDecl(pkg, "build_zig")) pkg.build_zig else null, pkg_hash, pkg.deps, args);
                                  ^
[snip]

This is because you're missing those options in build.zig.

It should be:

 pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});

     _ = b.addModule("win32", .{
         .root_source_file = b.path("win32.zig"),
+        .target = target,
+        .optimize = optimize,
     });
 }

Turns out, there's already an open PR (#40) for this.

[marler8997]

The original code from my comment above was a bit naive. It shouldn't have included passing any build options to the zigwin32 dependency, i.e. that line should have just been:

    const zigwin32_dep = b.dependency("zigwin32", .{});

The zig build system is a bit weird here, although a "module" accepts a target/optimize mode, if you don't specify one then it defaults to whatever the root module target/optimize mode is. zigwin32 is mostly just bindings so I don't see any reason to want to set them differently to what the root module is setting.

The main use cases for accepting a target/optimize mode are if your build.zig file is building executables, or libraries, accepting them to pass to a module is a bit "misleading" in my opinion. For example, if your build.zig had instructions to build an executable that uses zigwin32 as a module, you don't need to create a new zigwin32 dependency and module for each target/optimize combination, you only need 1 module and can re-use it for all your executables regardless of which target/optimize mode they use.

[sigod]

@marler8997 Wouldn't it be best to do it the way all libraries are doing to avoid confusing users?

There's no real reason not to provide these options.

[marler8997]

Actually the reason to not provide these options is if you have a user who thinks zigwin32 needs them, it likely means this person is already "confused" as you say. I believe you've demonstrated this right? It seems like you may have had a small misunderstanding of zig modules before and now understand them a little better, just like myself in the time between when I made that first comment above and now. Would you agree this is a positive outcome? Users who already understood this aspect of zig modules wouldn't be surprised or confused by the lack of these options, and, users who didn't understand would become aware/learn that these options aren't necessary. You could naturally deduce that the module must be using the target/optimize mode of the root module. Making users "confused" about an aspect of which they are "mistaken" is a pathway to better understanding.

[gabrielkryss]

P.S. I should also mention that soon Zig's package manager should be ready and with that you'll be able to add an entry in build.zig.zon that will cause zig to automatically download zigwin32 for you, i.e.

build.zig.zon

.{
.name = "myexample",
.version = "0.0.0",

.dependencies = .{
    .zigwin32 = .{
        .url = "https://github.com/marlersoft/zigwin32/archive/b70e7f818d77a0c0f39b0bd9c549e16439ff5780.tar.gz",
        .hash = "TODO PUT CORRECT HASH HERE",
    },
},

}
The build.zig file for this would look something like:

const std = @import("std");

pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});

const zigwin32_dep = b.dependency("zigwin32", .{
    .target = target,
    .optimize = optimize,
});

const exe = b.addExecutable(.{
    .name = "hellowindows",
    .root_source_file = .{ .path = "hellowindows.zig" },
    .target = target,
    .optimize = optimize,
});
exe.addModule("win32", zigwin32_dep);

b.installArtifact(exe);

}

@marler8997, I apologize if this is minor, but is there an updated version for this for 0.15.1? Or is there a document for it somewhere that I'm not aware of? Like official steps to import and use the library using the Zig build system? I'm new to Zig, so this would be my first package to import. However, it seems that since 0.15.1, people no longer add modules to executables, or at least, that's what I've observed.

Anyways if there is help I'd appreciate it.