From dc86bac6801b88ea44abb525ecd87e4b2140d9c0 Mon Sep 17 00:00:00 2001 From: Francisco Ramirez de Anton Date: Mon, 6 Feb 2023 18:35:30 +0100 Subject: [PATCH] wip --- reference.rst | 1 - reference/commands/config.rst | 2 + .../client_certificates.rst | 26 +- .../configuration_files/default_profile.rst | 518 +++++++++++++++++- reference/configuration_files/global_conf.rst | 65 +-- reference/profiles.rst | 485 ---------------- 6 files changed, 554 insertions(+), 543 deletions(-) delete mode 100644 reference/profiles.rst diff --git a/reference.rst b/reference.rst index 2cbd6927c706..940fdca41be0 100644 --- a/reference.rst +++ b/reference.rst @@ -12,6 +12,5 @@ Reference reference/conanfile reference/conanfile_txt reference/tools - reference/profiles reference/configuration_files reference/extensions diff --git a/reference/commands/config.rst b/reference/commands/config.rst index fc952f3ae5bb..f83bdfa5f654 100644 --- a/reference/commands/config.rst +++ b/reference/commands/config.rst @@ -24,6 +24,8 @@ conan config home $ conan config home +.. _reference_commands_conan_config_install: + conan config install -------------------- diff --git a/reference/configuration_files/client_certificates.rst b/reference/configuration_files/client_certificates.rst index b90cd0d5773c..52455efa0323 100644 --- a/reference/configuration_files/client_certificates.rst +++ b/reference/configuration_files/client_certificates.rst @@ -1,14 +1,24 @@ .. _client_certificates: -client.crt / client.key -======================= +Client certificates +=================== -Conan support client TLS certificates. Create a *client.crt* with the client certificate in the -Conan home directory (default *~/[CONAN_HOME]/*) and a *client.key* with the private key. +Conan supports client TLS certificates. You can configure the path to your existing *Cacert* file and/or your client +certificate (and the key) using the following configuration variables: -You could also create only the ``client.crt`` file containing both the certificate and the private key -concatenated. +* ``core.net.http:cacert_path``: Path containing a custom Cacert file. +* ``core.net.http:client_cert``: Path or tuple of files containing a client cert (and key). -Alternatively, you can define a path to those files in whichever location using the `client_cert_path` and -`client_cert_key_path` configuration entries in the :ref:`conan_conf`. +For instance: + +.. code-block:: + :caption: **[CONAN_HOME]/global.conf** + + core.net.http:cacert_path=/path/to/cacert_file + core.net.http:client_cert=/path/to/client_certificate + + +.. seealso:: + + You can see more information about configurations in :ref:`global.conf section `. diff --git a/reference/configuration_files/default_profile.rst b/reference/configuration_files/default_profile.rst index 61668442ca40..a49dd3e5c44a 100644 --- a/reference/configuration_files/default_profile.rst +++ b/reference/configuration_files/default_profile.rst @@ -3,41 +3,525 @@ profiles/default ================ -This is the typical *~/[CONAN_HOME]/profiles/default* file: +The **default** profile file is located in the Conan user home *profiles* directory, e.g., *[CONAN_HOME]/profiles/default*. + +Introduction to profiles +------------------------ + +Conan profiles allows users to set a complete configuration set for **settings**, **options**, +**environment variables** (for build time and runtime context), **requirements** (and build requirements), and +**configuration variables** in a file. + +They have this structure: + +.. code-block:: text + + [settings] + setting=value + + [options] + MyLib:shared=True + + [buildenv] + env_var=value + + [build_requires] + tool1/0.1@user/channel + tool2/0.1@user/channel, tool3/0.1@user/channel + *: tool4/0.1@user/channel + + +Profiles can be created with ``detect`` option in :command:`conan profile`, and edited later. + +.. code-block:: bash + + $ conan profile detect --name myprofile + Found apple-clang 12.0 + Detected profile: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + + WARN: This profile is a guess of your environment, please check it. + WARN: The output of this command is not guaranteed to be stable and can change in future Conan versions + Saving detected profile to /Users/myuser/.conan2/profiles/myprofile + + +Profile files can be used with ``-pr``/``--profile`` option in many commands like :command:`conan install` or +:command:`conan create` commands. + +.. code-block:: bash + + $ conan create . demo/testing -pr=myprofile + +.. note:: + + Remember that ``-pr``/``--profile`` refers to ``host`` context by default. You can use ``-pr:h``/``-pr:b`` to use + host/build context respectively. + + +Profiles can be located in different folders. For instance, the default *[CONAN_HOME]/profiles* could be referenced by absolute or +relative path: + +.. code-block:: bash + + $ conan install . -pr /abs/path/to/profile # abs path + $ conan install . -pr ./relpath/to/profile # resolved to current dir + $ conan install . -pr ../relpath/to/profile # resolved to relative dir + $ conan install . -pr profile # resolved to [CONAN_HOME]/profiles/profile + +Listing existing profiles in the *profiles* folder can be done like this: + +.. code-block:: bash + + $ conan profile list + Profiles found in the cache: + default + myprofile1 + myprofile2 + ... + +You can also show profile's content: + +.. code-block:: bash + + $ conan profile show + Host profile: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + + Build profile: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + + +Use ``$PROFILE_DIR`` in your profile and it will be replaced with the absolute path to +the directory where the profile file is (this path will contain only forward slashes). +It is useful to declare relative folders: + +.. code-block:: text + + [buildenv] + PATH=(path)$PROFILE_DIR/dev_tools + +.. tip:: + + You can manage your profiles and share them using :ref:`reference_commands_conan_config_install`. + + +Package settings and buildenv vars +---------------------------------- + +Profiles also support **package settings** and **package build environment variables** definition, +so you can override some settings or environment variables for some specific package: + +.. code-block:: text + :caption: *[CONAN_HOME]/profiles/zlib_with_clang* + + [settings] + zlib:compiler=clang + zlib:compiler.version=3.5 + zlib:compiler.libcxx=libstdc++11 + compiler=gcc + compiler.version=4.9 + compiler.libcxx=libstdc++11 + + [buildenv] + zlib:CC=/usr/bin/clang + zlib:CXX=/usr/bin/clang++ + + +Your build tool will locate **clang** compiler only for the **zlib** package and **gcc** (default one) for the rest of your dependency tree. + +They accept patterns too, like ``-s *@myuser/*``, which means that packages that have the username "myuser" will use clang 3.5 as compiler, and gcc otherwise: + +.. code-block:: text + + [settings] + *@myuser/*:compiler=clang + *@myuser/*:compiler.version=3.5 + *@myuser/*:compiler.libcxx=libstdc++11 + compiler=gcc + compiler.version=4.9 + compiler.libcxx=libstdc++11 + +Also `&` can be specified as the package name. It will apply only to the consumer conanfile (.py or .txt). +This is a special case because the consumer conanfile might not declare a `name` so it would be impossible to reference it. + +.. code-block:: text + + [settings] + &:compiler=gcc + &:compiler.version=4.9 + &:compiler.libcxx=libstdc++11 + +.. note:: + + If you want to override existing system environment variables, you should use the ``key=value`` syntax. If you need to pre-pend to the + system environment variables you should use the syntax ``key=[value]`` or ``key=[value1, value2, ...]``. A typical example is the + ``PATH`` environment variable, when you want to add paths to the existing system PATH, not override it, you would use: + + .. code-block:: text + + [buildenv] + PATH=[/some/path/to/my/tool] + +.. _profiles_buildenv: + +[buildenv] +++++++++++ + +Available since: `1.35.0 `_ + +.. important:: + + The use of this ``[buildenv]`` section requires using the ``VirtualBuildEnv`` generator in your recipe, + or putting the configuration ``tools.env.virtualenv:auto_use=True`` in your profile. + + +This profile section is aimed to be the replacement of the legacy ``[buildenv]`` one. It's more powerful, and it is able to +apply some additional operators to each variable declared when you're composing profiles or even local variables: + +* ``+=`` == ``append``: appends values at the end of the existing value. +* ``=+`` == ``prepend``: puts values at the beginning of the existing value. +* ``=!`` == ``unset``: gets rid of any variable value. + +Another essential point to mention is the possibility of defining variables as `PATH` ones by simply putting ``(path)`` as +the prefix of the variable. It is useful to automatically get the append/prepend of the `PATH` in different systems +(Windows uses ``;`` as separation, and UNIX ``:``). + + +.. code-block:: text + :caption: *[CONAN_HOME]/profiles/myprofile* + + [buildenv] + # Define a variable "MyVar1" + MyVar1=My Value; other + + # Append another value to "MyVar1" + MyVar1+=MyValue12 + + # Define a PATH variable "MyPath1" + MyPath1=(path)/some/path11 + + # Prepend another PATH to "MyPath1" + MyPath1=+(path)/other path/path12 + + # Unset the variable "PATH" for all the packages matching the pattern "mypkg*" + mypkg*:PATH=! + + +Then, the result of applying this profile is: + +* ``MyVar1``: ``My Value; other MyValue12`` +* ``MyPath1``: + * Unix: ``/other path/path12:/some/path11`` + * Windows: ``/other path/path12;/some/path11`` +* ``mypkg*:PATH``: ``None`` + + +See more information about the new environments in the :ref:`conan_tools_env` reference. + + +.. _profiles_runenv: + +[runenv] +++++++++++ + +Available since: `1.53.0 `_ + +.. important:: + + The use of this ``[runenv]`` section requires using the ``VirtualRunEnv`` generator in your recipe. + +This profile section allows defining environment variables that will be injected to the +environment every time the ConanFile ``run(cmd, env="conanrun")`` method is invoked. You can use the same +operators explained for the :ref:`profiles_buildenv` section and also define `PATH` +variables. + +.. _profiles_tools_conf: + +Tools configurations +-------------------- + +.. important:: + + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. + +Tools configurations can also be used in profile files and *global.conf* one. Profile values will have priority over globally defined ones in *global.conf*, and can be defined as: + +.. code-block:: text + + [settings] + ... + + [conf] + tools.microsoft.msbuild:verbosity=Diagnostic + tools.microsoft.msbuild:max_cpu_count=2 + tools.microsoft.msbuild:vs_version = 16 + tools.build:jobs=10 + +.. seealso:: + + You can see more information about configurations in :ref:`global.conf section `. + + +Profile composition +------------------- + +You can specify multiple profiles in the command line. The applied configuration will be the composition +of all the profiles applied in the order they are specified. + +If, for example, you want to apply a :ref:`tool require`, like a ``cmake`` installer to your dependency tree, +it won't be very practical adding the `cmake` installer reference, e.g, ``cmake/3.16.3`` to all your profiles where you could +need to inject ``cmake`` as a tool require. + +You can specify both profiles instead: + +.. code-block:: text + :caption: *[CONAN_HOME]/profiles/cmake_316* + + [build_requires] + cmake/3.16.3 + +.. code-block:: bash + + $ conan install . --profile clang --profile cmake_316 + +Profile includes +---------------- + +You can include other profiles using the ``include()`` statement. The path can be relative to the current profile, absolute, or a profile +name from the default profile location in the local cache. + +The ``include()`` statement has to be at the top of the profile file: + +.. code-block:: text + :caption: *gcc_49* + + [settings] + compiler=gcc + compiler.version=4.9 + compiler.libcxx=libstdc++11 + +.. code-block:: text + :caption: *myprofile* + + include(gcc_49) + + [settings] + zlib:compiler=clang + zlib:compiler.version=3.5 + zlib:compiler.libcxx=libstdc++11 + + [buildenv] + zlib:CC=/usr/bin/clang + zlib:CXX=/usr/bin/clang++ + +Variable declaration +-------------------- + +In a profile you can declare variables that will be replaced automatically by Conan before the profile is applied. The variables have to be +declared at the top of the file, after the ``include()`` statements. + +.. code-block:: text + :caption: *myprofile* + + include(gcc_49) + CLANG=/usr/bin/clang + + [settings] + zlib:compiler=clang + zlib:compiler.version=3.5 + zlib:compiler.libcxx=libstdc++11 + + [buildenv] + zlib:CC=$CLANG/clang + zlib:CXX=$CLANG/clang++ + +The variables will be inherited too, so you can declare variables in a profile and then include the profile in a different one, all the +variables will be available: + +.. code-block:: text + :caption: *gcc_49* + + GCC_PATH=/my/custom/toolchain/path/ + + [settings] + compiler=gcc + compiler.version=4.9 + compiler.libcxx=libstdc++11 .. code-block:: text + :caption: *myprofile* + + include(gcc_49) [settings] - os=Macos - arch=x86_64 - compiler=apple-clang - compiler.version=8.1 - compiler.libcxx=libc++ - build_type=Release + zlib:compiler=clang + zlib:compiler.version=3.5 + zlib:compiler.libcxx=libstdc++11 + + [buildenv] + zlib:CC=$GCC_PATH/gcc + zlib:CXX=$GCC_PATH/g++ + + +.. _build_profiles_and_host_profiles: + +Build profiles and host profiles +-------------------------------- -The settings defaults are the setting values used whenever you issue a :command:`conan install` command over a *conanfile* in one of your -projects. The initial values for these default settings are auto-detected the first time you run a :command:`conan` command. +All the commands that take a profile as an argument, from Conan v1.24 are starting to accept two profiles with +command line arguments ``-pr:h``/``--profile:host`` and ``-pr:b``/``--profile:build``. If both profiles are +provided, Conan will build a graph with some packages associated with the ``host`` platform and some build +requirements associated to the ``build`` platform. There are two scenarios where this feature is +extremely useful: -You can override the default settings using the :command:`-s` parameter in :command:`conan install` and :command:`conan info` commands but -when you specify a profile, :command:`conan install -pr gcc48`, the default profile won't be applied, unless you specify it with an -``include()`` statement: +* :ref:`create_installer_packages` +* :ref:`cross_building` +The default build profile in Conan 1.X is not defined by default, and needs to be specified in command line. +However, it is also possible to define a default one in ``global.conf`` configuration file with: .. code-block:: text - :caption: my_clang_profile + :caption: *global.conf* + + core:default_build_profile=default + core:default_profile=linux_armv8 + +The default host profile can be defaulted as well using this configuration method. + + +Profile templates +----------------- + +.. important:: + + This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, + some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. + + +From Conan 1.38 it is possible to use **jinja2** template engine for profiles. This feature is +enabled by naming the profile file with the ``.jinja`` extension. When Conan loads a profile with +this extension, immediately parses and renders the template, which must result in a standard +text profile. + +Some of the capabilities of the profile templates are: + +- Using the platform information, like obtaining the current OS is possible because the + Python ``platform`` module is added to the render context.: + + .. code:: jinja + + [settings] + os = {{ {"Darwin": "Macos"}.get(platform.system(), platform.system()) }} + +- Reading environment variables can be done because the Python ``os`` module is added + to the render context.: + + .. code:: jinja + + [settings] + build_type = {{ os.getenv("MY_BUILD_TYPE") }} + +- Defining your own variables and using them in the profile: + + .. code:: jinja - include(default) + {% set a = "FreeBSD" %} + [settings] + os = {{ a }} + +- Joining and defining paths, including referencing the current profile directory. For + example, defining a toolchain which file is located besides the profile can be done. + Besides the ``os`` Python module, the variable ``profile_dir`` pointing to the current profile + folder is added to the context. + + .. code:: jinja + + [conf] + tools.cmake.cmaketoolchain:toolchain_file = {{ os.path.join(profile_dir, "toolchain.cmake") }} + +- Including or importing other files from ``profiles`` folder: + + .. code-block:: jinja + :caption: profile_vars.jinja + + {% set a = "Debug" %} + + .. code-block:: jinja + :caption: profile1.jinja + + {% import "profile_vars.jinja" as vars %} + [settings] + build_type = {{ vars.a }} + +- Any other feature supported by *jinja2* is possible: for loops, if-else, etc. This + would be useful to define custom per-package settings or options for multiple packages + in a large dependency graph. + +Examples +-------- + +If you are working with Linux and you usually work with **gcc** compiler, but you have installed **clang** compiler and want to install some +package for ``clang`` compiler, you could do: + +- Create a ``[CONAN_HOME]/profiles/clang`` file: + +.. code-block:: text [settings] compiler=clang compiler.version=3.5 compiler.libcxx=libstdc++11 - [conf] - tools.build:compiler_executables={'c': '/usr/bin/clang', 'cpp': '/usr/bin/clang++'} + [buildenv] + CC=/usr/bin/clang + CXX=/usr/bin/clang++ + +- Execute an install command passing the :command:`--profile` or :command:`-pr` parameter: + +.. code-block:: bash + + $ conan install . --profile clang + +Without profiles you would have needed to set CC and CXX variables in the environment to point to your clang compiler and use :command:`-s` +parameters to specify the settings: + +.. code-block:: bash + + $ export CC=/usr/bin/clang + $ export CXX=/usr/bin/clang++ + $ conan install -s compiler=clang -s compiler.version=3.5 -s compiler.libcxx=libstdc++11 + +A profile can also be used in :command:`conan create` and :command:`conan info`: + +.. code-block:: bash + $ conan create . demo/testing --profile clang .. seealso:: - Check the section :ref:`conan_profiles` to read more about this feature. + - Check the section :ref:`build_requires` to read more about its usage in a profile. + - Check :ref:`conan_profile` and :ref:`default_profile` for full reference. + - Related section: :ref:`cross_building`. diff --git a/reference/configuration_files/global_conf.rst b/reference/configuration_files/global_conf.rst index 62c24a11cf5a..fac2116bafed 100644 --- a/reference/configuration_files/global_conf.rst +++ b/reference/configuration_files/global_conf.rst @@ -3,38 +3,21 @@ global.conf =========== -The **global.conf** file is located in the Conan user home directory. +The **global.conf** file is located in the Conan user home directory, e.g., *[CONAN_HOME]/global.conf*. -Global configuration --------------------- - -- ``core:required_conan_version = expression`` allows defining a version expression like - ``>=1.30``. Conan will raise an error if its current version does not satisfy the - condition -- ``core.package_id:msvc_visual_incompatible`` allows opting-out the fallback from the new - ``msvc`` compiler to the ``Visual Studio`` compiler existing binaries -- ``core:default_profile`` defines the default host profile ('default' by default) -- ``core:default_build_profile`` defines the default build profile (None by default) - -Tools configurations --------------------- - -Tools and user configurations allows them to be defined both in the *global.conf* file and in profile files. Profile values will -have priority over globally defined ones in *global.conf*, and can be defined as: - -.. code-block:: text +Introduction to configuration +----------------------------- - [settings] - ... +*global.conf* is aimed to save some core/tools configuration variables that will be used by Conan. For instance: - [conf] - tools.microsoft.msbuild:verbosity=Diagnostic - tools.microsoft.msbuild:max_cpu_count=2 - tools.microsoft.msbuild:vs_version = 16 - tools.build:jobs=10 +* Package ID modes. +* General HTTP(python-requests) configuration. +* Number of retries when downloading/uploading recipes. +* Related tools configurations (used by toolchains, helpers, etc.) +* Others (required Conan version, CLI non-interactive, etc.) -To list all possible configurations available, run :command:`conan config list`. +To list all the possible configurations available, run :command:`conan config list`: .. code-block:: text @@ -125,7 +108,25 @@ To list all possible configurations available, run :command:`conan config list`. .. important:: - This list may be outdated. Please, run the command :command:`conan config list` to check the latest configurations. + Remember to run that command locally to actually see the latest list because this one may be outdated. + + +Tools configurations +-------------------- + +Tools and user configurations allows them to be defined both in the *global.conf* file and in profile files. Profile values will +have priority over globally defined ones in *global.conf*, and can be defined as: + +.. code-block:: text + + [settings] + ... + + [conf] + tools.microsoft.msbuild:verbosity=Diagnostic + tools.microsoft.msbuild:max_cpu_count=2 + tools.microsoft.msbuild:vs_version = 16 + tools.build:jobs=10 Configuration file template @@ -341,10 +342,10 @@ This example illustrates all of these methods: like the example above. -Configuration from tool_requires --------------------------------- +Configuration from build_requires +--------------------------------- -From Conan 1.37, it is possible to define configuration in packages that are ``tool_requires``. For example, assuming +From Conan 1.37, it is possible to define configuration in packages that are ``build_requires``. For example, assuming there is a package that bundles the AndroidNDK, it could define the location of such NDK to the ``tools.android:ndk_path`` configuration as: @@ -361,4 +362,4 @@ configuration as: self.conf_info.define("tools.android:ndk_path", os.path.join(self.package_folder, "ndk")) -Note that this only propagates from the immediate, direct ``tool_requires`` of a recipe. +Note that this only propagates from the immediate, direct ``build_requires`` of a recipe. diff --git a/reference/profiles.rst b/reference/profiles.rst deleted file mode 100644 index 3fbd704c6558..000000000000 --- a/reference/profiles.rst +++ /dev/null @@ -1,485 +0,0 @@ -.. _conan_profiles: - -Profiles -========= - -Profiles allows users to set a complete configuration set for **settings**, **options**, **environment variables**, and **build -requirements** in a file. They have this structure: - -.. code-block:: text - - [settings] - setting=value - - [options] - MyLib:shared=True - - [env] - # [env] is deprecated! Use [buildenv] instead - env_var=value - - [tool_requires] - tool1/0.1@user/channel - tool2/0.1@user/channel, tool3/0.1@user/channel - *: tool4/0.1@user/channel - -Profile can be created with ``new`` option in :command:`conan profile`. And then edit it later. - -.. code-block:: bash - - $ conan profile new mynewprofile --detect - -Profile files can be used with ``-pr``/``--profile`` option in many commands like :command:`conan install` or :command:`conan create` commands. - -.. code-block:: bash - - $ conan create . demo/testing -pr=myprofile - -Profiles can be located in different folders. For example, the default */.conan/profiles*, and be referenced by absolute or -relative path: - -.. code-block:: bash - - $ conan install . --profile /abs/path/to/profile # abs path - $ conan install . --profile ./relpath/to/profile # resolved to current dir - $ conan install . --profile ../relpath/to/profile # resolved to relative dir - $ conan install . --profile profile # resolved to user/.conan/profiles/profile - -Listing existing profiles in the *profiles* folder can be done like this: - -.. code-block:: bash - - $ conan profile list - default - myprofile1 - myprofile2 - ... - -You can also show profile's content: - -.. code-block:: bash - - $ conan profile show myprofile1 - Configuration for profile myprofile1: - - [settings] - os=Windows - arch=x86_64 - compiler=Visual Studio - compiler.version=15 - build_type=Release - [options] - [tool_requires] - [env] - -Use ``$PROFILE_DIR`` in your profile and it will be replaced with the absolute path to -the directory where the profile file is (this path will contain only forward slashes). -It is useful to declare relative folders: - -.. code-block:: text - - [env] - PATH=$PROFILE_DIR/dev_tools - -.. tip:: - - You can manage your profiles and share them using :ref:`conan_config_install`. - -Package settings and env vars ------------------------------ - -Profiles also support **package settings** and **package environment variables** definition, so you can override some settings or -environment variables for some specific package: - -.. code-block:: text - :caption: *.conan/profiles/zlib_with_clang* - - [settings] - zlib:compiler=clang - zlib:compiler.version=3.5 - zlib:compiler.libcxx=libstdc++11 - compiler=gcc - compiler.version=4.9 - compiler.libcxx=libstdc++11 - - [env] - zlib:CC=/usr/bin/clang - zlib:CXX=/usr/bin/clang++ - -Your build tool will locate **clang** compiler only for the **zlib** package and **gcc** (default one) for the rest of your dependency tree. - -They accept patterns too, like ``-s *@myuser/*``, which means that packages that have the username "myuser" will use clang 3.5 as compiler, and gcc otherwise: - -.. code-block:: text - - [settings] - *@myuser/*:compiler=clang - *@myuser/*:compiler.version=3.5 - *@myuser/*:compiler.libcxx=libstdc++11 - compiler=gcc - compiler.version=4.9 - compiler.libcxx=libstdc++11 - -Also `&` can be specified as the package name. It will apply only to the consumer conanfile (.py or .txt). -This is a special case because the consumer conanfile might not declare a `name` so it would be impossible to reference it. - -.. code-block:: text - - [settings] - &:compiler=gcc - &:compiler.version=4.9 - &:compiler.libcxx=libstdc++11 - -.. note:: - - If you want to override existing system environment variables, you should use the ``key=value`` syntax. If you need to pre-pend to the - system environment variables you should use the syntax ``key=[value]`` or ``key=[value1, value2, ...]``. A typical example is the - ``PATH`` environment variable, when you want to add paths to the existing system PATH, not override it, you would use: - - .. code-block:: text - - [env] - PATH=[/some/path/to/my/tool] - -.. _profiles_buildenv: - -[buildenv] -++++++++++ - -Available since: `1.35.0 `_ - -.. important:: - - The use of this ``[buildenv]`` section requires using the ``VirtualBuildEnv`` generator in your recipe, - or putting the configuration ``tools.env.virtualenv:auto_use=True`` in your profile. - - -This profile section is aimed to be the replacement of the legacy ``[env]`` one. It's more powerful, and it is able to -apply some additional operators to each variable declared when you're composing profiles or even local variables: - -* ``+=`` == ``append``: appends values at the end of the existing value. -* ``=+`` == ``prepend``: puts values at the beginning of the existing value. -* ``=!`` == ``unset``: gets rid of any variable value. - -Another essential point to mention is the possibility of defining variables as `PATH` ones by simply putting ``(path)`` as -the prefix of the variable. It is useful to automatically get the append/prepend of the `PATH` in different systems -(Windows uses ``;`` as separation, and UNIX ``:``). - - -.. code-block:: text - :caption: *.conan/profiles/myprofile* - - [buildenv] - # Define a variable "MyVar1" - MyVar1=My Value; other - - # Append another value to "MyVar1" - MyVar1+=MyValue12 - - # Define a PATH variable "MyPath1" - MyPath1=(path)/some/path11 - - # Prepend another PATH to "MyPath1" - MyPath1=+(path)/other path/path12 - - # Unset the variable "PATH" for all the packages matching the pattern "mypkg*" - mypkg*:PATH=! - - -Then, the result of applying this profile is: - -* ``MyVar1``: ``My Value; other MyValue12`` -* ``MyPath1``: - * Unix: ``/other path/path12:/some/path11`` - * Windows: ``/other path/path12;/some/path11`` -* ``mypkg*:PATH``: ``None`` - - -See more information about the new environments in the :ref:`conan_tools_env` reference. - - -.. _profiles_runenv: - -[runenv] -++++++++++ - -Available since: `1.53.0 `_ - -.. important:: - - The use of this ``[runenv]`` section requires using the ``VirtualRunEnv`` generator in your recipe. - -This profile section allows defining environment variables that will be injected to the -environment every time the ConanFile ``run(cmd, env="conanrun")`` method is invoked. You can use the same -operators explained for the :ref:`profiles_buildenv` section and also define `PATH` -variables. - -.. _profiles_tools_conf: - -Tools configurations --------------------- - -.. important:: - - This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, - some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. - -Tools configurations can also be used in profile files and *global.conf* one. Profile values will have priority over globally defined ones in *global.conf*, and can be defined as: - -.. code-block:: text - - [settings] - ... - - [conf] - tools.microsoft.msbuild:verbosity=Diagnostic - tools.microsoft.msbuild:max_cpu_count=2 - tools.microsoft.msbuild:vs_version = 16 - tools.build:jobs=10 - -.. seealso:: - - You can see more information about configurations in :ref:`global.conf section `. - - -Profile composition -------------------- - -You can specify multiple profiles in the command line. The applied configuration will be the composition -of all the profiles applied in the order they are specified. - -If, for example, you want to apply a :ref:`tool require`, like a ``cmake`` installer to your dependency tree, -it won't be very practical adding the `cmake` installer reference, e.g ``cmake/3.16.3`` to all your profiles where you could -need to inject ``cmake`` as a tool require. - -You can specify both profiles instead: - -.. code-block:: text - :caption: *.conan/profiles/cmake_316* - - [tool_requires] - cmake/3.16.3 - -.. code-block:: bash - - $ conan install . --profile clang --profile cmake_316 - -Profile includes ----------------- - -You can include other profiles using the ``include()`` statement. The path can be relative to the current profile, absolute, or a profile -name from the default profile location in the local cache. - -The ``include()`` statement has to be at the top of the profile file: - -.. code-block:: text - :caption: *gcc_49* - - [settings] - compiler=gcc - compiler.version=4.9 - compiler.libcxx=libstdc++11 - -.. code-block:: text - :caption: *myprofile* - - include(gcc_49) - - [settings] - zlib:compiler=clang - zlib:compiler.version=3.5 - zlib:compiler.libcxx=libstdc++11 - - [env] - zlib:CC=/usr/bin/clang - zlib:CXX=/usr/bin/clang++ - -Variable declaration --------------------- - -In a profile you can declare variables that will be replaced automatically by Conan before the profile is applied. The variables have to be -declared at the top of the file, after the ``include()`` statements. - -.. code-block:: text - :caption: *myprofile* - - include(gcc_49) - CLANG=/usr/bin/clang - - [settings] - zlib:compiler=clang - zlib:compiler.version=3.5 - zlib:compiler.libcxx=libstdc++11 - - [env] - zlib:CC=$CLANG/clang - zlib:CXX=$CLANG/clang++ - -The variables will be inherited too, so you can declare variables in a profile and then include the profile in a different one, all the -variables will be available: - -.. code-block:: text - :caption: *gcc_49* - - GCC_PATH=/my/custom/toolchain/path/ - - [settings] - compiler=gcc - compiler.version=4.9 - compiler.libcxx=libstdc++11 - -.. code-block:: text - :caption: *myprofile* - - include(gcc_49) - - [settings] - zlib:compiler=clang - zlib:compiler.version=3.5 - zlib:compiler.libcxx=libstdc++11 - - [env] - zlib:CC=$GCC_PATH/gcc - zlib:CXX=$GCC_PATH/g++ - - -.. _build_profiles_and_host_profiles: - -Build profiles and host profiles --------------------------------- - - -All the commands that take a profile as an argument, from Conan v1.24 are starting to accept two profiles with -command line arguments ``-pr:h``/``--profile:host`` and ``-pr:b``/``--profile:build``. If both profiles are -provided, Conan will build a graph with some packages associated with the ``host`` platform and some build -requirements associated to the ``build`` platform. There are two scenarios where this feature is -extremely useful: - -* :ref:`create_installer_packages` -* :ref:`cross_building` - -The default build profile in Conan 1.X is not defined by default, and needs to be specified in command line. -However, it is also possible to define a default one in ``global.conf`` configuration file with: - -.. code-block:: text - :caption: *global.conf* - - core:default_build_profile=default - core:default_profile=linux_armv8 - -The default host profile can be defaulted as well using this configuration method. - - -Profile templates ------------------ - -.. important:: - - This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases, - some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*. - - -From Conan 1.38 it is possible to use **jinja2** template engine for profiles. This feature is -enabled by naming the profile file with the ``.jinja`` extension. When Conan loads a profile with -this extension, immediately parses and renders the template, which must result in a standard -text profile. - -Some of the capabilities of the profile templates are: - -- Using the platform information, like obtaining the current OS is possible because the - Python ``platform`` module is added to the render context.: - - .. code:: jinja - - [settings] - os = {{ {"Darwin": "Macos"}.get(platform.system(), platform.system()) }} - -- Reading environment variables can be done because the Python ``os`` module is added - to the render context.: - - .. code:: jinja - - [settings] - build_type = {{ os.getenv("MY_BUILD_TYPE") }} - -- Defining your own variables and using them in the profile: - - .. code:: jinja - - {% set a = "FreeBSD" %} - [settings] - os = {{ a }} - -- Joining and defining paths, including referencing the current profile directory. For - example, defining a toolchain which file is located besides the profile can be done. - Besides the ``os`` Python module, the variable ``profile_dir`` pointing to the current profile - folder is added to the context. - - .. code:: jinja - - [conf] - tools.cmake.cmaketoolchain:toolchain_file = {{ os.path.join(profile_dir, "toolchain.cmake") }} - -- Including or importing other files from ``profiles`` folder: - - .. code-block:: jinja - :caption: profile_vars.jinja - - {% set a = "Debug" %} - - .. code-block:: jinja - :caption: profile1.jinja - - {% import "profile_vars.jinja" as vars %} - [settings] - build_type = {{ vars.a }} - -- Any other feature supported by *jinja2* is possible: for loops, if-else, etc. This - would be useful to define custom per-package settings or options for multiple packages - in a large dependency graph. - -Examples --------- - -If you are working with Linux and you usually work with **gcc** compiler, but you have installed **clang** compiler and want to install some -package for ``clang`` compiler, you could do: - -- Create a ``.conan/profiles/clang`` file: - -.. code-block:: text - - [settings] - compiler=clang - compiler.version=3.5 - compiler.libcxx=libstdc++11 - - [env] - CC=/usr/bin/clang - CXX=/usr/bin/clang++ - -- Execute an install command passing the :command:`--profile` or :command:`-pr` parameter: - -.. code-block:: bash - - $ conan install . --profile clang - -Without profiles you would have needed to set CC and CXX variables in the environment to point to your clang compiler and use :command:`-s` -parameters to specify the settings: - -.. code-block:: bash - - $ export CC=/usr/bin/clang - $ export CXX=/usr/bin/clang++ - $ conan install -s compiler=clang -s compiler.version=3.5 -s compiler.libcxx=libstdc++11 - -A profile can also be used in :command:`conan create` and :command:`conan info`: - -.. code-block:: bash - - $ conan create . demo/testing --profile clang - -.. seealso:: - - - Check the section :ref:`build_requires` to read more about its usage in a profile. - - Check :ref:`conan_profile` and :ref:`default_profile` for full reference. - - Related section: :ref:`cross_building`.