From f908184e11a23ac452a6d4aab361dcac520ac2a1 Mon Sep 17 00:00:00 2001
From: Wangchong Zhou <wangchong@konghq.com>
Date: Fri, 12 Jul 2024 13:56:47 +0800
Subject: [PATCH] doc(build): add readme for cross deps

---
 build/cross_deps/README.md                  | 25 +++++++++++++++++++++
 build/cross_deps/libxcrypt/repositories.bzl |  1 +
 build/cross_deps/libyaml/repositories.bzl   |  1 +
 build/cross_deps/zlib/repositories.bzl      |  1 +
 4 files changed, 28 insertions(+)
 create mode 100644 build/cross_deps/README.md

diff --git a/build/cross_deps/README.md b/build/cross_deps/README.md
new file mode 100644
index 000000000000..e2d52bf33b25
--- /dev/null
+++ b/build/cross_deps/README.md
@@ -0,0 +1,25 @@
+# Dependencies for cross build
+
+When cross building Kong (the target architecture is different from the host),
+we need to build some extra dependencies to produce headers and dynamic libraries
+to let compiler and linker work properly.
+
+Following are the dependencies:
+- libxcrypt
+- libyaml
+- zlib
+
+Note that the artifacts of those dependencies are only used during build time,
+they are not shipped together with our binary artifact (.deb, .rpm or docker image etc).
+
+We currently do cross compile on following platforms:
+- Amazonlinux 2
+- Amazonlinux 2023
+- Ubuntu 18.04 (Version 3.4.x.x only)
+- Ubuntu 22.04
+- RHEL 9
+- Debian 12
+
+As we do not use different versions in different distros just for simplicity, the version
+of those dependencies should remain the lowest among all distros originally shipped, to
+allow the produced artifacts has lowest ABI/API to be compatible across all distros.
\ No newline at end of file
diff --git a/build/cross_deps/libxcrypt/repositories.bzl b/build/cross_deps/libxcrypt/repositories.bzl
index f6c28d022445..ec6d450ba467 100644
--- a/build/cross_deps/libxcrypt/repositories.bzl
+++ b/build/cross_deps/libxcrypt/repositories.bzl
@@ -9,6 +9,7 @@ def libxcrypt_repositories():
     # thus crypt.h and libcrypt.so.1 are missing from cross tool chain
     # ubuntu2004: 4.4.10
     # ubuntu2204: 4.4.27
+    # NOTE: do not bump the following version, see build/cross_deps/README.md for detail.
     http_archive(
         name = "cross_deps_libxcrypt",
         url = "https://github.com/besser82/libxcrypt/releases/download/v4.4.27/libxcrypt-4.4.27.tar.xz",
diff --git a/build/cross_deps/libyaml/repositories.bzl b/build/cross_deps/libyaml/repositories.bzl
index b7b2800cf965..dffd0798cde6 100644
--- a/build/cross_deps/libyaml/repositories.bzl
+++ b/build/cross_deps/libyaml/repositories.bzl
@@ -6,6 +6,7 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 def libyaml_repositories():
     """Defines the libyaml repository"""
 
+    # NOTE: do not bump the following version, see build/cross_deps/README.md for detail.
     http_archive(
         name = "cross_deps_libyaml",
         url = "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz",
diff --git a/build/cross_deps/zlib/repositories.bzl b/build/cross_deps/zlib/repositories.bzl
index 3185b65222a8..325c23a5ac3f 100644
--- a/build/cross_deps/zlib/repositories.bzl
+++ b/build/cross_deps/zlib/repositories.bzl
@@ -6,6 +6,7 @@ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 def zlib_repositories():
     """Defines the zlib repository"""
 
+    # NOTE: do not bump the following version, see build/cross_deps/README.md for detail.
     http_archive(
         name = "cross_deps_zlib",
         urls = [