Automatic deploy (build number 22)

2.1/404.html

@@ -119,7 +119,7 @@ <h1>Page Not Found<a class="headerlink" href="#page-not-found" title="Link to th
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/Page Not Found.html

@@ -112,7 +112,7 @@ <h1>Page not found</h1>
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/_sources/reference/binary_model.rst.txt

@@ -14,6 +14,7 @@ Finally, the default binary compatibility model will be described, and how it ca
     :maxdepth: 1
 
     binary_model/package_id
+    binary_model/settings_and_options
     binary_model/dependencies
     binary_model/extending
     binary_model/custom_compatibility

2.1/_sources/reference/binary_model/package_id.rst.txt

@@ -1,3 +1,5 @@
+.. _reference_binary_model_package_id:
+
 How the ``package_id`` is computed
 ==================================
 

2.1/_sources/reference/binary_model/settings_and_options.rst.txt

@@ -0,0 +1,248 @@
+.. _reference_binary_model_settings_options:
+
+How settings and options of a recipe influence its package ID
+=============================================================
+
+In Conan, a package ID is a unique identifier for a package binary that takes into account all the factors that affect its binary compatibility.
+These factors include recipe options and settings as well as requirements or tool requirements.
+
+Let's see how settings and options affect the package ID and some examples where they should not.
+
+How settings influence the package ID
+-------------------------------------
+
+Settings are development project-wide variables, like the compiler, its version, or the OS itself.
+These variable values have to be defined, they should match the values of our development environment, and they cannot have a default value like options do.
+
+For example, let's define a recipe that generates packages that are only OS dependent:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class Pkg(ConanFile):
+        name = "pkg"
+        version = "1.0.0"
+        settings = "os"  # Only OS setting affects the package ID
+
+If we generate a package from this recipe for Linux we will get the following package ID:
+
+.. code-block:: bash
+   :emphasize-lines: 3, 12
+
+    $ conan create . --settings os=Linux
+    ...
+    pkg/1.0.0: Package '9a4eb3c8701508aa9458b1a73d0633783ecc2270' created
+
+    $ conan list pkg/1.0.0:*
+    Local Cache
+      pkg
+        pkg/1.0.0
+          revisions
+              476929a74c859bb5f646363a4900f7cf (2024-03-07 09:13:43 UTC)
+                packages
+                  9a4eb3c8701508aa9458b1a73d0633783ecc2270
+                    info
+                      settings
+                        os: Linux
+
+If we do the same thing with Windows, now the package ID will be diffent:
+
+.. code-block:: bash
+   :emphasize-lines: 3, 12, 16
+
+    $ conan create . --settings os=Windows
+    ...
+    pkg/1.0.0: Package 'ebec3dc6d7f6b907b3ada0c3d3cdc83613a2b715' created
+
+    $ conan list pkg/1.0.0:*
+    Local Cache
+      pkg
+        pkg/1.0.0
+          revisions
+              476929a74c859bb5f646363a4900f7cf (2024-03-07 09:13:43 UTC)
+                packages
+                  9a4eb3c8701508aa9458b1a73d0633783ecc2270
+                    info
+                      settings
+                        os: Linux
+                  ebec3dc6d7f6b907b3ada0c3d3cdc83613a2b715
+                    info
+                      settings
+                        os: Windows
+
+Whenever a value of the settings or subsettings changes, the package ID will be different to reflect that.
+
+The most common usage for settings is to model the different project-wide aspects that might influence the package ID.
+A recipe that does that will be:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class Pkg(ConanFile):
+        name = "pkg"
+        version = "1.0.0"
+        settings = "os", "arch", "compiler", "build_type"
+
+Now, compiling a package with different compiler versions will result into different package IDs:
+
+.. code-block:: bash
+   :emphasize-lines: 3, 7, 16, 27
+
+    $ conan create . --settings compiler.version=192
+    ...
+    pkg/1.0.0: Package '4f267380690f99b3ef385199826c268f63147457' created
+
+    $ conan create . --settings compiler.version=193
+    ...
+    pkg/1.0.0: Package 'c13a22a41ecd72caf9e556f68b406569547e0861' created
+
+    $ conan list pkg/1.0.0:*
+    Local Cache
+      pkg
+        pkg/1.0.0
+          revisions
+            f1f48830ecb04f3b328429b390fc5de8 (2024-03-07 09:21:07 UTC)
+              packages
+                4f267380690f99b3ef385199826c268f63147457
+                  info
+                    settings
+                      arch: x86_64
+                      build_type: Release
+                      compiler: msvc
+                      compiler.cppstd: 14
+                      compiler.runtime: dynamic
+                      compiler.runtime_type: Release
+                      compiler.version: 192
+                      os: Windows
+                c13a22a41ecd72caf9e556f68b406569547e0861
+                  info
+                    settings
+                      arch: x86_64
+                      build_type: Release
+                      compiler: msvc
+                      compiler.cppstd: 14
+                      compiler.runtime: dynamic
+                      compiler.runtime_type: Release
+                      compiler.version: 193
+                      os: Windows
+
+Removing settings for a package used as a tool_require
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+There could be cases when a setting should not influence the resulting package ID.
+An example of this could be when a recipe packages a tool that would be used to build other packages via ``tool_requires``
+
+In that case, the value of the compiler used is needed for the compilation of the tool but not that relevant for consumers, as we only want to execute the tool to build other projects.
+So we could eventually remove the influence of the compiler from the pacakge ID:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class CMake(ConanFile):
+        name = "cmake"
+        version = "1.0.0"
+        settings = "os", "arch", "compiler", "build_type"  # Only OS and architecture influence the resulting package
+
+        def build(self):
+            # self.settings.compiler value will be used here to compile cmake
+
+        def package_id(self):
+            # Remove compiler setting from package ID
+            del self.info.settings.compiler
+
+Why not removing the setting from the `settings` attribute? Because the compiler value is still needed in the `build()` method to perform the compilation of the executable.
+
+.. note::
+
+    In the case we are generating our own executables (our own apps, not a ``tool_require``), **removing the compiler setting from package ID is not recommended**, as we would always want to know
+    that the package was generated with a specific compiler.
+
+However, in case we are packaging a tool that does not even require a compiler input for building (a python script for example), we could also directly remove the settings attribute:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class MyPythonScripts(ConanFile):
+        name = "my-python-scripts"
+        version = "1.0.0"
+        # No settings this time
+
+Or, if the tool is platform specific we can just keep the OS and architecture information:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class MyScripts(ConanFile):
+        name = "my-scripts"
+        version = "1.0.0"
+        settings = "os", "arch"
+
+How options influence the package ID
+------------------------------------
+
+Options are used to specify characteristics that are particular to a single recipe, contrasting with settings that generally remain consistent across recipes within a project.
+They are usually a set of particular characteristics of a library executable or conan package may have.
+
+For example, a `shared` option is a very common option used in recipes that can produce shared libraries. However, it could not be a setting as not all recipes produce shared libraries.
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class Pkg(ConanFile):
+        name = "pkg"
+        version = "1.0.0"
+        options = {"shared": [True, False]}
+        default_options = {"shared": True}
+
+As in the previous case with settings, the different values of an option will influence the package ID and therefore, generate different packages depending on it.
+
+.. code-block:: bash
+   :emphasize-lines: 3, 7
+
+    $ conan create . --options shared=True
+    ...
+    pkg/1.0.0: Package '1744785cb24e3bdca70e27041dc5abd20476f947' created
+
+    $ conan create . --options shared=False
+    ...
+    pkg/1.0.0: Package '55c609fe8808aa5308134cb5989d23d3caffccf2' created
+
+In the same way, there might be "options" that are needed as input in a recipe to generate a package which shouldn't be taken into account in the package ID.
+An example of this could be an option to control something that during the build phase but that does not influence the package result, like the *verbosity* of a compilation.
+In that case, the recipe should remove the option in the :ref:`package_id() method <reference_conanfile_methods_package_id>`:
+
+However, the general advice is that **options should always affect the package ID**, and in case we would like to have an input to the recipe that should **not** affect it,
+it should be done via the :ref:`conf section <reference_config_files_profiles_conf>` of your profile. Then in the recipe we should just add:
+
+.. code-block:: python
+
+    from conan import ConanFile
+
+    class MyPkg(ConanFile):
+        name = "my-pkg"
+        version = "1.0.0"
+
+        def build(self):
+            verbosity = self.conf.get("user.my-pkg:verbosity")
+            self.output.info(f"Using verbosity level: {verbosity})
+            ...
+
+.. code-block:: text
+    :caption: *myprofile*
+
+    [conf]
+    user.my-pkg:verbosity=silent
+
+That way the package ID will be not affected, the recipe will be cleaner (without irrelevant options for package ID) and the input is easily managed via the profile's conf section.
+
+
+.. seealso::
+
+    - :ref:`reference_binary_model_package_id`
+    - :ref:`tutorial_creating_configure`

2.1/_sources/tutorial/consuming_packages/different_configurations.rst.txt

@@ -328,5 +328,5 @@ matched our specified configuration.
     - :ref:`creating_packages_configure_options_settings`
     - :ref:`Installing configurations with conan config install <reference_commands_conan_config_install>`
     - VS Multi-config
-    - Example about how settings and options influence the package id
+    - :ref:`How settings and options influence the package id <reference_binary_model_settings_options>`
     - :ref:`Using patterns for settings and options <reference_config_files_profile_patterns>`

2.1/changelog.html

@@ -826,7 +826,7 @@ <h2>2.0.0-beta1 (20-Jun-2022)<a class="headerlink" href="#beta1-20-jun-2022" tit
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops.html

@@ -139,7 +139,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/backup_sources/repositories/artifactory/creating_backup_sources_repo.html

@@ -166,7 +166,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/backup_sources/sources_backup.html

@@ -261,7 +261,7 @@ <h3>Upload the packages<a class="headerlink" href="#upload-the-packages" title="
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/conancenter/hosting_binaries.html

@@ -158,7 +158,7 @@ <h2>Updating from upstream<a class="headerlink" href="#updating-from-upstream" t
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/metadata.html

@@ -411,7 +411,7 @@ <h2>test_package as metadata<a class="headerlink" href="#test-package-as-metadat
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/save_restore.html

@@ -180,7 +180,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/using_conancenter.html

@@ -239,7 +239,7 @@ <h2>Control and customization<a class="headerlink" href="#control-and-customizat
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/versioning.html

@@ -137,7 +137,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/devops/versioning/resolve_prereleases.html

@@ -181,7 +181,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/examples.html

@@ -181,7 +181,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>
 

2.1/examples/commands.html

@@ -145,7 +145,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2016-2024, JFrog.
-      <span class="lastupdated">Last updated on Mar 12, 2024.
+      <span class="lastupdated">Last updated on Mar 18, 2024.
       </span></p>
   </div>