From d2f6bd81844cd8a7235f9f27386a22e376caec18 Mon Sep 17 00:00:00 2001 From: qmuntal Date: Thu, 19 Mar 2026 16:02:55 +0100 Subject: [PATCH 1/7] improve NocgoOpenSSL.md --- eng/doc/NocgoOpenSSL.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index 059576f7795..c57860dbce6 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -32,8 +32,23 @@ To see existing requests or request support for additional architectures, use th ## How the backend is selected -If cgo is enabled (e.g., `CGO_ENABLED=1`), the cgo-based OpenSSL backend is always used. -The cgo-less backend is only used when cgo is disabled **and** you're on a supported architecture. +* If cgo is explicitly enabled with `CGO_ENABLED=1`, the cgo-based OpenSSL backend is used. +* If cgo is disabled with `CGO_ENABLED=0` and you're on a supported architecture, the cgo-less OpenSSL backend is used. +* If cgo is not explicitly enabled or disabled, then the cgo-less OpenSSL backend is used if the Go toolchain decides that cgo should be disabled. The are the rules at the time of writing: + * cgo is disabled if the Go toolchain is build with `CGO_ENABLED=0`. Note that that's not currently the case for the Microsoft build of Go. + * cgo is disabled when cross-compiling. + * cgo is diables if the `CC` environment variable is not set to an existing executable. -This means if cgo is enabled by default on your platform or you enable cgo for other reasons (e.g., linking your own C library), the crypto backend will use the cgo-based implementation. -You can also intentionally enable cgo to successfully build for a platform without cgo-less OpenSSL support. +## Runtime dependencies + +The cgo-less OpenSSL backend still relies in the C machinery to load OpenSSL at runtime and manage threading. + +This is an exhaustive list of the runtime dependencies other than OpenSSL itself: + +* `libc.so.6` for various C library functions. There is no minimum version requirement. +* `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. There is no minimum version requirement. +* `libpthread.so.0` for managing Go's threads. There is no minimum version requirement. + +Note that `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. +The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. +If your platform doesn't provide these libraries, you can create them as symlinks to `libc.so.6` to satisfy the dependencies, e.g. `ln -s libc.so.6 libdl.so.2` and `ln -s libc.so.6 libpthread.so.0`. From 87e01b3737ff4809e8b3b99eeb23be2bed3a933c Mon Sep 17 00:00:00 2001 From: qmuntal Date: Thu, 19 Mar 2026 16:04:10 +0100 Subject: [PATCH 2/7] typo --- eng/doc/NocgoOpenSSL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index c57860dbce6..b28f72725fd 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -41,7 +41,7 @@ To see existing requests or request support for additional architectures, use th ## Runtime dependencies -The cgo-less OpenSSL backend still relies in the C machinery to load OpenSSL at runtime and manage threading. +The cgo-less OpenSSL backend still relies in the C machinery to load OpenSSL at runtime and manage threads. This is an exhaustive list of the runtime dependencies other than OpenSSL itself: From 7955954744d011241e3894b854f269d80eb35fc1 Mon Sep 17 00:00:00 2001 From: Quim Muntal Date: Thu, 19 Mar 2026 16:14:56 +0100 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- eng/doc/NocgoOpenSSL.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index b28f72725fd..a3519022784 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -34,21 +34,22 @@ To see existing requests or request support for additional architectures, use th * If cgo is explicitly enabled with `CGO_ENABLED=1`, the cgo-based OpenSSL backend is used. * If cgo is disabled with `CGO_ENABLED=0` and you're on a supported architecture, the cgo-less OpenSSL backend is used. -* If cgo is not explicitly enabled or disabled, then the cgo-less OpenSSL backend is used if the Go toolchain decides that cgo should be disabled. The are the rules at the time of writing: - * cgo is disabled if the Go toolchain is build with `CGO_ENABLED=0`. Note that that's not currently the case for the Microsoft build of Go. +* If cgo is not explicitly enabled or disabled, then the cgo-less OpenSSL backend is used if the Go toolchain decides that cgo should be disabled. These are the rules at the time of writing: + * cgo is disabled if the Go toolchain is built with `CGO_ENABLED=0`. Note that that's not currently the case for the Microsoft build of Go. * cgo is disabled when cross-compiling. - * cgo is diables if the `CC` environment variable is not set to an existing executable. + * cgo is disabled if the `CC` environment variable is not set to an existing executable. ## Runtime dependencies -The cgo-less OpenSSL backend still relies in the C machinery to load OpenSSL at runtime and manage threads. +The cgo-less OpenSSL backend still relies on the C machinery to load OpenSSL at runtime and manage threads. -This is an exhaustive list of the runtime dependencies other than OpenSSL itself: +The following are the expected runtime dependencies other than OpenSSL itself on glibc-based systems: -* `libc.so.6` for various C library functions. There is no minimum version requirement. -* `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. There is no minimum version requirement. -* `libpthread.so.0` for managing Go's threads. There is no minimum version requirement. +* `libc.so.6` for various C library functions. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. +* `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. +* `libpthread.so.0` for managing Go's threads. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. Note that `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. -If your platform doesn't provide these libraries, you can create them as symlinks to `libc.so.6` to satisfy the dependencies, e.g. `ln -s libc.so.6 libdl.so.2` and `ln -s libc.so.6 libpthread.so.0`. +If your platform doesn't provide these libraries, the preferred solution is to install the appropriate runtime or compatibility packages so that `libdl.so.2` and `libpthread.so.0` are available in standard system library directories (for example `/lib` or `/usr/lib`). +As an advanced workaround, you may instead create symlinks to `libc.so.6` in a directory searched by the dynamic linker (for example, a system library directory) and update the loader cache if required (for example by running `ldconfig`); this typically requires root privileges and should only be done if you understand the implications for your system's C library. From 94da23e8f9ab3e044916a918421db27677557e75 Mon Sep 17 00:00:00 2001 From: qmuntal Date: Thu, 19 Mar 2026 16:18:27 +0100 Subject: [PATCH 4/7] remove sentences --- eng/doc/NocgoOpenSSL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index a3519022784..85d6da27af5 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -45,9 +45,9 @@ The cgo-less OpenSSL backend still relies on the C machinery to load OpenSSL at The following are the expected runtime dependencies other than OpenSSL itself on glibc-based systems: -* `libc.so.6` for various C library functions. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. -* `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. -* `libpthread.so.0` for managing Go's threads. There is no additional minimum version requirement beyond the glibc baseline supported by this Go distribution. +* `libc.so.6` for various C library functions. +* `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. +* `libpthread.so.0` for managing Go's threads. Note that `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. From 35940078da51c2ee4be6d066174ef172fb316ded Mon Sep 17 00:00:00 2001 From: Quim Muntal Date: Fri, 20 Mar 2026 09:10:08 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Davis Goodin --- eng/doc/NocgoOpenSSL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index 85d6da27af5..8059e0ee720 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -33,8 +33,10 @@ To see existing requests or request support for additional architectures, use th ## How the backend is selected * If cgo is explicitly enabled with `CGO_ENABLED=1`, the cgo-based OpenSSL backend is used. -* If cgo is disabled with `CGO_ENABLED=0` and you're on a supported architecture, the cgo-less OpenSSL backend is used. -* If cgo is not explicitly enabled or disabled, then the cgo-less OpenSSL backend is used if the Go toolchain decides that cgo should be disabled. These are the rules at the time of writing: +* If cgo is disabled with `CGO_ENABLED=0`, then: + * If you're on a supported architecture, the cgo-less OpenSSL backend is used. + * If you're on an unsupported architecture, the build fails. +* If cgo is not explicitly enabled or disabled, then the cgo-less OpenSSL backend is used if the Go toolchain decides that cgo should be disabled. The rules are officially described by [cmd/cgo](https://pkg.go.dev/cmd/cgo). This is a summary, at the time of writing (2026-03-19): * cgo is disabled if the Go toolchain is built with `CGO_ENABLED=0`. Note that that's not currently the case for the Microsoft build of Go. * cgo is disabled when cross-compiling. * cgo is disabled if the `CC` environment variable is not set to an existing executable. From b4f4fea836a7bc99408f17b1471264abc428633a Mon Sep 17 00:00:00 2001 From: Quim Muntal Date: Fri, 20 Mar 2026 09:10:30 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Davis Goodin --- eng/doc/NocgoOpenSSL.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index 8059e0ee720..5c80410e076 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -51,7 +51,10 @@ The following are the expected runtime dependencies other than OpenSSL itself on * `libdl.so.2` for loading OpenSSL at runtime using `dlopen`. * `libpthread.so.0` for managing Go's threads. -Note that `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. -The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. -If your platform doesn't provide these libraries, the preferred solution is to install the appropriate runtime or compatibility packages so that `libdl.so.2` and `libpthread.so.0` are available in standard system library directories (for example `/lib` or `/usr/lib`). -As an advanced workaround, you may instead create symlinks to `libc.so.6` in a directory searched by the dynamic linker (for example, a system library directory) and update the loader cache if required (for example by running `ldconfig`); this typically requires root privileges and should only be done if you understand the implications for your system's C library. +> [!NOTE] +> The `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. +> The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. +> +> If your platform doesn't provide these libraries, the preferred solution is to install the appropriate runtime or compatibility packages so that `libdl.so.2` and `libpthread.so.0` are available in standard system library directories (for example `/lib` or `/usr/lib`). +> +> As an advanced workaround, you may instead symlink `libdl.so.2` and `libpthread.so.0` to `libc.so.6` in a directory searched by the dynamic linker (for example, a system library directory) and update the loader cache if required (for example by running `ldconfig`); this typically requires root privileges and should only be done if you understand the implications for your system's C library. From babafd4643e360a66ea28fb2aded4111c3863045 Mon Sep 17 00:00:00 2001 From: qmuntal Date: Fri, 20 Mar 2026 09:14:42 +0100 Subject: [PATCH 7/7] add clarification --- eng/doc/NocgoOpenSSL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index 5c80410e076..10826cf228b 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -55,6 +55,8 @@ The following are the expected runtime dependencies other than OpenSSL itself on > The `libdl.so.2` and `libpthread.so.0` functionality is already provided by `libc.so.6` since glibc 2.34. > The Microsoft build of Go supports platforms with older versions of glibc, so it still links to `libdl.so.2` and `libpthread.so.0` directly. > +> There is no runtime dependency on the same libc that the program was built with. You can, for example, build a program on a system with glibc 2.34 or later and run it on a system with an older glibc version. +> > If your platform doesn't provide these libraries, the preferred solution is to install the appropriate runtime or compatibility packages so that `libdl.so.2` and `libpthread.so.0` are available in standard system library directories (for example `/lib` or `/usr/lib`). > > As an advanced workaround, you may instead symlink `libdl.so.2` and `libpthread.so.0` to `libc.so.6` in a directory searched by the dynamic linker (for example, a system library directory) and update the loader cache if required (for example by running `ldconfig`); this typically requires root privileges and should only be done if you understand the implications for your system's C library.