From ebaff073df1e06fa7731f0b55b9d526b38b86057 Mon Sep 17 00:00:00 2001 From: Stephen Gutekanst Date: Wed, 6 Mar 2024 09:12:40 -0700 Subject: [PATCH] core: migrate to the mach standard library Helps hexops/mach#1165 Signed-off-by: Stephen Gutekanst --- content/_index.md | 8 +- content/about/nixos-usage.md | 4 +- content/core/examples.md | 146 +++++++++++++++--------------- content/core/getting-started.md | 50 ++++------ content/core/migrations/_index.md | 12 ++- 5 files changed, 108 insertions(+), 112 deletions(-) diff --git a/content/_index.md b/content/_index.md index 4fd49f4..8bdccfe 100644 --- a/content/_index.md +++ b/content/_index.md @@ -328,11 +328,11 @@ a.p-community-icon {

Zero system dependencies to slow you down; only zig is needed, we build and package the few relevant dependencies on our own.

To run on your machine:

-
$ git clone https://github.com/hexops/mach-core
-$ cd mach-core/
-$ zig build run-textured-cube
+
$ git clone https://github.com/hexops/mach
+$ cd mach/
+$ zig build run-core-textured-cube
 

-                Requires this Zig nightly version | known issues
+                Requires this nominated Zig version | known issues
diff --git a/content/about/nixos-usage.md b/content/about/nixos-usage.md index 38adc86..07c12b6 100644 --- a/content/about/nixos-usage.md +++ b/content/about/nixos-usage.md @@ -33,7 +33,7 @@ mkShell { Then running `zig build` as usual: ```sh -zig build run-textured-cube +zig build run-core-textured-cube ``` ## Usage via shell @@ -59,7 +59,7 @@ You can also run Mach examples via `steam-run`, for this you will need to instal env NIXPKGS_ALLOW_UNFREE=1 nix-shell -p steam-run ``` -(then `zig build run-textured-cube` as usual) +(then `zig build run-core-textured-cube` as usual) ## Known issues ### Incorrect cursor behavior with cursormode set to disabled diff --git a/content/core/examples.md b/content/core/examples.md index e69e31a..3864ef5 100644 --- a/content/core/examples.md +++ b/content/core/examples.md @@ -74,7 +74,7 @@ pre {

Mach core examples

- All examples require this Zig nightly version | known issues + All examples require this nominated Zig version | known issues
@@ -84,13 +84,13 @@ pre {
-

deferred-rendering

+

deferred-rendering

Dynamic lighting using deferred rendering techniques.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-deferred-rendering
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-deferred-rendering
~1300 lines of code @@ -99,13 +99,13 @@ zig build run-deferred-rendering
-

pbr-basic

+

pbr-basic

Physically based rendering (PBR) materials

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-pbr-basic
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-pbr-basic
~1000 lines of code @@ -124,13 +124,13 @@ zig build run-pbr-basic
-

gen-texture-light

+

gen-texture-light

Generates a brick texture at comptime, uses Blinn-Phong lighting, and several pipelines. Move camera with arrow keys / WASD.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-gen-texture-light
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-gen-texture-light
~800 lines of code @@ -139,13 +139,13 @@ zig build run-gen-texture-light
-

procedural-primitives

+

procedural-primitives

Procedurally generated geometry, implements a few different shapes (use arrow keys to switch between them.)

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-procedural-primitives
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-procedural-primitives
~600 lines of code @@ -164,13 +164,13 @@ zig build run-procedural-primitives
-

pixel-post-process

+

pixel-post-process

A post-processing effect which pixelates the entire screen.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-pixel-post-process
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-pixel-post-process
~500 lines of code @@ -179,13 +179,13 @@ zig build run-pixel-post-process
-

sprite2d

+

sprite2d

Loads a JSON file which describes a spritesheet, and renders sprites to the screen.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-sprite2d
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-sprite2d
~400 lines of code @@ -202,13 +202,13 @@ zig build run-sprite2d
-

fractal-cube

+

fractal-cube

Cube-inception! Renders the scene to a texture, which is then rendered on the rotating cube itself as a texture!

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-fractal-cube
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-fractal-cube
~400 lines of code @@ -217,13 +217,13 @@ zig build run-fractal-cube
-

cubemap

+

cubemap

Renders a cubemap / skybox. Nothing fancy, but these are instrumental as backgrounds in games.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-cubemap
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-cubemap
~400 lines of code @@ -242,13 +242,13 @@ zig build run-cubemap
-

textured-cube

+

textured-cube

Loads a PNG image and uploads the texture to the GPU. Renders it on a 3D cube.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-textured-cube
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-textured-cube
~300 lines of code @@ -257,13 +257,13 @@ zig build run-textured-cube
-

image-blur

+

image-blur

Leverages a compute shader to blur an image, then renders it. Don't worry if the details are a bit fuzzy!

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-image-blur
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-image-blur
~300 lines of code @@ -280,13 +280,13 @@ zig build run-image-blur
-

boids

+

boids

Uses a GPU compute shader to run calculations / simulate flocking behaviour of birds.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-boids
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-boids
~300 lines of code @@ -295,13 +295,13 @@ zig build run-boids
-

two-cubes

+

two-cubes

Once you've learned how to render one cube, two is just 30 lines of code more!

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-two-cubes
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-two-cubes
~200 lines of code @@ -320,13 +320,13 @@ zig build run-two-cubes
-

instanced-cube

+

instanced-cube

EVEN MORE CUBES! Instancing lets you duplicate an object & render it in multiple places with different parameters.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-instanced-cube
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-instanced-cube
~200 lines of code @@ -335,13 +335,13 @@ zig build run-instanced-cube
-

rotating-cube

+

rotating-cube

Uploads a basic 3D cube to the GPU and renders it. Demonstrates how to use vertex buffers to transfer a model from the CPU to GPU, how to use vertex attributes & more.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-rotating-cube
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-rotating-cube
~200 lines of code @@ -358,13 +358,13 @@ zig build run-rotating-cube
-

triangle-msaa

+

triangle-msaa

Remember that triangle from before? If we turn on MSAA (Multi-Sample Anti Aliasing) the edges will become smooooth.

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-triangle-msaa
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-triangle-msaa
~100 lines of code @@ -373,13 +373,13 @@ zig build run-triangle-msaa
-

triangle

+

triangle

This is where you should start learning. It tells the GPU to render 3 vertices (but doesn't transfer them using a vertex buffer or anything! The vertex positions are hard-coded in the shader.)

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-triangle
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-triangle
~100 lines of code @@ -394,13 +394,13 @@ zig build run-triangle
-

map-async

+

map-async

Some of the best examples have no graphics. This one shows how to transfer data to the GPU, perform computations on that data using the GPU's parallel processing capabilities, and get results back on the CPU. If you're interested in GPU compute, this is the place to start!

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-map-async
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-map-async
~100 lines of code @@ -409,13 +409,13 @@ zig build run-map-async
-

clear-color

+

clear-color

As simple as it gets: a blue screen of doom

-git clone https://github.com/hexops/mach-core
-cd mach-core/
-zig build run-clear-color
+git clone https://github.com/hexops/mach
+cd mach/
+zig build run-core-clear-color
~100 lines of code diff --git a/content/core/getting-started.md b/content/core/getting-started.md index 08d7d24..153309f 100644 --- a/content/core/getting-started.md +++ b/content/core/getting-started.md @@ -9,7 +9,11 @@ rss_ignore: true # Getting Started with _Mach core_ -Here you will learn how to use _mach-core_ in your own project/repository. If you haven't already, check out the [examples](../examples) as those describe how to actually use Mach core's APIs, this page just describes project setup. +Here you will learn how to use _mach core_ in your own project/repository. If you haven't already, check out the [examples](../examples) as those describe how to actually use Mach core's APIs, this page just describes project setup. + +## Check you are using a supported Zig version + +Make sure you're using a [supported Zig version](/about/zig-version/) ## Option 1: Copying the starter project @@ -22,38 +26,20 @@ If you like, you can simply start by copying [this starter project](https://gith ```sh mkdir myproject/ cd myproject/ -zig init-exe +zig init ``` ### Add dependencies -mach-core uses the Zig package manager. Create a `build.zig.zon` file [like this](https://github.com/hexops/mach-core-getting-started/blob/main/build.zig.zon) in your project next to your `build.zig` file. Replace `LATEST_COMMIT` with the latest commit hash: - -```zig -.{ - .name = "myproject", - .version = "0.1.0", - .dependencies = .{ - .mach_core = .{ - .url = "https://pkg.machengine.org/mach-core/LATEST_COMMIT.tar.gz", - }, - }, -} -``` - -Run `zig build` in your project, and the compiler will instruct you to add a `.hash = "..."` field next to `.url`: - -``` -note: expected .hash = "12209838fcfb7a77d2d6931efdc7448c033a1b7dad11d082c94bbeeba9d1038cd311", -``` +[Add the Mach standard library](/engine/stdlib) to your project so you can `@import("mach").core`. ### Setup build.zig -Your `build.zig` file will need to use `mach.App` to declare how your application should be built. Your `build.zig` should look something like this: +Your `build.zig` file will need to use `mach.CoreApp` to declare how your application should be built. Your `build.zig` should look something like this: ```zig const std = @import("std"); -const mach_core = @import("mach_core"); +const mach = @import("mach"); // Although this function looks imperative, note that its job is to // declaratively construct a build graph that will be executed by an external @@ -70,11 +56,15 @@ pub fn build(b: *std.Build) !void { // set a preferred release mode, allowing the user to decide how to optimize. const optimize = b.standardOptimizeOption(.{}); - const mach_core_dep = b.dependency("mach_core", .{ + const mach_dep = b.dependency("mach", .{ .target = target, .optimize = optimize, + + // Since we're only using @import("mach").core, we can specify this to avoid + // pulling in unneccessary dependencies. + .core = true, }); - const app = try mach_core.App.init(b, mach_core_dep.builder, .{ + const app = try mach.CoreApp.init(b, mach_dep.builder, .{ .name = "myapp", .src = "src/main.zig", .target = target, @@ -110,8 +100,8 @@ pub fn build(b: *std.Build) !void { To begin coding your project, we suggesting copying the two files from the `triangle` example into your `src/` folder: -* [`main.zig`](https://raw.githubusercontent.com/hexops/mach-core/main/examples/triangle/main.zig) -* [`shader.wgsl`](https://raw.githubusercontent.com/hexops/mach-core/main/examples/triangle/shader.wgsl) +* [`main.zig`](https://raw.githubusercontent.com/hexops/mach/main/src/core/examples/triangle/main.zig) +* [`shader.wgsl`](https://raw.githubusercontent.com/hexops/mach/main/src/core/examples/triangle/shader.wgsl) ## Building your project @@ -146,10 +136,6 @@ zig build -Dtarget=x86_64-macos zig build -Dtarget=aarch64-macos ``` -### Run in the browser - -Mach doesn't yet support _graphics_ in the browser ([issue #90](https://github.com/hexops/mach/issues/90)), but windowing, input, and audio all work already - as well as a nice dev server CLI we have. We're actively collaborating on building browser support in the `#wasm` channel in [Discord](/discord) and will update this section once it is ready. - ## Questions? Ran into an issue? Make sure you're using a [supported Zig version](/about/zig-version/) @@ -157,4 +143,4 @@ Make sure you're using a [supported Zig version](/about/zig-version/) There are two ways to get help: * [File a GitHub issue](https://github.com/hexops/mach/issues) -* [Join our Discord](/discord) and create a thread in `#help` +* [Join our Discord](/discord) and create a thread in the `#questions` forum diff --git a/content/core/migrations/_index.md b/content/core/migrations/_index.md index 77261dd..676a05c 100644 --- a/content/core/migrations/_index.md +++ b/content/core/migrations/_index.md @@ -11,11 +11,21 @@ rss_ignore: true To learn more about Mach's library stability guarantees, check out the [libraries overview](../../pkg) page. This page provides migration guides for Mach libraries-walking you through how to update your code to the latest version. +## mach.core: package URL change (2024-03-06) + +As part of [#1165](https://github.com/hexops/mach/issues/1165) mach-core is now part of the Mach standard library. The code now lives in https://github.com/hexops/mach and can be imported as `@import("mach").core`. + +Thanks to lazy code evaluation, and lazy dependencies recently added to Zig, we can have this code live in the same repository which makes testing and contributing easier - while still enabling someone to 'just use mach [core,sysaudio,sysgpu] without the entire engine'. + +To update your mach-core project, [make these changes](https://github.com/hexops/mach-core-starter-project/commit/cb319048dc793dff22a2a905af12d0a61c97e0db). + +See [the Mach standard library](/engine/stdlib/) for details on how the stdlib works, lazy dependencies, etc. + ## mach-core: updated to Zig 2024.1.0-mach (2024-01-14) Mach core [967d9b7](https://github.com/hexops/mach-core/tree/370bc1504cebaffcda5ed1ae9915fd2ac6778479) and above now uses [Zig 2024.1.0-mach](/about/nominated-zig/#202410-mach). This is the first mach-core version to follow [nominated Zig versions](https://devlog.hexops.com/2024/announcing-nominated-zig/). -To update your mach-core project, [follow this diff](https://github.com/hexops/mach-core-starter-project/commit/73633db522740e68ac4a65841f5e13924ceb0eef). +To update your mach-core project, [make these changes](https://github.com/hexops/mach-core-starter-project/commit/73633db522740e68ac4a65841f5e13924ceb0eef). To update your Zig code in general, see: [_tips on upgrading your Zig code_](https://github.com/hexops/mach/issues/1135#issuecomment-1891175749).