Просмотр исходного кода

Fix dependency groups example — all-strings or all-arrays, not mixed; each group is self-contained

clanker 1 неделя назад
Родитель
Сommit
c3d5a3f684
1 измененных файлов с 7 добавлено и 5 удалено
  1. 7 5
      PACKAGING_GUIDE.md

+ 7 - 5
PACKAGING_GUIDE.md

@@ -140,14 +140,15 @@ Provide what downstream packages might want to depend on:
 
 
 ## Dependency groups (alternatives)
 ## Dependency groups (alternatives)
 
 
-When a package can be satisfied by *either* of multiple dependency sets, use the nested array form:
+When a package can be satisfied by *either* of multiple dependency sets, use the nested array form. A phase must be **either all plain strings (standard)** **or all arrays (alternatives)** — mixing strings and arrays in the same phase is a validation error.
+
+Each inner array is a complete, self-contained candidate group. Common dependencies are repeated in every group:
 
 
 ```json
 ```json
 "depends": {
 "depends": {
     "build": [
     "build": [
-        "bin:valac",
-        ["pc:gtk4.pc", "pc:libadwaita-1.pc"],
-        ["pc:gtk3.pc", "pc:libhandy-1.pc"]
+        ["bin:valac", "pc:glib-2.0.pc", "pc:gtk4.pc", "pc:libadwaita-1.pc"],
+        ["bin:valac", "pc:glib-2.0.pc", "pc:gtk3.pc", "pc:libhandy-1.pc"]
     ]
     ]
 }
 }
 ```
 ```
@@ -155,12 +156,13 @@ When a package can be satisfied by *either* of multiple dependency sets, use the
 USM picks whichever group is fully satisfiable, preferring the one that installs the fewest packages.
 USM picks whichever group is fully satisfiable, preferring the one that installs the fewest packages.
 
 
 **When to use groups:**
 **When to use groups:**
-- A library supports multiple backends (e.g., OpenSSL OR GnuTLS)
+- A library supports multiple backends (e.g., GTK4 or GTK3)
 - A newer monolithic package replaces two older split ones
 - A newer monolithic package replaces two older split ones
 
 
 **When NOT to use groups:**
 **When NOT to use groups:**
 - Optional features (use separate packages or flags instead)
 - Optional features (use separate packages or flags instead)
 - Platform-specific deps (declare both; the resolver picks what's available)
 - Platform-specific deps (declare both; the resolver picks what's available)
+- When you only need "one of these" for a single dependency — that's what the resolver already does with SPM + USM fallback
 
 
 ---
 ---