add hash modules

docs/api/scripts/builtin-modules/hash.md

@@ -0,0 +1,188 @@
+
+# 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 string or file
+
+```lua
+local hashval = hash.md5("hello")
+local hashval = hash.md5("/path/to/file")
+```
+
+Calculates the MD5 hash value of the specified string or file and returns a hexadecimal format hash string. Supports both string and file path as input.
+
+Commonly used for calculating file content checksums:
+
+```lua
+-- Read file content and calculate MD5
+local content = io.readfile("file.txt")
+local checksum = hash.md5(content)
+print("MD5: " .. checksum)
+```
+
+## hash.sha1
+
+- Calculate the SHA1 hash value of a string or file
+
+```lua
+local hashval = hash.sha1("hello")
+local hashval = hash.sha1("/path/to/file")
+```
+
+Calculates the SHA1 hash value of the specified string or file and returns a hexadecimal format hash string.
+
+## hash.sha256
+
+- Calculate the SHA256 hash value of a string or file
+
+```lua
+local hashval = hash.sha256("hello")
+local hashval = hash.sha256("/path/to/file")
+```
+
+Calculates the SHA256 hash value of the specified string or file and returns a hexadecimal format hash string.
+
+SHA256 is more secure than MD5 and is commonly used for package integrity verification:
+
+```lua
+-- Verify downloaded package file
+local packagefile = "package.tar.gz"
+local checksum = hash.sha256(packagefile)
+if checksum ~= expected_hash then
+    raise("checksum mismatch!")
+end
+```
+
+## hash.uuid
+
+- Generate a UUID based on a name
+
+```lua
+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:
+
+```lua
+-- 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 string or file
+
+```lua
+local hashval = hash.xxhash32("hello")
+local hashval = hash.xxhash32("/path/to/file")
+```
+
+Calculates hash value using the xxHash32 algorithm. xxHash is an extremely fast non-cryptographic hash algorithm suitable for hash tables, checksums, and other scenarios.
+
+## hash.xxhash64
+
+- Calculate the 64-bit xxHash hash value of a string or file
+
+```lua
+local hashval = hash.xxhash64("hello")
+local hashval = hash.xxhash64("/path/to/file")
+```
+
+Calculates hash value using the xxHash64 algorithm. Fast and suitable for quick verification:
+
+```lua
+-- Generate fast hash key for compilation parameters
+local key = hash.xxhash64(table.concat(params, "|"))
+```
+
+## hash.xxhash128
+
+- Calculate the 128-bit xxHash hash value of a string or file
+
+```lua
+local hashval = hash.xxhash128("hello")
+local hashval = hash.xxhash128("/path/to/file")
+```
+
+Calculates hash value using the xxHash128 algorithm, providing longer hash values to reduce collisions.
+
+## hash.strhash32
+
+- Generate a 32-bit hash value from a string
+
+```lua
+local hashval = hash.strhash32("hello")
+```
+
+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
+
+```lua
+local hashval = hash.strhash64("hello")
+```
+
+Generates a 64-bit hash value from a string, returns format like: `91e8ecf191e8ecf1`
+
+## hash.strhash128
+
+- Generate a 128-bit hash value from a string
+
+```lua
+local hashval = hash.strhash128("hello")
+```
+
+Generates a 128-bit hash value from a string, returns format like: `91e8ecf1417f4edfa574e22d7d8d204a`
+
+Suitable for generating compilation cache keys:
+
+```lua
+-- Generate key for compilation cache
+local cache_key = hash.strhash128(compiler .. flags .. source)
+```
+
+## hash.rand32
+
+- Generate a 32-bit random hash value
+
+```lua
+local randval = hash.rand32()
+```
+
+Generates a 32-bit random hash value.
+
+::: warning 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
+
+```lua
+local randval = hash.rand64()
+```
+
+Generates a 64-bit random hash value.
+
+## hash.rand128
+
+- Generate a 128-bit random hash value
+
+```lua
+local randval = hash.rand128()
+```
+
+Generates a 128-bit random hash value.
+

docs/zh/api/scripts/builtin-modules/hash.md

@@ -0,0 +1,188 @@
+
+# hash
+
+hash 模块提供了哈希值计算和 UUID 生成功能，这是 xmake 的一个内置模块。
+
+## hash.md5
+
+- 计算字符串或文件的 MD5 哈希值
+
+```lua
+local hashval = hash.md5("hello")
+local hashval = hash.md5("/path/to/file")
+```
+
+计算指定字符串或文件的 MD5 哈希值，返回十六进制格式的哈希字符串。支持传入字符串或文件路径。
+
+通常用于计算文件内容校验和：
+
+```lua
+-- 读取文件内容并计算 MD5
+local content = io.readfile("file.txt")
+local checksum = hash.md5(content)
+print("MD5: " .. checksum)
+```
+
+## hash.sha1
+
+- 计算字符串或文件的 SHA1 哈希值
+
+```lua
+local hashval = hash.sha1("hello")
+local hashval = hash.sha1("/path/to/file")
+```
+
+计算指定字符串或文件的 SHA1 哈希值，返回十六进制格式的哈希字符串。
+
+## hash.sha256
+
+- 计算字符串或文件的 SHA256 哈希值
+
+```lua
+local hashval = hash.sha256("hello")
+local hashval = hash.sha256("/path/to/file")
+```
+
+计算指定字符串或文件的 SHA256 哈希值，返回十六进制格式的哈希字符串。
+
+SHA256 比 MD5 更安全，常用于包的完整性校验：
+
+```lua
+-- 校验下载的包文件
+local packagefile = "package.tar.gz"
+local checksum = hash.sha256(packagefile)
+if checksum ~= expected_hash then
+    raise("checksum mismatch!")
+end
+```
+
+## hash.uuid
+
+- 根据名称生成 UUID
+
+```lua
+local id = hash.uuid("name")
+```
+
+根据给定的名称字符串生成一个确定性的 UUID，相同的名称总是生成相同的 UUID。
+
+内部调用 `hash.uuid4(str)`，格式为：`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+
+适合为特定配置生成固定的唯一标识符：
+
+```lua
+-- 为不同的编译配置生成确定性 ID
+local config_id = hash.uuid("debug-x64-windows")
+```
+
+## hash.xxhash32
+
+- 计算字符串或文件的 32 位 xxHash 哈希值
+
+```lua
+local hashval = hash.xxhash32("hello")
+local hashval = hash.xxhash32("/path/to/file")
+```
+
+使用 xxHash32 算法计算哈希值，xxHash 是一个极快的非加密哈希算法，适合用于哈希表、校验和等场景。
+
+## hash.xxhash64
+
+- 计算字符串或文件的 64 位 xxHash 哈希值
+
+```lua
+local hashval = hash.xxhash64("hello")
+local hashval = hash.xxhash64("/path/to/file")
+```
+
+使用 xxHash64 算法计算哈希值，速度快，适合快速校验：
+
+```lua
+-- 为编译参数生成快速哈希键
+local key = hash.xxhash64(table.concat(params, "|"))
+```
+
+## hash.xxhash128
+
+- 计算字符串或文件的 128 位 xxHash 哈希值
+
+```lua
+local hashval = hash.xxhash128("hello")
+local hashval = hash.xxhash128("/path/to/file")
+```
+
+使用 xxHash128 算法计算哈希值，提供更长的哈希值以减少冲突。
+
+## hash.strhash32
+
+- 从字符串生成 32 位哈希值
+
+```lua
+local hashval = hash.strhash32("hello")
+```
+
+从字符串生成 32 位哈希值，返回格式如：`91e8ecf1`
+
+这个接口内部使用 xxhash32，专门用于字符串快速哈希。
+
+## hash.strhash64
+
+- 从字符串生成 64 位哈希值
+
+```lua
+local hashval = hash.strhash64("hello")
+```
+
+从字符串生成 64 位哈希值，返回格式如：`91e8ecf191e8ecf1`
+
+## hash.strhash128
+
+- 从字符串生成 128 位哈希值
+
+```lua
+local hashval = hash.strhash128("hello")
+```
+
+从字符串生成 128 位哈希值，返回格式如：`91e8ecf1417f4edfa574e22d7d8d204a`
+
+适合用于生成编译缓存键：
+
+```lua
+-- 为编译缓存生成键
+local cache_key = hash.strhash128(compiler .. flags .. source)
+```
+
+## hash.rand32
+
+- 生成 32 位随机哈希值
+
+```lua
+local randval = hash.rand32()
+```
+
+生成一个 32 位的随机哈希值。
+
+::: warning 注意
+此接口容易触发哈希冲突，不建议用于需要高唯一性的场景。
+:::
+
+## hash.rand64
+
+- 生成 64 位随机哈希值
+
+```lua
+local randval = hash.rand64()
+```
+
+生成一个 64 位的随机哈希值。
+
+## hash.rand128
+
+- 生成 128 位随机哈希值
+
+```lua
+local randval = hash.rand128()
+```
+
+生成一个 128 位的随机哈希值。
+