DOCSEARCHbyAlgolia
Submit Docs

anyzig

repository·master·Indexed 19 days ago

https://github.com/marler8997/anyzig

A universal Zig executable wrapper that enables seamless switching between multiple Zig versions. It automatically manages compiler downloads based on project configuration files like build.zig.zon, supporting explicit arguments, Mach version configurations, and minimum_zig_version fields. anyzig includes internal management commands via the 'zig any' prefix to list installed versions and configure system-wide verbosity.

Tokens
1.9K
Snippets
9
Records
12
Agent score
16%

What's inside anyzig

  1. How anyzig manages Zig versions

    master

    anyzig acts as a universal wrapper for the zig executable, allowing you to use multiple Zig versions without changing your PATH. It determines which version to run using the following priority:

    1. Explicit Argument: If you provide a version string as the first argument to the zig command, anyzig will use that version.
    2. Mach Version Config: If your build.zig.zon contains a .mach_zig_version property, anyzig uses that version.
    3. Minimum Zig Version: If no explicit argument or Mach config is found, anyzig searches the current or parent directories for a build.zig.zon file and uses the value of the minimum_zig_version field.

    When a required version is not found locally, anyzig automatically performs the equivalent of zig fetch ZIG_DOWNLOAD_URL to download the compiler into a global cache.

    # Using an explicit version argument
$ zig 0.13.0 build-exe myproject.zig

# Using a specific dev version
$ zig 0.14.0-dev.3028+cdc9d65b0 build-exe mynewerproject.zig

  2. Use Mach versions with anyzig

    master

    anyzig supports Mach engine's "nominated versions" (e.g., 2024.10.0-mach). If a version string ends with -mach, anyzig resolves it to a URL using Mach's download index.

    To avoid potential future verification issues with the official Zig minimum_zig_version field, it is recommended to specify Mach versions using the .mach_zig_version property in your build.zig.zon file.

  4. How anyzig determines the Zig version

    master

    By default, anyzig attempts to find the required Zig version by inspecting the build.zig.zon file in the current build root. It looks for the following keys in order of priority:

    1. .mach_zig_version
    2. .zig_version
    3. .minimum_zig_version

    If no build.zig.zon is found, you must provide the version manually (e.g., zig 0.13.0).

  5. Configure anyzig verbosity

    master

    You can control the logging verbosity of anyzig globally by setting a verbosity level. This is stored in your application data directory in a file named verbosity.

    Use the set-verbosity command to change this setting:

    zig any set-verbosity debug
# or
zig any set-verbosity warn
    zig any set-verbosity debug

  6. Specify a Zig version manually

    master

    If anyzig cannot determine the required Zig version from your build.zig.zon file, you can specify a version directly as a command-line argument. This is useful for initializing projects or overriding automatic detection.

    # Specify a semantic version
zig 0.13.0

# Specify the master branch
zig master
    zig 0.13.0
zig master

  7. Initialize a new project with anyzig

    master

    To initialize a new project and automatically create a build.zig.zon file with the correct minimum_zig_version based on the version you are currently using, use the init command. Note that init requires a version specification.

    zig 0.13.0 init
    zig 0.13.0 init

  9. Extract download URLs from Mach index

    master

    The extractUrlFromMachDownloadIndex function parses a Mach download index (JSON) to find specific download URLs for a given SemanticVersion and architecture/OS combination.

    Parameters:

    • allocator: An allocator for duplicating strings.
    • semantic_version: The target version to look up.
    • index_filepath: The path to the index file (used for error reporting).
    • download_index: The raw JSON content of the index.

    Returns:

    • ?DownloadUrl: An optional struct containing:
      • fetch: The URL for the tarball.
      • official: The zigTarball URL.

    It relies on an arch_os identifier (e.g., x86_64-linux) to locate the correct entry in the JSON structure.

    const url_info = extractUrlFromMachDownloadIndex(allocator, version, "index.json", json_data);
if (url_info) |urls|
{
    // urls.fetch and urls.official are available
}

  10. Locate a build root with findBuildRoot

    master

    The findBuildRoot function searches for a directory containing a build file (defaulting to build.zig) to establish a BuildRoot. It can either take a specific build file path or search upwards from a provided current working directory (cwd_path).

    Parameters:

    • arena: An allocator for path joining and string manipulation.
    • options: A FindBuildRootOptions struct containing:
      • build_file: An optional path to a specific build file.
      • cwd_path: An optional path to start the upward search from.

    Returns:

    • !?BuildRoot: An optional BuildRoot containing the directory handle and the basename of the build file, or an error.

    BuildRoot Structure:

    • directory: A Cache.Directory representing the found location.
    • build_zig_basename: The name of the build file found.
    • cleanup_build_dir: An optional directory handle used for cleanup.
    const options = .{ .build_file = "custom_build.zig", .cwd_path = "/path/to/project" };
const build_root = try findBuildRoot(arena, options);
if (build_root) |
    br|
|
{
    // Use br.directory and br.build_zig_basename
}

  11. Download a package with cmdFetch

    master

    The cmdFetch function initiates the downloading and fetching process for a package specified by a URL. It manages a thread pool, an HTTP client with proxy support, and a job queue to handle the fetch operation. If the fetch encounters errors, they are collected into an error bundle and rendered to stderr before exiting the process.

    Parameters:

    • gpa: An allocator for general purpose allocation.
    • arena: An arena allocator for managing the lifecycle of the fetch operation.
    • global_cache_directory: The directory where fetched packages are cached.
    • url: The URL of the package to fetch.
    • opt: An options struct containing:
      • debug_hash: A boolean to enable debug hashing.

    Returns:

    • !zig.Package.Hash: The computed hash of the fetched package on success, or an error.

    Note: This function handles the ZIG_BTRFS_WORKAROUND environment variable automatically if running on Linux.

    const hash = try cmdFetch(gpa, arena, cache_dir, "https://example.com/package.zip", .{ .debug_hash = false });

  12. Use anyzig subcommands

    master

    When running the anyzig binary (or when anyzig is acting as a wrapper for zig), you can use the any subcommand to access management tools.

    Available any subcommands:

    • zig any set-verbosity LEVEL: Sets the default system-wide verbosity. Accepts warn or debug.
    • zig any version: Prints the version of anyzig to stdout.
    • zig any list-installed: Lists all versions of Zig currently installed in the global cache.
    zig any set-verbosity debug
zig any version
zig any list-installed