From aca640eb5ee8eadea34490ac9693b9eafd013efd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 14 Nov 2025 16:03:31 +0100 Subject: [PATCH 1/5] KB: add a section on Windows install paths and naming conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a short section that covers Windows-specific install paths and library naming conventions. I suppose other people with primarily POSIX background will find this helpful, especially that these conventions are at least partially specific to conda-forge. The variables don't seem to be part of the core documentation, but they were documented in conda-build and rattler-build docs separately. I chose to document the intersection of both. Signed-off-by: Michał Górny --- docs/maintainer/knowledge_base.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md index ffef3020c3..6b6f96ae0b 100644 --- a/docs/maintainer/knowledge_base.md +++ b/docs/maintainer/knowledge_base.md @@ -349,6 +349,30 @@ Some packages do not provide build systems with first-hand support for Windows, You can use the [autotools_clang_conda](https://github.com/conda-forge/autotools_clang_conda-feedstock?tab=readme-ov-file#about-autotools_clang_conda-feedstock) to provide a build environment with a set of MSYS2 packages and a Clang toolchain configured to build packages compatible with MSVC. The feedstock's description provides example instructions. + + +### Install paths and naming conventions + +Unix-style packages in conda-forge are installed into a special `Library` directory tree under the build prefix. +For the convenience of writing build scripts, both conda-build and rattler-build define the following variables: + +| Variable | Value | Use | +| ---------------- | -------------------------- | ------------------------------ | +| `LIBRARY_PREFIX` | `%PREFIX%\Library` | Prefix for installing packages | +| `LIBRARY_BIN` | `%PREFIX%\Library\bin` | Executables and DLL libraries | +| `LIBRARY_INC` | `%PREFIX%\Library\include` | Header files | +| `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries | +| `SCRIPTS` | `%PREFIX%\Scripts` | Python scripts | + +Shared libraries on Windows generally follows the MSVC convention, and therefore are distributed as pairs of two files, usually without a `lib` prefix: + +- `{name}.dll`, the actual dynamic library that is used by compiled executables +- `{name}.lib`, the so-called import library that is used to link against the dynamic library when building packages + +If a static library is installed as well, it is usually prefixed with `lib` to distinguish it from the import library: + +- `lib{name}.lib`, the static library + ## Special Dependencies and Packages From 78bb8c0bf7e2d4c2646eb14967861becd1bc21e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 14 Nov 2025 17:20:01 +0100 Subject: [PATCH 2/5] Apply suggestion from @hmaarrfk Co-authored-by: Mark Harfouche --- docs/maintainer/knowledge_base.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md index 6b6f96ae0b..0752d7146d 100644 --- a/docs/maintainer/knowledge_base.md +++ b/docs/maintainer/knowledge_base.md @@ -359,9 +359,9 @@ For the convenience of writing build scripts, both conda-build and rattler-build | Variable | Value | Use | | ---------------- | -------------------------- | ------------------------------ | | `LIBRARY_PREFIX` | `%PREFIX%\Library` | Prefix for installing packages | -| `LIBRARY_BIN` | `%PREFIX%\Library\bin` | Executables and DLL libraries | +| `LIBRARY_BIN` | `%PREFIX%\Library\bin` | Executables and DLL libraries (`.exe` and `.dll` files) | | `LIBRARY_INC` | `%PREFIX%\Library\include` | Header files | -| `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries | +| `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries (`.lib` files) | | `SCRIPTS` | `%PREFIX%\Scripts` | Python scripts | Shared libraries on Windows generally follows the MSVC convention, and therefore are distributed as pairs of two files, usually without a `lib` prefix: From 9d325542c9b403409f637f8fd15b42c669c1cd37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 14 Nov 2025 18:03:07 +0100 Subject: [PATCH 3/5] Reformat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- docs/maintainer/knowledge_base.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md index 0752d7146d..e4f2513865 100644 --- a/docs/maintainer/knowledge_base.md +++ b/docs/maintainer/knowledge_base.md @@ -356,13 +356,13 @@ The feedstock's description provides example instructions. Unix-style packages in conda-forge are installed into a special `Library` directory tree under the build prefix. For the convenience of writing build scripts, both conda-build and rattler-build define the following variables: -| Variable | Value | Use | -| ---------------- | -------------------------- | ------------------------------ | -| `LIBRARY_PREFIX` | `%PREFIX%\Library` | Prefix for installing packages | -| `LIBRARY_BIN` | `%PREFIX%\Library\bin` | Executables and DLL libraries (`.exe` and `.dll` files) | -| `LIBRARY_INC` | `%PREFIX%\Library\include` | Header files | -| `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries (`.lib` files) | -| `SCRIPTS` | `%PREFIX%\Scripts` | Python scripts | +| Variable | Value | Use | +| ---------------- | -------------------------- | ------------------------------------------------------- | +| `LIBRARY_PREFIX` | `%PREFIX%\Library` | Prefix for installing packages | +| `LIBRARY_BIN` | `%PREFIX%\Library\bin` | Executables and DLL libraries (`.exe` and `.dll` files) | +| `LIBRARY_INC` | `%PREFIX%\Library\include` | Header files | +| `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries (`.lib` files) | +| `SCRIPTS` | `%PREFIX%\Scripts` | Python scripts | Shared libraries on Windows generally follows the MSVC convention, and therefore are distributed as pairs of two files, usually without a `lib` prefix: From 2ced2c6e2e3ebf3dbbac1417845f012b959b0e4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 14 Nov 2025 18:05:04 +0100 Subject: [PATCH 4/5] Mention `{name}-static.lib` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- docs/maintainer/knowledge_base.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md index e4f2513865..25b26bce66 100644 --- a/docs/maintainer/knowledge_base.md +++ b/docs/maintainer/knowledge_base.md @@ -373,6 +373,8 @@ If a static library is installed as well, it is usually prefixed with `lib` to d - `lib{name}.lib`, the static library +Some packages use `{name}-static.lib` instead, though it is considered a historical artifact. + ## Special Dependencies and Packages From 620a998764617431af03d1bf641bba555b108377 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Sat, 15 Nov 2025 11:36:19 +0100 Subject: [PATCH 5/5] Expand on possible conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- docs/maintainer/knowledge_base.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md index 25b26bce66..12f8be2d83 100644 --- a/docs/maintainer/knowledge_base.md +++ b/docs/maintainer/knowledge_base.md @@ -364,16 +364,29 @@ For the convenience of writing build scripts, both conda-build and rattler-build | `LIBRARY_LIB` | `%PREFIX%\Library\lib` | Import and static libraries (`.lib` files) | | `SCRIPTS` | `%PREFIX%\Scripts` | Python scripts | -Shared libraries on Windows generally follows the MSVC convention, and therefore are distributed as pairs of two files, usually without a `lib` prefix: +On Windows, it is not possible to link directly to dynamic libraries (`.dll` files); the linker needs to use so-called import libraries instead. +Import libraries have the same format and generally use the same suffix (`.lib`) as static libraries. +Therefore, whenever both dynamic and static libraries are installed, the import library and the static library must use different names. +There are two main naming conventions for installing libraries on Windows: the MSVC convention and the GCC/MinGW convention. -- `{name}.dll`, the actual dynamic library that is used by compiled executables -- `{name}.lib`, the so-called import library that is used to link against the dynamic library when building packages +The MSVC convention uses the following names: -If a static library is installed as well, it is usually prefixed with `lib` to distinguish it from the import library: +- dynamic library: `{name}.dll` (e.g. `zlib.dll`) +- import library: `{name}.lib` (e.g. `zlib.lib`) +- static library: no standard convention, often `lib{name}.lib` or `{name}-static.lib` (e.g. `zlibstatic.lib`) -- `lib{name}.lib`, the static library +Usually, `{name}` does not include a `lib` prefix. +Following this convention ensures that `-l{name}` works for dynamic linking, same as on Unix. +However, some packages do use `lib` prefix for historical reasons, e.g. `libprotobuf.dll` + `libprotobuf.lib`. -Some packages use `{name}-static.lib` instead, though it is considered a historical artifact. +The GCC/MinGW convention uses the following names: + +- dynamic library: `lib{name}.dll` +- import library: `lib{name}.dll.a` +- static library: `lib{name}.a` + +There is no standard convention for providing SONAME-style versioning for libraries. +Some packages do not provide versioning at all, others embed the version into the `.dll` name (but not the import library name, to preserve `-l{name}` behavior).