Skip to content

Configuration

Jump to bottom
Chung Leong edited this page Aug 9, 2024 · 10 revisions

Configuration file for node-zigar and bun-zigar

Node-zigar looks for node-zigar.config.json in the parent directories of a Zig file. The config file is used during development only. You should omit it when deploying an app.

For bun-zigar, the configuration is stored in bun-zigar.toml instead.

Configuration for zigar-loader

Options are stored in the options field of the rule matching .zig files. Example:

  module: {
    rules: [
      {
        test: /\.zig$/,
        exclude: /node_modules/,
        use: {
          loader: 'zigar-loader',
          options: {
            embedWASM: false,
          },
        },
      },
      /* ... */
    ],
  },

If the default options are adequate, you can refer to the plugin simply by name:

  module: {
    rules: [
      {
        test: /\.zig$/,
        exclude: /node_modules/,
        use: 'zigar-loader',
      },
      /* ... */
    ],
  },

Configuration for rollup-plugin-zigar

Options are passed to the plugin's constructor. Example:

    plugins: [
      zigar({
        optimize: 'ReleaseSmall',
        embedWASM: true,
      }),
      nodeResolve(),
    ],

Specifying options as GET variables

You can attach options to the path in require or import statements. Example:

import { sha1 } from '../zig/sha1.zig?optimize=release-fast&embed-wasm=1';

Options specified in this manner take precedence. Names in kebab-case and snake_case, in addition to camelCase ones, are recognized.

Options for node-zigar, bun-zigar, zigar-loader, and rollup-plugin-zigar

Additional options for node-zigar and bun-zigar

Additional options for zigar-loader and rollup-plugin-zigar

optimize

The optimization level used to compile Zig code.

Possible values:

  • Debug
  • ReleaseSafe
  • ReleaseSmall
  • ReleaseFast

Default:

ReleaseSmall when building for production, Debug otherwise

omitFunctions

When enabled, the module's public functions will not be exported. This option is useful in a situation where the same Zig code is used both on the server and the client side, with one side needing only the definitions of structures.

Default:

false

omitVariables

When enabled, the module's public variables will not be exported. This does not affects the availability of constants.

Default:

true for Electron, false otherwise

useLibc

When enabled, link in the C standard library.

Default:

true for native code, false for WebAssembly

zigPath

The command used to run the Zig compiler.

Default:

zig

zigArgs

The additional arguments provided to the Zig compiler. The list is merged with the default arguments build -Doptimize=${...} -Dtarget=${...}.

Default:

[empty]

buildDir

The root directory where temporary build directories are placed.

Default:

${os.tmpdir()}/zigar-build

buildDirSize

Limit in byte on the directory holding temporary build directories. When exceeded, Zigar will start purging old files.

Default:

1_000_000_000

clean

When enabled, the temporary build directory will be removed once the library has been built. This directory contains cached data used by the Zig compiler. Without it recompilation would take significantly longer.

Default:

false

cacheDir

The directory where compiled shared libraries are placed. The cache directory is used when you provide a .zig path to require() or import() (instead of a .zigar module path).

Default:

${process.cwd()}/.zigar-cache

sourceFiles

An object mapping Zigar modules to their source files. Example:

  "sourceFiles": {
    "lib/md5.zigar": "src/md5.zig",
    "lib/sha1.zigar": "src/sha1.zig"
  },

targets

An array listing the platform/archecture combination for which library files will be generated. Example:

  "targets": [
    { "platform": "win32", "arch": "x64" },
    { "platform": "win32", "arch": "arm64" },
    { "platform": "win32", "arch": "ia32" },
    { "platform": "linux", "arch": "x64" },
    { "platform": "linux", "arch": "arm64" },
    { "platform": "darwin", "arch": "x64" },
    { "platform": "darwin", "arch": "arm64" }
  ]

Possible platforms:

  • aix
  • darwin
  • freebsd
  • linux
  • linux-musl
  • openbsd
  • sunos
  • win32

Possible archectures:

  • arm
  • arm64
  • ia32
  • loong64
  • mips
  • mipsel
  • ppc
  • ppc64
  • riscv64
  • s390
  • s390x
  • x64

topLevelAwait

When enabled, top-level await will be used to wait for compilation of WASM code.

Default:

true

embedWASM

When enabled, the WASM binary will be embedded as a base64 string in the JavaScript code instead of being kept in a separate file.

Default:

false

stripWASM

When enabled, extraneous code and debugging information will be removed from the WASM binary.

Default:

true unless optimize is Debug

keepNames

When enabled, names of functions will be kept even when stripWASM is true, making it easier to follow the stack trace from a crash.

Default:

false

useReadFile

When enabled, Node's readFile() will be used to Load the WASM file when the code is used in Node.js. fetch() will still be used in the browser.

Default:

false

Clone this wiki locally