1 files changed, 61 insertions, 0 deletions
diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli
index 0b32604..e367828 100644
--- a/bpkg/cfg-create.cli
+++ b/bpkg/cfg-create.cli
@@ -51,6 +51,37 @@ namespace bpkg
      \
      bpkg create cxx. \"?cli\"
      \
+
+     Configurations can be associated with each other to allow a package to be
+     built in one configuration while its dependencies in one or more
+     associated configurations. This can be used to create a \"base\"
+     configuration with common dependencies that are shared between multiple
+     configurations. This mechanism is also used to provide a host
+     configuration that is used to build build-time dependencies.
+
+     Each configuration is assigned an automatically-generated UUID unless one
+     is specified with the \cb{--config-uuid} option. This UUID is used to
+     check the integrity of configuration associations. For convenience of
+     referring to associated configurations, a configuration can also be
+     assigned a name with the \cb{--name} option.
+
+     A configuration also has a type specified with the \cb{--type} option.
+     Two predefined types are \cb{host} and \cb{target}. If the type is not
+     specified explicitly, then \cb{target} is assumed. When satisfying a
+     dependency of one package on another, an associated configuration will
+     only be considered if (1) it has the same type as the other configuration
+     for run-time dependencies and (2) it has the \cb{host} type for
+     build-time dependencies. Note that a host configuration is a target
+     configuration for the host machine. So to create a self-hosted
+     configuration, use type \cb{host}.
+
+     To associate a configuration we use the \l{bpkg-cfg-add(1)} command. As a
+     shortcut, a host configuration can also be associated during the
+     configuration creation with the \cb{--host-config} option. If a
+     build-time dependency is encountered in a configuration that has no
+     associated host configuration (nor is itself a host configuration), then
+     a private host configuration named \cb{host} is created automatically
+     inside the configuration's \c{.bpkg/} subdirectory.
      "
   }
 
@@ -77,6 +108,36 @@ namespace bpkg
        configuration. For safety, this option requires that you specify the
        configuration directory explicitly with \cb{--directory|-d}."
     }
+
+    dir_path --host-config
+    {
+      "<dir>",
+      "Associate the specified host configuration with the configuration
+       being created as if by running the \l{bpkg-cfg-add(1)} command."
+    }
+
+    string --name
+    {
+      "<name>",
+      "The name of the configuration being created. If this configuration
+       is associated with another configuration using \l{bpkg-cfg-add(1)},
+       this name will be used as the association name unless overridden.
+       By default the configuration is created unnamed."
+    }
+
+    string --type = "target"
+    {
+      "<type>",
+      "The type of the configuration being created. By default, configuration
+       of type \cb{target} is created."
+    }
+
+    uuid --config-uuid
+    {
+      "<uuid>",
+      "Use the specified UUID as the configuration id instead of generating
+       one automatically."
+    }
   };
 
   "