hash

The hash module provides hash value calculation and UUID generation functions. It is a built-in module of xmake.

hash.md5

• Calculate the MD5 hash value of a file or binary data

Function Prototype

API

hash.md5(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function
• Common mistake: If the file doesn't exist, the function will incorrectly treat the file path as string data to calculate the hash value, and it won't report an error, resulting in incorrect results

Usage

Calculates the MD5 hash value of the specified file or binary data and returns a hexadecimal format hash string.

Calculate file hash value:

-- Calculate MD5 hash value of a file
local checksum = hash.md5("/path/to/file.txt")
print("MD5: " .. checksum)

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate MD5 hash value of binary data
local data = bytes("hello")
local checksum = hash.md5(data)
print("MD5: " .. checksum)

Incorrect usage (don't do this):

-- ❌ Wrong: If "hello" is not a file path, it will incorrectly calculate the hash of the file path string
local checksum = hash.md5("hello")

-- ✅ Correct: Use bytes wrapper for binary data
local checksum = hash.md5(bytes("hello"))

hash.sha1

• Calculate the SHA1 hash value of a file or binary data

Function Prototype

API

hash.sha1(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function

Usage

Calculates the SHA1 hash value of the specified file or binary data and returns a hexadecimal format hash string.

Calculate file hash value:

-- Calculate SHA1 hash value of a file
local checksum = hash.sha1("/path/to/file.txt")

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate SHA1 hash value of binary data
local checksum = hash.sha1(bytes("hello"))

hash.sha256

• Calculate the SHA256 hash value of a file or binary data

Function Prototype

API

hash.sha256(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function

Usage

Calculates the SHA256 hash value of the specified file or binary data and returns a hexadecimal format hash string.

SHA256 is more secure than MD5 and is commonly used for package integrity verification:

Calculate file hash value:

-- Verify downloaded package file
local packagefile = "package.tar.gz"
local checksum = hash.sha256(packagefile)
if checksum ~= expected_hash then
    raise("checksum mismatch!")
end

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate SHA256 hash value of binary data
local checksum = hash.sha256(bytes("hello"))

hash.uuid

• Generate a UUID based on a name

Function Prototype

API

hash.uuid(name: <string>)

Parameter Description

Parameter	Description
name	Name string for UUID generation

Usage

local id = hash.uuid("name")

Generates a deterministic UUID based on the given name string. The same name always generates the same UUID.

Internally calls hash.uuid4(str), format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

Suitable for generating fixed unique identifiers for specific configurations:

-- Generate deterministic IDs for different build configurations
local config_id = hash.uuid("debug-x64-windows")

hash.xxhash32

• Calculate the 32-bit xxHash hash value of a file or binary data

Function Prototype

API

hash.xxhash32(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function

Usage

Calculates hash value using the xxHash32 algorithm. xxHash is an extremely fast non-cryptographic hash algorithm suitable for hash tables, checksums, and other scenarios.

Calculate file hash value:

-- Calculate xxHash32 hash value of a file
local checksum = hash.xxhash32("/path/to/file.txt")

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate xxHash32 hash value of binary data
local checksum = hash.xxhash32(bytes("hello"))

hash.xxhash64

• Calculate the 64-bit xxHash hash value of a file or binary data

Function Prototype

API

hash.xxhash64(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function

Usage

Calculates hash value using the xxHash64 algorithm. Fast and suitable for quick verification.

Calculate file hash value:

-- Calculate xxHash64 hash value of a file
local checksum = hash.xxhash64("/path/to/file.txt")

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate xxHash64 hash value of binary data
local checksum = hash.xxhash64(bytes("hello"))

Incorrect usage (don't do this):

-- ❌ Wrong: Don't pass string data directly
local key = hash.xxhash64(table.concat(params, "|"))

-- ✅ Correct: Use bytes wrapper for binary data
local key = hash.xxhash64(bytes(table.concat(params, "|")))

hash.xxhash128

• Calculate the 128-bit xxHash hash value of a file or binary data

Function Prototype

API

hash.xxhash128(input: <string|bytes>)

Parameter Description

Parameter	Description
input	File path (string) or binary data (bytes)

Important Notes

• String parameter is only for file paths: If a string is passed, the function will calculate the hash value of that file
• Binary data must use bytes parameter: To calculate the hash value of binary data, you must wrap the data with the bytes() function

Usage

Calculates hash value using the xxHash128 algorithm, providing longer hash values to reduce collisions.

Calculate file hash value:

-- Calculate xxHash128 hash value of a file
local checksum = hash.xxhash128("/path/to/file.txt")

Calculate binary data hash value:

import("core.base.bytes")

-- Calculate xxHash128 hash value of binary data
local checksum = hash.xxhash128(bytes("hello"))

hash.strhash32

• Generate a 32-bit hash value from a string

Function Prototype

API

hash.strhash32(input: <string>)

Parameter Description

Parameter	Description
input	String

Usage

Generates a 32-bit hash value from a string, returns format like: 91e8ecf1

This interface uses xxhash32 internally, specifically designed for fast string hashing.

hash.strhash64

• Generate a 64-bit hash value from a string

Function Prototype

API

hash.strhash64(input: <string>)

Parameter Description

Parameter	Description
input	String

Usage

Generates a 64-bit hash value from a string, returns format like: 91e8ecf191e8ecf1

hash.strhash128

• Generate a 128-bit hash value from a string

Function Prototype

API

hash.strhash128(input: <string>)

Parameter Description

Parameter	Description
input	String

Usage

Generates a 128-bit hash value from a string, returns format like: 91e8ecf1417f4edfa574e22d7d8d204a

Suitable for generating compilation cache keys:

-- Generate key for compilation cache
local cache_key = hash.strhash128(compiler .. flags .. source)

hash.rand32

• Generate a 32-bit random hash value

Function Prototype

API

hash.rand32()

Parameter Description

No parameters required for this function.

Usage

Generates a 32-bit random hash value.

WARNING

This interface is prone to hash collisions and is not recommended for scenarios requiring high uniqueness.

hash.rand64

• Generate a 64-bit random hash value

Function Prototype

API

hash.rand64()

Parameter Description

No parameters required for this function.

Usage

Generates a 64-bit random hash value.

hash.rand128

• Generate a 128-bit random hash value

Function Prototype

API

hash.rand128()

Parameter Description

No parameters required for this function.

Usage

Generates a 128-bit random hash value.