Skip to content

Configuration

Jump to bottom
Chung Leong edited this page Apr 24, 2024 · 6 revisions

Configuration file for node-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.

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, zigar-loader, and rollup-plugin-zigar

Additional options for node-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

zigCmd

The command used to create the shared library.

Default:

zig build -Doptimize=${...} -Dtarget=${...} -Dcpu=${...}

buildDir

The root directory where temporary build directories are placed.

Default:

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

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