Docs for 11580 - validate_build() (#2667)

* Docs for 11580

* typo

* More complete

migrating_to_2.0/recipes.rst

@@ -193,6 +193,35 @@ are valid.
                 raise ConanInvalidConfiguration("This package is not compatible with Windows")
 
 
+If you are not checking if the resulting binary is valid for the current configuration but need to check if a package
+can be built or not for a specific configuration you must use the ``validate_build()`` method instead using ``self.settings``
+and ``self.options`` to perform the checks:
+
+
+.. code-block:: python
+
+    from conan import ConanFile
+    from conan.errors import ConanInvalidConfiguration
+
+    class myConan(ConanFile):
+        name = "foo"
+        version = "1.0"
+        settings = "os", "arch", "compiler"
+
+        def package_id(self):
+            # For this package, it doesn't matter the compiler used for the binary package
+            del self.info.settings.compiler
+
+        def validate_build(self):
+            # But we know this cannot be build with "gcc"
+            if self.settings.compiler == "gcc":
+                raise ConanInvalidConfiguration("This doesn't build in GCC")
+
+        def validate(self):
+            # We shouldn't check here if the self.info.settings.compiler because it has been removed in the package_id()
+            # so it doesn't make sense to check if the binary is compatible with gcc because the compiler doesn't matter
+            pass
+
 
 The layout() method
 -------------------

reference/conanfile/methods.rst

@@ -636,6 +636,51 @@ raise an error, but in the best case it will be wasted resources (compatible pac
 strongly recommended to properly define the ``package_id()`` method to no include incompatible configurations.
 
 
+validate_build()
+----------------
+
+.. warning::
+
+    This is an **experimental** feature subject to breaking changes in future releases.
+
+Available since: `1.51.0 <https://github.com/conan-io/conan/releases/tag/1.41.0>`_
+
+The ``validate_build()`` method is used to verify if a configuration is valid for building a package. It is different
+from the ``validate()`` method that checks if the binary package is "impossible" or invalid for a given configuration.
+
+In Conan 2.0, the ``validate()`` method should do the checks of the settings and options using the ``self.info.settings``
+and ``self.info.options``.
+
+The ``validate_build()`` method has to use always the ``self.settings`` and ``self.options``:
+
+.. code-block:: python
+
+    from conan import ConanFile
+    from conan.errors import ConanInvalidConfiguration
+
+    class myConan(ConanFile):
+        name = "foo"
+        version = "1.0"
+        settings = "os", "arch", "compiler"
+
+        def package_id(self):
+            # For this package, it doesn't matter the compiler used for the binary package
+            del self.info.settings.compiler
+
+        def validate_build(self):
+            # But we know this cannot be build with "gcc"
+            if self.settings.compiler == "gcc":
+                raise ConanInvalidConfiguration("This doesn't build in GCC")
+
+        def validate(self):
+            # We shouldn't check here the self.info.settings.compiler because it has been removed in the package_id()
+            # so it doesn't make sense to check if the binary is compatible with gcc because the compiler doesn't matter
+            pass
+
+
+
+
+
 .. _method_requirements:
 
 requirements()