diff --git a/README.md b/README.md index 2f6d06e75ec6..c4783fe4db99 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ Documentation for Conan C/C++ package manager: https://conan.io -[![Build Status](https://travis-ci.org/conan-io/docs.svg?branch=master)](https://travis-ci.org/conan-io/docs) - How to build ============ diff --git a/reference/commands/install.rst b/reference/commands/install.rst index e83a16276e66..66dc4fd6abd2 100644 --- a/reference/commands/install.rst +++ b/reference/commands/install.rst @@ -145,9 +145,11 @@ It is possible to also invoke the package recipes ``deploy()`` method with the ` .. code-block:: bash # Execute deploy() method of every recipe that defines it - $ conan install --requires=pkg/0.1 --deployer-package=* + $ conan install --requires=pkg/0.1 --deployer-package="*" # Execute deploy() method only for "pkg" (any version) recipes - $ conan install --requires=pkg/0.1 --deployer-package=pkg/* + $ conan install --requires=pkg/0.1 --deployer-package="pkg/*" + # Execute deploy() method for all packages except the "zlib" (transitive dep) one + $ conan install --requires=pkg/0.1 --deployer-package="*" --deployer-package="~zlib/*" The ``--deployer-package`` argument is a pattern and accepts multiple values, all package references matching any of the defined patterns will execute its ``deploy()`` method. This includes negated patterns, where for example ``--deployer-package=~pkg/*`` will execute the ``deploy()`` method for all packages except for that of the ``pkg`` recipe. diff --git a/reference/conanfile/methods/requirements.rst b/reference/conanfile/methods/requirements.rst index 1f32a2b452c3..a9d47e399f6a 100644 --- a/reference/conanfile/methods/requirements.rst +++ b/reference/conanfile/methods/requirements.rst @@ -88,7 +88,8 @@ when we want to use different versions of the same package during the build. transitive_headers ~~~~~~~~~~~~~~~~~~ -If ``True`` the headers of the dependency will be visible downstream. +If ``True`` the headers of the dependency will be visible downstream. +Read more about this trait in the :ref:`tutorial for headers transitivity`. transitive_libs ~~~~~~~~~~~~~~~ diff --git a/reference/conanfile/methods/system_requirements.rst b/reference/conanfile/methods/system_requirements.rst index e778b535413a..58d83651332c 100644 --- a/reference/conanfile/methods/system_requirements.rst +++ b/reference/conanfile/methods/system_requirements.rst @@ -101,3 +101,17 @@ On the other hand, the ``report-installed`` mode will do a check if the package ] } } + + +Build time system requirements +------------------------------ + +In some scenarios, it might be possible that some system-requirements are only necessary exclusively at +build time. For those scenarios, there are 2 possibilities: + +- Add the logic that install the build-time system requirements in a different method, like the ``build()`` + method or the ``generate()`` method. +- Wrap the installation and logic for the build-time system requirement in its own package recipe, and use + that recipe as a ``tool_requires``. + +There are examples :ref:`for build-time system requirements in this section ` diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index 352c82828194..525ce31465c0 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -33,36 +33,6 @@ To list all the possible configurations available, run :command:`conan config li :command: conan config list -Description of configurations -+++++++++++++++++++++++++++++ - -core.cache:storage_path -^^^^^^^^^^^^^^^^^^^^^^^ - -Absolute path to a folder where the Conan packages and the database of the packages will be stored. -This folder will be the heaviest Conan storage folder, as it stores the binary packages downloaded or created. - -.. code-block:: text - :caption: *global.conf* - - core.cache:storage_path = C:\Users\danielm\my_conan_storage_folder - -**Default value:** ``/p`` - -core.download:download_cache -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Absolute path to a folder where the Conan packages will be stored *compressed*. -This is useful to avoid recurrent downloads of the same packages, especially in CI. - -.. code-block:: text - :caption: *global.conf* - - core.download:download_cache = C:\Users\danielm\my_download_cache - -**Default value:** Not defined. - - User/Tools configurations ------------------------- @@ -244,6 +214,65 @@ For instance: (And even then, properly scoping the conf to only the required recipes is a good idea) or if you are using it for development purposes +Proxies ++++++++ + +There are 3 ``confs`` that can define proxies information: + +.. code-block:: bash + + $ conan config list proxies + core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded + core.net.http:no_proxy_match: List of urls to skip from proxies configuration + core.net.http:proxies: Dictionary containing the proxy configuration + +The ``core.net.http:proxies`` dictionary is passed to the underlying ``python-requests`` library, to the "proxies" argument +as described in the `python-requests documentation `_ + +The ``core.net:no_proxy_match`` is a list of URL patterns, like: + +.. code-block:: ini + + core.net.http:no_proxy_match = ["http://someurl.com/*"] + + +for URLs to be excluded from the ``proxies`` configuration. That means that all URLs that are referenced that matches any +of those patterns will not receive the ``proxies`` definition. Note the ``*`` in the pattern is necessary for the match. + +If ``core.net.http:clean_system_proxy`` is ``True``, then the environment variables ``"http_proxy", "https_proxy", "ftp_proxy", "all_proxy", "no_proxy"``, +will be temporary removed from the environment, so they are not taken into account when resolving proxies. + + + +Storage configurations +---------------------- + +core.cache:storage_path ++++++++++++++++++++++++ + +Absolute path to a folder where the Conan packages and the database of the packages will be stored. +This folder will be the heaviest Conan storage folder, as it stores the binary packages downloaded or created. + +.. code-block:: text + :caption: *global.conf* + + core.cache:storage_path = C:\Users\danielm\my_conan_storage_folder + +**Default value:** ``/p`` + +core.download:download_cache +++++++++++++++++++++++++++++ + +Absolute path to a folder where the Conan packages will be stored *compressed*. +This is useful to avoid recurrent downloads of the same packages, especially in CI. + +.. code-block:: text + :caption: *global.conf* + + core.download:download_cache = C:\Users\danielm\my_download_cache + +**Default value:** Not defined. + UX confs -------- diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst index 5cfe2c998599..5015703fc0ce 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -638,6 +638,20 @@ dependencies can be found. For this case, it should be possible to do something For more information about these blocks, please have a look at the source code. +Finding dependencies paths +-------------------------- + +The generated ``conan_toolchain.cmake`` contains information in its ``find_paths`` block for variables such as +``CMAKE_PROGRAM_PATH``, ``CMAKE_LIBRARY_PATH``, ``CMAKE_INCLUDE_PATH`` and others, that allow CMake to run +``find_program()``, ``find_file()`` and other special "finder" routines that find artifacts without a explicit +package and targets definition via the overall recommended ``find_package()``. + +With the new incubating ``CMakeConfigDeps``, the ``conan_toolchain.cmake`` block ``find_paths`` no longer +defines the information itself, but it just loads a new file generated by the ``CMakeConfigDeps`` generator, the +``conan_cmakedeps_paths.cmake`` file. This way, the responsibility for creating information about dependencies is +the ``CMakeConfigDeps`` generator, and that new file can be used in some scenarios in which passing a toolchain +is not possible. + Cross building -------------- diff --git a/reference/tools/env/virtualbuildenv.rst b/reference/tools/env/virtualbuildenv.rst index 78faad2284c2..28314f8e108a 100644 --- a/reference/tools/env/virtualbuildenv.rst +++ b/reference/tools/env/virtualbuildenv.rst @@ -42,6 +42,30 @@ And it can also be fully instantiated in the conanfile ``generate()`` method: ms.generate() +Note that instantiating the ``VirtualBuildEnv()`` generator without later calling the ``generate()`` method, +which is intended only for the ``generate()`` recipe method, will inhibit the creation of environment files. + +So something like: + +.. code-block:: python + + ms = VirtualBuildEnv(self) + my_env_var = ms.vars().get("MY_ENV_VAR") + # does not create conanbuildenv.sh|.bat files + + +will stop creating the ``conanbuild.sh|.bat`` and ``conanbuildenv.sh|.bat`` files that are created by default, +even when ``VirtualBuildEnv`` is not instantiated. + +In order to keep creating those files, the ``auto_generate=True`` argument can be passed to the constructor, as: + +.. code-block:: python + + ms = VirtualBuildEnv(self, auto_generate=True) + my_env_var = ms.vars().get("MY_ENV_VAR") + # does create conanbuildenv.sh|.bat files + + Generated files --------------- diff --git a/tutorial/creating_packages/add_dependencies_to_packages.rst b/tutorial/creating_packages/add_dependencies_to_packages.rst index 6cd8e3e1ca8c..c4012ce5ee44 100644 --- a/tutorial/creating_packages/add_dependencies_to_packages.rst +++ b/tutorial/creating_packages/add_dependencies_to_packages.rst @@ -117,6 +117,43 @@ colour now: hello/1.0: __clang_minor__ 1 hello/1.0: __apple_build_version__ 13160021 +.. _tutorial_create_packages_headers_transitivity: + +Headers transitivity +-------------------- + +By default, Conan assumes that the required dependency headers are an implementation detail of the current package, +to promote good software engineering practices like low coupling and encapsulation. In the example above, ``fmt`` +is purely an implementation detail in the ``hello/1.0`` package. Consumers of ``hello/1.0`` will not know anything +about ``fmt``, or has access to its headers, if a consumer of ``hello/1.0`` would try to add a ``#include ``, +it will fail, not being able to find that headers. + +But if the public headers of the ``hello/1.0`` package have the ``#include`` to ``fmt`` headers, that means that such +headers must be propagated down to allow consumers of ``hello/1.0`` to be compiled successfully. As this is not the +default expected behavior, recipes must declare it as: + +.. code-block:: python + + class helloRecipe(ConanFile): + name = "hello" + version = "1.0" + + def requirements(self): + self.requires("fmt/8.1.1", transitive_headers=True) + + +That will propagate the necessary compilation flags and headers ``includedirs`` to the consumers of ``hello/1.0``. + +.. note:: + + **Best practices** + + If a consumer of ``hello/1.0`` had a direct inclusion to ``fmt`` headers such as ``#include ``, then, + such a consumer should declare its own ``self.requires("fmt/8.1.1")`` requirement, as that is a direct requirement. + In other words, even if the dependency to ``hello/1.0`` was removed from that consumer, it would still depend on ``fmt``, + and consequently it cannot abouse the transitivity of the ``fmt`` headers from ``hello``, but declare them explicitly. + + .. seealso:: - :ref:`Reference for requirements() method `. diff --git a/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst b/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst index 6c6ea3917bec..b421a42fcf21 100644 --- a/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst +++ b/tutorial/creating_packages/other_types_of_packages/header_only_packages.rst @@ -39,6 +39,8 @@ This is a basic recipe for a header-only recipe: exports_sources = "include/*" # We can avoid copying the sources to the build folder in the cache no_copy_source = True + # Important, define the package_type + package_type = "header-library" def package(self): # This will also copy the "include" folder @@ -160,6 +162,8 @@ We have the same header-only library that sums two numbers, but now we have this exports_sources = "include/*", "test/*" no_copy_source = True generators = "CMakeToolchain", "CMakeDeps" + # Important, define the package_type + package_type = "header-library" def requirements(self): self.test_requires("gtest/1.11.0")