Feature/docs 4696 (conan-io#1141)

* Added: docs for #4696 describing that package references are matchable now instead of only package names * Document build patterns * Update reference/commands/consumer/install.rst Co-Authored-By: lasote <[email protected]>
Dattax · Mar 28, 2019 · 02846a8 · 02846a8
1 parent a083209
commit 02846a8
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 5 deletions.
diff --git a/mastering/policies.rst b/mastering/policies.rst
@@ -10,6 +10,7 @@ As previously demonstrated, we can use the :command:`--build` option to change t
 - :command:`--build missing` will build only the missing requires.
 - :command:`--build` will build all requirements from sources.
 - :command:`--build outdated` will try to build from code if the binary is not built with the current recipe or when missing binary package.
+- :command:`--build pattern*` will build only the packages with the reference starting with "pattern".
 
 With the ``build_policy`` attribute the package creator can change the default conan's build behavior. The allowed build_policy values are:
 
@@ -33,4 +34,5 @@ libraries.
 The ``always`` policy, will retrieve the sources each time the package is installed so it can be useful for providing a "latest" mechanism
 or ignoring the uploaded binary packages.
 
-The package pattern can be referred as the package name only or a full reference e.g :command:`--build Poco` or :command:`--build zlib/1.2.11@conan/stable`.
+The package pattern can be referred as a case-sensitive fnmatch pattern of the package name or the full package reference.
+e.g :command:`--build Poco`, :command:`--build Poc*`, :command:`--build zlib/*@conan/*`, :command:`--build *@conan/stable` or :command:`--build zlib/1.2.11@conan/stable`.
diff --git a/reference/commands/consumer/install.rst b/reference/commands/consumer/install.rst
@@ -173,10 +173,14 @@ to build things or not:
   requested configuration was not found on any of the active remotes.
 * :command:`--build=outdated`: Conan will try to build from code if the binary is not built with the
   current recipe or when missing binary package.
-* :command:`--build=[pattern]`: A fnmatch file pattern of a package name. E.g., ``zl*`` will match
-  ``zlib`` package. Conan will force the build of the packages, the name of which matches the given
-  **pattern**. Several patterns can be specified, chaining multiple options,
-  e.g., :command:`--build=pattern1 --build=pattern2`.
+* :command:`--build=[pattern]`: A fnmatch case-sensitive pattern of a package reference or only the package name.
+  Conan will force the build of the packages whose reference matches the given
+  **pattern**. Several patterns can be specified, chaining multiple options:
+
+   - e.g., :command:`--build=pattern1 --build=pattern2` can be used to specify more than one pattern.
+   - e.g., :command:`--build=zlib` will match any package named ``zlib`` (same as ``zlib/*``).
+   - e.g., :command:`--build=z*@conan/stable` will match any package starting with ``z`` with ``conan/stable`` as user/channel.
+
 * :command:`--build`: Always build everything from source. Produces a clean re-build of all packages
   and transitively dependent packages