Merge pull request #26 from mjakeman/issue/change-linking-approach

Linking: Remove `link_SDL2*` methods, update README, and fix race condition

Author: hazeycode

README.md

@@ -13,27 +13,45 @@ pub fn build(b: *std.Build) !void {
     exe.linkLibC();
 
     const zsdl = b.dependency("zsdl", .{});
-    
-    exe.root_module.addImport("zsdl2", zsdl.module("zsdl2"));
-    @import("zsdl").link_SDL2(exe);
 
+    exe.root_module.addImport("zsdl2", zsdl.module("zsdl2"));
     exe.root_module.addImport("zsdl2_ttf", zsdl.module("zsdl2_ttf"));
-    @import("zsdl").link_SDL2_ttf(exe);
-    
     exe.root_module.addImport("zsdl2_image", zsdl.module("zsdl2_image"));
-    @import("zsdl").link_SDL2_image(exe);
 
-    // Optionally use prebuilt libs instead of relying on system installed SDL...
-    @import("zsdl").prebuilt_sdl2.addLibraryPathsTo(exe);
-    if (@import("zsdl").prebuilt_sdl2.install(b, target.result, .bin), .{
-        .ttf = true,
-        .image = true,
-    }) |install_sdl2_step| {
-        b.getInstallStep().dependOn(install_sdl2_step);
+    // Link against SDL libs
+    linkSdlLibs(exe);
+}
+```
+
+Link against SDL:
+
+```zig
+pub fn linkSdlLibs(compile_step: *std.Build.Step.Compile) void {
+    // Adjust as needed for the libraries you are using.
+    switch (compile_step.rootModuleTarget().os.tag) {
+        .windows => {
+            compile_step.linkSystemLibrary("SDL2");
+            compile_step.linkSystemLibrary("SDL2main"); // Only needed for SDL2, not ttf or image
+
+            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL2_image");
+        },
+        .linux => {
+            compile_step.linkSystemLibrary("SDL2");
+            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL2_image");
+        },
+        .macos => {
+            compile_step.linkFramework("SDL2");
+            compile_step.linkFramework("SDL2_ttf");
+            compile_step.linkFramework("SDL2_image");
+        },
+        else => {},
     }
 }
 ```
 
+### Using prebuilt libraries
 NOTE: If you want to use our prebuilt libraries also add the following to your `build.zig.zon`:
 ```zig
         .@"sdl2-prebuilt-macos" = .{
@@ -53,6 +71,34 @@ NOTE: If you want to use our prebuilt libraries also add the following to your `
         },
 ```
 
+And add the following to your `build.zig`:
+
+```zig
+fn build(b: *std.Build) !void {
+
+    // ... other build steps ...
+
+    // Optionally use prebuilt libs instead of relying on system installed SDL...
+    @import("zsdl").prebuilt_sdl2.addLibraryPathsTo(exe);
+    if (@import("zsdl").prebuilt_sdl2.install(b, target.result, .bin), .{
+        .ttf = true,
+        .image = true,
+    }) |install_sdl2_step| {
+        b.getInstallStep().dependOn(install_sdl2_step);
+    }
+
+    // Prebuilt libraries are installed to the executable directory. Set the RPath so the
+    // executable knows where to look at runtime.
+    switch (exe.rootModuleTarget().os.tag) {
+        .windows => {}, // rpath is not used on Windows
+        .linux => exe.root_module.addRPathSpecial("$ORIGIN"),
+        .macos => exe.root_module.addRPathSpecial("@executable_path"),
+        else => {},
+    }
+}
+```
+
+### Using zsdl2 in your code
 Now in your code you may import and use `zsdl2`:
 
 ```zig

build.zig

@@ -33,7 +33,7 @@ pub fn build(b: *std.Build) void {
         const test_step = b.step("test", "Run bindings tests");
         { // Test SDL2 bindings
             const zsdl2_tests = addTests(test_step, target, optimize, "zsdl2-tests", "src/sdl2.zig");
-            link_SDL2(zsdl2_tests);
+            link_SDL2_libs_testing(zsdl2_tests);
             prebuilt_sdl2.addLibraryPathsTo(zsdl2_tests);
         }
         { // Test SDL2_ttf bindings
@@ -46,8 +46,7 @@ pub fn build(b: *std.Build) void {
                 "zsdl2",
                 zsdl2_module,
             );
-            link_SDL2(zsdl2_ttf_tests);
-            link_SDL2_ttf(zsdl2_ttf_tests);
+            link_SDL2_libs_testing(zsdl2_ttf_tests);
             prebuilt_sdl2.addLibraryPathsTo(zsdl2_ttf_tests);
         }
         { // Test SDL2_image bindings
@@ -60,13 +59,12 @@ pub fn build(b: *std.Build) void {
                 "zsdl2",
                 zsdl2_module,
             );
-            link_SDL2(zsdl2_image_tests);
-            link_SDL2_image(zsdl2_image_tests);
+            link_SDL2_libs_testing(zsdl2_image_tests);
             prebuilt_sdl2.addLibraryPathsTo(zsdl2_image_tests);
         }
         { // Test SDL3 bindings
             const zsdl3_tests = addTests(test_step, target, optimize, "zsdl3-tests", "src/sdl3.zig");
-            link_SDL3(zsdl3_tests);
+            link_SDL3_libs_testing(zsdl3_tests);
             prebuilt_sdl3.addLibraryPathsTo(zsdl3_tests);
         }
 
@@ -80,73 +78,73 @@ pub fn build(b: *std.Build) void {
     }
 }
 
-pub fn link_SDL2(compile_step: *std.Build.Step.Compile) void {
+fn link_SDL2_libs_testing(compile_step: *std.Build.Step.Compile) void {
     switch (compile_step.rootModuleTarget().os.tag) {
         .windows => {
             compile_step.linkSystemLibrary("SDL2");
             compile_step.linkSystemLibrary("SDL2main");
+            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL2_image");
         },
         .linux => {
             compile_step.linkSystemLibrary("SDL2");
+            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL2_image");
             compile_step.root_module.addRPathSpecial("$ORIGIN");
         },
         .macos => {
             compile_step.linkFramework("SDL2");
+            compile_step.linkFramework("SDL2_ttf");
+            compile_step.linkFramework("SDL2_image");
             compile_step.root_module.addRPathSpecial("@executable_path");
         },
         else => {},
     }
 }
 
-pub fn link_SDL2_ttf(compile_step: *std.Build.Step.Compile) void {
+fn link_SDL3_libs_testing(compile_step: *std.Build.Step.Compile) void {
     switch (compile_step.rootModuleTarget().os.tag) {
         .windows => {
-            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL3");
         },
         .linux => {
-            compile_step.linkSystemLibrary("SDL2_ttf");
+            compile_step.linkSystemLibrary("SDL3");
             compile_step.root_module.addRPathSpecial("$ORIGIN");
         },
         .macos => {
-            compile_step.linkFramework("SDL2_ttf");
+            compile_step.linkFramework("SDL3");
             compile_step.root_module.addRPathSpecial("@executable_path");
         },
         else => {},
     }
 }
 
+pub fn link_SDL2(compile_step: *std.Build.Step.Compile) void {
+    _ = compile_step;
+    @compileError("link_SDL2 no longer supported. Refer to README for linking instructions.");
+
+    // link_SDL2 is no longer supported for linking, as it assumes too much
+    // about the build environment. You should instead copy the relevant link
+    // calls from the README into your build.zig file and adjust as necessary.
+}
+
+pub fn link_SDL2_ttf(compile_step: *std.Build.Step.Compile) void {
+    _ = compile_step;
+    @compileError("link_SDL2_ttf no longer supported. Refer to README for linking instructions.");
+}
+
 pub fn link_SDL2_image(compile_step: *std.Build.Step.Compile) void {
-    switch (compile_step.rootModuleTarget().os.tag) {
-        .windows => {
-            compile_step.linkSystemLibrary("SDL2_image");
-        },
-        .linux => {
-            compile_step.linkSystemLibrary("SDL2_image");
-            compile_step.root_module.addRPathSpecial("$ORIGIN");
-        },
-        .macos => {
-            compile_step.linkFramework("SDL2_image");
-            compile_step.root_module.addRPathSpecial("@executable_path");
-        },
-        else => {},
-    }
+    _ = compile_step;
+    @compileError("link_SDL2_image no longer supported. Refer to README for linking instructions.");
 }
 
 pub fn link_SDL3(compile_step: *std.Build.Step.Compile) void {
-    switch (compile_step.rootModuleTarget().os.tag) {
-        .windows => {
-            compile_step.linkSystemLibrary("SDL3");
-        },
-        .linux => {
-            compile_step.linkSystemLibrary("SDL3");
-            compile_step.root_module.addRPathSpecial("$ORIGIN");
-        },
-        .macos => {
-            compile_step.linkFramework("SDL3");
-            compile_step.root_module.addRPathSpecial("@executable_path");
-        },
-        else => {},
-    }
+    _ = compile_step;
+    @compileError("link_SDL3 no longer supported. Refer to README for linking instructions.");
+
+    // link_SDL3 is no longer supported for linking, as it assumes too much
+    // about the build environment. You should instead copy the relevant link
+    // calls from the README into your build.zig file and adjust as necessary.
 }
 
 pub fn testVersionCheckSDL2(b: *std.Build, target: std.Build.ResolvedTarget) *std.Build.Step {
@@ -159,7 +157,7 @@ pub fn testVersionCheckSDL2(b: *std.Build, target: std.Build.ResolvedTarget) *st
         }),
     });
 
-    link_SDL2(test_sdl2_version_check);
+    link_SDL2_libs_testing(test_sdl2_version_check);
 
     prebuilt_sdl2.addLibraryPathsTo(test_sdl2_version_check);
 
@@ -391,7 +389,7 @@ fn addTests(
             .optimize = optimize,
         }),
     });
-    b.installArtifact(tests);
+    const install = b.addInstallArtifact(tests, .{});
 
     const run = b.addRunArtifact(tests);
     if (target.result.os.tag == .windows) {
@@ -400,6 +398,7 @@ fn addTests(
         });
     }
 
+    run.step.dependOn(&install.step);
     test_step.dependOn(&run.step);
     return tests;
 }