Docs for automatically handle CONAN_RUN_TESTS environment variable (#…

…2056)

* wip

* wip

* update bh docs

howtos/header_only.rst

@@ -81,14 +81,9 @@ If you want to run the library unit test while packaging, you would need this re
 
     If you are :ref:`cross-building <cross_building>` your **library** or **app** you'll probably need
     to skip the **unit tests** because your target binary cannot be executed in current building host.
-    To do it you can use :ref:`tools_get_env` in combination with
-    :ref:`env_vars_conan_run_tests` environment variable, defined as **False**
-    in profile for cross-building and replace ``cmake.test()`` with:
-
-    .. code-block:: python
-
-        if tools.get_env("CONAN_RUN_TESTS", True):
-            cmake.test()
+    To do it you can use :ref:`env_vars_conan_run_tests` environment variable, defined as **False**
+    in profile for cross-building in the call to ``cmake.test()`` this variable will be evaluated and
+    the tests will not run.
 
 Which will use a ``CMakeLists.txt`` file in the root folder:
 

reference/build_helpers/cmake.rst

@@ -335,7 +335,9 @@ test()
 
     def test(args=None, build_dir=None, target=None, output_on_failure=False)
 
-Build `CMake` test target (could be RUN_TESTS in multi-config projects or ``test`` in single-config projects), which usually means building and running unit tests
+Build `CMake` test target (could be RUN_TESTS in multi-config projects or ``test`` in single-config
+projects), which usually means building and running unit tests. When this function is called
+:ref:`env_vars_conan_run_tests` will be evaluated to check if tests should run.
 
 Parameters:
     - **args** (Optional, Defaulted to ``None``): A list of additional arguments to be passed to the ``cmake`` command. Each argument will be escaped according to the current shell. No extra arguments will be added if ``args=None``.

reference/build_helpers/meson.rst

@@ -89,7 +89,8 @@ test()
 
     def test(args=None, build_dir=None, target=None)
 
-Executes ninja test target, which usually means building and running unit tests.
+Executes ninja test target, which usually means building and running unit tests. When this function
+is called :ref:`env_vars_conan_run_tests` will be evaluated to check if tests should run.
 
 Parameters:
     - **args** (Optional, Defaulted to ``None``): A list of additional arguments to be passed to the ``ninja`` command. Each argument will be escaped

reference/env_vars.rst

@@ -477,7 +477,7 @@ or declared in command line when invoking :command:`conan install` to reduce the
 See how to retrieve the value with :ref:`tools.get_env() <tools_get_env>` and check a use case
 with :ref:`a header only with unit tests recipe <header_only_unit_tests_tip>` while cross building.
 
-See example of build method in ``conanfile.py`` to enable/disable running tests with CMake:
+This variable is evaluated inside the build helper call to ``test()`` and will not run the tests if set to ``False``.
 
 .. code-block:: python
 
@@ -491,8 +491,7 @@ See example of build method in ``conanfile.py`` to enable/disable running tests
             cmake = CMake(self)
             cmake.configure()
             cmake.build()
-            if tools.get_env("CONAN_RUN_TESTS", True):
-                cmake.test()
+            cmake.test()
 
 .. _env_vars_conan_skip_vs_project_upgrade: