Zig Programming Language

By default, Zig binaries do not depend on any external C library. To link a binary against glibc, use the -lc flag. The specific C library used is determined by the target ABI: gnu selects glibc, while musl selects the musl C library.

zig build-exe main.zig -lc

You can target a specific glibc version to ensure compatibility with older systems. This is done by appending the version number to the -target flag. For example, using gnu.2.19 will create a dependency on glibc v2.19 or later. Use zig env to check your current default target and version.

zig build-exe main.zig -lc -target native-native-gnu.2.19

Dependencies in the dependencies struct must be defined using either a url and hash OR a path. The url and path fields are mutually exclusive.

Remote Dependencies

When using a url, you must provide a hash (multihash format). The hash is the source of truth; the url is simply a mirror. If you update a url, you must delete the old hash to avoid mismatch errors.

Local Dependencies

When using path, the package is located in a directory relative to the build root. In this case, the hash is not computed and is irrelevant.

Lazy Fetching

Set lazy = true to declare a dependency as lazily fetched. The package will only be fetched if it is actually used by the build process.

You can enable SSL key logging by providing an SslKeyLog pointer in the Options.ssl_key_log field. This allows external tools to decrypt the captured traffic. The writer field in SslKeyLog is used during the handshake to record the necessary secrets.

const key_log = SslKeyLog{
    .client_key_seq = 0,
    .server_key_seq = 0,
    .client_random = undefined, // Populated during init
    .writer = my_file_writer,
};

const client = try tls.Client.init(input, output, .{ 
    .ssl_key_log = &key_log, 
    // ... other options
});

The Client uses a ConnectionPool to reuse open connections. The pool is a Least-Recently-Used (LRU) cache.

Core Functionality:

• findConnection(pool, criteria): Searches the pool for an available connection matching the provided Criteria (host, port, and protocol). Returns null if no match is found. This is thread-safe.
• release(pool, connection, io): Returns a connection to the pool. If the connection is marked as closing or the pool is at its free_size limit, the connection is destroyed instead. This is thread-safe.
• resize(pool, allocator, new_size): Adjusts the pool capacity. If shrinking, idle connections are closed until the new size is reached. This is thread-safe.
• deinit(pool, io): Frees the pool and closes all connections. Warning: All future operations on the pool will deadlock after this call.

You can manage preprocessor symbols using the /d (define) and /u (undefine) flags.

• Define a symbol: Use /d<name> or /d<name>=<value>. If a name is repeated, the last definition takes precedence.
• Undefine a symbol: Use /u<name>. Once a symbol is undefined, subsequent definitions of that same symbol are ignored.
• Precedence: Undefine operations always take precedence over define operations if they appear later in the command line.

Note: Symbol names must be valid C identifiers (e.g., no leading digits, only alphanumeric characters and underscores).

# Example usage
# Define 'FOO' as '1'
/dFOO foo.rc

# Define 'BAR' as 'baz'
/dBAR=baz foo.rc

# Undefine 'FOO'
/uFOO foo.rc

# Undefine takes precedence over define
/dFOO /uFOO foo.rc

To support WebSockets, first check if an upgrade is requested using upgradeRequested. If it returns a .websocket variant, use respondWebSocket to complete the handshake. This returns a WebSocket object for bidirectional communication.

const upgrade = std.http.Server.upgradeRequested(&request);
if (upgrade == .websocket) {
    const ws_options = std.http.Server.WebSocketOptions{
        .key = upgrade.websocket.?,
        .reason = "Switching Protocols",
    };
    var ws = try request.respondWebSocket(ws_options);
    // Use ws to read/write messages
}

The available cipher_suites are determined by whether the system has hardware support for AES.

If crypto.core.aes.has_hardware_support is true, the priority order is:

1. AEGIS_128L_SHA256
2. AEGIS_256_SHA512
3. AES_128_GCM_SHA256
4. ECDHE_RSA_WITH_AES_128_GCM_SHA256
5. AES_256_GCM_SHA384
6. ECDHE_RSA_WITH_AES_256_GCM_SHA384
7. CHACHA20_POLY1305_SHA256
8. ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

If hardware support is absent, CHACHA20_POLY1305_SHA256 and its ECDHE variant are prioritized for better software performance.