diff --git a/2.1/.buildinfo b/2.1/.buildinfo new file mode 100644 index 000000000000..ffec3688d8e3 --- /dev/null +++ b/2.1/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 856735d6c0de38aa845598484b969ea8 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/2.1/404.html b/2.1/404.html new file mode 100644 index 000000000000..81b28f6d3baa --- /dev/null +++ b/2.1/404.html @@ -0,0 +1,556 @@ + + + + + + + Page Not Found — conan 2.1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+ +
+ +
+
+
+
+ +
+

Page Not Found

+

Unfortunately, the page you are looking for does not exist or was removed.

+

You can look into our reference tree, or use the search bar for a desired topic.

+

If you think this is an error and the page should be there, please open an issue .

+_images/frogarian.png +
+ + +
+
+ +
+
+
+
+ +
+ + Version: 2.1 + + +
+
+
Versions
+ + +
2.1
+ + + +
2.0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
2
+ + +
+ + + + + + +
1
+ + + +
1.63
+ + + +
1.62
+ + + +
1.61
+ + + +
1.60
+ + + +
1.59
+ + + +
1.58
+ + + +
1.57
+ + + +
1.56
+ + + +
1.55
+ + + +
1.54
+ + + +
1.53
+ + + +
1.52
+ + + +
1.51
+ + + +
1.50
+ + + +
1.49
+ + + +
1.48
+ + + +
1.47
+ + + +
1.46
+ + + +
1.45
+ + + +
1.44
+ + + +
1.43
+ + + +
1.42
+ + + +
1.41
+ + + +
1.40
+ + + +
1.39
+ + + +
1.38
+ + + +
1.37
+ + + +
1.36
+ + + +
1.35
+ + + +
1.34
+ + + +
1.33
+ + + +
1.32
+ + + +
1.31
+ + + +
1.30
+ + + +
1.29
+ + + +
1.28
+ + + +
1.27
+ + + +
1.26
+ + + +
1.25
+ + + +
1.24
+ + + +
1.23
+ + + +
1.22
+ + + +
1.21
+ + + +
1.20
+ + + +
1.19
+ + + +
1.18
+ + + +
1.17
+ + + +
1.16
+ + + +
1.15
+ + + +
1.14
+ + + +
1.13
+ + + +
1.12
+ + + +
1.11
+ + + +
1.10
+ + + +
1.9
+ + + +
1.8
+ + + +
1.7
+ + + +
1.6
+ + + +
1.5
+ + + +
1.4
+ + + +
1.3
+ + + + +
+
+
Downloads
+ +
PDF
+ +
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/2.1/Page Not Found.html b/2.1/Page Not Found.html new file mode 100644 index 000000000000..3693ac69d986 --- /dev/null +++ b/2.1/Page Not Found.html @@ -0,0 +1,549 @@ + + + + + + Page not found — conan 2.1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+ +
+
    +
    • +
  • Page not found
    • +
  • +
    • +
+
+
+
+
+ +

Page not found

+ +Unfortunately we couldn't find the content you were looking for. + +
+
+ +
+
+
+
+ +
+ + Version: 2.1 + + +
+
+
Versions
+ + +
2.1
+ + + +
2.0
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
2
+ + +
+ + + + + + +
1
+ + + +
1.63
+ + + +
1.62
+ + + +
1.61
+ + + +
1.60
+ + + +
1.59
+ + + +
1.58
+ + + +
1.57
+ + + +
1.56
+ + + +
1.55
+ + + +
1.54
+ + + +
1.53
+ + + +
1.52
+ + + +
1.51
+ + + +
1.50
+ + + +
1.49
+ + + +
1.48
+ + + +
1.47
+ + + +
1.46
+ + + +
1.45
+ + + +
1.44
+ + + +
1.43
+ + + +
1.42
+ + + +
1.41
+ + + +
1.40
+ + + +
1.39
+ + + +
1.38
+ + + +
1.37
+ + + +
1.36
+ + + +
1.35
+ + + +
1.34
+ + + +
1.33
+ + + +
1.32
+ + + +
1.31
+ + + +
1.30
+ + + +
1.29
+ + + +
1.28
+ + + +
1.27
+ + + +
1.26
+ + + +
1.25
+ + + +
1.24
+ + + +
1.23
+ + + +
1.22
+ + + +
1.21
+ + + +
1.20
+ + + +
1.19
+ + + +
1.18
+ + + +
1.17
+ + + +
1.16
+ + + +
1.15
+ + + +
1.14
+ + + +
1.13
+ + + +
1.12
+ + + +
1.11
+ + + +
1.10
+ + + +
1.9
+ + + +
1.8
+ + + +
1.7
+ + + +
1.6
+ + + +
1.5
+ + + +
1.4
+ + + +
1.3
+ + + + +
+
+
Downloads
+ +
PDF
+ +
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/2.1/_downloads/2f1200745e077930a933aaa8ace47f8e/conan2-cheatsheet-v5.pdf b/2.1/_downloads/2f1200745e077930a933aaa8ace47f8e/conan2-cheatsheet-v5.pdf new file mode 100644 index 000000000000..2eee97c2ae80 Binary files /dev/null and b/2.1/_downloads/2f1200745e077930a933aaa8ace47f8e/conan2-cheatsheet-v5.pdf differ diff --git a/2.1/_downloads/eb7044b00e16116702e1d0dd5036c165/conan2-cheatsheet-v5.png b/2.1/_downloads/eb7044b00e16116702e1d0dd5036c165/conan2-cheatsheet-v5.png new file mode 100644 index 000000000000..f5b879cf454e Binary files /dev/null and b/2.1/_downloads/eb7044b00e16116702e1d0dd5036c165/conan2-cheatsheet-v5.png differ diff --git a/2.1/_images/artifactory_local_repository.png b/2.1/_images/artifactory_local_repository.png new file mode 100644 index 000000000000..72469ca0dd3d Binary files /dev/null and b/2.1/_images/artifactory_local_repository.png differ diff --git a/2.1/_images/clion-configuration-1.png b/2.1/_images/clion-configuration-1.png new file mode 100644 index 000000000000..b7e8a5a9a216 Binary files /dev/null and b/2.1/_images/clion-configuration-1.png differ diff --git a/2.1/_images/clion-configuration-2.png b/2.1/_images/clion-configuration-2.png new file mode 100644 index 000000000000..3390ca60c814 Binary files /dev/null and b/2.1/_images/clion-configuration-2.png differ diff --git a/2.1/_images/clion-inspect.png b/2.1/_images/clion-inspect.png new file mode 100644 index 000000000000..85a50c635d3b Binary files /dev/null and b/2.1/_images/clion-inspect.png differ diff --git a/2.1/_images/clion-install-plugin.png b/2.1/_images/clion-install-plugin.png new file mode 100644 index 000000000000..98ec4f0023db Binary files /dev/null and b/2.1/_images/clion-install-plugin.png differ diff --git a/2.1/_images/clion-use-libcurl.png b/2.1/_images/clion-use-libcurl.png new file mode 100644 index 000000000000..8919005c4fff Binary files /dev/null and b/2.1/_images/clion-use-libcurl.png differ diff --git a/2.1/_images/conan-android-logo.png b/2.1/_images/conan-android-logo.png new file mode 100644 index 000000000000..ef3edacca106 Binary files /dev/null and b/2.1/_images/conan-android-logo.png differ diff --git a/2.1/_images/conan-autotools-logo.png b/2.1/_images/conan-autotools-logo.png new file mode 100644 index 000000000000..8f888511b373 Binary files /dev/null and b/2.1/_images/conan-autotools-logo.png differ diff --git a/2.1/_images/conan-bazel-logo.png b/2.1/_images/conan-bazel-logo.png new file mode 100644 index 000000000000..4c331b2cdfaa Binary files /dev/null and b/2.1/_images/conan-bazel-logo.png differ diff --git a/2.1/_images/conan-binary_mgmt.png b/2.1/_images/conan-binary_mgmt.png new file mode 100644 index 000000000000..3648d3bfba39 Binary files /dev/null and b/2.1/_images/conan-binary_mgmt.png differ diff --git a/2.1/_images/conan-cmake-logo.png b/2.1/_images/conan-cmake-logo.png new file mode 100644 index 000000000000..ad68b732b125 Binary files /dev/null and b/2.1/_images/conan-cmake-logo.png differ diff --git a/2.1/_images/conan-icon-clion.png b/2.1/_images/conan-icon-clion.png new file mode 100644 index 000000000000..d6db975942e8 Binary files /dev/null and b/2.1/_images/conan-icon-clion.png differ diff --git a/2.1/_images/conan-jfrog-logo.png b/2.1/_images/conan-jfrog-logo.png new file mode 100644 index 000000000000..91783663e407 Binary files /dev/null and b/2.1/_images/conan-jfrog-logo.png differ diff --git a/2.1/_images/conan-list-html.png b/2.1/_images/conan-list-html.png new file mode 100644 index 000000000000..d64498035202 Binary files /dev/null and b/2.1/_images/conan-list-html.png differ diff --git a/2.1/_images/conan-meson-logo.png b/2.1/_images/conan-meson-logo.png new file mode 100644 index 000000000000..79e3b63b7b6c Binary files /dev/null and b/2.1/_images/conan-meson-logo.png differ diff --git a/2.1/_images/conan-package_id.png b/2.1/_images/conan-package_id.png new file mode 100644 index 000000000000..4de8bbdc3bdb Binary files /dev/null and b/2.1/_images/conan-package_id.png differ diff --git a/2.1/_images/conan-systems.png b/2.1/_images/conan-systems.png new file mode 100644 index 000000000000..8550a749f980 Binary files /dev/null and b/2.1/_images/conan-systems.png differ diff --git a/2.1/_images/conan-visual_studio-logo.png b/2.1/_images/conan-visual_studio-logo.png new file mode 100644 index 000000000000..242fc5a86966 Binary files /dev/null and b/2.1/_images/conan-visual_studio-logo.png differ diff --git a/2.1/_images/conan-xcode-logo.jpg b/2.1/_images/conan-xcode-logo.jpg new file mode 100644 index 000000000000..e9fe8f490856 Binary files /dev/null and b/2.1/_images/conan-xcode-logo.jpg differ diff --git a/2.1/_images/conan2-cheatsheet-v5.png b/2.1/_images/conan2-cheatsheet-v5.png new file mode 100644 index 000000000000..f5b879cf454e Binary files /dev/null and b/2.1/_images/conan2-cheatsheet-v5.png differ diff --git a/2.1/_images/conan_package_id.png b/2.1/_images/conan_package_id.png new file mode 100644 index 000000000000..9f1c7790d61a Binary files /dev/null and b/2.1/_images/conan_package_id.png differ diff --git a/2.1/_images/conan_package_id_full.png b/2.1/_images/conan_package_id_full.png new file mode 100644 index 000000000000..c3e80a0f43ce Binary files /dev/null and b/2.1/_images/conan_package_id_full.png differ diff --git a/2.1/_images/create_reference_token.png b/2.1/_images/create_reference_token.png new file mode 100644 index 000000000000..a41212f93987 Binary files /dev/null and b/2.1/_images/create_reference_token.png differ diff --git a/2.1/_images/frogarian.png b/2.1/_images/frogarian.png new file mode 100644 index 000000000000..4e62d700d1f0 Binary files /dev/null and b/2.1/_images/frogarian.png differ diff --git a/2.1/_images/graphviz-1029d6e0291c426aa04f9d8d3aa7a2a2d2896279.svg b/2.1/_images/graphviz-1029d6e0291c426aa04f9d8d3aa7a2a2d2896279.svg new file mode 100644 index 000000000000..8d9d93079d32 --- /dev/null +++ b/2.1/_images/graphviz-1029d6e0291c426aa04f9d8d3aa7a2a2d2896279.svg @@ -0,0 +1,43 @@ + + + + + + +%3 + + + +cli + +cli + + + +binutils/2.38 + +binutils/2.38 + + + +cli->binutils/2.38 + + + + + +zlib/1.2.13 + +zlib/1.2.13 + + + +binutils/2.38->zlib/1.2.13 + + + + + diff --git a/2.1/_images/graphviz-115f4ec9aab1d3344a1295f607eedfc41f6983f3.svg b/2.1/_images/graphviz-115f4ec9aab1d3344a1295f607eedfc41f6983f3.svg new file mode 100644 index 000000000000..6a37e65c3d12 --- /dev/null +++ b/2.1/_images/graphviz-115f4ec9aab1d3344a1295f607eedfc41f6983f3.svg @@ -0,0 +1,63 @@ + + + + + + +G + + + +app + +app + + + +libpng/1.6.40 + +libpng/1.6.40 + + + +app->libpng/1.6.40 + + + + + +libmysqlclient/8.1.0 + +libmysqlclient/8.1.0 + + + +app->libmysqlclient/8.1.0 + + + + + +zlib/1.2.13 + +zlib/1.2.13 + + + +libpng/1.6.40->zlib/1.2.13 + + +[>1.2 <2] + + + +libmysqlclient/8.1.0->zlib/1.2.13 + + +[>1.2 <2] + + + diff --git a/2.1/_images/graphviz-1e0749d0f2f51c081234bb0ceeee207bc3358b96.svg b/2.1/_images/graphviz-1e0749d0f2f51c081234bb0ceeee207bc3358b96.svg new file mode 100644 index 000000000000..9de0636765f6 --- /dev/null +++ b/2.1/_images/graphviz-1e0749d0f2f51c081234bb0ceeee207bc3358b96.svg @@ -0,0 +1,80 @@ + + + + + + +conflict + + + +game/1.0 + +game/1.0 + + + +engine/1.0 + +engine/1.0 + + + +game/1.0->engine/1.0 + + + + + +intro/1.0 + +intro/1.0 + + + +game/1.0->intro/1.0 + + + + + +matrix/1.2 + +matrix/1.2 + + + +game/1.0->matrix/1.2 + + + + + +matrix/1.0 + +matrix/1.0 + + + +engine/1.0->matrix/1.0 + + + + + +matrix/1.1 + +matrix/1.1 + + + +intro/1.0->matrix/1.1 + + + + + + diff --git a/2.1/_images/graphviz-25640955a58208c4a8abb8821375a14f47c5122f.svg b/2.1/_images/graphviz-25640955a58208c4a8abb8821375a14f47c5122f.svg new file mode 100644 index 000000000000..dfccc2256def --- /dev/null +++ b/2.1/_images/graphviz-25640955a58208c4a8abb8821375a14f47c5122f.svg @@ -0,0 +1,67 @@ + + + + + + +conflict + + + +game/1.0 + +game/1.0 + + + +engine/1.0 + +engine/1.0 + + + +game/1.0->engine/1.0 + + + + + +intro/1.0 + +intro/1.0 + + + +game/1.0->intro/1.0 + + + + + +matrix/1.0 + +matrix/1.0 + + + +engine/1.0->matrix/1.0 + + + + + +matrix/1.1 + +matrix/1.1 + + + +intro/1.0->matrix/1.1 + + + + + diff --git a/2.1/_images/graphviz-317dc6a5b8993cd90a4082a76c6abfa66e38b398.svg b/2.1/_images/graphviz-317dc6a5b8993cd90a4082a76c6abfa66e38b398.svg new file mode 100644 index 000000000000..7ea173919f11 --- /dev/null +++ b/2.1/_images/graphviz-317dc6a5b8993cd90a4082a76c6abfa66e38b398.svg @@ -0,0 +1,81 @@ + + + + + + +conflict + + + +game/1.0 + +game/1.0 + + + +engine/1.0 + +engine/1.0 + + + +game/1.0->engine/1.0 + + + + + +matrix/1.2 + +matrix/1.2 + + + +game/1.0->matrix/1.2 + + + + + +intro/1.0 + +intro/1.0 + + + +game/1.0->intro/1.0 + + + + + +engine/1.0->matrix/1.2 + + + + + +matrix/1.0 + +matrix/1.0 + + + + +intro/1.0->matrix/1.2 + + + + + +matrix/1.1 + +matrix/1.1 + + + + diff --git a/2.1/_images/graphviz-81c63434939b8fa86a10d38ca3edc2fece907a0e.svg b/2.1/_images/graphviz-81c63434939b8fa86a10d38ca3edc2fece907a0e.svg new file mode 100644 index 000000000000..6da50a598ac7 --- /dev/null +++ b/2.1/_images/graphviz-81c63434939b8fa86a10d38ca3edc2fece907a0e.svg @@ -0,0 +1,68 @@ + + + + + + +conflict + + + +game/1.0 + +game/1.0 + + + +engine/1.0 + +engine/1.0 + + + +game/1.0->engine/1.0 + + + + + +intro/1.0 + +intro/1.0 + + + +game/1.0->intro/1.0 + + + + + +matrix/1.1 + +matrix/1.1 + + + +engine/1.0->matrix/1.1 + + + + + +matrix/1.0 + +matrix/1.0 + + + + +intro/1.0->matrix/1.1 + + + + + diff --git a/2.1/_images/graphviz-8af47a14c61e2c80a08970d1d53665718f3e52a4.svg b/2.1/_images/graphviz-8af47a14c61e2c80a08970d1d53665718f3e52a4.svg new file mode 100644 index 000000000000..d45e210209bf --- /dev/null +++ b/2.1/_images/graphviz-8af47a14c61e2c80a08970d1d53665718f3e52a4.svg @@ -0,0 +1,44 @@ + + + + + + +lockfiles + + + +engine/1.0 + +engine/1.0 + + + +matrix/1.0 + +matrix/1.0 + + + +engine/1.0->matrix/1.0 + + + + + +sound32/1.0 + +sound32/1.0 + + + +engine/1.0->sound32/1.0 + + +if arch==x86 + + + diff --git a/2.1/_images/graphviz-b99e8bbb2dffefe30c303cef653992b1f008c154.svg b/2.1/_images/graphviz-b99e8bbb2dffefe30c303cef653992b1f008c154.svg new file mode 100644 index 000000000000..d51b564147c5 --- /dev/null +++ b/2.1/_images/graphviz-b99e8bbb2dffefe30c303cef653992b1f008c154.svg @@ -0,0 +1,49 @@ + + + + + + +components + + + +algorithms + +algorithms + + + +ai + +ai + + + +algorithms->ai + + + + + +rendering + +rendering + + + +algorithms->rendering + + + + + +network + +network + + + diff --git a/2.1/_images/independent_dependencies_deploy.png b/2.1/_images/independent_dependencies_deploy.png new file mode 100644 index 000000000000..9576001c34f8 Binary files /dev/null and b/2.1/_images/independent_dependencies_deploy.png differ diff --git a/2.1/_images/packages_from_cache.png b/2.1/_images/packages_from_cache.png new file mode 100644 index 000000000000..79a1a6be9167 Binary files /dev/null and b/2.1/_images/packages_from_cache.png differ diff --git a/2.1/_images/permissions_add_backup_access.png b/2.1/_images/permissions_add_backup_access.png new file mode 100644 index 000000000000..d86d9fcc41d1 Binary files /dev/null and b/2.1/_images/permissions_add_backup_access.png differ diff --git a/2.1/_images/zlib_1_2_11.png b/2.1/_images/zlib_1_2_11.png new file mode 100644 index 000000000000..265a77d43e9f Binary files /dev/null and b/2.1/_images/zlib_1_2_11.png differ diff --git a/2.1/_images/zlib_1_2_12.jpg b/2.1/_images/zlib_1_2_12.jpg new file mode 100644 index 000000000000..07addfd1d4b0 Binary files /dev/null and b/2.1/_images/zlib_1_2_12.jpg differ diff --git a/2.1/_sources/404.rst.txt b/2.1/_sources/404.rst.txt new file mode 100644 index 000000000000..d003c9fb2bff --- /dev/null +++ b/2.1/_sources/404.rst.txt @@ -0,0 +1,14 @@ +:orphan: + +Page Not Found +============== + +Unfortunately, the page you are looking for does not exist or was removed. + +You can look into our reference tree, or use the search bar for a desired topic. + +If you think this is an error and the page should be there, please open an `issue `_ . + +.. image:: images/frogarian.png + :width: 240 px + :align: center diff --git a/2.1/_sources/changelog.rst.txt b/2.1/_sources/changelog.rst.txt new file mode 100644 index 000000000000..99674414e864 --- /dev/null +++ b/2.1/_sources/changelog.rst.txt @@ -0,0 +1,687 @@ +Changelog +========= + +For a more detailed description of the major changes that Conan 2.0 brings, compared with Conan 1.X, please read :ref:`whatsnew` + +2.1.0 (15-Feb-2024) +------------------- + +- Feature: Implement multi-config ``tools.build:xxxx`` flags in ``CMakeToolchain``. `#15654 `_ +- Feature: Add ability to pass patterns to `--update` flag. `#15652 `_ . Docs `here `__ +- Feature: Add `--format=json` formatter to :command:`conan build`. `#15651 `_ +- Feature: Added `tools.build.cross_building:cross_build` to decide whether cross-building or not regardless of the internal Conan mechanism. `#15616 `_ +- Feature: Add `--format=json` option to `conan cache path`. `#15613 `_ +- Feature: Add the --order-by argument for conan graph build-order. `#15602 `_ . Docs `here `__ +- Feature: Provide a new ``graph build-order --reduce`` argument to reduce the order exclusively to packages that need to be built from source. `#15573 `_ . Docs `here `__ +- Feature: Add configuration to specify desired CUDA Toolkit in CMakeToolchain for Visual Studio CMake generators. `#15572 `_ . Docs `here `__ +- Feature: New "important" options values definition, with higher precedence over regular option value definitions. `#15571 `_ . Docs `here `__ +- Feature: Display message when calling `deactivate_conanvcvars`. `#15557 `_ +- Feature: Add ``self.info`` information of ``package_id`` to serialized output in the graph, and forward it to package-lists. `#15553 `_ . Docs `here `__ +- Feature: Log Git tool commands when running in verbose mode. `#15514 `_ +- Feature: Add verbose debug information (with ``-vvv``) for ``conan.tools.files.copy()`` calls. `#15513 `_ +- Feature: Define ``python_requires = "tested_reference_str"`` for explicit ``test_package`` of ``python_requires``. `#15485 `_ . Docs `here `__ +- Feature: Adding `CMakeToolchain.presets_build/run_environment` to modify `CMakePresets` environment in `generate()` method. `#15470 `_ . Docs `here `__ +- Feature: Add `--allowed-packges` to remotes to limit what references a remote can supply. `#15464 `_ . Docs `here `__ +- Feature: Initial documentation to make ``RemotesAPI`` publicly available (experimental). `#15462 `_ +- Feature: Add support for use of vcvars env variables when calling from powershell. `#15461 `_ . Docs `here `__ +- Feature: New ``Git(..., excluded=[])`` feature to avoid "dirty" errors in ``Git`` helper. `#15457 `_ . Docs `here `__ +- Feature: New ``core.scm:excluded`` feature to avoid "dirty" errors in ``Git`` helper and ``revision_mode = "scm"``. `#15457 `_ . Docs `here `__ +- Feature: Recipe ``python_package_id_mode`` for ``python_requires`` recipes, to define per-recipe effect on consumers ``package_id``. `#15453 `_ . Docs `here `__ +- Feature: Add cmakeExecutable to configure preset. `#15447 `_ . Docs `here `__ +- Feature: Add new ``--core-conf`` command line argument to allow passing `core.` confs via CLI. `#15441 `_ . Docs `here `__ +- Feature: Add ``detect_api.detect_msvc_update(version)`` helper to ``detect_api``. `#15435 `_ . Docs `here `__ +- Feature: ``CMakeToolchain`` defines ``jobs`` in generated ``CMakePresets.json`` buildPresets. `#15422 `_ +- Feature: Allow nested "ANY" definitions in ``settings.yml``. `#15415 `_ . Docs `here `__ +- Feature: Helpers ``Git().coordinates_to_conandata()`` and ``Git().checkout_from_conandata_coordinates()`` to simplify scm based flows. `#15377 `_ +- Feature: ``AutotoolsToolchain`` automatically inject ``-FS`` for VS. `#15375 `_ +- Feature: New :command:`conan upload` ``core.upload:parallel`` for faster parallel uploads. `#15360 `_ . Docs `here `__ +- Feature: Intel oneAPI compiler detection improvement. `#15358 `_ +- Feature: Display progress for long ``conan list`` commands. `#15354 `_ +- Feature: Add `extension_properties` attribute to pass information to extensions from recipes. `#15348 `_ . Docs `here `__ +- Feature: Implement `compatibility_cppstd` in `extension_properties` for the ``compatibility.py`` plugin to disable fallback to other cppstd for the recipe. `#15348 `_ . Docs `here `__ +- Feature: Add ``Git.get_commit(..., repository=True)`` to obtain the repository commit, not the folder commit. `#15304 `_ +- Feature: Ensure ``--build=editable`` and ``--build=cascade`` works together. `#15300 `_ . Docs `here `__ +- Feature: New ``conan graph build-order --order=configuration`` to output a different order, sorted by package binaries/configurations, not grouped by recipe revisions. `#15270 `_ . Docs `here `__ +- Feature: Allow copy&paste of recipe revisions with timestamps from ``--format=compact`` into ``conan lock add``. `#15262 `_ . Docs `here `__ +- Fix: Guarantee order of `generators` attribute execution. `#15678 `_ +- Fix: Solve issue with ``[platform_tool_requires]`` in the build profile and context. Discard ``[platform_requires]`` in build profile. `#15665 `_ +- Fix: Fix gcc detection in conda environments. `#15664 `_ +- Fix: Improve handling of `.dirty` download files when uploading backup sources. `#15601 `_ +- Fix: Fix relativize paths in generated files. `#15592 `_ +- Fix: Allow ``None`` values for ``CMakeToolchain.preprocessor_definitions`` that will map to definitions without values. `#15545 `_ . Docs `here `__ +- Fix: Fix `graph build-order --order=configuration` text format output. `#15538 `_ +- Fix: Raise a helpful error when the remote is not reachable in case the user wants to work in offline mode. `#15516 `_ +- Fix: Avoid missing file stacktrace when no metadata exists for a source backup. `#15501 `_ +- Fix: Remove ``--lockfile-packages`` argument, it was not documented as it is was not intended for public usage. `#15499 `_ . Docs `here `__ +- Fix: Raise if `check_type=int` and conf value is set to `bool`. `#15378 `_ +- Fix: Add `pkg-config` entry to machine file generated by MesonToolchain, due to `pkgconfig` entry being deprecated since Meson 1.3.0. `#15369 `_ +- Fix: Fix `graph explain` not showing some differences in requirements if missing. `#15355 `_ +- Fix: Fix `tools.info.package_id:confs` when pattern did not match any defined conf. `#15353 `_ +- Fix: Fix ``upload_policy=skip`` with ``--build=missing`` issues. `#15336 `_ +- Fix: Accept ``conan download/upload --list=.. --only-recipe`` to download only the recipes. `#15312 `_ +- Fix: Allow ``cmake.build(build_type="Release")`` for recipes built with multi-config systems but without ``build_type`` setting. `#14780 `_ +- Bugfix: Fix ``MSBuildDeps`` with components and skipped dependencies. `#15626 `_ +- Bugfix: Avoid ``provides`` raising an error for packages that self ``tool_requires`` to themselves to cross-build. `#15575 `_ +- Bugfix: Fix build scope OS detection in `tools.microsoft.visual.VCVars`. `#15568 `_ +- Bugfix: Fix wrong propagation over ``visible=False`` when dependency is header-only. `#15564 `_ +- Bugfix: Store the temporary cache folders inside ``core.cache:storage_path``, so ``conan cache clean`` also finds and clean them correctly. `#15505 `_ +- Bugfix: The ``conan export-pkg --format=json`` output now returns ``recipe = "cache"`` status, as the recipe is in the cache after the command. `#15504 `_ +- Bugfix: The :command:`conan export-pkg` command stores the lockfile excluding the ``test_package``, following the same behavior as :command:`conan create`. `#15504 `_ +- Bugfix: Avoid :command:`conan test` failing for ``python_requires`` test-package. `#15485 `_ . Docs `here `__ +- Bugfix: MesonToolchain calculates a valid `apple_min_version_flag`. `#15465 `_ +- Bugfix: Allow to limit ``os``, ``compiler`` and other settings with subsettings in ``build_id()`` and ``package_id()`` methods. `#15439 `_ +- Bugfix: Fix getting environment variable CONAN_LOGIN_USERNAME_REMOTE. `#15388 `_ +- Bugfix: Don't take `.` folder into consideration for `tools.files.copy()` `excludes` patterns. `#15349 `_ +- Bugfix: Disable creating editables without name and version. `#15337 `_ +- Bugfix: Fix `Git.get_url_and_commit` raising for some Git configs. `#15271 `_ +- Bugfix: Direct dependencies in the "host" context of packages being built shouldn't be skipped. This allows for non C/C++ libraries artifacts, like images, in the "host" context, to be used as build-time resources. `#15128 `_ + + +2.0.17 (10-Jan-2024) +-------------------- + +- Fix: Automatically create folder if ``conan cache save --file=subfolder/file.tgz`` subfolder doesn't exist. `#15409 `_ +- Bugfix: Fix libcxx detection when using `CC/CXX` env vars. `#15418 `_ . Docs `here `__ +- Bugfix: Solve ``winsdk_version`` bug in ``CMakeToolchain`` generator for ``cmake_minimum_required(3.27)``. `#15373 `_ +- Bugfix: Fix visible trait propagation with ``build=True`` trait. `#15357 `_ +- Bugfix: Fix `package_id` calculation when including conf values thru `tools.info.package_id:confs`. `#15356 `_ +- Bugfix: Order `conf` items when dumping them to allow reproducible `package_id` independent of the order the confs were declared. `#15356 `_ + + +2.0.16 (21-Dec-2023) +-------------------- + +- Bugfix: Revert the default of ``source_buildenv``, make it ``False`` by default. `#15319 `_ . Docs `here `__ + + +2.0.15 (20-Dec-2023) +-------------------- + +- Feature: New ``conan lock remove`` command to remove requires from lockfiles. `#15284 `_ . Docs `here `__ +- Feature: New ``CMake.ctest()`` helper method to launch directly ``ctest`` instead of via ``cmake --target=RUN_TEST``. `#15282 `_ +- Feature: Add tracking syntax in `` for different references. `#15274 `_ . Docs `here `__ +- Feature: Adding ``tools.microsoft:winsdk_version`` conf to make ``VCVars`` generator to use the given ``winsdk_version``. `#15272 `_ . Docs `here `__ +- Feature: Add `pkglist` formatter for conan export command. `#15266 `_ . Docs `here `__ +- Feature: Define ``CONAN_LOG_LEVEL`` env-var to be able to change verbosity at a global level. `#15263 `_ . Docs `here `__ +- Feature: `conan cache path xxx --folder xxxx` raises an error if the folder requested does not exist. `#15257 `_ +- Feature: Add `in` operator support for ConanFile's `self.dependencies`. `#15221 `_ . Docs `here `__ +- Feature: Make ``CMakeDeps`` generator create a ``conandeps.cmake`` that aggregates all direct dependencies in a ``cmake``-like generator style. `#15207 `_ . Docs `here `__ +- Feature: Add build environment information to CMake configure preset and run environment information to CMake test presets. `#15192 `_ . Docs `here `__ +- Feature: Removed a warning about a potential issue with conan migration that would print every time a build failed. `#15174 `_ +- Feature: New ``deploy()`` method in recipes for explicit per-recipe deployment. `#15172 `_ . Docs `here `__ +- Feature: Allow ``tool-requires`` to be used in ``source()`` method injecting environment. `#15153 `_ . Docs `here `__ +- Feature: Allow accessing the contents of `settings.yml` (and `settings_user`!) from `ConfigAPI`. `#15151 `_ +- Feature: Add builtin conf access from `ConfigAPI`. `#15151 `_ +- Feature: Add `redirect_stdout` to CMake integration methods. `#15150 `_ +- Feature: Add `core:warnings_as_errors` configuration option to make Conan raise on warnings and errors. `#15149 `_ . Docs `here `__ +- Feature: Added `FTP_TLS` option using `secure` argument in `ftp_download` for secure communication. `#15137 `_ +- Feature: New ``[replace_requires]`` and ``[replace_tool_requires]`` in profile for redefining requires, useful for package replacements like ``zlibng/zlib``, to solve conflicts, and to replace some dependencies by system alternatives wrapped in another Conan package recipe. `#15136 `_ . Docs `here `__ +- Feature: Add `stderr` capture argument to conanfile's `run()` method. `#15121 `_ . Docs `here `__ +- Feature: New ``[platform_requires]`` profile definition to be able to replace Conan dependencies by platform-provided dependencies. `#14871 `_ . Docs `here `__ +- Feature: New ``conan graph explain`` command to search, compare and explain missing binaries. `#14694 `_ . Docs `here `__ +- Feature: Global ``cpp_info`` can be used to initialize components values. `#13994 `_ +- Fix: Make `core:warnings_as_errors` accept a list `#15297 `_ +- Fix: Fix `user` confs package scoping when no separator was given `#15296 `_ +- Fix: Fix range escaping in conflict reports involving ranges. `#15222 `_ +- Fix: Allow hard ``set_name()`` and ``set_version()`` to mutate name and version provided in command line. `#15211 `_ . Docs `here `__ +- Fix: Make `conan graph info --format=text` print to stdout. `#15170 `_ +- Fix: Avoid warning in CMake output due to `CMAKE_POLICY_DEFAULT_CMP0091` unused variable. `#15127 `_ +- Fix: Deprecate ``[system_tools]`` in favor of ``[platform_tool_requires]`` to align with ``[platform_requires]`` for regular dependencies. Changed output from "System tool" to "Platform". `#14871 `_ . Docs `here `__ +- Bugfix: Ensure `user` confs have at least 1 `:` separator `#15296 `_ +- Bugfix: ``Git.is_dirty()`` will use ``git status . -s`` to make sure it only process the current path, not the whole repo, similarly to other ``Git`` methods. `#15289 `_ +- Bugfix: Make ``self.info.clear()`` and header-only packages to remove ``python_requires`` and ``tool_requires``. `#15285 `_ . Docs `here `__ +- Bugfix: Make ``conan cache save/restore`` portable across Windows and other OSs. `#15253 `_ +- Bugfix: Do not relativize absolute paths in ``deployers``. `#15244 `_ +- Bugfix: Add ``architecture`` to ``CMakePresets`` to avoid cmake ignoring toolchain definitions when using presets. `#15215 `_ +- Bugfix: Fix `conan graph info --format=html` reporting misleading conflicting nodes. `#15196 `_ +- Bugfix: Fix serialization of tool_requires in `conan profile show --format=json`. `#15185 `_ +- Bugfix: Fix NMakeDeps quoting issues. `#15140 `_ +- Bugfix: Fix the 2.0.14 migration to add LRU data to the cache when ``storage_path`` conf is defined. `#15135 `_ +- Bugfix: Fix definition of ``package_metadata_folder`` for :command:`conan export-pkg` command. `#15126 `_ +- Bugfix: `pyinstaller.py` was broken for Python 3.12 due to a useless `distutils` import. `#15116 `_ +- Bugfix: Fix backup sources error when no `core.sources:download_cache` is set. `#15109 `_ + + +2.0.14 (14-Nov-2023) +-------------------- + +- Feature: Added ``riscv64, riscv32`` architectures to default ``settings.yml`` and management of them in Meson and Autotools. `#15053 `_ +- Feature: Allow only one simultaneous database connection. `#15029 `_ +- Feature: Add `conan cache backup-upload` to upload all the backup sources in the cache, regardless of which references they are from `#15013 `_ . Docs `here `__ +- Feature: New ``conan list --format=compact`` for better UX. `#15011 `_ . Docs `here `__ +- Feature: Ignore metadata upload by passing --metadata="" `#15007 `_ . Docs `here `__ +- Feature: Better output messages in :command:`conan upload` `#14984 `_ +- Feature: Add extra flags to CMakeToolchain. `#14966 `_ . Docs `here `__ +- Feature: Implement package load/restore from the cache, for CI workflows and moving packages over air-gaps. `#14923 `_ . Docs `here `__ +- Feature: Compute version-ranges intersection to avoid graph version conflicts for compatible ranges `#14912 `_ +- Feature: CMake helper can use multiple targets in target argument. `#14883 `_ +- Feature: Add Macos 13.6 to settings.yml. `#14858 `_ . Docs `here `__ +- Feature: Add CMakeDeps and PkgConfigDeps generators listening to system_package_version property. `#14808 `_ . Docs `here `__ +- Feature: Add shorthand syntax in cli to specify host and build in 1 argument `#14727 `_ . Docs `here `__ +- Feature: Implement cache LRU control for cleaning of unused artifacts. `#14054 `_ . Docs `here `__ +- Fix: Avoid ``CMakeToolchain`` overwriting user ``CMakePresets.json`` when no layout nor output-folder is defined `#15058 `_ +- Fix: Add ``astra``, ``elbrus`` and ``altlinux`` as distribution using ``apt`` in SystemPackageManager `#15051 `_ +- Fix: Default to apt-get package manager in Linux Mint `#15026 `_ . Docs `here `__ +- Fix: Make ``Git()`` check commits in remote server even for shallow clones. `#15023 `_ +- Fix: Add new Apple OS versions to settings.yml `#15015 `_ +- Fix: Fix AutotoolsToolchain extraflags priority. `#15005 `_ . Docs `here `__ +- Fix: Remove colors from ``conan --version`` output `#15002 `_ +- Fix: Add an error message if the sqlite3 version is unsupported (less than 3.7.11 from 2012) `#14950 `_ +- Fix: Make cache DB always use forward slash for paths, to be uniform across Windows and Linux `#14940 `_ +- Fix: Solve re-build of an existing package revision (like forcing rebuild of a an existing header-only package), while previous folder was still used by other projects. `#14938 `_ +- Fix: Avoid a recipe mutating a ``conf`` to affect other recipes. `#14932 `_ . Docs `here `__ +- Fix: The output of system packages via ``Apt.install()`` or ``PkgConfig.fill_cpp_info``, like ``xorg/system`` was very noisy to the Conan output, making it more quiet `#14924 `_ +- Fix: Serialize the ``path`` information of ``python_requires``, necessary for computing buildinfo `#14886 `_ +- Fix: Define remotes in :command:`conan source` command in case recipe has ``python_requires`` that need to be downloaded from remotes. `#14852 `_ +- Fix: Fix min target flag for xros and xros-simulator. `#14776 `_ +- Bugfix: ``--build=missing`` was doing unnecessary builds of packages that were not needed and could be skipped, in the case of ``tool_requires`` having transitive dependencies. `#15082 `_ +- BugFix: Add package revision to format=json in 'conan export-pkg' command `#15042 `_ +- Bugfix: ``tools.build:download_source=True`` will not fail when there are editable packages. `#15004 `_ . Docs `here `__ +- Bugfix: Transitive dependencies were incorrectly added to conandeps.xcconfig. `#14898 `_ +- Bugfix: Fix integrity-check (``upload --check`` or ``cache check-integrity``) when the ``export_source`` has not been downloaded `#14850 `_ +- Bugfix: Properly lock release candidates of python requires `#14846 `_ +- BugFix: Version ranges ending with ``-`` do not automatically activate pre-releases resolution in the full range. `#14814 `_ . Docs `here `__ +- BugFix: Fix version ranges so pre-releases are correctly included in the lower bound and excluded in the upper bound. `#14814 `_ . Docs `here `__ + + +2.0.13 (28-Sept-2023) +--------------------- + +- Bugfix: Fix wrong cppstd detection for newer apple-clang versions introduced in 2.0.11. `#14837 `_ + +2.0.12 (26-Sept-2023) +--------------------- + +- Feature: Add support for Clang 17. `#14781 `_ . Docs `here `__ +- Feature: Add `--dry-run` for :command:`conan remove`. `#14760 `_ . Docs `here `__ +- Feature: Add `host_tool` to `install()` method in `package_manager` to indicate whether the package is a host tool or a library. `#14752 `_ . Docs `here `__ +- Fix: Better error message when trying to ``export-pkg`` a ``python-require`` package, and avoid it being exported and then failing. `#14819 `_ +- Fix: ``CMakeDeps`` allows ``set_property()`` on all properties. `#14813 `_ +- Fix: Add minor version for Apple clang 15.0. `#14797 `_ . Docs `here `__ +- Fix: :command:`conan build` command prettier error when argument not provided. `#14787 `_ +- Bugfix: fix ``compatibility()`` over ``settings_target`` making it None `#14825 `_ +- Bugfix: ``compatible`` packages look first in the cache, and only if not found, the servers, to allow offline installs when there are compatible packages. `#14800 `_ +- BugFix: Reuse session in ConanRequester to speed up requests. `#14795 `_ +- Bugfix: Fix relative paths of ``editable`` packages when they have components partially defining directories. `#14782 `_ + +2.0.11 (18-Sept-2023) +--------------------- + +- Feature: Add ``--format=json`` formatter to ``conan profile show`` command `#14743 `_ . Docs `here `__ +- Feature: add new --deployer --generators args to 'conan build' cmd `#14737 `_ . Docs `here `__ +- Feature: Better ``CMakeToolchain`` blocks interface. Added new ``.blocks.select()``, ``.blocks.keys()``. `#14731 `_ . Docs `here `__ +- Feature: Add message when copying large files from download cache instead of downloading from server. `#14716 `_ +- Feature: MesonToolchain shows a warning message if any options are used directly. `#14692 `_ . Docs `here `__ +- Feature: Support clang-cl in default profile plugin. `#14682 `_ . Docs `here `__ +- Feature: Added mechanism to transform `c`, `cpp`, and/or `ld` binaries variables from Meson into lists if declared blank-separated strings. `#14676 `_ +- Feature: Add `nobara` distro to `dnf` package manager mapping. `#14668 `_ +- Feature: Ensure meson toolchain sets `b_vscrt` with clang-cl. `#14664 `_ +- Feature: Supporting regex pattern for conf `tools.info.package_id:confs` `#14621 `_ . Docs `here `__ +- Feature: MakeDeps: Provide "require" information, and more styling tweaks. `#14605 `_ +- Feature: New ``detect_api`` to be used in profiles jinja templates. `#14578 `_ . Docs `here `__ +- Feature: Allow access to `settings_target` in compatibility method. `#14532 `_ +- Fix: Add missing minor macos versions `#14740 `_ . Docs `here `__ +- Fix: Improve error messages in `ConanApi` init failures, `#14735 `_ +- Fix: CMakeDeps: Remove "Target name ... already exists" warning about duplicating aliases. `#14644 `_ +- Bugfix: Fix regression in ``Git.run()`` when ``win_bash=True``. `#14756 `_ +- Bugfix: Change the default `check=False` in `conan.tools.system.package_manager.Apt` to `True` as the other package manager tools. `#14728 `_ . Docs `here `__ +- Bugfix: Solved propagation of transitive shared dependencies of ``test_requires`` with diamonds. `#14721 `_ +- Bugfix: Solve crash with :command:`conan export-pkg` with ``test_package`` doing calls to remotes. `#14712 `_ +- Bugfix: Do not binary-skip packages that have transitive dependencies that are not skipped, otherwise the build chain of build systems to those transitive dependencies like ``CMakeDeps`` generated files are broken. `#14673 `_ +- Bugfix: Fix detected CPU architecture when running ``conan profile detect`` on native ARM64 Windows. `#14667 `_ +- Bugfix: ``conan lock create --update`` now correctly updates references from servers if newer than cache ones. `#14643 `_ +- Bugfix: Fix unnecessarily decorating command stdout with escape sequences. `#14642 `_ +- Bugfix: ``tools.info.package_id:confs`` shouldn't affect header-only libraries. `#14622 `_ + +2.0.10 (29-Aug-2023) +-------------------- + +- Feature: Allow ``patch_user`` in ``conandata.yml`` definition for user patches, not handled by ``apply_conandata_patches()``. `#14576 `_ . Docs `here `__ +- Feature: Support for Xcode 15, iOS 17, tvOS 17, watchOS 10, macOS 14. `#14538 `_ +- Feature: Raise an error if users are adding incorrect ConanCenter web URL as remote. `#14531 `_ +- Feature: Serialization of graph with ``--format=json`` adds information to ``python_requires`` so ``conan list --graph`` can list ``python_requires`` too. `#14529 `_ +- Feature: Add ``rrev``, ``rrev_timestamp`` and ``prev_timestamp`` to the graph json serialization. `#14526 `_ +- Feature: Allow ``version-ranges`` to resolve to editable packages too. `#14510 `_ +- Feature: Add `tools.files.download:verify`. `#14508 `_ . Docs `here `__ +- Feature: Add support for Apple visionOS. `#14504 `_ +- Feature: Warn of unknown version range options. `#14493 `_ +- Feature: Add `tools.graph:skip_binaries` to control binary skipping in the graph. `#14466 `_ . Docs `here `__ +- Feature: New ``tools.deployer:symlinks`` configuration to disable symlinks copy in deployers. `#14461 `_ . Docs `here `__ +- Feature: Allow remotes to automatically resolve missing ``python_requires`` in 'editable add'. `#14413 `_ . Docs `here `__ +- Feature: Add ``cli_args`` argument for ``CMake.install()``. `#14397 `_ . Docs `here `__ +- Feature: Allow ``test_requires(..., force=True)``. `#14394 `_ . Docs `here `__ +- Feature: New ``credentials.json`` file to store credentials for Conan remotes. `#14392 `_ . Docs `here `__ +- Feature: Added support for `apk` package manager and Alpine Linux `#14382 `_ . Docs `here `__ +- Feature: `conan profile detect` can now detect the version of msvc when invoked within a Visual Studio prompt where `CC` or `CXX` are defined and pointing to the `cl` compiler executable `#14364 `_ +- Feature: Properly document ``--build=editable`` build mode. `#14358 `_ . Docs `here `__ +- Feature: ``conan create --build-test=missing`` new argument to control what is being built as dependencies of the ``test_package`` folder. `#14347 `_ . Docs `here `__ +- Feature: Provide new ``default_build_options`` attribute for defining options for ``tool_requires`` in recipes. `#14340 `_ . Docs `here `__ +- Feature: Implement ``...@`` as a pattern for indicating matches with packages without user/channel. `#14338 `_ . Docs `here `__ +- Feature: Add support to Makefile by the new MakeDeps generator `#14133 `_ . Docs `here `__ +- Fix: Allow `--format=json` in :command:`conan create` for `python-requires` `#14594 `_ +- Fix: Remove conan v2 ready conan-center link. `#14593 `_ +- Fix: Make :command:`conan inspect` use all remotes by default. `#14572 `_ . Docs `here `__ +- Fix: Allow extra hyphens in versions pre-releases. `#14561 `_ +- Fix: Allow confs for ``tools.cmake.cmaketoolchain`` to be used if defined even if ``tools.cmake.cmaketoolchain:user_toolchain`` is defined. `#14556 `_ . Docs `here `__ +- Fix: Serialize booleans of ``dependencies`` in ``--format=json`` for graphs as booleans, not strings. `#14530 `_ . Docs `here `__ +- Fix: Avoid errors in :command:`conan upload` when ``python_requires`` are not in the cache and need to be downloaded. `#14511 `_ +- Fix: Improve error check of ``lock add`` adding a full package reference instead of a recipe reference. `#14491 `_ +- Fix: Better error message when a built-in deployer failed to copy files. `#14461 `_ . Docs `here `__ +- Fix: Do not print non-captured stacktraces to ``stdout`` but to ``stderr``. `#14444 `_ +- Fix: Serialize ``conf_info`` in ``--format=json`` output. `#14442 `_ +- Fix: `MSBuildToolchain`/`MSBuildDeps`: Avoid passing C/C++ compiler options as options for `ResourceCompile`. `#14378 `_ +- Fix: Removal of plugin files result in a better error message instead of stacktrace. `#14376 `_ +- Fix: Fix CMake system processor name on armv8/aarch64. `#14362 `_ +- Fix: Make backup sources ``core.sources`` conf not mandate the final slash. `#14342 `_ +- Fix: Correctly propagate options defined in recipe ``default_options`` to ``test_requires``. `#14340 `_ . Docs `here `__ +- Fix: Invoke XCRun using conanfile.run() so that environment is injected. `#14326 `_ +- Fix: Use ``abspath`` for ``conan config install`` to avoid symlinks issues. `#14183 `_ +- Bugfix: Solve ``build_id()`` issues, when multiple different ``package_ids`` reusing same build-folder. `#14555 `_ +- Bugfix: Avoid DB errors when timestamp is not provided to :command:`conan download` when using package lists. `#14526 `_ +- Bugfix: Print exception stacktrace (when `-vtrace` is set) into stderr instead of stdout `#14522 `_ +- Bugfix: Print only packages confirmed interactively in :command:`conan upload`. `#14512 `_ +- Bugfix: 'conan remove' was outputting all entries in the cache matching the filter not just the once which where confirmed by the user. `#14478 `_ +- Bugfix: Better error when passing `--channel` without `--user`. `#14443 `_ +- Bugfix: Fix ``settings_target`` computation for ``tool_requires`` of packages already in the "build" context. `#14441 `_ +- Bugfix: Avoid ``DB is locked`` error when ``core.download:parallel`` is defined. `#14410 `_ +- Bugfix: Make generated powershell environment scripts relative when using deployers. `#14391 `_ +- Bugfix: fix profile [tool_requires] using revisions that were ignored. `#14337 `_ + +2.0.9 (19-Jul-2023) +------------------- + +- Feature: Add `implements` attribute in ConanFile to provide automatic management of some options and settings. `#14320 `_ . Docs `here `__ +- Feature: Add `apple-clang` 15. `#14302 `_ +- Fix: Allow repository being dirty outside of `conanfile.py` folder when using `revision_mode = "scm_folder"`. `#14330 `_ +- Fix: Improve the error messages and provide Conan traces for errors in `compatibility.py` and `profile.py` plugins. `#14322 `_ +- Fix: ``flush()`` output streams after every message write. `#14310 `_ +- Bugfix: Fix Package signing plugin not verifying the downloaded sources. `#14331 `_ . Docs `here `__ +- Bugfix: Fix ``CMakeUserPresets`` inherits from conan generated presets due to typo. `#14325 `_ +- Bugfix: ConanPresets.json contains duplicate presets if multiple user presets inherit from the same conan presets. `#14296 `_ +- Bugfix: Meson `prefix` param is passed as UNIX path. `#14295 `_ +- Bugfix: Fix `CMake Error: Invalid level specified for --loglevel` when `tools.build:verbosity` is set to `quiet`. `#14289 `_ + +2.0.8 (13-Jul-2023) +------------------- + +- Feature: Add GCC 10.5 to default settings.yml. `#14252 `_ +- Feature: Let `pkg_config_custom_content` overwrite default `*.pc` variables created by `PkgConfigDeps`. `#14233 `_ . Docs `here `__ +- Feature: Let `pkg_config_custom_content` be a dict-like object too. `#14233 `_ . Docs `here `__ +- Feature: The `fix_apple_shared_install_name` tool now uses `xcrun` to resolve the `otool` and `install_name_tool` programs. `#14195 `_ +- Feature: Manage shared, fPIC, and header_only options automatically. `#14194 `_ . Docs `here `__ +- Feature: Manage package ID for header-library package type automatically. `#14194 `_ . Docs `here `__ +- Feature: New ``cpp_info.set_property("cmake_package_version_compat" , "AnyNewerVersion")`` for ``CMakeDeps`` generator. `#14176 `_ . Docs `here `__ +- Feature: Metadata improvements. `#14152 `_ +- Fix: Improve error message when missing binaries with :command:`conan test` command. `#14272 `_ +- Fix: Make :command:`conan download` command no longer need to load conanfile, won't fail for 1.X recipes or missing ``python_requires``. `#14261 `_ +- Fix: Using `upload` with the `--list` argument now permits empty recipe lists. `#14254 `_ +- Fix: Guarantee that ``Options.rm_safe`` never raises. `#14238 `_ +- Fix: Allow `tools.gnu:make_program` to affect every CMake configuration. `#14223 `_ +- Fix: Add missing `package_type` to :command:`conan new` lib templates. `#14215 `_ +- Fix: Add clarification for the default folder shown when querying a package reference. `#14199 `_ . Docs `here `__ +- Fix: Enable existing status-message code in the `patch()` function. `#14177 `_ +- Fix: Use ``configuration`` in ``XcodeDeps`` instead of always ``build_type``. `#14168 `_ +- Fix: Respect symlinked path for cache location. `#14164 `_ +- Fix: ``PkgConfig`` uses ``conanfile.run()`` instead of internal runner to get full Conan environment from profiles and dependencies. `#13985 `_ +- Bugfix: Fix leaking of ``CMakeDeps`` ``CMAKE_FIND_LIBRARY_SUFFIXES`` variable. `#14253 `_ +- Bugfix: Fix conan not finding generator by name when multiple custom global generators are detected. `#14227 `_ +- Bugfix: Improve display of graph conflicts in `conan graph info` in html format. `#14190 `_ +- Bugfix: Fix ``CMakeToolchain`` cross-building from Linux to OSX. `#14187 `_ +- Bugfix: Fix KeyError in backup sources when no package is selected. `#14185 `_ + +2.0.7 (21-Jun-2023) +------------------- + +- Feature: Add new ``arm64ec`` architecture, used to define CMAKE_GENERATOR_PLATFORM. `#14114 `_ . Docs `here `__ +- Feature: Make ``CppInfo`` a public, documented, importable tool for generators that need to aggregate them. `#14101 `_ . Docs `here `__ +- Feature: Allow ``conan remove --list=pkglist`` to remove package-lists. `#14082 `_ . Docs `here `__ +- Feature: Output for ``conan remove --format`` both text (summary of deleted things) and json. `#14082 `_ . Docs `here `__ +- Feature: Add `core.sources:excluded_urls` to backup sources. `#14020 `_ +- Feature: :command:`conan test` command learned the ``--format=json`` formatter. `#14011 `_ . Docs `here `__ +- Feature: Allow ``pkg/[version-range]`` expressions in ``conan list`` (and download, upload, remove) patterns. `#14004 `_ . Docs `here `__ +- Feature: Add ``conan upload --dry-run`` equivalent to 1.X ``conan upload --skip-upload``. `#14002 `_ . Docs `here `__ +- Feature: Add new command `conan version` to format the output. `#13999 `_ . Docs `here `__ +- Feature: Small UX improvement to print some info while downloading large files. `#13989 `_ +- Feature: Use ``PackagesList`` as input argument for ``conan upload --list=pkglist.json``. `#13928 `_ . Docs `here `__ +- Feature: Use ``--graph`` input for ``conan list`` to create a ``PackagesList`` that can be used as input for :command:`conan upload`. `#13928 `_ . Docs `here `__ +- Feature: New metadata files associated to recipes and packages that can be uploaded, downloaded and added after the package exists. `#13918 `_ +- Feature: Allow to specify a custom deployer output folder. `#13757 `_ . Docs `here `__ +- Feature: Split build & compilation verbosity control to two confs. `#13729 `_ . Docs `here `__ +- Feature: Added `bindir` to generated `.pc` file in `PkgConfigDeps`. `#13623 `_ . Docs `here `__ +- Fix: Deprecate ``AutoPackage`` remnant from Conan 1.X. `#14083 `_ . Docs `here `__ +- Fix: Fix description for the conf entry for default build profile used. `#14075 `_ . Docs `here `__ +- Fix: Allow spaces in path in ``Git`` helper. `#14063 `_ . Docs `here `__ +- Fix: Remove trailing ``.`` in ``conanfile.xxx_folder`` that is breaking subsystems like msys2. `#14061 `_ +- Fix: Avoid caching issues when some intermediate package in the graph calls ``aggregated_components()`` over some dependency and using ``--deployer``, generators still pointed to the Conan cache and not deployed copy. `#14060 `_ +- Fix: Allow internal ``Cli`` object to be called more than once. `#14053 `_ +- Fix: Force ``pyyaml>=6`` for Python 3.10, as previous versions broke. `#13990 `_ +- Fix: Improve graph conflict message when Conan can't show one of the conflicting recipes. `#13946 `_ +- Bugfix: Solve bug in timestamp of non-latest revision download from the server. `#14110 `_ +- Bugfix: Fix double base path setup in editable packages. `#14109 `_ +- Bugfix: Raise if ``conan graph build-order`` graph has any errors, instead of quietly doing nothing and outputting and empty json. `#14106 `_ +- Bugfix: Avoid incorrect path replacements for ``editable`` packages when folders have overlapping matching names. `#14095 `_ +- Bugfix: Set clang as the default FreeBSD detected compiler. `#14065 `_ +- Bugfix: Add prefix var and any custom content (through the `pkg_config_custom_content` property) to already generated pkg-config root .pc files by `PkgConfigDeps`. `#14051 `_ +- Bugfix: :command:`conan create` command returns always the same output for ``--format=json`` result graph, irrespective of test_package existence. `#14011 `_ . Docs `here `__ +- Bugfix: Fix problem with ``editable`` packages when defining ``self.folders.root=".."`` parent directory. `#13983 `_ +- Bugfix: Removed `libdir1` and `includedir1` as the default index. Now, `PkgConfigDeps` creates the `libdir` and `includedir` variables by default in `.pc` files. `#13623 `_ . Docs `here `__ + +2.0.6 (26-May-2023) +------------------- + +- Feature: Add a `tools.cmake:cmake_program` configuration item to allow specifying the location of the desired CMake executable. `#13940 `_ . Docs `here `__ +- Fix: Output "id" property in graph json output as str instead of int. `#13964 `_ . Docs `here `__ +- Fix: Fix custom commands in a layer not able to do a local import. `#13944 `_ +- Fix: Improve the output of download + unzip. `#13937 `_ +- Fix: Add missing values to `package_manager:mode` in `conan config install`. `#13929 `_ +- Bugfix: Ensuring the same graph-info JSON output for `graph info`, `create`, `export-pkg`, and `install`. `#13967 `_ . Docs `here `__ +- Bugfix: ``test_requires`` were affecting the ``package_id`` of consumers as regular ``requires``, but they shouldn't. `#13966 `_ +- Bugfix: Define ``source_folder`` correctly in the json output when ``-c tools.build:download_source=True``. `#13953 `_ +- Bugfix: Fixed and completed the `graph info xxxx --format json` output, to publicly document it. `#13934 `_ . Docs `here `__ +- Bugfix: Fix "double" absolute paths in premakedeps. `#13926 `_ +- Bugfix: Fix regression from 2.0.5 https://github.com/conan-io/conan/pull/13898, in which overrides of packages and components specification was failing `#13923 `_ + +2.0.5 (18-May-2023) +------------------- + +- Feature: `-v` argument defaults to the `VERBOSE` level. `#13839 `_ +- Feature: Avoid showing unnecessary skipped dependencies. Now, it only shows a list of reference names if exists skipped binaries. They can be completely listed by adding `-v` (verbose mode) to the current command. `#13836 `_ +- Feature: Allow step-into dependencies debugging for packages built locally with ``--build`` `#13833 `_ . Docs `here `__ +- Feature: Allow non relocatable, locally built packages with ``upload_policy="skip"`` and ``build_policy="missing"`` `#13833 `_ . Docs `here `__ +- Feature: Do not move "build" folders in cache when ``package-revision`` is computed to allow locating sources for dependencies debuggability with step-into `#13810 `_ +- Feature: New ``settings.possible_values()`` method to query the range of possible values for a setting. `#13796 `_ . Docs `here `__ +- Feature: Optimize and avoid hitting servers for binaries when ``upload_policy=skip`` `#13771 `_ +- Feature: Partially relativize generated environment .sh shell scripts `#13764 `_ +- Feature: Improve settings.yml error messages `#13748 `_ +- Feature: Auto create empty ``global.conf`` to improve UX looking for file in home. `#13746 `_ . Docs `here `__ +- Feature: Render the profile file name as profile_name `#13721 `_ . Docs `here `__ +- Feature: New global custom generators in cache "extensions/generators" that can be used by name. `#13718 `_ . Docs `here `__ +- Feature: Improve :command:`conan inspect` output, it now understands `set_name`/`set_version`. `#13716 `_ . Docs `here `__ +- Feature: Define new ``self.tool_requires("pkg/")`` to allow some tool-requires to follow and use the same version as the "host" regular requires do. `#13712 `_ . Docs `here `__ +- Feature: Introduce new ``core:skip_warns`` configuration to be able to silence some warnings in the output. `#13706 `_ . Docs `here `__ +- Feature: Add info_invalid to graph node serialization `#13688 `_ +- Feature: Computing and reporting the ``overrides`` in the graph, and in the ``graph build-order`` `#13680 `_ +- Feature: New ``revision_mode = "scm_folder"`` for mono-repo projects that want to use ``scm`` revisions. `#13562 `_ . Docs `here `__ +- Feature: Demonstrate that it is possible to ``tool_requires`` different versions of the same package. `#13529 `_ . Docs `here `__ +- Fix: `build_scripts` now set the `run` trait to `True` by default `#13901 `_ . Docs `here `__ +- Fix: Fix XcodeDeps includes skipped dependencies. `#13880 `_ +- Fix: Do not allow line feeds into ``pkg/version`` reference fields `#13870 `_ +- Fix: Fix ``AutotoolsToolchain`` definition of ``tools.build:compiler_executable`` for Windows subsystems `#13867 `_ +- Fix: Speed up the CMakeDeps generation `#13857 `_ +- Fix: Fix imported library config suffix. `#13841 `_ +- Fix: Fail when defining an unkown conf `#13832 `_ +- Fix: Fix incorrect printing of "skipped" binaries in the ``conan install/create`` commands, when they are used by some other dependencies. `#13778 `_ +- Fix: Renaming the cache "deploy" folder to "deployers" and allow ``-d, --deployer`` cli arg. ("deploy" folder will not break but will warn as deprecated). `#13740 `_ . Docs `here `__ +- Fix: Omit ``-L`` libpaths in ``CMakeDeps`` for header-only libraries. `#13704 `_ +- Bugfix: Fix when a ``test_requires`` is also a regular transitive "host" requires and consumer defines components. `#13898 `_ +- Bugfix: Fix propagation of options like ``*:shared=True`` defined in recipes `#13855 `_ +- Bugfix: Fix ``--lockfile-out`` paths for 'graph build-order' and 'test' commands `#13853 `_ +- Bugfix: Ensure backup sources are uploaded in more cases `#13846 `_ +- Bugfix: fix ``settings.yml`` definition of ``intel-cc`` ``cppstd=03`` `#13844 `_ +- Bugfix: Fix :command:`conan upload` with backup sources for exported-only recipes `#13779 `_ +- Bugfix: Fix ``conan lock merge`` of lockfiles containing alias `#13763 `_ +- Bugfix: Fix python_requires in transitive deps with version ranges `#13762 `_ +- Bugfix: fix CMakeToolchain CMAKE_SYSTEM_NAME=Generic for baremetal `#13739 `_ +- Bugfix: Fix incorrect environment scripts deactivation order `#13707 `_ +- Bugfix: Solve failing lockfiles when graph has requirements with ``override=True`` `#13597 `_ + +2.0.4 (11-Apr-2023) +------------------- + +- Feature: extend ``--build-require`` to more commands (``graph info``, ``lock create``, ``install``) and cases. `#13669 `_ . Docs `here `__ +- Feature: Add `-d tool_requires` to :command:`conan new`. `#13608 `_ . Docs `here `__ +- Feature: Make CMakeDeps, CMakeToolchain and Environment (.bat, Windows only) generated files have relative paths. `#13607 `_ +- Feature: Adding preliminary (non documented, dev-only) support for premake5 deps (PremakeDeps). `#13390 `_ +- Fix: Update old :command:`conan user` references to ``conan remote login``. `#13671 `_ +- Fix: Improve dependencies options changed in ``requirements()`` error msg. `#13668 `_ +- Fix: [system_tools] was not reporting the correct resolved version, but still the original range. `#13667 `_ +- Fix: Improve `provides` conflict message error. `#13661 `_ +- Fix: When server responds Forbidden to the download of 1 file in a recipe/package, make sure other files and DB are cleaned. `#13626 `_ +- Fix: Add error in :command:`conan remove` when using `--package-query` without providing a pattern that matches packages. `#13622 `_ +- Fix: Add ``direct_deploy`` subfolder for the ``direct_deploy`` deployer. `#13612 `_ . Docs `here `__ +- Fix: Fix html output when pattern does not list package revisions, like: ``conan list "*#*:*"``. `#13605 `_ +- Bugfix: ``conan list -p `` failed when a package had no settings or options. `#13662 `_ +- Bugfix: `python_requires` now properly loads remote requirements. `#13657 `_ +- Bugfix: Fix crash when ``override`` is used in a node of the graph that is also the closing node of a diamond. `#13631 `_ +- Bugfix: Fix the ``--package-query`` argument for ``options``. `#13618 `_ +- Bugfix: Add ``full_deploy`` subfolder for the ``full_deploy`` deployer to avoid collision with "build" folder. `#13612 `_ . Docs `here `__ +- Bugfix: Make `STATUS` the default log level. `#13610 `_ +- Bugfix: Fix double delete error in `conan cache clean`. `#13601 `_ + +2.0.3 (03-Apr-2023) +------------------- + +- Feature: ``conan cache clean`` learned the ``--all`` and ``--temp`` to clean everything (sources, builds) and also the temporary folders. `#13581 `_ . Docs `here `__ +- Feature: Introduce the ``conf`` dictionary update semantics with ``*=`` operator. `#13571 `_ . Docs `here `__ +- Feature: Support MacOS SDK 13.1 (available in Xcode 14.2). `#13531 `_ +- Feature: The ``full_deploy`` deployer together with ``CMakeDeps`` generator learned to create relative paths deploys, so they are relocatable. `#13526 `_ +- Feature: Introduce the ``conan remove *#!latest`` (also for package-revisions), to remove all revisions except the latest one. `#13505 `_ . Docs `here `__ +- Feature: New ``conan cache check-integrity`` command to replace 1.X legacy ``conan upload --skip-upload --check``. `#13502 `_ . Docs `here `__ +- Feature: Add filtering for options and settings in conan list html output. `#13470 `_ +- Feature: Automatic server side source backups for third parties. `#13461 `_ +- Feature: Add `tools.android:cmake_legacy_toolchain` configuration useful when building CMake projects for Android. If defined, this will set the value of `ANDROID_USE_LEGACY_TOOLCHAIN_FILE`. It may be useful to set this to `False` if compiler flags are defined via `tools.build:cflags` or `tools.build:cxxflags` to prevent Android's legacy CMake toolchain from overriding the values. `#13459 `_ . Docs `here `__ +- Feature: Default ``tools.files.download:download_cache`` to ``core.download:download_cache``, so it is only necessary to define one. `#13458 `_ +- Feature: Authentication for ``tools.files.download()``. `#13421 `_ . Docs `here `__ +- Fix: Define a way to update ``default_options`` in ``python_requires_extend`` extension. `#13487 `_ . Docs `here `__ +- Fix: Allow again to specify ``self.options["mydep"].someoption=value``, equivalent to ``"mydep/*"``. `#13467 `_ +- Fix: Generate `cpp_std=vc++20` for c++20 with meson with VS2019 and VS2022, rather than `vc++latest`. `#13450 `_ +- Bugfix: Fixed ``CMakeDeps`` not clearing ``CONAN_SHARED_FOUND_LIBRARY`` var in ``find_library()``. `#13596 `_ +- Bugfix: Do not allow adding more than 1 remote with the same remote name. `#13574 `_ +- Bugfix: ``cmd_wrapper`` added missing parameter ``conanfile``. `#13564 `_ . Docs `here `__ +- Bugfix: Avoid generators errors because dependencies binaries of editable packages were "skip". `#13544 `_ +- Bugfix: Fix subcommands names when the parent command has underscores. `#13516 `_ +- Bugfix: Fix ``python-requires`` in remotes when running :command:`conan export-pkg`. `#13496 `_ +- Bugfix: Editable packages now also follow ``build_folder_vars`` configuration. `#13488 `_ +- Bugfix: Fix ``[system_tools]`` profile composition. `#13468 `_ + +2.0.2 (15-Mar-2023) +------------------- + +- Feature: Allow relative paths to the Conan home folder in the ``global.conf``. `#13415 `_ . Docs `here `__ +- Feature: Some improvements for html formatter in :command:`conan list` command. `#13409 `_ . Docs `here `__ +- Feature: Adds an optional "build_script_folder" argument to the `autoreconf` method of the `Autotools` class. It mirrors the same argument and behavior of the `configure` method of the same class. That is, it allows one to override where the tool is run (by default it runs in the `source_folder`. `#13403 `_ +- Feature: Create summary of cached content. `#13386 `_ +- Feature: Add `conan config show ` command. `#13354 `_ . Docs `here `__ +- Feature: Allow ``global.conf`` jinja2 inclusion of other files. `#13336 `_ +- Feature: Add ``conan export-pkg --skip-binaries`` to allow exporting without binaries of dependencies. `#13324 `_ . Docs `here `__ +- Feature: Add `core.version_ranges:resolve_prereleases` conf to control whether version ranges can resolve to prerelease versions `#13321 `_ +- Fix: Allow automatic processing of ``package_type = "build-scripts"`` in :command:`conan create` as ``--build-require``. `#13433 `_ +- Fix: Improve the detection and messages of server side package corruption. `#13432 `_ +- Fix: Fix conan download help typo. `#13430 `_ +- Fix: Remove profile arguments from `conan profile path`. `#13423 `_ . Docs `here `__ +- Fix: Fix typo in _detect_compiler_version. `#13396 `_ +- Fix: Fix ``conan profile detect`` detection of ``libc++`` for ``clang`` compiler on OSX. `#13359 `_ +- Fix: Allow internal ``vswhere`` calls to detect and use VS pre-releases too. `#13355 `_ +- Fix: Allow :command:`conan export-pkg` to use remotes to install missing dependencies not in the cache. `#13324 `_ . Docs `here `__ +- Fix: Allow conversion to ``dict`` of ``settings.yml`` lists when ``settings_user.yml`` define a ``dict``. `#13323 `_ +- Fix: Fix flags passed by AutotoolsToolchain when cross compiling from macOS to a non-Apple OS. `#13230 `_ +- BugFix: Fix issues in ``MSBuild`` with custom configurations when custom configurations has spaces. `#13435 `_ +- Bugfix: Solve bug in ``conan profile path `` that was crashing. `#13434 `_ +- Bugfix: Add global verbosity conf `tools.build:verbosity` instead of individual ones. `#13428 `_ . Docs `here `__ +- Bugfix: Avoid raising fatal exceptions for malformed custom commands. `#13365 `_ +- Bugfix: Do not omit ``system_libs`` from dependencies even if they are header-only. `#13364 `_ +- Bugfix: Fix ``VirtualBuildEnv`` environment not being created when ``MesonToolchain`` is instantiated. `#13346 `_ +- Bugfix: Nicer error in the compatibility plugin with custom compilers. `#13328 `_ +- Bugfix: adds qcc cppstd compatibility info to allow dep graph to be calculated. `#13326 `_ + +2.0.1 (03-Mar-2023) +------------------- + +- Feature: Add `--insecure` alias to `--verify-ssl` in config install. `#13270 `_ . Docs `here `__ +- Feature: Add `.conanignore` support to `conan config install`. `#13269 `_ . Docs `here `__ +- Feature: Make verbose tracebacks on exception be shown for ``-vv`` and ``-vvv``, instead of custom env-var used in 1.X. `#13226 `_ +- Fix: Minor improvements to :command:`conan install` and 2.0-readiness error messages. `#13299 `_ +- Fix: Remove ``vcvars.bat`` VS telemetry env-var, to avoid Conan hanging. `#13293 `_ +- Fix: Remove legacy ``CMakeToolchain`` support for ``CMakePresets`` schema2 for ``CMakeUserPresets.json``. `#13288 `_ . Docs `here `__ +- Fix: Remove ``--logger`` json logging and legacy traces. `#13287 `_ . Docs `here `__ +- Fix: Fix typo in `conan remote auth` help. `#13285 `_ . Docs `here `__ +- Fix: Raise arg error if ``conan config list unexpected-arg``. `#13282 `_ +- Fix: Do not auto-detect ``compiler.runtime_type`` for ``msvc``, rely on profile plugin. `#13277 `_ +- Fix: Fix conanfile.txt options parsing error message. `#13266 `_ +- Fix: Improve error message for unified patterns in options. `#13264 `_ +- Fix: Allow ``conan remote add --force`` to force re-definition of an existing remote name. `#13249 `_ +- Fix: Restore printing of profiles for build command. `#13214 `_ +- Fix: Change :command:`conan build` argument description for "path" to indicate it is only for conanfile.py and explicitly state that it does not work with conanfile.txt. `#13211 `_ . Docs `here `__ +- Fix: Better error message when dependencies ``options`` are defined in ``requirements()`` method. `#13207 `_ +- Fix: Fix broken links to docs from error messages and readme. `#13186 `_ +- Bugfix: Ensure that `topics` are always serialized as lists. `#13298 `_ +- Bugfix: Ensure that `provides` are always serialized as lists. `#13298 `_ +- Bugfix: Fixed the detection of certain visual c++ installations. `#13284 `_ +- Bugfix: Fix supported ``cppstd`` values for ``msvc`` compiler. `#13278 `_ +- Bugfix: CMakeDeps generate files for ``tool_requires`` with the same ``build_type`` as the "host" context. `#13267 `_ +- Bugfix: Fix definition of patterns for dependencies options in configure(). `#13263 `_ +- Bugfix: Fix CMakeToolchain error when output folder in different Win drive. `#13248 `_ +- Bugfix: Do not raise errors if a ``test_requires`` is not used by components ``.requires``. `#13191 `_ + +2.0.0 (22-Feb-2023) +------------------- + +- Feature: Change default profile cppstd for apple-clang to gnu17. `#13185 `_ +- Feature: New ``conan remote auth`` command to force authentication in the remotes `#13180 `_ +- Fix: Allow defining options trait in ``test_requires(..., options={})`` `#13178 `_ +- Fix: Unifying Conan commands help messages. `#13176 `_ +- Bugfix: Fix MesonToolchain wrong cppstd in apple-clang `#13172 `_ +- Feature: Improved global Conan output messages (create, install, export, etc.) `#12746 `_ + +2.0.0-beta10 (16-Feb-2023) +-------------------------- + +- Feature: Add basic html output to `conan list` command. `#13135 `_ +- Feature: Allow ``test_package`` to process ``--build`` arguments (computing --build=never for the main, non test_package graph). `#13117 `_ +- Feature: Add `--force` argument to remote add. `#13112 `_ +- Feature: Validate if the input configurations exist, to avoid typos. `#13110 `_ +- Feature: Allow defining ``self.folders.build_folder_vars`` in recipes ``layout()``. `#13109 `_ +- Feature: Block settings assignment. `#13099 `_ +- Feature: Improve `conan editable` ui. `#13093 `_ +- Feature: Provide the ability for users to extend Conan generated CMakePresets. `#13090 `_ +- Feature: Add error messages to help with the migration of recipes to 2.0, both from ConanCenter and from user repos. `#13074 `_ +- Feature: Remove option.fPIC for shared in :command:`conan new` templates. `#13066 `_ +- Feature: Add `conan cache clean` subcommand to clean build and source folders. `#13050 `_ +- Feature: Implement customizable ``CMakeToolchain.presets_prefix`` so presets name prepend this. `#13015 `_ +- Feature: Add `[system_tools]` section to profiles to use your own installed tools instead of the packages declared in the requires. `#10166 `_ +- Fix: Fixes in powershell escaping. `#13084 `_ +- Fix: Define ``CMakeToolchain.presets_prefix="conan"`` by default, to avoid conflict with other users presets. `#13015 `_ + +2.0.0-beta9 (31-Jan-2023) +------------------------- + +- Feature: Add package names in Conan cache hash paths. `#13011 `_ +- Feature: Implement ``tools.build:download_source`` conf to force the installation of sources in :command:`conan install` or ``conan graph info``. `#13003 `_ +- Feature: Users can define their own settings in `settings_user.yml` that will be merged with the Conan `settings.yml`. `#12980 `_ +- Feature: List disabled remotes too. `#12937 `_ +- Fix: PkgConfiDeps is using the wrong ``dependencies.host`` from dependencies instead of ``get_transitive_requires()`` computation. `#13013 `_ +- Fix: Fixing transitive shared linux libraries in CMakeDeps. `#13010 `_ +- Fix: Fixing issues with test_package output folder. `#12992 `_ +- Fix: Improve error messages for wrong methods. `#12962 `_ +- Fix: Fix fail in parallel packages download due to database concurrency issues. `#12930 `_ +- Fix: Enable authentication against disabled remotes. `#12913 `_ +- Fix: Improving system_requirements. `#12912 `_ +- Fix: Change tar format to PAX, which is the Python3.8 default. `#12899 `_ + +2.0.0-beta8 (12-Jan-2023) +------------------------- + +- Feature: Add `unix_path_package_info_legacy` function for those cases in which it is used in `package_info` in recipes that require compatibility with Conan 1.x. In Conan 2, path conversions should not be performed in the `package_info` method. `#12886 `_ +- Feature: New serialization json and printing for ``conan list``. `#12883 `_ +- Feature: Add requirements to `conan new cmake_{lib,exe}` `#12875 `_ +- Feature: Allow ``--no-remotes`` to force temporal disabling of remotes `#12808 `_ +- Feature: Add barebones template option to conan new. `#12802 `_ +- Feature: Avoid requesting package configuration if PkgID is passed. `#12801 `_ +- Feature: Implemented `conan list *#latest` and `conan list *:*#latest`. Basically, this command can show the latest RREVs and PREVs for all the matching references. `#12781 `_ +- Feature: Allow chaining of `self.output` write methods `#12780 `_ +- Fix: Make ``graph info`` filters to work on json output too `#12836 `_ +- Bugfix: Fix bug to pass a valid GNU triplet when using AutotoolsToolchain and cross-building on Windows. `#12881 `_ +- Bugfix: Ordering if same ref.name but different versions. `#12801 `_ + +2.0.0-beta7 (22-Dec-2022) +------------------------- + +- Feature: Raise an error when a generator is both defined in generators attribute and instantiated in generate() method `#12722 `_ +- Feature: `test_requires` improvements, including allowing it in conanfile.txt `#12699 `_ +- Feature: Improve errors for when required_conan_version has spaces between the operator and the version `#12695 `_ +- Feature: ConanAPI cleanup and organization `#12666 `_ + +2.0.0-beta6 (02-Dec-2022) +------------------------- + +- Feature: Use ``--confirm`` to not request confirmation when removing instead of ``--force`` `#12636 `_ +- Feature: Simplify loading conaninfo.txt for search results `#12616 `_ +- Feature: Renamed ConanAPIV2 to ConanAPI `#12615 `_ +- Feature: Refactor ConanAPI `#12615 `_ +- Feature: Improve conan cache path command `#12554 `_ +- Feature: Improve #latest and pattern selection from remove/upload/download `#12572 `_ +- Feature: Add build_modules to provided deprecated warning to allow migration from 1.x `#12578 `_ +- Feature: Lockfiles alias support `#12525 `_ + +2.0.0-beta5 (11-Nov-2022) +------------------------- + +- Feature: Improvements in the remotes management and API `#12468 `_ +- Feature: Implement env_info and user_info as fake attributes in Conan 2.0 `#12351 `_ +- Feature: Improve settings.rm_safe() `#12379 `_ +- Feature: New RecipeReference equality `#12506 `_ +- Feature: Simplifying compress and uncompress of .tgz files `#12378 `_ +- Feature: conan source command does not require a default profile `#12475 `_ +- Feature: Created a proper LockfileAPI, with detailed methods (update, save, etc), instead of several loose methods `#12502 `_ +- Feature: The conan export can also produce lockfiles, necessary for users doing a 2 step (export + install--build) process `#12502 `_ +- Feature: Drop compat_app `#12484 `_ +- Fix: Fix transitive propagation of transitive_headers=True `#12508 `_ +- Fix: Fix transitive propagation of transitive_libs=False for static libraries `#12508 `_ +- Fix: Fix test_package for python_requires `#12508 `_ + +2.0.0-beta4 (11-Oct-2022) +------------------------- + +- Feature: Do not allow doing conan create/export with uncommitted changes using revision_mode=scm `#12267 `_ +- Feature: Simplify conan inspect command, removing path subcommand `#12263 `_ +- Feature: Add --deploy argument to graph info command `#12243 `_ +- Feature: Pass graph object to deployers instead of ConanFile `#12243 `_ +- Feature: Add included_files method to conan.tools.scm.Git `#12246 `_ +- Feature: Improve detection of clang libcxx `#12251 `_ +- Feature: Remove old profile variables system in favor of Jinja2 syntax in profiles `#12152 `_ +- Fix: Update command to follow Conan 2.0 conventions about CLI output `#12235 `_ +- Fix: Fix aggregation of test trait in diamonds `#12080 `_ + +2.0.0-beta3 (12-Sept-2022) +-------------------------- + +- Feature: Decouple test_package from create. `#12046 `_ +- Feature: Warn if special chars in exported refs. `#12053 `_ +- Feature: Improvements in MSBuildDeps traits. `#12032 `_ +- Feature: Added support for CLICOLOR_FORCE env var, that will activate the colors in the output if the value is declared and different to 0. `#12028 `_ +- Fix: Call source() just once for all configurations. `#12050 `_ +- Fix: Fix deployers not creating output_folder. `#11977 `_ +- Fix: Fix build_id() removal of require. `#12019 `_ +- Fix: If Conan fails to load a custom command now it fails with a useful error message. `#11720 `_ +- Bugfix: If the 'os' is not specified in the build profile and a recipe, in Windows, wanted to run a command. `#11728 `_ + +2.0.0-beta2 (27-Jul-2022) +------------------------- + +- Feature: Add traits support in MSBuildDeps. `#11680 `_ +- Feature: Add traits support in XcodeDeps. `#11615 `_ +- Feature: Let dependency define package_id modes. `# `_ +- Feature: Add ``conan.conanrc`` file to setup the conan user home. `#11675 `_ +- Feature: Add ``core.cache:storage_path`` to declare the absolute path where you want to store the Conan packages. `#11672 `_ +- Feature: Add tools for checking max cppstd version. `#11610 `_ +- Feature: Add a ``post_build_fail`` hook that is called when a build fails. `#11593 `_ +- Feature: Add ``pre_generate`` and ``post_generate`` hook, covering the generation of files around the ``generate()`` method call. `#11593 `_ +- Feature: Brought ``conan config list`` command back and other conf improvements. `#11575 `_ +- Feature: Added two new arguments for all commands -v for controlling the verbosity of the output and --logger to output the contents in a json log format for log processors. `#11522 `_ + +2.0.0-beta1 (20-Jun-2022) +------------------------- + +- Feature: New graph model to better support C and C++ binaries relationships, compilation, and linkage. +- Feature: New documented public Python API, for user automation +- Feature: New build system integrations, more flexible and powerful, and providing transparent integration when possible, like ``CMakeDeps`` and ``CMakeToolchain`` +- Feature: New custom user commands, that can be built using the public PythonAPI and can be shared and installed with ``conan config install`` +- Feature: New CLI interface, with cleaner commands and more structured output +- Feature: New deployers mechanism to copy artifacts from the cache to user folders, and consume those copies while building. +- Feature: Improved ``package_id`` computation, taking into account the new more detailed graph model. +- Feature: Added ``compatibility.py`` extension mechanism to allow users to define binary compatibility globally. +- Feature: Simpler and more powerful ``lockfiles`` to provide reproducibility over time. +- Feature: Better configuration with ``[conf]`` and better environment management with the new ``conan.tools.env`` tools. +- Feature: Conan cache now can store multiple revisions simultaneously. +- Feature: New extensions plugins to implement profile checking, package signing, and build commands wrapping. +- Feature: Used the package immutability for an improved update, install and upload flows. diff --git a/2.1/_sources/devops.rst.txt b/2.1/_sources/devops.rst.txt new file mode 100644 index 000000000000..57e4d35915fc --- /dev/null +++ b/2.1/_sources/devops.rst.txt @@ -0,0 +1,19 @@ +.. _devops: + + +Devops guide +============ + +The previous tutorial section was aimed at users in general and developers. + +This section is intended for DevOps users, build and CI engineers, administrators, and architects adopting, designing and implementing Conan in production in their teams and organizations. +If you plan to use Conan in production in your project, team, or organization, this section contains the necessary information. + +.. toctree:: + :maxdepth: 1 + + devops/using_conancenter + devops/backup_sources/sources_backup + devops/metadata + devops/versioning + devops/save_restore diff --git a/2.1/_sources/devops/backup_sources/repositories/artifactory/creating_backup_sources_repo.rst.txt b/2.1/_sources/devops/backup_sources/repositories/artifactory/creating_backup_sources_repo.rst.txt new file mode 100644 index 000000000000..5e3f44642e60 --- /dev/null +++ b/2.1/_sources/devops/backup_sources/repositories/artifactory/creating_backup_sources_repo.rst.txt @@ -0,0 +1,49 @@ +.. _devops_artifactory_backup_sources_repo: + +Creating an Artifactory backup repo for your sources +==================================================== + +For the backup repository, we'll create a generic Artifactory repo using the free Community Edition version. + +For this, in the repositories section of the administration tab, +we'll create a new generic repository, and in this example we'll imaginatively give it the name of *backup-sources*. + +The URL of the remote should now be added to the :ref:`global.conf` file's +``core.sources:upload_url`` conf + +.. code-block:: text + :caption: global.conf + + core.sources:upload_url=https://myteam.myorg.com/artifactory/backup-sources/ + + +Next, as we want this to be a public read repo, we'll allow anonymous read access to our repo. +`See the official Artifactory documentation for a step-by-step guide on how to create one `_. + +Now, to be able to upload contents, we'll also create a new user from the User Management section, called *backup uploader*, +and from the Access Tokens section, we'll generate a reference token associated with the user + +.. image:: images/create_reference_token.png + + +The generated token should now live in the :ref:`source_credentials.json` file: + +.. code-block:: json + :caption: source_credentials.json + + { + "credentials": [ + { + "url": "https://myteam.myorg.com/artifactory/backup-sources/", + "token": "cmVmdGtu1234567890abcdefghijklmnopqrstuvwxyz" + } + ] + } + + +And last but not least, from the Permissions section we'll give the user manage access to the new repository +(which will automatically give it every other permission available, feel free to modify them according to your needs) + +.. image:: images/permissions_add_backup_access.png + +With this, access to our remote backup is now configured to allow anonymous read but authenticated upload. diff --git a/2.1/_sources/devops/backup_sources/sources_backup.rst.txt b/2.1/_sources/devops/backup_sources/sources_backup.rst.txt new file mode 100644 index 000000000000..f6968cd3edb6 --- /dev/null +++ b/2.1/_sources/devops/backup_sources/sources_backup.rst.txt @@ -0,0 +1,151 @@ +.. _conan_backup_sources: + +Backing up third-party sources with Conan +========================================= + +For recipes and build scripts for open source, publicly available libraries, +it is common practice to download the sources from a canonical source, like Github releases, or project download web pages. +Keeping a record of the origin of these files is useful for traceability purposes, however, +it is often not guaranteed that the files will be available in the long term, +and a user in the future building the same recipe from source may encounter a problem. +Conan can thus be configured to transparently retrieve sources from a configured mirror, +without modifying the recipes or `conandata.yml`. +Additionally, these sources can be transparently uploaded alongside the packages via :command:`conan upload`. + +The *sources backup* feature is intended for storing the downloaded recipe sources in a file server in your own infrastructure, +allowing future reproducibility of your builds even in the case where the original download URLs are no longer accessible. + +The backup is triggered for calls to the :ref:`download` and :ref:`get` methods +when a ``sha256`` file signature is provided. + + +.. _backup_sources_config: + +Configuration overview +---------------------- + +This feature is controlled by a few :ref:`global.conf` items: + +* ``core.sources:download_cache``: Local path to store the sources backups to. + *If not set, the default Conan home cache path will be used.* +* ``core.sources:download_urls``: Ordered list of URLs that Conan will try to download the sources from, + where ``origin`` represents the original URL passed to ``get``/``download`` from `conandata.yml`. + This allows to control the fetch order, either ``["origin", "https://your.backup/remote/"]`` + to look into and fetch from your backup remote only if and when the original source is not present, + or ``["https://your.backup/remote/", "origin"]`` to prefer your backup server ahead of the recipes' canonical links. + Being a list, multiple remotes are also possible. ``["origin"]`` *by default* +* ``core.sources:upload_url``: URL of the remote to upload the backups to when calling :command:`conan upload`, + which might or might not be different from any of the URLs defined for download. *Empty by default* +* ``core.sources:exclude_urls``: List of origins to skip backing up. + If the URL passed to ``get``/``download`` starts with any of the origins included in this list, + the source won't be uploaded to the backup remote when calling :command:`conan upload`. *Empty by default* + + +Usage +----- + +Let's overview how the feature works by providing an example usage from beginning to end: + +In summary, it looks something like: + +- A remote backup repository is set up. This should allow ``PUT`` and ``GET`` HTTP methods to modify and fetch its contents. + If access credentials are desired (which is strongly recommended for uploading permissions), + you can use the :ref:`source_credentials.json` feature. + :ref:`See below` if you are in need for configuring your own. +- The remote's URL can then be set in ``core.sources:download_urls`` and ``core.sources:upload_url``. +- In your recipe's ``source()`` method, ensure the relevant ``get``/``download`` + calls supply the ``sha256`` signature of the downloaded files. +- Set ``core.sources:download_cache`` in your :ref:`global.conf` file if a custom location is desired, + else the default cache folder will be used +- Run Conan normally, creating packages etc. +- Once some sources have been locally downloaded, the folder pointed to by ``core.sources:download_cache`` will contain, for each downloaded file: + - A blob file (no extensions) with the name of the ``sha256`` signature provided in ``get``/``download``. + - A ``.json`` file which will also have the name of the ``sha256`` signature, + that will contain information about which references and which mirrors this blob belongs to. +- Calling ``conan upload`` will now optionally upload the backups for the matching references if ``core.sources:upload_url`` is set. + +.. note:: + + :ref:`See below` for a guide on how to configure your own backup server + + +Setting up the necessary configs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`global.conf` file should contain the +``core.sources:download_urls`` + +.. code-block:: text + :caption: global.conf + + core.sources:download_urls=["https://myteam.myorg.com/artifactory/backup-sources/", "origin"] + + +You might want to add extra confs based on your use case, as described :ref:`in the beginning of this document`. + +.. note:: + + The recommended approach for dealing with the configuration of CI workers and developers in your organization is + to install the configs using the ``conan config install`` command on a repository. Read more :ref:`here` + + +Run Conan as normal +~~~~~~~~~~~~~~~~~~~ + +With the above steps completed, Conan can now be used as normal, and for every downloaded source, +Conan will first look into the folder indicated in ``core.sources:download_cache``, and if not found there, +will traverse ``core.sources:download_urls`` until it find the file or fails, +and store a local copy in the same ``core.sources:download_cache`` location. + +When the backup is fetched from the the backup remote, a message like what follows will be shown to the user: + +.. code-block:: text + :caption: The client will now print information regarding from which remote it was capable of downloading the sources + + $ conan create . --version=1.3 + + ... + + ======== Installing packages ======== + zlib/1.3: Calling source() in /Users/ruben/.conan2/p/zlib0f4e45286ecd1/s/src + zlib/1.3: Sources for ['https://zlib.net/fossils/zlib-1.3.tar.gz', 'https://github.com/madler/zlib/releases/download/v1.3/zlib-1.3.tar.gz'] + found in remote backup https://myteam.myorg.com/artifactory/backup-sources + + -------- Installing package zlib/1.3 (1 of 1) -------- + + ... + + +If we now again try to run this, we'll find that no download is performed and the locally stored version of the files is used. + + +Upload the packages +~~~~~~~~~~~~~~~~~~~ + +Once a package has been created as shown above, when a call to ``conan upload zlib/1.3 -c`` is performed +to upload the resulting binary to your Conan repository, it will also upload the source backups for that same reference +to your backups remote if configured to do so, +and future source downloads of this recipe will use the newly updated contents when necessary. + +.. note:: + + See :ref:`the packages list feature` for a way to only upload the packages that have been built + + +In case there's a need to upload backups for sources not linked to any package, or for packages that are already on the remote and would therefore be skipped during upload, the :command:`conan cache backup-upload` command can be used to address this scenario. + +.. _backup_sources_setup_remote: + +Creating the backup repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also set up your own remote backup repository instead of relying on an already available one. +While an Artifactory generic repository (available for free with Artifactory CE) is recommend for this purpose, +any simple server that allows ``PUT`` and ``GET`` HTTP methods to modify and fetch its contents is sufficient. + +Read the following section for instructions on how to create a generic Artifactory backup repo and how to give it public read permissions, +while keeping write access only for authorized agents + +.. toctree:: + + repositories/artifactory/creating_backup_sources_repo diff --git a/2.1/_sources/devops/conancenter/hosting_binaries.rst.txt b/2.1/_sources/devops/conancenter/hosting_binaries.rst.txt new file mode 100644 index 000000000000..53df53767bd5 --- /dev/null +++ b/2.1/_sources/devops/conancenter/hosting_binaries.rst.txt @@ -0,0 +1,34 @@ +.. _devops_conancenter_hosting_your_own_conancenter_fork: + +Creating and hosting your own ConanCenter binaries +================================================== + + +Hosting your own copy of the packages you need in your server could be done by just downloading binaries from ConanCenter and then uploading them to your own server. However, it is much better to fully own the complete supply chain and create the binaries in your own CI systems. So the recommended flow to use ConanCenter packages in production would be: + +- Create a fork of the ConanCenter Github repository: https://github.com/conan-io/conan-center-index +- Create a list of the packages and versions you need for your projects. This list can be added to the fork too, and maintained there (packages can be added and removed with PRs when the teams need them). +- Create a script that first ``conan export`` all the packages in your list, then ``conan create --build=missing`` them. Do not add ``user/channel`` to these packages, it is way simpler to use them as ``zlib/1.2.13`` without user-channel. The ``user/channel`` part would be mostly recommended for your own proprietary packages, but not for open source ConanCenter packages. +- Upload your build packages to your own server, that you use in production, instead of ConanCenter. + +This is the basic flow idea. We will be adding examples and tools to further automate this flow as soon as possible. + + +This flow is relatively straightforward, and has many advantages that mitigate the risks described before: + +- No central repository outage can affect your builds. +- No changes in the central repository can break your projects, you are in full control when and how those changes are updated in your packages (as explained below). +- You can customize, adapt, fix and perfectly control what versions are used, and release fixes in minutes, not weeks. You can apply customizations that wouldn't be accepted in the central repository. +- You fully control the binaries supply chain, from the source (recipes) to the binaries, eliminating in practice the majority of potential supply chain attacks of central repositories. + + +Updating from upstream +++++++++++++++++++++++ + +Updating from the upstream ``conan-center-index`` Github repo is still possible, and it can be done in a fully controlled way: + +- Merge the latest changes in the upstream main fork of ``conan-center-index`` into your fork. +- You can check and audit those changes if you want to, analyzing the diffs (some automation that trims the diffs of recipes that you don't use could be useful) +- Firing the above process will efficiently rebuild the new binaries that are needed. If your recipes are not affected by changes, the process will avoid rebuilding binaries (thanks to ``--build=missing``). +- You can upload the packages to a secondary "test" server repository. Then test your project against that test server, to check that your project is not broken by the new ConanCenter packages. +- Once you verify that everything is good with the new packages, you can copy them from the secondary "test" repository to your main production repository to start using them. diff --git a/2.1/_sources/devops/metadata.rst.txt b/2.1/_sources/devops/metadata.rst.txt new file mode 100644 index 000000000000..9b7b98c64e34 --- /dev/null +++ b/2.1/_sources/devops/metadata.rst.txt @@ -0,0 +1,346 @@ +.. _devops_metadata: + +Managing package metadata files +=============================== + +.. include:: ../common/experimental_warning.inc + + +A Conan package is typically composed by several C and C++ artifacts, headers, compiled libraries and executables. But there are other files that might not be necessary for the normal consumption of such a package, but which could be very important for compliance, technical or business reasons, for example: + +- Full build logs +- The tests executables +- The tests results from running the test suite +- Debugging artifacts like heavy .pdb files +- Coverage, sanitizers, or other source or binary analysis tools results +- Context and metadata about the build, exact machine, environment, author, CI data +- Other compliance and security related files + + +There are several important reasons to store and track these files like regulations, compliance, security, reproducibility and traceability. +The problem with these files is that they can be large/heavy, if we store them inside the package (just copying the artifacts in the ``package()`` method), this will make the packages much larger, and it will affect the speed of downloading, unzipping and using packages in general. And this typically happens a lot of times, both in developer machines but also in CI, and it can have an impact on the developer experience and infrastructure costs. Furthermore, packages are immutable, that is, once a package has been created, it shouldn't be modified. This might be a problem if we want to add extra metadata files after the package has been created, or even after the package has been uploaded. + + +The **metadata files** feature allows to create, upload, append and store metadata associated to packages in an integrated and unified way, while avoiding the impact on developers and CI speed and costs, because metadata files are not downloaded and unzipped by default when packages are used. + + +It is important to highlight that there are two types of metadata: + +- Recipe metadata, associated to the ``conanfile.py`` recipe, the metadata should be common to all binaries created from this recipe (package name, version and recipe revision). This metadata will probably be less common, but for example results of some scanning of the source code, that would be common for all configurations and builds, can be recipe metadata. +- Package binary metadata, associated to the package binary for a given specific configuration and represented by a ``package_id``. Build logs, tests reports, etc, that are specific to a binary configuration will be package metadata. + + +Creating metadata in recipes +---------------------------- +Recipes can directly define metadata in their methods. A common use case would be to store logs. +Using the ``self.recipe_metadata_folder`` and ``self.package_metadata_folder``, the recipe can store files +in those locations. + +.. code-block:: python + + import os + from conan import ConanFile + from conan.tools.files import save, copy + + class Pkg(ConanFile): + name = "pkg" + version = "0.1" + + def layout(self): + # Or something else, like the "cmake_layout(self)" built-in layout + self.folders.build = "mybuild" + self.folders.generators = "mybuild/generators" + + def export(self): + # logs that might be generated in the recipe folder at "export" time. + # these would be associated with the recipe repo and original source of the recipe repo + copy(self, "*.log", src=self.recipe_folder, + dst=os.path.join(self.recipe_metadata_folder, "logs")) + + def source(self): + # logs originated in the source() step, for example downloading files, patches or other stuff + save(self, os.path.join(self.recipe_metadata_folder, "logs", "src.log"), "srclog!!") + + def build(self): + # logs originated at build() step, the most common ones + save(self, "mylogs.txt", "some logs!!!") + copy(self, "mylogs.txt", src=self.build_folder, + dst=os.path.join(self.package_metadata_folder, "logs")) + + +Note that "recipe" methods (those that are common for all binaries, like ``export()`` and ``source()``) should use +``self.recipe_metadata_folder``, while "package" specific methods (``build()``, ``package()``) should use the +``self.package_metadata_folder``. + +Doing a ``conan create`` over this recipe, will create "metadata" folders in the Conan cache. We can have a look at those folders with: + +.. code-block:: bash + + $ conan create . + $ conan cache path pkg/0.1 --folder=metadata + # folder containing the recipe metadata + $ conan cache path pkg/0.1:package_id --folder=metadata + # folder containing the specific "package_id" binary metadata + + +It is also possible to use the "local flow" commands and get local "metadata" folders. If we want to do this, it is very recommended +to use a ``layout()`` method like above to avoid cluttering the current folder. Then the local commands will allow to test and debug the functionality: + +.. code-block:: bash + + $ conan source . + # check local metadata/logs/src.log file + $ conan build . + # check local mybuild/metadata/logs/mylogs.txt file + + +**NOTE**: This metadata is not valid for the ``conan export-pkg`` flow. If you want to use the ``export-pkg`` flow you might want to check the +"Adding metadata" section below. + + +Creating metadata with hooks +---------------------------- +If there is some common metadata accross recipes, it is possible to capture it without modifying the recipes, using hooks. +Let's say that we have a simpler recipe: + +.. code-block:: python + + import os + from conan import ConanFile + from conan.tools.files import save, copy + + class Pkg(ConanFile): + name = "pkg" + version = "0.1" + no_copy_source = True + + def layout(self): + self.folders.build = "mybuild" + self.folders.generators = "mybuild/generators" + + def source(self): + save(self, "logs/src.log", "srclog!!") + + def build(self): + save(self, "logs/mylogs.txt", "some logs!!!") + +As we can see, this is not using the metadata folders at all. +Let's define now the following hooks: + +.. code-block:: python + + import os + from conan.tools.files import copy + + def post_export(conanfile): + conanfile.output.info("post_export") + copy(conanfile, "*.log", src=conanfile.recipe_folder, + dst=os.path.join(conanfile.recipe_metadata_folder, "logs")) + + def post_source(conanfile): + conanfile.output.info("post_source") + copy(conanfile, "*", src=os.path.join(conanfile.source_folder, "logs"), + dst=os.path.join(conanfile.recipe_metadata_folder, "logs")) + + def post_build(conanfile): + conanfile.output.info("post_build") + copy(conanfile, "*", src=os.path.join(conanfile.build_folder, "logs"), + dst=os.path.join(conanfile.package_metadata_folder, "logs")) + + +The usage of these hooks will have a very similar effect to the in-recipe approach: the metadata files +will be created in the cache when ``conan create`` executes, and also locally for the ``conan source`` and ``conan build`` +local flow. + + +Adding metadata with commands +----------------------------- + +Metadata files can be added or modified after the package has been created. To achieve this, using the ``conan cache path`` +command will return the folders to do that operation, so copying, creating or modifying files in that location will achieve this. + +.. code-block:: bash + + $ conan create . --name=pkg --version=0.1 + $ conan cache path pkg/0.1 --folder=metadata + # folder to put the metadata, initially empty if we didn't use hooks + # and the recipe didn't store any metadata. We can copy and put files + # in the folder + $ conan cache path pkg/0.1:package_id --folder=metadata + # same as above, for the package metadata, we can copy and put files in + # the returned folder + + +This metadata is added locally, in the Conan cache. If you want to update the server metadata, uploading it from the cache is necessary. + + +Uploading metadata +------------------ + +So far the metadata has been created locally, stored in the Conan cache. Uploading the metadata to the server is integrated with +the existing ``conan upload`` command: + +.. code-block:: bash + + $ conan upload "*" -c -r=default + # Uploads recipes, packages and metadata to the "default" remote + ... + pkg/0.1: Recipe metadata: 1 files + pkg/0.1:da39a3ee5e6b4b0d3255bfef95601890afd80709: Package metadata: 1 files + + +By default, ``conan upload`` will upload recipes and packages metadata when a recipe or a package is uploaded to the server. +But there are some situations that Conan will completely avoid this upload, if it detects that the revisions do already exist +in the server, it will not upload the recipes or the packages. +If the metadata has been locally modified or added new files, we can force the upload explicitly with: + +.. code-block:: bash + + # We added some metadata to the packages in the cache + # But those packages already exist in the server + $ conan upload "*" -c -r=default --metadata="*" + ... + pkg/0.1: Recipe metadata: 1 files + pkg/0.1:da39a3ee5e6b4b0d3255bfef95601890afd80709: Package metadata: 1 files + +The ``--metadata`` argument allows to specify the metadata files that we are uploading. If we structure them in folders, +we could specify ``--metadata="logs*"`` to upload only the logs metadata, but not other possible ones like ``test`` metadata. + +.. code-block:: bash + + # Upload only the logs metadata of the zlib/1.2.13 binaries + # This will upload the logs even if zlib/1.2.13 is already in the server + $ conan upload "zlib/1.2.13:*" -r=remote -c --metadata="logs/*" + # Multiple patterns are allowed: + $ conan upload "*" -r=remote -c --metadata="logs/*" --metadata="tests/*" + +Sometimes it might be useful to upload packages without uploading the metadata, even if the metadata cache folders contain files. +To ignore uploading the metadata, use an empty argument as metadata pattern: + +.. code-block:: bash + + # Upload only the packages, not the metadata + $ conan upload "*" -r=remote -c --metadata="" + +The case of mixing ``--metadata=""`` with ``--metadata="*"`` is not allowed, and it will raise an error. + +.. code-block:: bash + + # Invalid command, it will raise an error + $ conan upload "*" -r=remote -c --metadata="" --metadata="logs/*" + ERROR: Empty string and patterns can not be mixed for metadata. + + +Downloading metadata +-------------------- + +As described above, metadata is not downloaded by default. When packages are downloaded with a ``conan install`` or ``conan create`` +fetching dependencies from the servers, the metadata from those servers will not be downloaded. + +The way to recover the metadata from the server is to explicitly specify it with the ``conan download`` command: + +.. code-block:: bash + + # Get the metadata of the "pkg/0.1" package + $ conan download pkg/0.1 -r=default --metadata="*" + ... + $ conan cache path pkg/0.1 --folder=metadata + # Inspect the recipe metadata in the returned folder + $ conan cache path pkg/0.1:package_id --folder=metadata + # Inspect the package metadata for binary "package_id" + + +The retrieval of the metadata is done with ``download`` per-package. If we want to download the metadata for a whole dependency graph, it is necessary to use "package-lists": + +.. code-block:: bash + + $ conan install . --format=json -r=remote > graph.json + $ conan list --graph=graph.json --format=json > pkglist.json + # the list will contain the "remote" origin of downloaded packages + $ conan download --list=pkglist.json --metadata="*" -r=remote + + +Note that the "package-list" will only contain associated to the "remote" origin the packages that were downloaded. If they were previously in the cache, then, they will not be listed under the "remote" origin and the metadata will not be downloaded. If you want to collect the dependencies metadata, recall to download it when the package is installed from the server. +There are other possibilities, like a custom command that can automatically collect and download dependencies metadata from the servers. + + +Removing metadata +----------------- +At the moment it is not possible to remove metadata from the server side using Conan, as the metadata are "additive", it is possible to add new data, but not to remove it (otherwise it would not be possible to add new metadata without downloading first all the previous metadata, and that can be quite inefficient and more error prone, specially sensitive to possible race conditions). + +The recommendation to remove metatada from the server side would be to use the tools, web interface or APIs that the server might provide. + +.. note:: + + **Best practices** + + - Metadata shouldn't be necessary for using packages. It should be possible to consume recipes and packages without downloading their + metadata. If metadata is mandatory for a package to be used, then it is not metadata and should be packaged as headers and binaries. + - Metadata reading access should not be a frequent operation, or something that developers have to do. Metadata read is intended for + excepcional cases, when some build logs need to be recovered for compliance, or some test executables might be needed for debugging or + re-checking a crash. + - Conan does not do any compression or decompression of the metadata files. If there are a lot of metadata files, consider zipping them yourself, otherwise the upload of those many files can take a lot of time. If you need to handle different types of metadata (logs, tests, reports), zipping the files under each category might be better to be able to filter with the ``--metadata=xxx`` argument. + + +test_package as metadata +------------------------ + +This is an illustrative example of usage of metadata, storing the full ``test_package`` folder as +metadata to later recover it and execute it. Note that this is not necessarily intended for production. + +Let's start with a hook that automatically stores as **recipe metadata** the ``test_package`` folder + +.. code-block:: python + + import os + from conan.tools.files import copy + + def post_export(conanfile): + conanfile.output.info("Storing test_package") + folder = os.path.join(conanfile.recipe_folder, "test_package") + copy(conanfile, "*", src=folder, + dst=os.path.join(conanfile.recipe_metadata_folder, "test_package")) + + +Note that this hook doesn't take into account that ``test_package`` can be dirty with tons of temporary build +objects (it should be cleaned before being added to metadata), and it doesn't check that ``test_package`` might +not exist at all and crash. + +When a package is created and uploaded, it will upload to the server the recipe metadata containing the ``test_package``: + +.. code-block:: bash + + $ conan create ... + $ conan upload "*" -c -r=default # uploads metadata + ... + pkg/0.1: Recipe metadata: 1 files + +Let's remove the local copy, and assume that the package is installed, but the metadata is not: + +.. code-block:: bash + + $ conan remove "*" -c # lets remove the local packages + $ conan install --requires=pkg/0.1 -r=default # this will not download metadata + + +If at this stage the installed package is failing in our application, we could recover the ``test_package``, +downloading it, and copying it to our current folder: + +.. code-block:: bash + + $ conan download pkg/0.1 -r=default --metadata="test_package*" + $ conan cache path pkg/0.1 --folder=metadata + # copy the test_package folder from the cache, to the current folder + # like `cp -R ...` + + # Execute the test_package + $ conan test metadata/test_package pkg/0.1 + pkg/0.1 (test package): Running test() + + +.. seealso:: + + - TODO: Examples how to collect the metadata of a complete dependency graph with some custom deployer or command + + +This is an **experimental** feature. We are looking forward to hearing your feedback, use cases and needs, to keep improving this feature. Please report it in `Github issues `_ diff --git a/2.1/_sources/devops/save_restore.rst.txt b/2.1/_sources/devops/save_restore.rst.txt new file mode 100644 index 000000000000..7a5314e398f7 --- /dev/null +++ b/2.1/_sources/devops/save_restore.rst.txt @@ -0,0 +1,59 @@ +.. _devops_save_restore: + +Save and restore packages from/to the cache +=========================================== + +.. include:: ../common/experimental_warning.inc + +With the ``conan cache save`` and ``conan cache restore`` commands, it is possible to create a .tgz from one or several packages from a Conan cache and later restore those packages into another Conan cache. There are some scenarios this can be useful: + +- In Continuous Integration, specially if doing distributed builds, it might be very convenient to be able to move temporary packages recently built. Most CI systems have the capability of transferring files between jobs for this purpose. The Conan cache is not concurrent, sometimes for paralllel jobs different caches have to be used. +- For air-gapped setups, in which packages can only be transferred via client side. +- Developers directly sharing some packages with other developers for testing or inspection. + + +The process of saving the packages is using the ``conan cache save`` command. +It can use a pattern, like the ``conan list`` command, but it can also accept a package-list, like other commands like ``remove, upload, download``. For example: + +.. code-block:: bash + + $ conan cache save "pkg/*:*" + Saving pkg/1.0: p/pkg1df6df1a3b33c + Saving pkg/1.0:9a4eb3c8701508aa9458b1a73d0633783ecc2270: p/b/pkgd573962ec2c90/p + Saving pkg/1.0:9a4eb3c8701508aa9458b1a73d0633783ecc2270 metadata: p/b/pkgd573962ec2c90/p + ... + # creates conan_cache_save.tgz + +The ``conan_cache_save.tgz`` file contains the packages named ``pkg`` (any version), the last recipe revision, and the last package revision of all the package binaries. +The name of the file can be changed with the optional ``--file=xxxx`` argument. Some important considerations: + +- The command saves the contents of the cache "recipe" folders, containing the subfolders "export", "export_sources", "download", "source" and recipe "metadata". +- The command saves the contents of the "package" and the package "metadata" folders, but not the binary "build" or "download", that are considered temporary folders. +- If the user doesn't want any of those folders to be saved, they can be cleaned before saving them with ``conan cache clean`` command +- The command saves the cache files and artifacts as well as the metadata (revisions, package_id) to be able to restore those packages in another cache. But it doesn't save any other cache state like ``settings.yml``, ``global.conf``, ``remotes``, etc. If the saved packages require any other specific configuration, it should be managed with ``conan config install``. + +We can move this ``conan_cache_save.tgz`` file to another Conan cache and restore it as: + +.. code-block:: bash + + $ conan cache restore conan_cache_save.tgz + Restore: pkg/1.0 in p/pkg1df6df1a3b33c + Restore: pkg/1.0:9a4eb3c8701508aa9458b1a73d0633783ecc2270 in p/b/pkg773791b8c97aa/p + Restore: pkg/1.0:9a4eb3c8701508aa9458b1a73d0633783ecc2270 metadata in p/b/pkg773791b8c97aa/d/metadata + ... + +The restore process will overwrite existing packages if they already exist in the cache. + + +.. note:: + + **Best practices** + + - Saving and restoring packages is not a substitute for proper storage (upload) of packages in a Conan server repository. + It is only intended as a transitory mechanism, in CI systems, to save an air-gap, etc., but not as a long-term storage + and retrieval. + - Saving and restoring packages is not a substitute for proper backup of server repositories. The recommended way to + implement long term backup of Conan packages is using some server side backup strategy. + - The storage format and serialization is not guaranteed at this moment to be future-proof and stable. It is expected + to work in the same Conan version, but future Conan versions might break the storage format created with previous versions. + (this is aligned with the above recommendation to not use it as a backup strategy) diff --git a/2.1/_sources/devops/using_conancenter.rst.txt b/2.1/_sources/devops/using_conancenter.rst.txt new file mode 100644 index 000000000000..9fca935027db --- /dev/null +++ b/2.1/_sources/devops/using_conancenter.rst.txt @@ -0,0 +1,124 @@ +.. _devops_consuming_conan_center: + +Using ConanCenter packages in production environments +===================================================== + +ConanCenter is a fantastic resource that contains reference implementations of +recipes for over 1500 libraries and applications contributed by the community. +As such, it is a great knowledge base on how to create and build Conan packages +for open source dependencies. + +ConanCenter also builds and provides binary packages for a wide range of +configurations: multiple operating systems (Windows, Linux, macOS), compilers, +compiler versions, and library variants (shared, static). On top of this, +for a lot of libraries community contributors ensure that recipes are compatible +for additional operating systems (Android, iOS, FreeBSD, QNX) and CPU architectures. +The recipes in Conan Center are the greatest example of Conan’s universality promise. + +Unlike other package managers or repositories, ConanCenter does not maintain a +fixed snapshot of versions. On the contrary, for a given library (e.g. OpenCV), +multiple versions are actively maintained at the same time. This gives users +greater control of which versions to use, rather than having to remain fixed +to an older version, or pushing them to always be on the latest version. + +In order to support this ecosystem, ConanCenter recipes are updated very +frequently. Recipes themselves may be updated to support a new platform, +bug fixes, or to require newer versions of their dependencies. +On the other hand, each user of ConanCenter may have a different combination +of versions in their requirements. This means that given the same input +list of requirements, Conan may resolve the graph differently at different +points in time - resolving to different recipe revisions, versions, or packages. +This is similar to the default behavior of package managers in other languages +(pip/PyPi, npm, cargo, etc). In production environments where reproducibility +is important, it is therefore discouraged to depend directly on Conan Center +in an unconstrained manner. + +The following guidelines contain a series of recommendations to ensure repeatability, +reliability, compliance and, where applicable, control to enable customization. +As a summary, it is highly recommended to follow these approaches when using packages from ConanCenter: + +- Lock the versions and revisions you depend on using :ref:`lockfiles` +- Host your own copy ConanCenter recipes and package binaries :ref:`in a server under your control ` + +Repeatability and reproducibility +--------------------------------- +As mentioned earlier - given a set of requirements, changes in ConanCenter +can cause the Conan dependency solver to resolve different graphs over time. +This does not only apply to the actual versions of libraries (e.g. ``opencv/4.5.0`` +instead ``opencv/4.2.1``) - but also the recipes themselves. That is, +there may exist multiple revisions of the ``opencv/4.5.0`` recipe, which can +have side effects for consumers. Changes in recipes typically address a problem +(bugfixes), target functionality (e.g. adding a conditional option, support for +a new platform), or change versions of dependencies. + +In order to ensure repeatability, the use of lockfiles on the consumer side +is greatly encouraged: please check :ref:`the lockfile docs` +for more information. + +Lockfiles ensure that Conan will resolve the same graph in a repeatable and +consistent manner - thus making sure the same versions are used across multiple +systems (CI, developers, etc). + +Lockfiles are also used in other package managers like Python pip, Rust Cargo, npm - +these recommendations are in line with the practices of these other technologies. + +Additionally, it is highly recommended to host your recipes and packages in your +own server (see below). Both of these approaches help you achieve having control +on when upstream changes from ConanCenter are propagated across your team and systems. + + +Service reliability +------------------- +Consuming recipes and packages from the ConanCenter remote can be impacted during +periods of downtime (scheduled or otherwise). While every effort is made to ensure +that the ConanCenter is always available, and unscheduled downtime is rare and +treated with urgency - this can impact users that depend on ConanCenter directly. +Additionally, when building recipes from source, this requires retrieving the source +packages (typically zip or tar files) from remote servers outside of the control of +ConanCenter. Occasionally, these too can suffer from unscheduled downtime. + +In enterprise production environments with strong uptime is required, it is strongly +recommended to host recipes and binary packages in a server under your control. + +- Read more: :ref:`creating and hosting your own Conan Center binaries ` + +This can also protect against transient network issues, and issues caused by transfer +of binary data from external sources. These recommendations also apply when consuming +packages from external sources in any package manager. + + +Compliance and security +----------------------- +Some industries such as finance, robotics and embedded, have stronger requirements +around change management, open source licenses and reproducibility. For example, +changes in recipes could result in a new version being resolved for a dependency, +in a way that the license for that version has changed and needs to be validated +and audited by your organization. +In some industries like medical or automotive, you may be required to ensure all +your dependencies can be built from source in a repeatable way, and thus using +binaries provided by Conan Center may not be advisable. In these instances, +we recommend building your own binary packages from source: + +- Read more: :ref:`creating and hosting your own Conan Center binaries ` + +Control and customization +------------------------- +It is very common for users of dependencies to require custom changes to external +libraries - typically to support specific platform configurations not considered +by either ConanCenter or the original library authors, backport bug fixes, etc. +Some of these changes may not be suitable to be merged in ConanCenter, +and it may not happen until this has been reviewed and validated by ConanCenter maintainers. +For this reason, if you need tight control over the changes in recipes, +it is highly recommended to host not only a Conan remote, but your own fork of the +conan-center-index recipe repository. + +- Read more: :ref:`creating and hosting your own Conan Center binaries ` + + +The following subsections describe in more details the above strategies: + +.. toctree:: + :maxdepth: 1 + + conancenter/hosting_binaries + diff --git a/2.1/_sources/devops/versioning.rst.txt b/2.1/_sources/devops/versioning.rst.txt new file mode 100644 index 000000000000..f0fd5febe518 --- /dev/null +++ b/2.1/_sources/devops/versioning.rst.txt @@ -0,0 +1,11 @@ +.. _devops_versioning: + +Versioning +========== + +This section deals with different versioning topics: + +.. toctree:: + :maxdepth: 1 + + versioning/resolve_prereleases diff --git a/2.1/_sources/devops/versioning/resolve_prereleases.rst.txt b/2.1/_sources/devops/versioning/resolve_prereleases.rst.txt new file mode 100644 index 000000000000..a5366c094914 --- /dev/null +++ b/2.1/_sources/devops/versioning/resolve_prereleases.rst.txt @@ -0,0 +1,63 @@ +.. _resolve_prereleases_summary: + +Handling version ranges and pre-releases +======================================== + +When developing a package and using version ranges for defining our dependencies, +there might come a time when a new version of a dependency gets a new pre-release version that we would like to test +before it's released to have a change to validate the new version ahead of time. + +At first glance, it could be expected that the new version matches our range if it intersect it, +but :ref:`as described in the version ranges tutorial`, +by default Conan does not match pre-release versions to ranges that don't specify it. +Conan provides the :ref:`global.conf` ``core.version_ranges:resolve_prereleases``, +which when set to ``True``, enables pre-release matching in version ranges. +This avoids having to modify and export the recipes of your dependency graph, which would become unfeasible for large ones. + +This conf has the added benefit of affecting the whole dependency graph, so that if any of our dependencies also define +a requirement to our library of interest, the new version will also be picked up by it. + +Let's see this in action. Imagine we have the following (summarized) dependency graph, +in which we depend on ``libpng`` and ``libmysqlclient``, both of which depend on ``zlib`` via the ``[>1.2 <2]`` version range: + +.. graphviz:: + + digraph G { + node [fillcolor="lightskyblue", style=filled, shape=box] + "app" -> "libpng/1.6.40" + "app" -> "libmysqlclient/8.1.0" + + "libpng/1.6.40" -> "zlib/1.2.13" [label="[>1.2 <2]"] + "libmysqlclient/8.1.0" -> "zlib/1.2.13" [label="[>1.2 <2]"] + } + +If ``zlib/1.3-pre`` is now published, using it is as easy as modifying your :ref:`global.conf` +file and adding the line ``core.version_ranges:resolve_prereleases=True`` +(or adding the ``--core-conf core.version_ranges:resolve_prereleases=True`` CLI argument to your command invocations), +after which, running ``conan create`` will now output the expected prerelease version of ``zlib`` being used: + +.. code-block:: text + + ... + + ======== Computing dependency graph ======== + Graph root + cli + Requirements + libmysqlclient/8.1.0#493d36bd9641e15993479706dea3c341 - Cache + libpng/1.6.40#2ba025f1324ff820cf68c9e9c94b7772 - Cache + lz4/1.9.4#b572cad582ca4d39c0fccb5185fbb691 - Cache + openssl/3.1.2#f2eb8e67d3f5513e8a9b5e3b62d87ea1 - Cache + zlib/1.3-pre#f2eb8e6ve24ff825bca32bea494b77dd - Cache + zstd/1.5.5#54d99a44717a7ff82e9d37f9b6ff415c - Cache + Build requirements + cmake/3.27.1#de7930d308bf5edde100f2b1624841d9 - Cache + Resolved version ranges + cmake/[>=3.18 <4]: cmake/3.27.1 + openssl/[>=1.1 <4]: openssl/3.1.2 + zlib/[>1.2 <2]: zlib/1.3-pre + ... + + +Now our package can be tested and validated against this new version, +and the conf be afterwards removed once the testing is over to go back to the usual Conan behaviour. diff --git a/2.1/_sources/examples.rst.txt b/2.1/_sources/examples.rst.txt new file mode 100644 index 000000000000..f6a29957e6c4 --- /dev/null +++ b/2.1/_sources/examples.rst.txt @@ -0,0 +1,17 @@ +.. _examples: + +Examples +======== + + +.. toctree:: + :maxdepth: 2 + + examples/conanfile + examples/extensions + examples/tools + examples/cross_build + examples/config_files + examples/graph + examples/dev_flow + examples/commands diff --git a/2.1/_sources/examples/commands.rst.txt b/2.1/_sources/examples/commands.rst.txt new file mode 100644 index 000000000000..85dda6caa271 --- /dev/null +++ b/2.1/_sources/examples/commands.rst.txt @@ -0,0 +1,9 @@ +.. _examples_commands: + +Conan commands examples +========================= + +.. toctree:: + :maxdepth: 2 + + commands/pkglists diff --git a/2.1/_sources/examples/commands/pkglists.rst.txt b/2.1/_sources/examples/commands/pkglists.rst.txt new file mode 100644 index 000000000000..4cec4695f8a7 --- /dev/null +++ b/2.1/_sources/examples/commands/pkglists.rst.txt @@ -0,0 +1,209 @@ +.. _examples_commands_pkglists: + +Using packages-lists +==================== + +.. include:: ../../common/experimental_warning.inc + + +Packages lists are a powerful and convenient Conan feature that allows to automate and concatenate different Conan commands. +Let's see some common use cases: + + +Listing packages and downloading them +------------------------------------- + +A first simple use case could be listing some recipes and/or binaries in a server, and then downloading them. + +We can do any ``conan list``, for example, to list all ``zlib`` versions above ``1.2.11``, the latest recipe revision, +all Windows binaries for that latest recipe revision, and finally the latest package revision for every binary. +Note that if we want to actually download something later, it is necessary to specify the ``latest`` package revision, +otherwise only the recipes will be downloaded. + +.. code-block:: bash + + $ conan list "zlib/[>1.2.11]#latest:*#latest" -p os=Windows --format=json -r=conancenter > pkglist.json + + +The output of the command is sent in ``json`` format to the file ``pkglist.json`` that looks like: + + +.. code-block:: json + :caption: pkglist.json (simplified) + + "conancenter": { + "zlib/1.2.12": { + "revisions": { + "b1fd071d8a2234a488b3ff74a3526f81": { + "timestamp": 1667396813.987, + "packages": { + "ae9eaf478e918e6470fe64a4d8d4d9552b0b3606": { + "revisions": { + "19808a47de859c2408ffcf8e5df1fdaf": { + } + }, + "info": { + "settings": { + "arch": "x86_64", + "os": "Windows" + } + } + } + } + } + }, + "zlib/1.2.13": { + } + } + + +The first level in the ``pkglist.json`` is the "origin" remote or "Local Cache" if the list happens in the cache. +In this case, as we listed the packages in ``conancenter`` remote, that will be the origin. + + +We can now do a download of these recipes and binaries with a single ``conan download`` invocation: + +.. code-block:: bash + + $ conan download --list=pkglist.json -r=conancenter + # Download the recipes and binaries in pkglist.json + # And displays a report of the downloaded things + + +Downloading from one remote and uploading to a different remote +--------------------------------------------------------------- + +Let's say that we create a new package list from the packages downloaded in the previous step: + +.. code-block:: bash + + $ conan download --list=pkglist.json -r=conancenter --format=json > downloaded.json + # Download the recipes and binaries in pkglist.json + # And stores the result in "downloaded.json" + + +The resulting ``downloaded.json`` will be almost the same as the ``pkglist.json`` file, but in this case, the "origin" of +those packages is the ``"Local Cache"`` (as the downloaded packages will be in the cache): + + +.. code-block:: json + :caption: downloaded.json (simplified) + + "Local Cache": { + "zlib/1.2.12": { + "revisions": { + } + } + } + +That means that we can now upload this same set of recipes and binaries to a different remote: + +.. code-block:: bash + + $ conan upload --list=downloaded.json -r=myremote -c + # Upload those artifacts to the same remote + + +.. note:: + + **Best practices** + + This would be a **slow** mechanism to run promotions between different server repositories. Servers like + Artifactory provide ways to directly copy packages from one repository to another without using a client, + that are orders of magnitude faster because of file deduplication, so that would be the recommended approach. + The presented approach in this section might be used for air-gapped environments and other situations in which + it is not possible to do a server-to-server copy. + + + +Building and uploading packages +------------------------------- + +One of the most interesting flows is the one when some packages are being built in the local cache, with a +``conan create`` or ``conan install --build=xxx`` command. Typically, we would like to upload the locally built +packages to the server, so they don't have to be re-built again by others. But we might want to upload only +the built binaries, but not all others transitive dependencies, or other packages that we had previously in +our local cache. + +It is possible to compute a package list from the output of a ``conan install``, ``conan create`` and ``conan graph info`` +commands. Then, that package list can be used for the upload. Step by step: + +First let's say that we have our own package ``mypkg/0.1`` and we create it: + +.. code-block:: bash + + $ conan new cmake_lib -d name=mypkg -d version=0.1 + $ conan create . --format=json > create.json + + +This will create a json representation of the graph, with information of what packages have been built ``"binary": "Build"``: + +.. code-block:: json + :caption: create.json (simplified) + + { + "graph": { + "nodes": { + "0": { + "ref": "conanfile", + "id": "0", + "recipe": "Cli", + "context": "host", + "test": false + }, + "1": { + "ref": "mypkg/0.1#f57cc9a1824f47af2f52df0dbdd440f6", + "id": "1", + "recipe": "Cache", + "package_id": "2401fa1d188d289bb25c37cfa3317e13e377a351", + "prev": "75f44d989175c05bc4be2399edc63091", + "build_id": null, + "binary": "Build" + } + } + } + + +We can compute a package list from this file, and then upload those artifacts to the server with: + +.. code-block:: bash + + $ conan list --graph=create.json --graph-binaries=build --format=json > pkglist.json + # Create a pkglist.json with the known list of recipes and binaries built from sources + $ conan upload --list=pkglist.json -r=myremote -c + + +Removing packages lists +----------------------- + +It is also possible to first ``conan list`` and create a list of things to remove, and then remove them: + +.. code-block:: bash + + # Removes everything from the cache + $ conan list *#* --format=json > pkglist.json + $ conan remove --list=pkglist.json -c + +Note that in this case, the default patterns are different in ``list`` and ``remove``, because of the destructive nature of ``conan remove``: + +- When a recipe is passed to ``remove`` like ``conan remove zlib/1.2.13``, it will remove the recipe of ``zlib/1.2.13`` and all of its binaries, because the binaries cannot live without the recipe. +- When a ``package_id`` is passed, like ``conan remove zlib/1.2.13:package_id``, then that specific ``package_id`` will be removed, but the recipe will not + +Then the pattern to remove everything will be different if we call directly ``conan remove`` or if we call first ``conan list``, for example: + +.. code-block:: bash + + # Removes everything from the cache + $ conan remove * + # OR via list, we need to explicitly include all revisions + $ conan list *#* --format=json > pkglist.json + $ conan remove --list=pkglist.json -c + + # Removes only the binaries from the cache (leave recipes) + $ conan remove *:* + # OR via list, we need to explicitly include all revisions + $ conan list *#*:* --format=json > pkglist.json + $ conan remove --list=pkglist.json -c + + +For more information see the :ref:`Reference commands section` diff --git a/2.1/_sources/examples/conanfile.rst.txt b/2.1/_sources/examples/conanfile.rst.txt new file mode 100644 index 000000000000..f6746d79036b --- /dev/null +++ b/2.1/_sources/examples/conanfile.rst.txt @@ -0,0 +1,10 @@ +.. _examples_conanfile: + +ConanFile methods examples +========================== + +.. toctree:: + :maxdepth: 2 + + conanfile/package_info + conanfile/layout diff --git a/2.1/_sources/examples/conanfile/layout.rst.txt b/2.1/_sources/examples/conanfile/layout.rst.txt new file mode 100644 index 000000000000..497fc51d7fdb --- /dev/null +++ b/2.1/_sources/examples/conanfile/layout.rst.txt @@ -0,0 +1,12 @@ +.. _examples_conanfile_layout: + +ConanFile layout() examples +=========================== + +.. toctree:: + :maxdepth: 2 + + layout/conanfile_in_subfolder + layout/third_party_libraries + layout/multiple_subprojects + layout/editable_components diff --git a/2.1/_sources/examples/conanfile/layout/conanfile_in_subfolder.rst.txt b/2.1/_sources/examples/conanfile/layout/conanfile_in_subfolder.rst.txt new file mode 100644 index 000000000000..c645211d4cf7 --- /dev/null +++ b/2.1/_sources/examples/conanfile/layout/conanfile_in_subfolder.rst.txt @@ -0,0 +1,88 @@ +.. _examples_conanfile_layout_conanfile_in_subfolder: + +Declaring the layout when the Conanfile is inside a subfolder +------------------------------------------------------------- + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/conanfile/layout/conanfile_in_subfolder + +If we have a project intended to package the code that is in the same repo as the +``conanfile.py``, but the ``conanfile.py`` is not in the root of the project: + +.. code-block:: text + + . + ├── CMakeLists.txt + ├── conan + │ └── conanfile.py + ├── include + │ └── say.h + └── src + └── say.cpp + +The ``conanfile.py`` would look like this: + +.. code-block:: python + + import os + from conan import ConanFile + from conan.tools.files import load, copy + from conan.tools.cmake import CMake + + + class PkgSay(ConanFile): + name = "say" + version = "1.0" + settings = "os", "compiler", "build_type", "arch" + generators = "CMakeToolchain" + + def layout(self): + # The root of the project is one level above + self.folders.root = ".." + # The source of the project (the root CMakeLists.txt) is the source folder + self.folders.source = "." + self.folders.build = "build" + + def export_sources(self): + # The path of the CMakeLists.txt and sources we want to export are one level above + folder = os.path.join(self.recipe_folder, "..") + copy(self, "*.txt", folder, self.export_sources_folder) + copy(self, "src/*.cpp", folder, self.export_sources_folder) + copy(self, "include/*.h", folder, self.export_sources_folder) + + def source(self): + # Check that we can see that the CMakeLists.txt is inside the source folder + cmake_file = load(self, "CMakeLists.txt") + + def build(self): + # Check that the build() method can also access the CMakeLists.txt in the source folder + path = os.path.join(self.source_folder, "CMakeLists.txt") + cmake_file = load(self, path) + + cmake = CMake(self) + cmake.configure() + cmake.build() + + def package(self): + cmake = CMake(self) + cmake.install() + +You can try and create the ``say`` package: + +.. code-block:: bash + + $ cd conan + $ conan create . + +.. seealso:: + + - Read more about the :ref:`layout method` and :ref:`how the + package layout works`. + + + \ No newline at end of file diff --git a/2.1/_sources/examples/conanfile/layout/editable_components.rst.txt b/2.1/_sources/examples/conanfile/layout/editable_components.rst.txt new file mode 100644 index 000000000000..a0fdfcd9ebe0 --- /dev/null +++ b/2.1/_sources/examples/conanfile/layout/editable_components.rst.txt @@ -0,0 +1,123 @@ +.. _examples_conanfile_layout_components_editables: + +Using components and editable packages +-------------------------------------- + +It is possible to define components in the ``layout()`` method, to support the case of ``editable`` packages. +That is, if we want to put a package in ``editable`` mode, and that package defines ``components``, it is +necessary to define the components layout correctly in the ``layout()`` method. +Let's see it in a real example. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/conanfile/layout/editable_components + +There we find a ``greetings`` subfolder and package, that contains 2 libraries, the ``hello`` library and the +``bye`` library. Each one is modeled as a ``component`` inside the package recipe: + +.. code-block:: python + :caption: greetings/conanfile.py + + class GreetingsConan(ConanFile): + name = "greetings" + version = "0.1" + settings = "os", "compiler", "build_type", "arch" + generators = "CMakeDeps", "CMakeToolchain" + exports_sources = "src/*" + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + + def layout(self): + cmake_layout(self, src_folder="src") + # This "includedirs" starts in the source folder, which is "src" + # So the components include dirs is the "src" folder (includes are + # intended to be included as ``#include "hello/hello.h"``) + self.cpp.source.components["hello"].includedirs = ["."] + self.cpp.source.components["bye"].includedirs = ["."] + # compiled libraries "libdirs" will be inside the "build" folder, depending + # on the platform they will be in "build/Release" or directly in "build" folder + bt = "." if self.settings.os != "Windows" else str(self.settings.build_type) + self.cpp.build.components["hello"].libdirs = [bt] + self.cpp.build.components["bye"].libdirs = [bt] + + def package(self): + copy(self, "*.h", src=self.source_folder, + dst=join(self.package_folder, "include")) + copy(self, "*.lib", src=self.build_folder, + dst=join(self.package_folder, "lib"), keep_path=False) + copy(self, "*.a", src=self.build_folder, + dst=join(self.package_folder, "lib"), keep_path=False) + + def package_info(self): + self.cpp_info.components["hello"].libs = ["hello"] + self.cpp_info.components["bye"].libs = ["bye"] + + self.cpp_info.set_property("cmake_file_name", "MYG") + self.cpp_info.set_property("cmake_target_name", "MyGreetings::MyGreetings") + self.cpp_info.components["hello"].set_property("cmake_target_name", "MyGreetings::MyHello") + self.cpp_info.components["bye"].set_property("cmake_target_name", "MyGreetings::MyBye") + +While the location of the ``hello`` and ``bye`` libraries in the final package is in the final ``lib`` folder, +then nothing special is needed in the ``package_info()`` method, beyond the definition of the components. In +this case, the customization of the CMake generated filenames and targets is also included, but it is not +necessary for this example. + +The important part is the ``layout()`` definition. Besides the common ``cmake_layout``, it is necessary to +define the location of the components headers (``self.cpp.source`` as they are source code) and the location +of the locally built libraries. As the location of the libraries depends on the platform, the final +``self.cpp.build.components["component"].libdirs`` depends on the platform. + +With this recipe we can put the package in editable mode and locally build it with: + +.. code-block:: bash + + $ conan editable add greetings + $ conan build greetings + # we might want to also build the debug config + + +In the ``app`` folder we have a package recipe to build 2 executables, that link with the ``greeting`` package +components. The ``app/conanfile.py`` recipe there is simple, the ``build()`` method builds and runs both ``example`` +and ``example2`` executables that are built with ``CMakeLists.txt``: + + +.. code-block:: cmake + + # Note the MYG file name, not matching the package name, + # because the recipe defined "cmake_file_name" + find_package(MYG) + + add_executable(example example.cpp) + # Note the MyGreetings::MyGreetings target name, not matching the package name, + # because the recipe defined "cmake_target_name" + # "example" is linking with the whole package, both "hello" and "bye" components + target_link_libraries(example MyGreetings::MyGreetings) + + add_executable(example2 example2.cpp) + # "example2" is only using and linking "hello" component, but not "bye" + target_link_libraries(example2 MyGreetings::MyHello) + + +.. code-block:: bash + + $ conan build app + hello: Release! + bye: Release! + + +If you now go to the ``bye.cpp`` source file and modify the output message, then build ``greetings`` and +``app`` locally, the final output message for the "bye" component library should change: + +.. code-block:: bash + + $ conan build greetings + $ conan build app + hello: Release! + adios: Release! diff --git a/2.1/_sources/examples/conanfile/layout/multiple_subprojects.rst.txt b/2.1/_sources/examples/conanfile/layout/multiple_subprojects.rst.txt new file mode 100644 index 000000000000..63e009540bb6 --- /dev/null +++ b/2.1/_sources/examples/conanfile/layout/multiple_subprojects.rst.txt @@ -0,0 +1,115 @@ +.. _examples_conanfile_layout_multiple_subprojects: + +Declaring the layout when we have multiple subprojects +------------------------------------------------------ + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/conanfile/layout/multiple_subprojects + +Let's say that we have a project that contains two subprojects: *hello* and *bye*, that need to +access some information that is at their same level (sibling folders). Each subproject +would be a Conan package. The structure could be something similar to this: + +.. code-block:: text + + . + ├── bye + │ ├── CMakeLists.txt + │ ├── bye.cpp # contains an #include "../common/myheader.h" + │ └── conanfile.py # contains include(../common/myutils.cmake) + ├── common + │ ├── myheader.h + │ └── myutils.cmake + └── hello + ├── CMakeLists.txt # contains include(../common/myutils.cmake) + ├── conanfile.py + └── hello.cpp # contains an #include "../common/myheader.h" + + +Both *hello* and *bye* subprojects needs to use some of the files located inside the +``common`` folder (that might be used and shared by other subprojects too), and it +references them by their relative location. Note that ``common`` is not intended to be a +Conan package. It is just some common code that will be copied into the different +subproject packages. + +We can use the ``self.folders.root = ".."`` layout specifier to locate the root of the +project, then use the ``self.folders.subproject = "subprojectfolder"`` to relocate back +most of the layout to the current subproject folder, as it would be the one containing the +build scripts, sources code, etc., so other helpers like ``cmake_layout()`` keep working. +Let's see how the *conanfile.py* of *hello* could look like: + + +.. code-block:: python + :caption: ./hello/conanfile.py + + import os + from conan import ConanFile + from conan.tools.cmake import cmake_layout, CMake + from conan.tools.files import copy + + + class hello(ConanFile): + name = "hello" + version = "1.0" + + settings = "os", "compiler", "build_type", "arch" + generators = "CMakeToolchain" + + def layout(self): + self.folders.root = ".." + self.folders.subproject = "hello" + cmake_layout(self) + + def export_sources(self): + source_folder = os.path.join(self.recipe_folder, "..") + copy(self, "hello/conanfile.py", source_folder, self.export_sources_folder) + copy(self, "hello/CMakeLists.txt", source_folder, self.export_sources_folder) + copy(self, "hello/hello.cpp", source_folder, self.export_sources_folder) + copy(self, "common*", source_folder, self.export_sources_folder) + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + self.run(os.path.join(self.cpp.build.bindirs[0], "hello")) + +Let's build *hello* and check that it's building correctly, using the contents of the +common folder. + +.. code-block:: bash + + $ conan install hello + $ conan build hello + ... + [100%] Built target hello + conanfile.py (hello/1.0): RUN: ./hello + hello WORLD + +You can also run a :command:`conan create` and check that it works fine too: + +.. code-block:: bash + + $ conan create hello + ... + [100%] Built target hello + conanfile.py (hello/1.0): RUN: ./hello + hello WORLD + +.. note:: + + Note the importance of the ``export_sources()`` method, which is able to maintain the + same relative layout of the ``hello`` and ``common`` folders, both in the local developer + flow in the current folder, but also when those sources are copied to the Conan cache, to + be built there with ``conan create`` or ``conan install --build=hello``. This is one of the + design principles of the ``layout()``, the relative location of things must be consistent + in the user folder and in the cache. + +.. seealso:: + + - Read more about the :ref:`layout method` and :ref:`how the + package layout works`. diff --git a/2.1/_sources/examples/conanfile/layout/third_party_libraries.rst.txt b/2.1/_sources/examples/conanfile/layout/third_party_libraries.rst.txt new file mode 100644 index 000000000000..c7feb9c59af1 --- /dev/null +++ b/2.1/_sources/examples/conanfile/layout/third_party_libraries.rst.txt @@ -0,0 +1,95 @@ +.. _examples_conanfile_layout_third_party_libraries: + +Declaring the layout when creating packages for third-party libraries +--------------------------------------------------------------------- + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/conanfile/layout/third_party_libraries + + +If we have this project, intended to create a package for a third-party library whose code +is located externally: + +.. code-block:: text + + . + ├── conanfile.py + └── patches + └── mypatch + +The ``conanfile.py`` would look like this: + +.. code-block:: python + + ... + + class Pkg(ConanFile): + name = "hello" + version = "1.0" + exports_sources = "patches*" + + ... + + def layout(self): + cmake_layout(self, src_folder="src") + # if you are declaring your own layout, just declare: + # self.folders.source = "src" + + def source(self): + # we are inside a "src" subfolder, as defined by layout + # the downloaded soures will be inside the "src" subfolder + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", + strip_root=True) + # Please, be aware that using the head of the branch instead of an immutable tag + # or commit is not a good practice in general as the branch may change the contents + + # patching, replacing, happens here + patch(self, patch_file=os.path.join(self.export_sources_folder, "patches/mypatch")) + + def build(self): + # If necessary, the build() method also has access to the export_sources_folder + # for example if patching happens in build() instead of source() + #patch(self, patch_file=os.path.join(self.export_sources_folder, "patches/mypatch")) + cmake = CMake(self) + cmake.configure() + cmake.build() + ... + + +We can see that the ``ConanFile.export_sources_folder`` attribute can provide access to the root +folder of the sources: + +- Locally it will be the folder where the ``conanfile.py`` lives +- In the cache it will be the "source" folder, that will contain a copy of + ``CMakeLists.txt`` and ``patches``, while the "source/src" folder will contain the + actual downloaded sources. + + +We can check that everything runs fine now: + +.. code-block:: bash + + $ conan create . + ... + Downloading main.zip + hello/1.0: Unzipping 3.7KB + Unzipping 100 % + ... + [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o + [100%] Linking CXX static library libhello.a + [100%] Built target hello + ... + $ conan list hello/1.0 + Local Cache + hello + hello/1.0 + +.. seealso:: + + - Read more about the :ref:`layout method` and :ref:`how the + package layout works`. diff --git a/2.1/_sources/examples/conanfile/package_info.rst.txt b/2.1/_sources/examples/conanfile/package_info.rst.txt new file mode 100644 index 000000000000..71df8cb6f6c5 --- /dev/null +++ b/2.1/_sources/examples/conanfile/package_info.rst.txt @@ -0,0 +1,10 @@ +.. _examples_conanfile_package_info: + +ConanFile package_info() examples +================================= + +.. toctree:: + :maxdepth: 2 + + package_info/package_info_conf_and_env + package_info/components \ No newline at end of file diff --git a/2.1/_sources/examples/conanfile/package_info/components.rst.txt b/2.1/_sources/examples/conanfile/package_info/components.rst.txt new file mode 100644 index 000000000000..c360ea2c55e3 --- /dev/null +++ b/2.1/_sources/examples/conanfile/package_info/components.rst.txt @@ -0,0 +1,238 @@ +.. _examples_conanfile_package_info_components: + +Define components for Conan packages that provide multiple libraries +==================================================================== + +At the :ref:`section of the tutorial about the package_info() method +`, we learned how to define information in a package for +consumers, such as library names or include and library folders. In the tutorial, we +created a package with only one library that consumers linked to. However, in some cases, +libraries provide their functionalities separated into different *components*. These +components can be consumed independently, and in some cases, they may require other +components from the same library or others. For example, consider a library like OpenSSL +that provides *libcrypto* and *libssl*, where *libssl* depends on *libcrypto*. + +Conan provides a way to abstract this information using the `components` attribute of the +`CppInfo` object to define the information for each separate component of a Conan package. +Consumers can also select specific components to link against but not the rest of the +package. + +Let's take a game-engine library as an example, which provides several components such as +*algorithms*, *ai*, *rendering*, and *network*. Both *ai* and *rendering* depend on the *algorithms* +component. + +.. graphviz:: + :caption: components of the game-engine package + + digraph components { + node [fillcolor="lightskyblue", style=filled, shape=box] + algorithms -> ai; + algorithms -> rendering; + ai; + algorithms; + network; + } + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/conanfile/package_info/components + + +You can check the contents of the project: + +.. code-block:: text + + . + ├── CMakeLists.txt + ├── conanfile.py + ├── include + │ ├── ai.h + │ ├── algorithms.h + │ ├── network.h + │ └── rendering.h + ├── src + │ ├── ai.cpp + │ ├── algorithms.cpp + │ ├── network.cpp + │ └── rendering.cpp + └── test_package + ├── CMakeLists.txt + ├── CMakeUserPresets.json + ├── conanfile.py + └── src + └── example.cpp + +As you can see, there are sources for each of the components and a CMakeLists.txt file to +build them. We also have a `test_package` that we are going to use to test the consumption +of the separate components. + +First, let's have a look at package_info() method in the *conanfile.py* and how we declared +the information for each component that we want to provide to the consumers of the +game-engine package: + +.. code-block:: python + + ... + + def package_info(self): + self.cpp_info.components["algorithms"].libs = ["algorithms"] + self.cpp_info.components["algorithms"].set_property("cmake_target_name", "algorithms") + + self.cpp_info.components["network"].libs = ["network"] + self.cpp_info.components["network"].set_property("cmake_target_name", "network") + + self.cpp_info.components["ai"].libs = ["ai"] + self.cpp_info.components["ai"].requires = ["algorithms"] + self.cpp_info.components["ai"].set_property("cmake_target_name", "ai") + + self.cpp_info.components["rendering"].libs = ["rendering"] + self.cpp_info.components["rendering"].requires = ["algorithms"] + self.cpp_info.components["rendering"].set_property("cmake_target_name", "rendering") + + +There are a couple of relevant things: + +- We declare the libraries generated by each of the components by setting information in + the ``cpp_info.components`` attribute. You can set the same information for each of the + components as you would for the ``self.cpp_info`` object. The ``cpp_info`` for + components has some defaults defined, just like it does for + :ref:`self.cpp_info`. For example, the + ``cpp_info.components`` object provides the ``.includedirs`` and ``.libdirs`` properties + to define those locations, but Conan sets their value as ``["lib"]`` and ``["include"]`` by default, + so it's not necessary to add them in this case. + +- We are also declaring the components' dependencies using the ``.requires`` attribute. + With this attribute, you can declare requirements at the component level, not only for + components in the same recipe but also for components from other packages that are + declared as requires of the Conan package. + +- We are changing the default target names for the components using the :ref:`properties + model`. By default, Conan sets a + target name for components like ````, but for this + tutorial we will set the component target names just with the component names omitting + the ``::``. + +You can have a look at the consumer part by checking the *test_package* folder. First the +*conanfile.py*: + +.. code-block:: python + + ... + + def generate(self): + deps = CMakeDeps(self) + deps.check_components_exist = True + deps.generate() + +You can see that we are setting the :ref:`check_components_exist +` property for CMakeDeps. This is not +needed, just to show how you can do if you want your consumers to fail if the component +does not exist. So, the CMakeLists.txt could look like this: + + +.. code-block:: text + + cmake_minimum_required(VERSION 3.15) + project(PackageTest CXX) + + find_package(game-engine REQUIRED COMPONENTS algorithms network ai rendering) + + add_executable(example src/example.cpp) + + target_link_libraries(example algorithms + network + ai + rendering) + +And the ``find_package()`` call would fail if any of the components targets do not exist. + +Let's run the example: + +.. code-block:: text + + $ conan create . + ... + game-engine/1.0: RUN: cmake --build "/Users/barbarian/.conan2/p/t/game-d6e361d329116/b/build/Release" -- -j16 + [ 12%] Building CXX object CMakeFiles/algorithms.dir/src/algorithms.cpp.o + [ 25%] Building CXX object CMakeFiles/network.dir/src/network.cpp.o + [ 37%] Linking CXX static library libnetwork.a + [ 50%] Linking CXX static library libalgorithms.a + [ 50%] Built target network + [ 50%] Built target algorithms + [ 62%] Building CXX object CMakeFiles/ai.dir/src/ai.cpp.o + [ 75%] Building CXX object CMakeFiles/rendering.dir/src/rendering.cpp.o + [ 87%] Linking CXX static library libai.a + [100%] Linking CXX static library librendering.a + [100%] Built target ai + [100%] Built target rendering + ... + + ======== Launching test_package ======== + + ... + -- Conan: Component target declared 'algorithms' + -- Conan: Component target declared 'network' + -- Conan: Component target declared 'ai' + -- Conan: Component target declared 'rendering' + ... + [ 50%] Building CXX object CMakeFiles/example.dir/src/example.cpp.o + [100%] Linking CXX executable example + [100%] Built target example + + + ======== Testing the package: Executing test ======== + game-engine/1.0 (test package): Running test() + game-engine/1.0 (test package): RUN: ./example + I am the algorithms component! + I am the network component! + I am the ai component! + └───> I am the algorithms component! + I am the rendering component! + └───> I am the algorithms component! + +You could check that requiring a component that does not exist will raise an error. Add +the *nonexistent* component to the find_package() call: + +.. code-block:: text + + cmake_minimum_required(VERSION 3.15) + project(PackageTest CXX) + + find_package(game-engine REQUIRED COMPONENTS nonexistent algorithms network ai rendering) + + add_executable(example src/example.cpp) + + target_link_libraries(example algorithms + network + ai + rendering) + +And test the package again: + +.. code-block:: text + + $ conan test test_package game-engine/1.0 + + ... + + Conan: Component 'nonexistent' NOT found in package 'game-engine' + Call Stack (most recent call first): + CMakeLists.txt:4 (find_package) + + -- Configuring incomplete, errors occurred! + + ... + + ERROR: game-engine/1.0 (test package): Error in build() method, line 22 + cmake.configure() + ConanException: Error 1 while executing + + +.. seealso:: + + If you want to use recipes defining components in ``editable`` mode, check the example in + :ref:`examples_conanfile_layout_components_editables`. diff --git a/2.1/_sources/examples/conanfile/package_info/package_info_conf_and_env.rst.txt b/2.1/_sources/examples/conanfile/package_info/package_info_conf_and_env.rst.txt new file mode 100644 index 000000000000..b0b9e9b6051a --- /dev/null +++ b/2.1/_sources/examples/conanfile/package_info/package_info_conf_and_env.rst.txt @@ -0,0 +1,6 @@ +.. _examples_conanfile_package_info_conf_and_env: + +Propagating environment or configuration information to consumers +================================================================= + +TBD \ No newline at end of file diff --git a/2.1/_sources/examples/config_files.rst.txt b/2.1/_sources/examples/config_files.rst.txt new file mode 100644 index 000000000000..397e26726d02 --- /dev/null +++ b/2.1/_sources/examples/config_files.rst.txt @@ -0,0 +1,9 @@ +.. _examples_config_files: + +Configuration files examples +============================ + +.. toctree:: + :maxdepth: 2 + + config_files/settings/settings_user diff --git a/2.1/_sources/examples/config_files/settings/settings_user.rst.txt b/2.1/_sources/examples/config_files/settings/settings_user.rst.txt new file mode 100644 index 000000000000..19b786f112b8 --- /dev/null +++ b/2.1/_sources/examples/config_files/settings/settings_user.rst.txt @@ -0,0 +1,253 @@ +.. _examples_config_files_settings_user: + +Customize your settings: create your settings_user.yml +====================================================== + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/config_files/settings_user + + +In this example we are going to see how to customize your settings without overwriting the original **settings.yml** file. + +.. note:: + + To understand better this example, it is highly recommended to read previously the reference + about :ref:`reference_config_files_settings_yml`. + + +Locate the settings_user.yml +---------------------------- + +First of all, let's have a look at the proposed ``source/settings_user.yml``: + +.. code-block:: yaml + :caption: **settings_user.yml** + + os: + webOS: + sdk_version: [null, "7.0.0", "6.0.1", "6.0.0"] + arch: ["cortexa15t2hf"] + compiler: + gcc: + version: ["13.0-rc"] + + +As you can see, we don't have to rewrite all the settings because they will be merged with the already defined in +**settings.yml**. + +Then, what are we adding through that ``settings_user.yml`` file? + +* New OS: ``webOS``, and its sub-setting: ``sdk_version``. +* New ``arch`` available: ``cortexa15t2hf``. +* New gcc version: ``13.0-rc``. + +Now, it's time to copy the file ``source/settings_user.yml`` into your ``[CONAN_HOME]/`` folder: + +.. code-block:: bash + + $ conan config install sources/settings_user.yml + Copying file settings_user.yml to /Users/myuser/.conan2/. + + +Use your new settings +--------------------- + +After having copied the ``settings_user.yml``, you should be able to use them for your recipes. Add this simple one +into your local folder: + +.. code-block:: python + :caption: **conanfile.py** + + from conan import ConanFile + + class PkgConan(ConanFile): + name = "pkg" + version = "1.0" + settings = "os", "compiler", "build_type", "arch" + + +Then, create several Conan packages (not binaries, as it does not have any source file for sure) to see +that it's working correctly: + + +.. code-block:: bash + :caption: **Using the new OS and its sub-setting** + :emphasize-lines: 11,12,34 + + $ conan create . -s os=webOS -s os.sdk_version=7.0.0 + ... + Profile host: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=webOS + os.sdk_version=7.0.0 + + Profile build: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + ... + -------- Installing (downloading, building) binaries... -------- + pkg/1.0: Copying sources to build folder + pkg/1.0: Building your package in /Users/myuser/.conan2/p/t/pkg929d53a5f06b1/b + pkg/1.0: Aggregating env generators + pkg/1.0: Package 'a0d37d10fdb83a0414d7f4a1fb73da2c210211c6' built + pkg/1.0: Build folder /Users/myuser/.conan2/p/t/pkg929d53a5f06b1/b + pkg/1.0: Generated conaninfo.txt + pkg/1.0: Generating the package + pkg/1.0: Temporary package folder /Users/myuser/.conan2/p/t/pkg929d53a5f06b1/p + pkg/1.0 package(): WARN: No files in this package! + pkg/1.0: Package 'a0d37d10fdb83a0414d7f4a1fb73da2c210211c6' created + pkg/1.0: Created package revision 6a947a7b5669d6fde1a35ce5ff987fc6 + pkg/1.0: Full package reference: pkg/1.0#637fc1c7080faaa7e2cdccde1bcde118:a0d37d10fdb83a0414d7f4a1fb73da2c210211c6#6a947a7b5669d6fde1a35ce5ff987fc6 + pkg/1.0: Package folder /Users/myuser/.conan2/p/pkgb3950b1043542/p + +.. code-block:: bash + :caption: **Using new gcc compiler version** + :emphasize-lines: 9,32 + + $ conan create . -s compiler=gcc -s compiler.version=13.0-rc -s compiler.libcxx=libstdc++11 + ... + Profile host: + [settings] + arch=x86_64 + build_type=Release + compiler=gcc + compiler.libcxx=libstdc++11 + compiler.version=13.0-rc + os=Macos + + Profile build: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + ... + -------- Installing (downloading, building) binaries... -------- + pkg/1.0: Copying sources to build folder + pkg/1.0: Building your package in /Users/myuser/.conan2/p/t/pkg918904bbca9dc/b + pkg/1.0: Aggregating env generators + pkg/1.0: Package '44a4588d3fe63ccc6e7480565d35be38d405718e' built + pkg/1.0: Build folder /Users/myuser/.conan2/p/t/pkg918904bbca9dc/b + pkg/1.0: Generated conaninfo.txt + pkg/1.0: Generating the package + pkg/1.0: Temporary package folder /Users/myuser/.conan2/p/t/pkg918904bbca9dc/p + pkg/1.0 package(): WARN: No files in this package! + pkg/1.0: Package '44a4588d3fe63ccc6e7480565d35be38d405718e' created + pkg/1.0: Created package revision d913ec060e71cc56b10768afb9620094 + pkg/1.0: Full package reference: pkg/1.0#637fc1c7080faaa7e2cdccde1bcde118:44a4588d3fe63ccc6e7480565d35be38d405718e#d913ec060e71cc56b10768afb9620094 + pkg/1.0: Package folder /Users/myuser/.conan2/p/pkg789b624c93fc0/p + +.. code-block:: bash + :caption: **Using the new OS and the new architecture** + :emphasize-lines: 5,11,33 + + $ conan create . -s os=webOS -s arch=cortexa15t2hf + ... + Profile host: + [settings] + arch=cortexa15t2hf + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=webOS + + Profile build: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu98 + compiler.libcxx=libc++ + compiler.version=12.0 + os=Macos + ... + -------- Installing (downloading, building) binaries... -------- + pkg/1.0: Copying sources to build folder + pkg/1.0: Building your package in /Users/myuser/.conan2/p/t/pkgde9b63a6bed0a/b + pkg/1.0: Aggregating env generators + pkg/1.0: Package '19cf3cb5842b18dc78e5b0c574c1e71e7b0e17fc' built + pkg/1.0: Build folder /Users/myuser/.conan2/p/t/pkgde9b63a6bed0a/b + pkg/1.0: Generated conaninfo.txt + pkg/1.0: Generating the package + pkg/1.0: Temporary package folder /Users/myuser/.conan2/p/t/pkgde9b63a6bed0a/p + pkg/1.0 package(): WARN: No files in this package! + pkg/1.0: Package '19cf3cb5842b18dc78e5b0c574c1e71e7b0e17fc' created + pkg/1.0: Created package revision f5739d5a25b3757254dead01b30d3af0 + pkg/1.0: Full package reference: pkg/1.0#637fc1c7080faaa7e2cdccde1bcde118:19cf3cb5842b18dc78e5b0c574c1e71e7b0e17fc#f5739d5a25b3757254dead01b30d3af0 + pkg/1.0: Package folder /Users/myuser/.conan2/p/pkgd154182aac59e/p + + +As you could observe, each command has created a different package. That was completely right because we were using +different settings for each one. If you want to see all the packages created, you can use the :ref:`reference_commands_list` command: + + +.. code-block:: bash + :caption: List all the *pkg/1.0*'s packages + + $ conan list pkg/1.0:* + Local Cache + pkg + pkg/1.0 + revisions + 637fc1c7080faaa7e2cdccde1bcde118 (2023-02-16 06:42:10 UTC) + packages + 19cf3cb5842b18dc78e5b0c574c1e71e7b0e17fc + info + settings + arch: cortexa15t2hf + build_type: Release + compiler: apple-clang + compiler.cppstd: gnu98 + compiler.libcxx: libc++ + compiler.version: 12.0 + os: webOS + 44a4588d3fe63ccc6e7480565d35be38d405718e + info + settings + arch: x86_64 + build_type: Release + compiler: gcc + compiler.libcxx: libstdc++11 + compiler.version: 13.0-rc + os: Macos + a0d37d10fdb83a0414d7f4a1fb73da2c210211c6 + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.cppstd: gnu98 + compiler.libcxx: libc++ + compiler.version: 12.0 + os: webOS + os.sdk_version: 7.0.0 + + +Try any other custom setting! + +.. seealso:: + + - :ref:`reference_config_files_profiles`. + - :ref:`creating_packages_configure_options_settings` diff --git a/2.1/_sources/examples/cross_build.rst.txt b/2.1/_sources/examples/cross_build.rst.txt new file mode 100644 index 000000000000..00bdee1642bf --- /dev/null +++ b/2.1/_sources/examples/cross_build.rst.txt @@ -0,0 +1,10 @@ +.. _examples_cross_build: + +Cross-building examples +======================= + +.. toctree:: + :maxdepth: 1 + + cross_build/android/ndk + cross_build/android/android_studio diff --git a/2.1/_sources/examples/cross_build/android/android_studio.rst.txt b/2.1/_sources/examples/cross_build/android/android_studio.rst.txt new file mode 100644 index 000000000000..5b8645714bd7 --- /dev/null +++ b/2.1/_sources/examples/cross_build/android/android_studio.rst.txt @@ -0,0 +1,279 @@ + +.. _examples_cross_build_android_studio: + + +Integrating Conan in Android Studio +=================================== + +At the :ref:`Cross building to Android with the NDK` we learned how to build a package +for Android using the NDK. In this example we are going to learn how to do it with the Android Studio and how to use +the libraries in a real Android application. + + +Creating a new project +---------------------- + +First of all, download and install the `Android Studio IDE `_. + +Then create a ``new project`` selecting ``Native C++`` from the templates. + +In the next wizard window, select a name for your application, for example `MyConanApplication`, you can leave the +"Minimum SDK" with the suggested value (21 in our case), but remember the value as we are using it later in the Conan +profile at ``os.api_level``` + +Select a "C++ Standard" in the next window, again, remember the choice as later we should use the same in the profile at +``compiler.cppstd``. + +In the project generated with the wizard we have a folder ``cpp`` with a ``native-lib.cpp``. We are going to modify that +file to use ``zlib`` and print a message with the used ``zlib`` version. Copy only the highlighted lines, it is important +to keep the function name. + + +.. code-block:: c++ + :emphasize-lines: 3, 9, 10 + :caption: native-lib.cpp + + #include + #include + #include "zlib.h" + + extern "C" JNIEXPORT jstring JNICALL + Java_com_example_myconanapp_MainActivity_stringFromJNI( + JNIEnv* env, + jobject /* this */) { + std::string hello = "Hello from C++, zlib version: "; + hello.append(zlibVersion()); + return env->NewStringUTF(hello.c_str()); + } + + +Now we are going to learn how to introduce a requirement to the ``zlib`` library and how to prepare our project. + +Introducing dependencies with Conan +----------------------------------- + +conanfile.txt +^^^^^^^^^^^^^ + +We need to provide the ``zlib`` package with Conan. Create a file ``conanfile.txt`` in the ``cpp`` folder: + + +.. code-block:: text + :caption: conanfile.txt + + [requires] + zlib/1.2.12 + + [generators] + CMakeToolchain + CMakeDeps + + [layout] + cmake_layout + + +build.gradle +^^^^^^^^^^^^ + +We are going to automate calling ``conan install`` before building the Android project, so the requires are prepared, +open the ``build.gradle`` file in the ``My_Conan_App.app`` (Find it in the `Gradle Scripts` section of the Android project view). +Paste the ``task conanInstall`` contents after the ``plugins`` and before the ``android`` elements: + + +.. code-block:: groovy + :caption: build.gradle + + + plugins { + ... + } + + + task conanInstall { + def conanExecutable = "conan" // define the path to your conan installation + def buildDir = new File("app/build") + buildDir.mkdirs() + ["Debug", "Release"].each { String build_type -> + ["armv7", "armv8", "x86", "x86_64"].each { String arch -> + def cmd = conanExecutable + " install " + + "../src/main/cpp --profile android -s build_type="+ build_type +" -s arch=" + arch + + " --build missing -c tools.cmake.cmake_layout:build_folder_vars=['settings.arch']" + print(">> ${cmd} \n") + + def sout = new StringBuilder(), serr = new StringBuilder() + def proc = cmd.execute(null, buildDir) + proc.consumeProcessOutput(sout, serr) + proc.waitFor() + println "$sout $serr" + if (proc.exitValue() != 0) { + throw new Exception("out> $sout err> $serr" + "\nCommand: ${cmd}") + } + } + } + } + + android { + compileSdk 32 + + defaultConfig { + + ... + + +The ``conanInstall`` task is calling :command:`conan install` for Debug/Release and for each architecture we want to build, you +can adjust these values to match your requirements. + +If we focus on the ``conan install`` task we can see: + + 1. We are passing a ``--profile android``, so we need to create the proile. Go to the ``profiles`` folder in the + conan config home directory (check it running :command:`conan config home`) and create a file named ``android`` + with the following contents: + + .. code-block:: text + + include(default) + + [settings] + os=Android + os.api_level=21 + compiler=clang + compiler.version=12 + compiler.libcxx=c++_static + compiler.cppstd=14 + + [conf] + tools.android:ndk_path=/Users/luism/Library/Android/sdk/ndk/21.4.7075529/ + + + You might need to modify: + + - ``tools.android:ndk_path`` conf: The location of the NDK provided by Android Studio. You should be able to see the path + to the NDK if you open the ``cpp/includes`` folder in your IDE. + - ``compiler.version``: Check the NDK documentation or find a ``bin`` folder containing the compiler executables like + ``x86_64-linux-android31-clang``. In a Macos installation it is found in the NDK path + ``toolchains/llvm/prebuilt/darwin-x86_64/bin``. + Run ``./x86_64-linux-android31-clang --version`` to check the running ``clang`` version and adjust the profile. + - ``compiler.libcxx``: The supported values are ``c++_static`` and ``c++_shared``. + - ``compiler.cppstd``: The C++ standard version, this should be the value you selected in the Wizard. + - ``os.api_level``: Use the same value you selected in the Wizard. + + 2. We are passing ``-c tools.cmake.cmake_layout:build_folder_vars=['settings.arch']``, thanks to that, Conan will create a different + folder for the specified ``settings.arch`` so we can have all the configurations available at the same time. + + + +To make Conan work we need to pass CMake a custom toolchain. We can do it introducing a single line in the same file, in the +``android/defaultConfig/externalNativeBuild/cmake`` element: + +.. code-block:: groovy + :emphasize-lines: 15 + :caption: build.gradle + + android { + compileSdk 32 + + defaultConfig { + applicationId "com.example.myconanapp" + minSdk 21 + targetSdk 21 + versionCode 1 + versionName "1.0" + + testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner" + externalNativeBuild { + cmake { + cppFlags '-v' + arguments("-DCMAKE_TOOLCHAIN_FILE=conan_android_toolchain.cmake") + } + } + + +conan_android_toolchain.cmake +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a file called ``conan_android_toolchain.cmake`` in the ``cpp`` folder, that file will be responsible +of including the right toolchain depending on the ``ANDROID_ABI`` variable that indicates the build configuration that +the IDE is currently running: + +.. code-block:: cmake + :caption: conan_android_toolchain.cmake + + + # During multiple stages of CMake configuration, the toolchain file is processed and command-line + # variables may not be always available. The script exits prematurely if essential variables are absent. + + if ( NOT ANDROID_ABI OR NOT CMAKE_BUILD_TYPE ) + return() + endif() + if(${ANDROID_ABI} STREQUAL "x86_64") + include("${CMAKE_CURRENT_LIST_DIR}/build/x86_64/${CMAKE_BUILD_TYPE}/generators/conan_toolchain.cmake") + elseif(${ANDROID_ABI} STREQUAL "x86") + include("${CMAKE_CURRENT_LIST_DIR}/build/x86/${CMAKE_BUILD_TYPE}/generators/conan_toolchain.cmake") + elseif(${ANDROID_ABI} STREQUAL "arm64-v8a") + include("${CMAKE_CURRENT_LIST_DIR}/build/armv8/${CMAKE_BUILD_TYPE}/generators/conan_toolchain.cmake") + elseif(${ANDROID_ABI} STREQUAL "armeabi-v7a") + include("${CMAKE_CURRENT_LIST_DIR}/build/armv7/${CMAKE_BUILD_TYPE}/generators/conan_toolchain.cmake") + else() + message(FATAL "Not supported configuration") + endif() + + +CMakeLists.txt +^^^^^^^^^^^^^^ + +Finally, we need to modify the ``CMakeLists.txt`` to link with the ``zlib`` library: + +.. code-block:: cmake + :emphasize-lines: 7, 9 + :caption: CMakeLists.txt + + cmake_minimum_required(VERSION 3.18.1) + project("myconanapp") + add_library(myconanapp SHARED native-lib.cpp) + + find_library(log-lib log) + + find_package(ZLIB CONFIG) + + target_link_libraries(myconanapp ${log-lib} ZLIB::ZLIB) + + +Building the application +------------------------ + +If we build our project we can see that `conan install` is called multiple times building the different configurations +of ``zlib``. + +Then if we run the application in a Virtual Device or in a real device pairing it with the QR code we can see: + +|zlib1.2.11| + +Once we have our project configured, it is very easy to change our dependencies and keep developing the application, for example, +we can edit the ``conanfile.txt`` file and change the ``zlib`` to the version ``1.12.2``: + + +.. code-block:: text + + [requires] + zlib/1.2.12 + + [generators] + CMakeToolchain + CMakeDeps + + [layout] + cmake_layout + + +If we click build and then run the application, we will see that the zlib dependency has been updated: + +|zlib1.2.12| + + + + +.. |zlib1.2.11| image:: ../../../images/examples/cross_build/android/android_studio/zlib_1_2_11.png + :width: 400 + :alt: Android application showing the zlib 1.2.11 +.. |zlib1.2.12| image:: ../../../images/examples/cross_build/android/android_studio/zlib_1_2_12.jpg + :width: 400 + :alt: Android application showing the zlib 1.2.12 \ No newline at end of file diff --git a/2.1/_sources/examples/cross_build/android/ndk.rst.txt b/2.1/_sources/examples/cross_build/android/ndk.rst.txt new file mode 100644 index 000000000000..697c01b01b88 --- /dev/null +++ b/2.1/_sources/examples/cross_build/android/ndk.rst.txt @@ -0,0 +1,75 @@ +.. _examples_cross_build_android_ndk: + + +Cross building to Android with the NDK +====================================== + +In this example, we are going to see how to cross-build a Conan package to Android. + +First of all, download the Android NDK from `the download page `_ +and unzip it. In MacOS you can also install it with ``brew install android-ndk``. + +Then go to the ``profiles`` folder in the conan config home directory (check it running :command:`conan config home`) +and create a file named ``android`` with the following contents: + +.. code-block:: text + + include(default) + + [settings] + os=Android + os.api_level=21 + arch=armv8 + compiler=clang + compiler.version=12 + compiler.libcxx=c++_static + compiler.cppstd=14 + + [conf] + tools.android:ndk_path=/usr/local/share/android-ndk + +You might need to modify: + +- ``compiler.version``: Check the NDK documentation or find a ``bin`` folder containing the compiler executables like + ``x86_64-linux-android31-clang``. In a Macos installation it is found in the NDK path + ``toolchains/llvm/prebuilt/darwin-x86_64/bin``. + Run ``./x86_64-linux-android31-clang --version`` to check the running ``clang`` version and adjust the profile. +- ``compiler.libcxx``: The supported values are ``c++_static`` and ``c++_shared``. +- ``compiler.cppstd``: The C++ standard version, adjust as your needs. +- ``os.api_level``: You can check `here `_ the usage of each Android Version/API level and choose + the one that fits better with your requirements. This is typically a balance between new features and more compatible applications. +- ``arch``: There are several architectures supported by Android: ``x86``, ``x86_64``, ``armv7``, and ``armv8``. +- ``tools.android:ndk_path`` conf: Write the location of the unzipped NDK. + + +Use the :command:`conan new` command to create a "Hello World" C++ library example project: + +.. code-block:: bash + + $ conan new cmake_lib -d name=hello -d version=1.0 + + +Then we can specify the ``android`` profile and our hello library will be built for Android: + +.. code-block:: bash + + $ conan create . --profile android + + [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o + [100%] Linking CXX static library libhello.a + [100%] Built target hello + ... + [ 50%] Building CXX object CMakeFiles/example.dir/src/example.cpp.o + [100%] Linking CXX executable example + [100%] Built target example + +Both the library and the ``test_package`` executable are built for Android, so we cannot use them in our local computer. + +Unless you have access to a `root` Android device, running the test application or using the built library is not possible +directly so it is more common to build an Android application that uses the ``hello`` library. + +Read more +--------- + +- Check the example :ref:`Integrating Conan in Android Studio` to know how to use your + c++ libraries in a native Android application. +- Check the tutorial :ref:`How to cross-compile your applications using Conan`. \ No newline at end of file diff --git a/2.1/_sources/examples/dev_flow.rst.txt b/2.1/_sources/examples/dev_flow.rst.txt new file mode 100644 index 000000000000..f32ec7428bde --- /dev/null +++ b/2.1/_sources/examples/dev_flow.rst.txt @@ -0,0 +1,9 @@ +.. _developer_flow: + +Developer tools and flows +========================= + +.. toctree:: + :maxdepth: 2 + + dev_flow/debug/step_into_dependencies diff --git a/2.1/_sources/examples/dev_flow/debug/step_into_dependencies.rst.txt b/2.1/_sources/examples/dev_flow/debug/step_into_dependencies.rst.txt new file mode 100644 index 000000000000..83fbd0c682d3 --- /dev/null +++ b/2.1/_sources/examples/dev_flow/debug/step_into_dependencies.rst.txt @@ -0,0 +1,84 @@ + +.. _examples_dev_flow_debug_step_into: + + +Debugging and stepping into dependencies +======================================== + +Sometimes, when developing and debugging your own code, it could be useful to be able to step-into the +dependencies source code too. There are a couple of things to take into account: + +- Recipes and packages from ConanCenter do not package always all the debug artifacts necessary to debug. For example in Windows, the ``*.pdb`` files are not packaged, because they are very heavy, and in practice barely used. It is possible to have your own packages to package the PDB files if you want, but that still won't solve the next point. +- Debug artifacts are often not relocatable, that means that such artifacts can only be used in the location they were built from sources. But packages that are uploaded to a server and downloaded to a different machine can put those artifacts in a different folder. Then, the debug artifacts might not correctly locate the source code, the symbols, etc. + + +Building from source +-------------------- + +The recommended approach for debugging dependencies is building them from source in the local cache. This approach should work out of the box for most recipes, including ConanCenter recipes. + +We can reuse the code from the very first example in the tutorial for this use case. Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/tutorial/consuming_packages/simple_cmake_project + +Then, lets make sure the dependency is built from source: + +.. code-block:: bash + + $ conan install . -s build_type=Debug --build="zlib/*" + ... + Install finished successfully + +Assuming that we have CMake>=3.23, we can use the presets (otherwise, please use the ``-DCMAKE_TOOLCHAIN_FILE`` arguments): + +.. code-block:: bash + + $ cmake . --preset conan-default + + +This will create our project, that we can start building and debugging. + + +Step into a dependency with Visual Studio +----------------------------------------- + +Once the project is created, in Visual Studio, we can double-click on the ``compressor.sln`` file, or open the file from the open Visual Studio IDE. + +Once the project is open, the first step is building it, making sure the ``Debug`` configuration is the active one, going to ``Build -> Build Solution`` will do it. Then we can define ``compressor`` as the "Startup project" in project view. + +Going to the ``compressor/main.c`` source file, we can introduce a breakpoint in some line there: + +.. code-block:: c++ + :caption: main.c + + int main(void) { + ... + + // add a breakpoint in deflateInit line in your IDE + deflateInit(&defstream, Z_BEST_COMPRESSION); + deflate(&defstream, Z_FINISH); + +Clicking on the ``Debug -> Start Debugging`` (or F5), the program will start debugging and stop at the ``deflateInit()`` line. Clicking on the ``Debug -> Step Into``, the IDE should be able to navigate to the ``deflate.c`` source code. If we check this file, its path will be inside the Conan cache, like ``C:\Users\\.conan2\p\b\zlib4f7275ba0a71f\b\src\deflate.c`` + +.. code-block:: c++ + :caption: deflate.c + + int ZEXPORT deflateInit_(strm, level, version, stream_size) + z_streamp strm; + int level; + const char *version; + int stream_size; + { + return deflateInit2_(strm, level, Z_DEFLATED, MAX_WBITS, DEF_MEM_LEVEL, + Z_DEFAULT_STRATEGY, version, stream_size); + /* To do: ignore strm->next_in if we use it as window */ + } + + +.. seealso:: + + - Modifying the dependency source code while debugging is not possible with this approach. If that is the intended flow, the recommended approach is to use :ref:`editable package`. diff --git a/2.1/_sources/examples/extensions.rst.txt b/2.1/_sources/examples/extensions.rst.txt new file mode 100644 index 000000000000..cb0dbb772c7e --- /dev/null +++ b/2.1/_sources/examples/extensions.rst.txt @@ -0,0 +1,16 @@ +.. _examples_extensions: + +Conan extensions examples +========================= + +.. note:: + + Check the `conan-extensions `_ repository, + which hosts useful extensions ready to use or to take inspiration from for your custom ones + +.. toctree:: + :maxdepth: 2 + + extensions/commands/custom_commands + extensions/deployers/builtin_deployers + extensions/deployers/custom_deployers diff --git a/2.1/_sources/examples/extensions/commands/clean/custom_command_clean_revisions.rst.txt b/2.1/_sources/examples/extensions/commands/clean/custom_command_clean_revisions.rst.txt new file mode 100644 index 000000000000..95c27831658a --- /dev/null +++ b/2.1/_sources/examples/extensions/commands/clean/custom_command_clean_revisions.rst.txt @@ -0,0 +1,229 @@ +.. _examples_extensions_commands_clean_revisions: + +Custom command: Clean old recipe and package revisions +====================================================== + +.. note:: + + This is mostly an example command. The built-in ``conan remove *#!latest`` syntax, + meaning "all revisions but the latest" would probably be enough for this use case, + without needing this custom command. + + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/extensions/commands/clean + + +In this example we are going to see how to create/use a custom command: :command:`conan clean`. It removes +every recipe and its package revisions from the local cache or the remotes, except the latest package revision from +the latest recipe one. + +.. note:: + + To understand better this example, it is highly recommended to read previously the :ref:`Custom commands reference`. + + +Locate the command +------------------ + +Copy the command file ``cmd_clean.py`` into your ``[YOUR_CONAN_HOME]/extensions/commands/`` folder (create it if it's not there). +If you don't know where ``[YOUR_CONAN_HOME]`` is located, you can run :command:`conan config home` to check it. + + +Run it +------ + +Now, you should be able to see the new command in your command prompt: + +.. code-block:: bash + + $ conan -h + ... + Custom commands + clean Deletes (from local cache or remotes) all recipe and package revisions but the + latest package revision from the latest recipe revision. + + $ conan clean -h + usage: conan clean [-h] [-r REMOTE] [--force] + + Deletes (from local cache or remotes) all recipe and package revisions but + the latest package revision from the latest recipe revision. + + optional arguments: + -h, --help show this help message and exit + -r REMOTE, --remote REMOTE + Will remove from the specified remote + --force Remove without requesting a confirmation + + +Finally, if you execute :command:`conan clean`: + +.. code-block:: bash + + $ conan clean + Do you want to remove all the recipes revisions and their packages ones, except the latest package revision from the latest recipe one? (yes/no): yes + other/1.0 + Removed package revision: other/1.0#31da245c3399e4124e39bd4f77b5261f:da39a3ee5e6b4b0d3255bfef95601890afd80709#a16985deb2e1aa73a8480faad22b722c [Local cache] + Removed recipe revision: other/1.0#721995a35b1a8d840ce634ea1ac71161 and all its package revisions [Local cache] + hello/1.0 + Removed package revision: hello/1.0#9a77cdcff3a539b5b077dd811b2ae3b0:da39a3ee5e6b4b0d3255bfef95601890afd80709#cee90a74944125e7e9b4f74210bfec3f [Local cache] + Removed package revision: hello/1.0#9a77cdcff3a539b5b077dd811b2ae3b0:da39a3ee5e6b4b0d3255bfef95601890afd80709#7cddd50952de9935d6c3b5b676a34c48 [Local cache] + libcxx/0.1 + +Nothing should happen if you run it again: + +.. code-block:: bash + + $ conan clean + Do you want to remove all the recipes revisions and their packages ones, except the latest package revision from the latest recipe one? (yes/no): yes + other/1.0 + hello/1.0 + libcxx/0.1 + +Code tour +--------- + +The ``conan clean`` command has the following code: + +.. code-block:: python + :caption: cmd_clean.py + + from conan.api.conan_api import ConanAPI + from conan.api.output import ConanOutput, Color + from conan.cli.command import OnceArgument, conan_command + from conans.client.userio import UserInput + + + recipe_color = Color.BRIGHT_BLUE + removed_color = Color.BRIGHT_YELLOW + + + @conan_command(group="Custom commands") + def clean(conan_api: ConanAPI, parser, *args): + """ + Deletes (from local cache or remotes) all recipe and package revisions but + the latest package revision from the latest recipe revision. + """ + parser.add_argument('-r', '--remote', action=OnceArgument, + help='Will remove from the specified remote') + parser.add_argument('--force', default=False, action='store_true', + help='Remove without requesting a confirmation') + args = parser.parse_args(*args) + + def confirmation(message): + return args.force or ui.request_boolean(message) + + ui = UserInput(non_interactive=False) + out = ConanOutput() + remote = conan_api.remotes.get(args.remote) if args.remote else None + output_remote = remote or "Local cache" + + # Getting all the recipes + recipes = conan_api.search.recipes("*/*", remote=remote) + if recipes and not confirmation("Do you want to remove all the recipes revisions and their packages ones, " + "except the latest package revision from the latest recipe one?"): + return + for recipe in recipes: + out.writeln(f"{str(recipe)}", fg=recipe_color) + all_rrevs = conan_api.list.recipe_revisions(recipe, remote=remote) + latest_rrev = all_rrevs[0] if all_rrevs else None + for rrev in all_rrevs: + if rrev != latest_rrev: + conan_api.remove.recipe(rrev, remote=remote) + out.writeln(f"Removed recipe revision: {rrev.repr_notime()} " + f"and all its package revisions [{output_remote}]", fg=removed_color) + else: + packages = conan_api.list.packages_configurations(rrev, remote=remote) + for package_ref in packages: + all_prevs = conan_api.list.package_revisions(package_ref, remote=remote) + latest_prev = all_prevs[0] if all_prevs else None + for prev in all_prevs: + if prev != latest_prev: + conan_api.remove.package(prev, remote=remote) + out.writeln(f"Removed package revision: {prev.repr_notime()} [{output_remote}]", fg=removed_color) + + + +Let's analyze the most important parts. + +parser +++++++ + +The ``parser`` param is an instance of the Python command-line parsing ``argparse.ArgumentParser``, +so if you want to know more about its API, visit `its official website `_. + + +User input and user output +++++++++++++++++++++++++++ + +Important classes to manage user input and user output: + +.. code-block:: python + + ui = UserInput(non_interactive=False) + out = ConanOutput() + + +* ``UserInput(non_interactive)``: class to manage user inputs. In this example we're using ``ui.request_boolean("Do you want to proceed?")``, + so it'll be automatically translated to ``Do you want to proceed? (yes/no):`` in the command prompt. + **Note**: you can use ``UserInput(non_interactive=conan_api.config.get("core:non_interactive"))`` too. +* ``ConanOutput()``: class to manage user outputs. In this example, we're using only ``out.writeln(message, fg=None, bg=None)`` + where ``fg`` is the font foreground, and ``bg`` is the font background. Apart from that, you have some predefined methods + like ``out.info()``, ``out.success()``, ``out.error()``, etc. + + +Conan public API +++++++++++++++++ + +.. include:: ../../../../common/experimental_warning.inc + +The most important part of this example is the usage of the Conan API via ``conan_api`` parameter. These are some examples +which are being used in this custom command: + +.. code-block:: python + + conan_api.remotes.get(args.remote) + conan_api.search.recipes("*/*", remote=remote) + conan_api.list.recipe_revisions(recipe, remote=remote) + conan_api.remove.recipe(rrev, remote=remote) + conan_api.list.packages_configurations(rrev, remote=remote) + conan_api.list.package_revisions(package_ref, remote=remote) + conan_api.remove.package(prev, remote=remote) + + + +* ``conan_api.remotes.get(...)``: ``[RemotesAPI]`` Returns a RemoteRegistry given the remote name. +* ``conan_api.search.recipes(...)``: ``[SearchAPI]`` Returns a list with all the recipes matching the given pattern. +* ``conan_api.list.recipe_revisions(...)``: ``[ListAPI]`` Returns a list with all the recipe revisions given a recipe reference. +* ``conan_api.list.packages_configurations(...)``: ``[ListAPI]`` Returns the list of different configurations (package_id's) for a recipe revision. +* ``conan_api.list.package_revisions(...)``: ``[ListAPI]`` Returns the list of package revisions for a given recipe revision. +* ``conan_api.remove.recipe(...)``: ``[RemoveAPI]`` Removes the given recipe revision. +* ``conan_api.remove.package(...)``: ``[RemoveAPI]`` Removes the given package revision. + +Besides that, it deserves especial attention these lines: + +.. code-block:: python + + all_rrevs = conan_api.list.recipe_revisions(recipe, remote=remote) + latest_rrev = all_rrevs[0] if all_rrevs else None + + ... + + packages = conan_api.list.packages_configurations(rrev, remote=remote) + + ... + + all_prevs = conan_api.list.package_revisions(package_ref, remote=remote) + latest_prev = all_prevs[0] if all_prevs else None + +Basically, these API calls are returning a list of recipe revisions and package ones +respectively, but we're saving the first element as the latest one because these calls are +getting an ordered list always. + + +If you want to know more about the Conan API, visit the :ref:`ConanAPI section` diff --git a/2.1/_sources/examples/extensions/commands/custom_commands.rst.txt b/2.1/_sources/examples/extensions/commands/custom_commands.rst.txt new file mode 100644 index 000000000000..52b03e13535e --- /dev/null +++ b/2.1/_sources/examples/extensions/commands/custom_commands.rst.txt @@ -0,0 +1,12 @@ +.. _examples_extensions_custom_commands: + + +Custom commands +=============== + + +.. toctree:: + :maxdepth: 2 + + + clean/custom_command_clean_revisions \ No newline at end of file diff --git a/2.1/_sources/examples/extensions/deployers/builtin_deployers.rst.txt b/2.1/_sources/examples/extensions/deployers/builtin_deployers.rst.txt new file mode 100644 index 000000000000..3d392f3fccc4 --- /dev/null +++ b/2.1/_sources/examples/extensions/deployers/builtin_deployers.rst.txt @@ -0,0 +1,10 @@ +.. _examples_extensions_builtin_deployers: + + +Builtin deployers +================= + +.. toctree:: + :maxdepth: 2 + + dev/development_deploy diff --git a/2.1/_sources/examples/extensions/deployers/custom_deployers.rst.txt b/2.1/_sources/examples/extensions/deployers/custom_deployers.rst.txt new file mode 100644 index 000000000000..1e3a1ccb37b5 --- /dev/null +++ b/2.1/_sources/examples/extensions/deployers/custom_deployers.rst.txt @@ -0,0 +1,14 @@ +.. _examples_extensions_deployers: + + + + +Custom deployers +================ + + +.. toctree:: + :maxdepth: 2 + + + sources/custom_deployer_sources diff --git a/2.1/_sources/examples/extensions/deployers/dev/development_deploy.rst.txt b/2.1/_sources/examples/extensions/deployers/dev/development_deploy.rst.txt new file mode 100644 index 000000000000..42d516c4d5ea --- /dev/null +++ b/2.1/_sources/examples/extensions/deployers/dev/development_deploy.rst.txt @@ -0,0 +1,148 @@ +.. _examples_extensions_builtin_deployers_development: + + +Creating a Conan-agnostic deploy of dependencies for developer use +================================================================== + +With the ``full_deploy`` deployer it is possible to create a Conan-agnostic copy of dependencies that can be used by developers without even having Conan installed in their computers. + +The common and recommended flow for most cases is using Conan packages directly from the Conan cache: + +.. image:: /images/examples/extensions/deployers/packages_from_cache.png + :align: center + +However, in some situations, it might be useful to be able to deploy a copy of the dependencies into a user folder, so the dependencies can be located there instead of in the Conan cache. +This is possible using the Conan deployers. + +Let's see it with an example. All the source code is in the +`examples2.0 Github repository `_ + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/extensions/deployers/development_deploy + +In the folder we can find the following ``conanfile.txt``: + +.. code-block:: ini + + [requires] + zlib/1.2.13 + + [tool_requires] + cmake/3.25.3 + + [generators] + CMakeDeps + CMakeToolchain + + [layout] + cmake_layout + +The folder also contains a standard ``CMakeLists.txt`` and a ``main.cpp`` source file that can create +an executable that links with ``zlib`` library. + +We can install the Debug and Release dependencies, and deploy a local copy of the packages with: + +.. code-block:: bash + + $ conan install . --deployer=full_deploy --build=missing + $ conan install . --deployer=full_deploy -s build_type=Debug --build=missing + +This will create the following folders: + +.. code-block:: text + + ├──src + ├──build + │ ├──generators + | └── ZLibConfig.cmake + ├──full_deploy + │ ├──build + │ │ └──cmake + │ │ └──3.25.3 + │ │ └──x86_64 + │ │ ├──bin + │ │ + │ └──host + │ └──zlib + │ └──1.2.13 + │ ├──Debug + │ │ └──x86_64 + │ │ ├──include + │ │ ├──lib + │ └──Release + │ └──x86_64 + │ ├──include + │ ├──lib + + +(Note that you could use the ``--deployer-folder`` argument to change the base folder output path for the deployer) + +This folder is fully self-contained. It contains both the necessary tools (like ``cmake`` executable), the headers and compiled libraries of ``zlib`` and the necessary files like ``ZLibConfig.cmake`` in the ``build/generators`` folder, that point to the binaries inside ``full_deploy`` with a relative path. + +.. image:: /images/examples/extensions/deployers/independent_dependencies_deploy.png + :align: center + + +The Conan cache can be removed, and even Conan uninstalled, then the folder could be moved elsewhere in the computer or copied to another computer, assuming it has the same configuration of OS, compiler, etc. + +.. code-block:: bash + + $ cd .. + $ cp -R development_deploy /some/other/place + $ cd /some/other/place + +And the files could be used by developers as: + +.. code-block:: bash + :caption: Windows + + $ cd build + # Activate the environment to use CMake 3.25 + $ generators\conanbuild.bat + $ cmake --version + cmake version 3.25.3 + # Configure, should match the settings used at install + $ cmake .. -G \"Visual Studio 17 2022\" -DCMAKE_TOOLCHAIN_FILE=generators/conan_toolchain.cmake + $ cmake --build . --config Release + $ Release\compressor.exe + ZLIB VERSION: 1.2.13 + + +The environment scripts in Linux and OSX are not relocatable, because they contain absolute paths and the ``sh`` shell `does not have any way to provide access to the current script directory for sourced files `_. + +This shouldn't be a big blocker, as a "search and replace" with ``sed`` in the generators folder can fix it: + +.. code-block:: bash + :caption: Linux + + $ cd build/Release/generators + # Fix folders in Linux + $ sed -i 's,{old_folder},{new_folder},g' * + # Fix folders in MacOS + $ sed -i '' 's,{old_folder},{new_folder},g' * + $ source conanbuild.sh + $ cd .. + $ cmake --version + cmake version 3.25.3 + $ cmake ../.. -DCMAKE_TOOLCHAIN_FILE=generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release + $ cmake --build . + $ ./compressor + ZLIB VERSION: 1.2.13 + + +.. note:: + + **Best practices** + + The fact that this flow is possible doesn't mean that it is recommended for the majority of cases. + It has some limitations: + + - It is less efficient, requiring an extra copy of dependencies + - Only ``CMakeDeps`` and ``CMakeToolchain`` are relocatable at this moment. For other build system integrations, please create a ticket in Github + - Linux and OSX shell scripts are not relocatable and require a manual ``sed`` + - The binary variability is limited to Release/Debug. The generated files are exclusively for the current configuration, changing any other setting (os, compiler, architecture) will require a different deploy + + In the general case, normal usage of the cache is recommended. This "relocatable development deployment" + could be useful for distributing final products that looks like an SDK, to consumers of a project not using Conan. diff --git a/2.1/_sources/examples/extensions/deployers/sources/custom_deployer_sources.rst.txt b/2.1/_sources/examples/extensions/deployers/sources/custom_deployer_sources.rst.txt new file mode 100644 index 000000000000..560cc698a9c6 --- /dev/null +++ b/2.1/_sources/examples/extensions/deployers/sources/custom_deployer_sources.rst.txt @@ -0,0 +1,100 @@ +.. examples_extensions_deployers_sources: + +Copy sources from all your dependencies +======================================= + + + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/extensions/deployers/sources + + +In this example we are going to see how to create and use a custom deployer. +This deployer copies all the source files from your dependencies and puts them into a specific output folder + +.. note:: + + To better understand this example, it is highly recommended to have previously read the :ref:`Deployers ` reference. + + +Locate the deployer +------------------- + +In this case, the deployer is located in the same directory as our example conanfile, +but as shown in :ref:`Deployers ` reference, +Conan will look for the specified deployer in a few extra places in order, namely: + +#. Absolute paths +#. Relative to cwd +#. In the ``[CONAN_HOME]/extensions/deployers`` folder +#. Built-in deployers + + +Run it +------ + +For our example, we have a simple recipe that lists both ``zlib`` and ``mcap`` as requirements. +With the help of the ``tools.build:download_source=True`` conf, we can force the invocation of its ``source()`` method, +which will ensure that sources are available even if no build needs to be carried out. + +Now, you should be able to use the new deployer in both ``conan install`` and ``conan graph`` commands for any given recipe: + +.. code-block:: bash + + $ conan graph info . -c tools.build:download_source=True --deployer=sources_deploy + + +Inspecting the command output we can see that it copied the sources of our direct dependencies ``zlib`` and ``mcap``, +**plus** the sources of our transitive dependencies, ``zstd`` and ``lz4`` to a ``dependencies_sources`` folder. +After this is done, extra preprocessing could be done to accomplish more specific needs. + +Note that you can pass the ``--deployer-folder`` argument to change the base folder output path for the deployer. + +Code tour +--------- + +The **source_deploy.py** file has the following code: + + + +.. code-block:: python + :caption: **sources_deploy.py** + + from conan.tools.files import copy + import os + + + def deploy(graph, output_folder, **kwargs): + # Note the kwargs argument is mandatory to be robust against future changes. + for name, dep in graph.root.conanfile.dependencies.items(): + if dep.folders is None or dep.folders.source_folder is None: + raise ConanException(f"Sources missing for {name} dependency.\n" + "This deployer needs the sources of every dependency present to work, either building from source, " + "or by using the 'tools.build:download_source' conf.") + copy(graph.root.conanfile, "*", dep.folders.source_folder, os.path.join(output_folder, "dependency_sources", str(dep))) + + +deploy() +++++++++ + +The ``deploy()`` method is called by Conan, and gets both a dependency graph and an output folder path as arguments. +It iterates all the dependencies of our recipe and copies every source file to their respective folders +under ``dependencies_sources`` using :ref:`conan.tools.copy`. + + +.. note:: + + If you're using this deployer as an example for your own, remember that + ``tools.build:download_source=True`` is necessary so that ``dep.folders.source_folder`` is defined for the dependencies. + Without the conf, said variable will not be defined for those dependencies that do not need to be built from sources + nor in those commands that do not require building, such as :command:`conan graph`. + +.. note:: + + If your custom deployer needs access to the full dependency graph, including those libraries that might be skipped, + use the ``tools.graph:skip_binaries=False`` conf. This is useful for collecting, for example, all the licenses in your graph. diff --git a/2.1/_sources/examples/graph.rst.txt b/2.1/_sources/examples/graph.rst.txt new file mode 100644 index 000000000000..439954e43f9b --- /dev/null +++ b/2.1/_sources/examples/graph.rst.txt @@ -0,0 +1,17 @@ +.. _examples_graph: + +Graph examples +============== + +This section contains examples about different types of advanced graphs, using different types of ``requires`` and ``tool_requires``, +advanced usage of requirement traits, etc. + + +.. toctree:: + :maxdepth: 2 + + graph/requires/consume_cmake_macro + graph/tool_requires/use_cmake_modules + graph/tool_requires/different_versions + graph/tool_requires/different_options + graph/tool_requires/using_protobuf diff --git a/2.1/_sources/examples/graph/requires/consume_cmake_macro.rst.txt b/2.1/_sources/examples/graph/requires/consume_cmake_macro.rst.txt new file mode 100644 index 000000000000..48bd3643c0c9 --- /dev/null +++ b/2.1/_sources/examples/graph/requires/consume_cmake_macro.rst.txt @@ -0,0 +1,79 @@ +.. _consume_cmake_macro: + +Use a CMake macro packaged in a dependency +------------------------------------------ + +When a package recipe wants to provide a CMake functionality via a macro, it can be done as follows. +Let's say that we have a ``pkg`` recipe, that will "export" and "package" a ``Macros.cmake`` file +that contains a ``pkg_macro()`` CMake macro: + + +.. code-block:: python + :caption: pkg/conanfile.py + + from conan import ConanFile + from conan.tools.files import copy + + class Pkg(ConanFile): + name = "pkg" + version = "0.1" + package_type = "static-library" + # Exporting, as part of the sources + exports_sources = "*.cmake" + + def package(self): + # Make sure the Macros.cmake is packaged + copy(self, "*.cmake", src=self.source_folder, dst=self.package_folder) + + def package_info(self): + # We need to define that there are "build-directories", in this case + # the current package root folder, containing build files and scripts + self.cpp_info.builddirs = ["."] + +.. code-block:: cmake + :caption: pkg/Macros.cmake + + function(pkg_macro) + message(STATUS "PKG MACRO WORKING!!!") + endfunction() + +When this package is created (``cd pkg && conan create .``), it can be consumed by other package +recipes, for example this application: + +.. code-block:: python + :caption: app/conanfile.py + + from conan import ConanFile + from conan.tools.cmake import CMake + + class App(ConanFile): + package_type = "application" + generators = "CMakeToolchain" + settings = "os", "compiler", "arch", "build_type" + requires = "pkg/0.1" + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + +That has this ``CMakeLists.txt``: + +.. code-block:: cmake + :caption: app/CMakeLists.txt + + cmake_minimum_required(VERSION 3.15) + project(App LANGUAGES NONE) + + include(Macros) # include the file with the macro (note no .cmake extension) + pkg_macro() # call the macro + + +So when we run a local build, we will see how the file is included and the macro called: + + +.. code-block:: bash + + $ cd app + $ conan build . + PKG MACRO WORKING!!! diff --git a/2.1/_sources/examples/graph/tool_requires/different_options.rst.txt b/2.1/_sources/examples/graph/tool_requires/different_options.rst.txt new file mode 100644 index 000000000000..2040369196b7 --- /dev/null +++ b/2.1/_sources/examples/graph/tool_requires/different_options.rst.txt @@ -0,0 +1,121 @@ +Depending on same version of a tool-require with different options +================================================================== + +.. note:: + + This is an **advanced** use case. It shouldn't be necessary in the vast majority of cases. + + +In the general case, trying to do something like this: + +.. code-block:: python + + def build_requirements(self): + self.tool_requires("gcc/1.0") + self.tool_requires("gcc/1.0") + +Will generate a "conflict", showing an error like ``Duplicated requirement``. + +However there are some exceptional situations that we could need to depend on the same ``tool_requires`` version, +but using different binaries of that ``tool_requires``. This can be achieved by passing different ``options`` to those +``tool_requires``. Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: shell + + git clone https://github.com/conan-io/examples2.git + cd examples2/examples/graph/tool_requires/different_options + +There we have a ``gcc`` fake recipe with: + +.. code-block:: python + + class Pkg(ConanFile): + name = "gcc" + version = "1.0" + options = {"myoption": [1, 2]} + + def package(self): + # This fake compiler will print something different based on the option + echo = f"@echo off\necho MYGCC={self.options.myoption}!!" + save(self, os.path.join(self.package_folder, "bin", f"mygcc{self.options.myoption}.bat"), echo) + save(self, os.path.join(self.package_folder, "bin", f"mygcc{self.options.myoption}.sh"), echo) + os.chmod(os.path.join(self.package_folder, "bin", f"mygcc{self.options.myoption}.sh"), 0o777) + + +This is not an actual compiler, it fakes it with a shell or bat script that prints ``MYGCC=current-option`` when executed. +Note the binary itself is called ``mygcc1`` and ``mygcc2``, that is, it contains the option in the executable name itself. + +We can create 2 different binaries for ``gcc/1.0`` with: + + +.. code-block:: bash + + $ conan create gcc -o myoption=1 + $ conan create gcc -o myoption=2 + +Now, in the ``wine`` folder there is a ``conanfile.py`` like this: + +.. code-block:: python + + class Pkg(ConanFile): + name = "wine" + version = "1.0" + + def build_requirements(self): + self.tool_requires("gcc/1.0", run=False, options={"myoption": 1}) + self.tool_requires("gcc/1.0", run=False, options={"myoption": 2}) + + def generate(self): + gcc1 = self.dependencies.build.get("gcc", options={"myoption": 1}) + assert gcc1.options.myoption == "1" + gcc2 = self.dependencies.build.get("gcc", options={"myoption": 2}) + assert gcc2.options.myoption == "2" + + def build(self): + ext = "bat" if platform.system() == "Windows" else "sh" + self.run(f"mygcc1.{ext}") + self.run(f"mygcc2.{ext}") + + +The first important point is the ``build_requirements()`` method, that does a ``tool_requires()`` to both binaries, +but defining ``run=False`` and ``options={"myoption": value}`` traits. **This is very important**: we are telling Conan +that we actually don't need to run anything from those packages. As ``tool_requires`` are not visible, they don't define +headers or libraries and they define different ``options``, there is nothing that makes Conan identify those 2 ``tool_requires`` +as conflicting. So the dependency graph can be constructed without errors, and the ``wine/1.0`` package will contain +2 different tool-requires to both ``gcc/1.0`` with ``myoption=1`` and with ``myoption=2``. + +Of course, it is not true that we won't run anything from those ``tool_requires``, but now Conan is not aware of it, +and it is completely the responsibility of the user to manage it. + +.. warning:: + + Using ``run=False`` makes the ``tool_requires()`` completely invisible, that means that profile ``[tool_requires]`` + will not be able to override its version, but it would create an extra tool-require dependency with the version + injected from the profile. You might want to exclude specific packages with something like ``!wine/*: gcc/3.0``. + +The recipe still has access in the ``generate()`` method to each different ``tool_require`` version, just by providing +the options values for the dependency that we want ``self.dependencies.build.get("gcc", options={"myoption": 1})``. + +Finally, the most important part is that the usage of those tools is completely the responsibility of the user. The ``bin`` +folder of both ``tool_requires`` containing the executables will be in the path thanks to the ``VirtualBuildEnv`` generator +that by default updates the PATH env-var. In this case the executables are different like ``mygcc1.sh```and ``mygcc2.sh``, +so it is not an issue, and each one will be found inside its package. + +But if the executable file was exactly the same like ``gcc.exe``, then it would be necessary to obtain the full folder +(typically in the ``generate()`` method) with something like ``self.dependencies.build.get("gcc", options={"myoption": 1}).cpp_info.bindir`` and +use the full path to disambiguate. + + +Let's see it working. If we execute: + + +.. code-block:: bash + + $ conan create wine + ... + wine/1.0: RUN: mygcc1.bat + MYGCC=1!! + + wine/1.0: RUN: mygcc2.bat + MYGCC=2!! diff --git a/2.1/_sources/examples/graph/tool_requires/different_versions.rst.txt b/2.1/_sources/examples/graph/tool_requires/different_versions.rst.txt new file mode 100644 index 000000000000..01e2dcec40e5 --- /dev/null +++ b/2.1/_sources/examples/graph/tool_requires/different_versions.rst.txt @@ -0,0 +1,119 @@ +Depending on different versions of the same tool-require +======================================================== + +.. note:: + + This is an **advanced** use case. It shouldn't be necessary in the vast majority of cases. + + +In the general case, trying to do something like this: + +.. code-block:: python + + def build_requirements(self): + self.tool_requires("gcc/1.0") + self.tool_requires("gcc/2.0") + +Will generate a "conflict", showing an error like ``Duplicated requirement``. This is correct in most situations, +when it is obvious that it is not possible to use 2 versions of the same compiler to build the current package. + +However there are some exceptional situations when something like that is desired. Let's recreate the potential +scenario. Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: shell + + git clone https://github.com/conan-io/examples2.git + cd examples2/examples/graph/tool_requires/different_versions + +There we have a ``gcc`` fake recipe with: + +.. code-block:: python + + class Pkg(ConanFile): + name = "gcc" + + def package(self): + echo = f"@echo off\necho MYGCC={self.version}!!" + save(self, os.path.join(self.package_folder, "bin", f"mygcc{self.version}.bat"), echo) + save(self, os.path.join(self.package_folder, "bin", f"mygcc{self.version}.sh"), echo) + os.chmod(os.path.join(self.package_folder, "bin", f"mygcc{self.version}.sh"), 0o777) + + +This is not an actual compiler, it fakes it with a shell or bat script that prints ``MYGCC=current-version`` when executed. +Note the binary itself is called ``mygcc1.0`` and ``mygcc2.0``, that is, it contains the version in the executable name itself. + +We can create 2 different versions for ``gcc/1.0`` and ``gcc/2.0`` with: + + +.. code-block:: bash + + $ conan create gcc --version=1.0 + $ conan create gcc --version=2.0 + +Now, in the ``wine`` folder there is a ``conanfile.py`` like this: + +.. code-block:: python + + class Pkg(ConanFile): + name = "wine" + version = "1.0" + + def build_requirements(self): + # If we specify "run=False" they no longer conflict + self.tool_requires("gcc/1.0", run=False) + self.tool_requires("gcc/2.0", run=False) + + def generate(self): + # It is possible to individually reference each one + gcc1 = self.dependencies.build["gcc/1.0"] + assert gcc1.ref.version == "1.0" + gcc2 = self.dependencies.build["gcc/2.0"] + assert gcc2.ref.version == "2.0" + + def build(self): + ext = "bat" if platform.system() == "Windows" else "sh" + self.run(f"mygcc1.0.{ext}") + self.run(f"mygcc2.0.{ext}") + + +The first important point is the ``build_requirements()`` method, that does a ``tool_requires()`` to both versions, +but defining ``run=False``. **This is very important**: we are telling Conan that we actually don't need to run +anything from those packages. As ``tool_requires`` are not visible, they don't define headers or libraries, there is +nothing that makes Conan identify those 2 ``tool_requires`` as conflicting. So the dependency graph can be constructed +without errors, and the ``wine/1.0`` package will contain 2 different tool-requires to both ``gcc/1.0`` and ``gcc/2.0``. + +Of course, it is not true that we won't run anything from those ``tool_requires``, but now Conan is not aware of it, +and it is completely the responsibility of the user to manage it. + +.. warning:: + + Using ``run=False`` makes the ``tool_requires()`` completely invisible, that means that profile ``[tool_requires]`` + will not be able to override its version, but it would create an extra tool-require dependency with the version + injected from the profile. You might want to exclude specific packages with something like ``!wine/*: gcc/3.0``. + +The recipe has still access in the ``generate()`` method to each different ``tool_require`` version, just by providing +the full reference like ``self.dependencies.build["gcc/1.0"]``. + +Finally, the most important part is that the usage of those tools is completely the responsibility of the user. The ``bin`` +folder of both ``tool_requires`` containing the executables will be in the path thanks to the ``VirtualBuildEnv`` generator +that by default updates the PATH env-var. In this case the executables are different like ``mygcc1.0.sh```and ``mygcc2.0.sh``, +so it is not an issue, and each one will be found inside its package. + +But if the executable file was exactly the same like ``gcc.exe``, then it would be necessary to obtain the full folder +(typically in the ``generate()`` method) with something like ``self.dependencies.build["gcc/1.0"].cpp_info.bindir`` and +use the full path to disambiguate. + + +Let's see it working. If we execute: + + +.. code-block:: bash + + $ conan create wine + ... + wine/1.0: RUN: mygcc1.0.bat + MYGCC=1.0!! + + wine/1.0: RUN: mygcc2.0.bat + MYGCC=2.0!! diff --git a/2.1/_sources/examples/graph/tool_requires/use_cmake_modules.rst.txt b/2.1/_sources/examples/graph/tool_requires/use_cmake_modules.rst.txt new file mode 100644 index 000000000000..10f6ba361617 --- /dev/null +++ b/2.1/_sources/examples/graph/tool_requires/use_cmake_modules.rst.txt @@ -0,0 +1,92 @@ +Use cmake modules inside a ``tool_requires`` transparently +========================================================== + +When we want to reuse some ``.cmake`` scripts that are inside another Conan package +there are several possible different scenarios, like if the ``.cmake`` scripts are inside +a regular ``requires`` or a ``tool_requires``. + +Also, it is possible to want 2 different approaches: + +- The consumer of the scripts can do a explicit ``include(MyScript)`` in their CMakeLists.txt. This approach is nicely explicit and simpler to setup, just define ``self.cpp_info.builddirs`` in the recipe, and consumers with ``CMakeToolchain`` will automatically be able to do the ``include()`` and use the functionality. See the :ref:`example here` +- The consumer wants to have the dependency cmake modules automatically loaded when the ``find_package()`` is executed. This current example implements this case. + + +Let's say that we have a package, intended to be used as a ``tool_require``, with the following recipe: + +.. code-block:: python + :caption: myfunctions/conanfile.py + + import os + from conan import ConanFile + from conan.tools.files import copy + + class Conan(ConanFile): + name = "myfunctions" + version = "1.0" + exports_sources = ["*.cmake"] + + def package(self): + copy(self, "*.cmake", self.source_folder, self.package_folder) + + def package_info(self): + self.cpp_info.set_property("cmake_build_modules", ["myfunction.cmake"]) + +And a ``myfunction.cmake`` file in: + +.. code-block:: cmake + :caption: myfunctions/myfunction.cmake + + function(myfunction) + message("Hello myfunction!!!!") + endfunction() + +We can do a ``cd myfunctions && conan create .`` which will create the ``myfunctions/1.0`` package containing the cmake script. + +Then, a consumer package will look like: + +.. code-block:: python + :caption: consumer/conanfile.py + + from conan import ConanFile + from conan.tools.cmake import CMake, CMakeDeps, CMakeToolchain + + class Conan(ConanFile): + settings = "os", "compiler", "build_type", "arch" + tool_requires = "myfunctions/1.0" + + def generate(self): + tc = CMakeToolchain(self) + tc.generate() + + deps = CMakeDeps(self) + # By default 'myfunctions-config.cmake' is not created for tool_requires + # we need to explicitly activate it + deps.build_context_activated = ["myfunctions"] + # and we need to tell to automatically load 'myfunctions' modules + deps.build_context_build_modules = ["myfunctions"] + deps.generate() + + def build(self): + cmake = CMake(self) + cmake.configure() + +And a ``CMakeLists.txt`` like: + +.. code-block:: cmake + :caption: consumer/CMakeLists.txt + + cmake_minimum_required(VERSION 3.0) + project(test) + find_package(myfunctions CONFIG REQUIRED) + myfunction() + + +Then, the consumer will be able to automatically call the ``myfunction()`` from the dependency module: + +.. code-block:: bash + + $ conan build . + ... + Hello myfunction!!!! + +If for some reason the consumer wants to force the usage from the ``tool_requires()`` as a CMake module, the consumer could do ``deps.set_property("myfunctions", "cmake_find_mode", "module", build_context=True)``, and then ``find_package(myfunctions MODULE REQUIRED)`` will work. diff --git a/2.1/_sources/examples/graph/tool_requires/using_protobuf.rst.txt b/2.1/_sources/examples/graph/tool_requires/using_protobuf.rst.txt new file mode 100644 index 000000000000..a6d39e2fc448 --- /dev/null +++ b/2.1/_sources/examples/graph/tool_requires/using_protobuf.rst.txt @@ -0,0 +1,249 @@ +.. _examples_graph_tool_requires_protobuf: + +Using the same requirement as a requires and as a tool_requires +===================================================================== + +There are libraries which could behave as a library and as a tool requirement, e.g., `protobuf `__ +Those libraries normally contains headers/sources of the library itself, and, perhaps, some extra tools +(compilers, shell scripts, etc.). Both parts are used in different contexts, let's think of this scenario using +*protobuf* for instance: + +* I want to create a library which includes a compiled protobuf message. The protobuf compiler (build context) + needs to be invoked at build time, and the library with the compiled *.pb.cc* file needs to be linked against + the protobuf library (host context). + + +Given that, we should be able to use protobuf in build/host context in the same Conan recipe. Basically, your package recipe +should look like: + +.. code-block:: python + + def requirements(self): + self.requires("protobuf/3.18.1") + + def build_requirements(self): + self.tool_requires("protobuf/") + +.. note:: + + The ``protobuf/`` expression ensures that the same version of the library is used in both contexts. + You can read more about it :ref:`here`. + + +This is the way to proceed with any other library used in both contexts. Nonetheless, let's see a detailed example to see +how the example looks like. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: shell + + git clone https://github.com/conan-io/examples2.git + cd examples2/examples/graph/tool_requires/using_protobuf/myaddresser + + +The structure of the project is the following: + +.. code-block:: text + + ./ + ├── conanfile.py + ├── CMakeLists.txt + ├── addressbook.proto + ├── apple-arch-armv8 + ├── apple-arch-x86_64 + └── src + └── myaddresser.cpp + └── include + └── myaddresser.h + └── test_package + ├── conanfile.py + ├── CMakeLists.txt + └── src + └── example.cpp + + +The ``conanfile.py`` looks like: + +.. code-block:: python + :caption: ./conanfile.py + + from conan import ConanFile + from conan.tools.cmake import CMake, cmake_layout + + + class myaddresserRecipe(ConanFile): + name = "myaddresser" + version = "1.0" + package_type = "library" + settings = "os", "compiler", "build_type", "arch" + options = {"shared": [True, False], "fPIC": [True, False]} + default_options = {"shared": False, "fPIC": True} + generators = "CMakeDeps", "CMakeToolchain" + # Sources are located in the same place as this recipe, copy them to the recipe + exports_sources = "CMakeLists.txt", "src/*", "include/*", "addressbook.proto" + + def config_options(self): + if self.settings.os == "Windows": + self.options.rm_safe("fPIC") + + def configure(self): + if self.options.shared: + self.options.rm_safe("fPIC") + + def requirements(self): + self.requires("protobuf/3.18.1") + + def build_requirements(self): + self.tool_requires("protobuf/") + + def layout(self): + cmake_layout(self) + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + + def package(self): + cmake = CMake(self) + cmake.install() + + def package_info(self): + self.cpp_info.libs = ["myaddresser"] + self.cpp_info.requires = ["protobuf::libprotobuf"] + +As you can see, we're using *protobuf* at the same time but in different contexts. + +The ``CMakeLists.txt`` shows how this example uses protobuf compiler and library: + +.. code-block:: cmake + :caption: ./CMakeLists.txt + + cmake_minimum_required(VERSION 3.15) + project(myaddresser LANGUAGES CXX) + + find_package(protobuf CONFIG REQUIRED) + + protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS addressbook.proto) + + add_library(myaddresser src/myaddresser.cpp ${PROTO_SRCS}) + target_include_directories(myaddresser PUBLIC include) + + target_include_directories(myaddresser PUBLIC + $ + $ + $ + ) + + target_link_libraries(myaddresser PUBLIC protobuf::libprotobuf) + + set_target_properties(myaddresser PROPERTIES PUBLIC_HEADER "include/myaddresser.h;${PROTO_HDRS}") + install(TARGETS myaddresser) + + +Where the library itself defines a simple *myaddresser.cpp* which uses the generated *addressbook.pb.h* header: + +.. code-block:: cpp + :caption: ./src/myaddresser.cpp + + #include + #include + #include + #include "addressbook.pb.h" + #include "myaddresser.h" + + void myaddresser(){ + // Testing header generated by protobuf + GOOGLE_PROTOBUF_VERIFY_VERSION; + + tutorial::AddressBook address_book; + auto * person = address_book.add_people(); + person->set_id(1337); + std::cout << "myaddresser(): created a person with id 1337\n"; + // Optional: Delete all global objects allocated by libprotobuf. + google::protobuf::ShutdownProtobufLibrary(); + } + +Finally, the *test_package* example simply calls the ``myaddresser()`` function to check that everything works correctly: + +.. code-block:: cpp + :caption: ./test_package/src/example.cpp + + #include + #include + #include + #include "myaddresser.h" + + + int main(int argc, char* argv[]) { + myaddresser(); + return 0; + } + + +So, let's see if it works fine: + +.. code-block:: shell + + $ conan create . --build missing + ... + + Requirements + myaddresser/1.0#71305099cc4dc0b08bb532d4f9196ac1:c4e35584cc696eb5dd8370a2a6d920fb2a156438 - Build + protobuf/3.18.1#ac69396cd9fbb796b5b1fc16473ca354:e60fa1e7fc3000cc7be2a50a507800815e3f45e0#0af7d905b0df3225a3a56243841e041b - Cache + zlib/1.2.13#13c96f538b52e1600c40b88994de240f:d0599452a426a161e02a297c6e0c5070f99b4909#69b9ece1cce8bc302b69159b4d437acd - Cache + Build requirements + protobuf/3.18.1#ac69396cd9fbb796b5b1fc16473ca354:e60fa1e7fc3000cc7be2a50a507800815e3f45e0#0af7d905b0df3225a3a56243841e041b - Cache + ... + + -- Install configuration: "Release" + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/lib/libmyaddresser.a + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/include/myaddresser.h + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/include/addressbook.pb.h + + myaddresser/1.0: package(): Packaged 2 '.h' files: myaddresser.h, addressbook.pb.h + myaddresser/1.0: package(): Packaged 1 '.a' file: libmyaddresser.a + .... + + ======== Testing the package: Executing test ======== + myaddresser/1.0 (test package): Running test() + myaddresser/1.0 (test package): RUN: ./example + myaddresser(): created a person with id 1337 + + +After seeing it's running OK, let's try to use cross-building. Notice that this part is based on MacOS Intel systems, +and cross-compiling for MacOS ARM ones, but you could use your own profiles depending on your needs for sure. + +.. warning:: + + MacOS system is required to run this part of the example. + + +.. code-block:: shell + + $ conan create . --build missing -pr:b apple-arch-x86_64 -pr:h apple-arch-armv8 + ... + + -- Install configuration: "Release" + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/lib/libmyaddresser.a + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/include/myaddresser.h + -- Installing: /Users/myuser/.conan2/p/b/myser03f790a5a5533/p/include/addressbook.pb.h + + myaddresser/1.0: package(): Packaged 2 '.h' files: myaddresser.h, addressbook.pb.h + myaddresser/1.0: package(): Packaged 1 '.a' file: libmyaddresser.a + .... + + ======== Testing the package: Executing test ======== + myaddresser/1.0 (test package): Running test() + + +Now, we cannot see the example running because of the host architecture. If we want to check that the *example* executable +is built for the correct one: + +.. code-block:: shell + + $ file test_package/build/apple-clang-13.0-armv8-gnu17-release/example + test_package/build/apple-clang-13.0-armv8-gnu17-release/example: Mach-O 64-bit executable arm64 + +Everything works as expected, and the executable was built for 64-bit executable arm64 architectures. diff --git a/2.1/_sources/examples/tools.rst.txt b/2.1/_sources/examples/tools.rst.txt new file mode 100644 index 000000000000..422c7b169661 --- /dev/null +++ b/2.1/_sources/examples/tools.rst.txt @@ -0,0 +1,14 @@ +.. _examples_tools: + +Conan recipe tools examples +=========================== + +.. toctree:: + :maxdepth: 2 + + tools/cmake/cmake + tools/files/files + tools/meson/meson + tools/google/bazel + tools/autotools/autotools + tools/scm/git/capture_scm/git_capture_scm diff --git a/2.1/_sources/examples/tools/autotools/autotools.rst.txt b/2.1/_sources/examples/tools/autotools/autotools.rst.txt new file mode 100644 index 000000000000..7cc0478f041a --- /dev/null +++ b/2.1/_sources/examples/tools/autotools/autotools.rst.txt @@ -0,0 +1,12 @@ +.. _examples_autotools: + + +tools.autotools +=============== + + +.. toctree:: + :maxdepth: 2 + + + autotools_toolchain/build_project_autotools_toolchain diff --git a/2.1/_sources/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst.txt b/2.1/_sources/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst.txt new file mode 100644 index 000000000000..c6722283cce3 --- /dev/null +++ b/2.1/_sources/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst.txt @@ -0,0 +1,178 @@ +.. _examples_tools_autotools_autotools_toolchain_build_project_autotools_toolchain: + +Build a simple Autotools project using Conan +============================================ + +In this example, we are going to create a string formatter application +that uses one of the most popular C++ libraries: `fmt `_. + +We'll use `Autotools `_ as build system and `pkg-config `_ as a helper tool in this case, so you should get them installed +on Linux and Mac before going forward with this example. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: shell + + git clone https://github.com/conan-io/examples2.git + cd examples2/examples/tools/autotools/autotoolstoolchain/string_formatter + +We start with a very simple C++ language project with the following structure: + +.. code-block:: text + + . + ├── configure.ac + ├── Makefile.am + ├── conanfile.txt + └── src + └── main.cpp + +This project contains a basic `configure.ac _` including the **fmt** pkg-config dependency and the +source code for the string formatter program in *main.cpp*. + +Let's have a look at the *main.cpp* file, it only prints a simple message but uses ``fmt::print`` method for it. + +.. code-block:: cpp + :caption: **main.cpp** + + #include + #include + + int main() { + fmt::print("{} - The C++ Package Manager!\n", "Conan"); + return EXIT_SUCCESS; + } + +The ``configure.ac`` file checks for a C++ compiler using the ``AC_PROG_CXX`` macro and also checks for the ``fmt.pc`` pkg-config module using the ``PKG_CHECK_MODULES`` macro. + +.. code-block:: text + :caption: **configure.ac** + + AC_INIT([stringformatter], [0.1.0]) + AM_INIT_AUTOMAKE([1.10 -Wall no-define foreign]) + AC_CONFIG_SRCDIR([src/main.cpp]) + AC_CONFIG_FILES([Makefile]) + PKG_CHECK_MODULES([fmt], [fmt]) + AC_PROG_CXX + AC_OUTPUT + +The *Makefile.am* specifies that ``string_formatter`` is the expected executable and that it should be linked to the ``fmt`` library. + +.. code-block:: text + :caption: **Makefile.am** + + AUTOMAKE_OPTIONS = subdir-objects + ACLOCAL_AMFLAGS = ${ACLOCAL_FLAGS} + + bin_PROGRAMS = string_formatter + string_formatter_SOURCES = src/main.cpp + string_formatter_CPPFLAGS = $(fmt_CFLAGS) + string_formatter_LDADD = $(fmt_LIBS) + +The *conanfile.txt* looks simple as it just installs the **fmt** package and uses two generators to build our project. + +.. code-block:: ini + :caption: **conanfile.txt** + + [requires] + fmt/9.1.0 + + [generators] + AutotoolsToolchain + PkgConfigDeps + +In this case, we will use :ref:`PkgConfigDeps` to generate information about where the **fmt** library +files are installed thanks to the `*.pc` files and :ref:`AutotoolsToolchain` to pass build information +to *autotools* using a `conanbuild[.sh|.bat]` file that describes the compilation environment. + +We will use Conan to install **fmt** library, generate a toolchain for Autotools, and, .pc files for find **fmt** by pkg-config. + + +Building on Linux and macOS +--------------------------- + +First, we should install some requirements. On Linux you need to have ``automake`` , ``pkgconf`` and ``make`` packages installed, +their packages names should vary according to the Linux distribution, but essentially, +it should include all tools (aclocal, automake, autoconf and make) that you will need to build the following example. + +For this example, we will not consider a specific Conan profile, but ``fmt`` is highly compatible with many different configurations. +So it should work mostly with versions of GCC and Clang compiler. + +As the first step, we should install all dependencies listed in the ``conanfile.txt``. +The command :ref: `conan install` will not only install the ``fmt`` package, +but also build it from sources in case your profile does not match with a pre-built binary in your remotes. +Plus, it will provide these generators listed in the ``conanfile.txt`` + +.. code-block:: shell + + conan install . --build=missing + +After running ``conan install`` command, we should have new files present in the *string_formatter* folder: + +.. code-block:: text + + + └── string_formatter + ├── Makefile.am + ├── conanautotoolstoolchain.sh + ├── conanbuild.conf + ├── conanbuild.sh + ├── conanbuildenv-release-armv8.sh + ├── conanfile.txt + ├── conanrun.sh + ├── conanrunenv-release-armv8.sh + ├── configure.ac + ├── deactivate_conanbuild.sh + ├── deactivate_conanrun.sh + ├── fmt-_fmt.pc + ├── fmt.pc + ├── run_example.sh + └── src + └── main.cpp + + +These files are the result of those generators listed in the ``conanfile.txt``. +Once all files needed to build the example are generated and ``fmt`` is installed, now we can load the script ``conanbuild.sh``. + +.. code-block:: shell + + source conanbuild.sh + +The ``conanbuild.sh`` is a default file generated by the :ref:`VirtualBuildEnv` and helps us to load other +script files, so we don't need to execute more manual steps to load each generator file. It will load ``conanautotoolstoolchain.sh``, +generated by `AutotoolsToolchain`, which defines environment variables according to our +Conan profile, used when running ``conan install`` command. Those environment variables configured are related to the compiler +and ``autotools``, like ``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``, and ``PKG_CONFIG_PATH``. + +As the next step, we can configure the project by running the following commands in sequence: + +.. code-block:: shell + + aclocal + automake --add-missing + autoconf + ./configure + +The `aclocal `_ command will read the file ``configure.ac`` +and generate a new file named ``aclocal.m4``, which contains macros needed by the ``automake``. As the second step, +the `automake `_ command will read the ``Makefile.am``, and will generate the file ``Makefile.in``. +So the command `autoconf `_ will use those files and generate the ``configure`` file. +Once we run ``configure``, all environment variables will be consumed. The ``fmt.pc`` will be loaded at this step too, +as ``autotools`` uses the custom ``PKG_CONFIG_PATH`` to find it. + +Then, finally, we can build the project to generate the string formatter application. +Now we run the ``make`` command, which will consume the ``Makefile`` generated by ``autotools``. + +.. code-block:: shell + + make + +The ``make`` command will read the ``Makefile`` and invoke the compiler, then, build the ``main.cpp``, generating the executable ``string_formatter`` in the same folder. + +.. code-block:: shell + + ./string_formatter + Conan - The C++ Package Manager! + +The final output is the result of a new application, printing a message with the help of ``fmt`` library, and built by ``Autotools``. diff --git a/2.1/_sources/examples/tools/cmake/cmake.rst.txt b/2.1/_sources/examples/tools/cmake/cmake.rst.txt new file mode 100644 index 000000000000..d63d5ec18594 --- /dev/null +++ b/2.1/_sources/examples/tools/cmake/cmake.rst.txt @@ -0,0 +1,14 @@ +.. _examples_cmake: + + +tools.cmake +=========== + + +.. toctree:: + :maxdepth: 2 + + + cmake_toolchain/build_project_cmake_presets + cmake_toolchain/extend_own_cmake_presets + cmake_toolchain/inject_cmake_variables \ No newline at end of file diff --git a/2.1/_sources/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst.txt b/2.1/_sources/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst.txt new file mode 100644 index 000000000000..25dc1c86f224 --- /dev/null +++ b/2.1/_sources/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst.txt @@ -0,0 +1,91 @@ +.. _examples-tools-cmake-toolchain-build-project-presets: + +CMakeToolchain: Building your project using CMakePresets +======================================================== + +In this example we are going to see how to use ``CMakeToolchain``, predefined layouts like ``cmake_layout`` and the +``CMakePresets`` CMake feature. + +Let's create a basic project based on the template ``cmake_exe`` as an example of a C++ project: + +.. code:: bash + + $ conan new -d name=foo -d version=1.0 cmake_exe + + +Generating the toolchain +------------------------ + +The recipe from our project declares the generator "CMakeToolchain". + +We can call :command:`conan install` to install both ``Release`` and ``Debug`` +configurations. Conan will generate a ``conan_toolchain.cmake`` at the corresponding +*generators* folder: + +.. code:: bash + + $ conan install . + $ conan install . -s build_type=Debug + + +Building the project using ``CMakePresets`` +------------------------------------------- + +A ``CMakeUserPresets.json`` file is generated in the same folder of your ``CMakeLists.txt`` file, +so you can use the ``--preset`` argument from ``cmake >= 3.23`` or use an IDE that supports it. + + +The ``CMakeUserPresets.json`` is including the ``CMakePresets.json`` files located at the +corresponding *generators* folder. + + +The ``CMakePresets.json`` contain information about the ``conan_toolchain.cmake`` location +and even the ``binaryDir`` set with the output directory. + + +.. include:: ../../../../tutorial/cmake_presets_note.inc + + +If you are using a multi-configuration generator: + +.. code:: bash + + $ cmake --preset conan-default + $ cmake --build --preset conan-debug + $ build\Debug\foo.exe + foo/1.0: Hello World Release! + + $ cmake --build --preset conan-release + $ build\Release\foo.exe + foo/1.0: Hello World Release! + + +If you are using a single-configuration generator: + +.. code:: bash + + $ cmake --preset conan-debug + $ cmake --build --preset conan-debug + $ ./build/Debug/foo + foo/1.0: Hello World Debug! + + + $ cmake --preset conan-release + $ cmake --build --preset conan-release + $ ./build/Release/foo + foo/1.0: Hello World Release! + + +Note that we didn't need to create the ``build/Release`` or ``build/Debug`` folders, as we did :ref:`in the +tutorial`. The output directory +is declared by the ``cmake_layout()`` and automatically managed by the CMake Presets feature. + +This behavior is also managed automatically by Conan (with CMake >= 3.15) when you build a package in the Conan +cache (with :command:`conan create` command). The CMake >= 3.23 is not required. + +Read More: + +- ``cmake_layout()`` :ref:`reference ` +- Conanfile :ref:`layout() method reference ` +- Package layout tutorial :ref:`tutorial ` +- Understanding :ref:`Conan package layouts ` diff --git a/2.1/_sources/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst.txt b/2.1/_sources/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst.txt new file mode 100644 index 000000000000..f40525f4777b --- /dev/null +++ b/2.1/_sources/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst.txt @@ -0,0 +1,119 @@ +.. _examples-tools-cmake-toolchain-build-project-extend-presets: + +CMakeToolchain: Extending your CMakePresets with Conan generated ones +===================================================================== + +In this example we are going to see how to extend your own CMakePresets to include Conan +generated ones. + +.. include:: ../../../../tutorial/cmake_presets_note.inc + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets + +Please open the `conanfile.py` and check how it sets ``tc.user_presets_path = +'ConanPresets.json'``. By modifying this attribute of `CMakeToolchain`, you can change the +default filename of the generated preset. + +.. code:: python + + def generate(self): + tc = CMakeToolchain(self) + tc.user_presets_path = 'ConanPresets.json' + tc.generate() + ... + +Now you can provide your own ``CMakePresets.json``, besides the ``CMakeLists.txt``: + +.. code-block:: json + :caption: CMakePresets.json + + { + "version": 4, + "include": ["./ConanPresets.json"], + "configurePresets": [ + { + "name": "default", + "displayName": "multi config", + "inherits": "conan-default" + }, + { + "name": "release", + "displayName": "release single config", + "inherits": "conan-release" + }, + { + "name": "debug", + "displayName": "debug single config", + "inherits": "conan-debug" + } + ], + "buildPresets": [ + { + "name": "multi-release", + "configurePreset": "default", + "configuration": "Release", + "inherits": "conan-release" + }, + { + "name": "multi-debug", + "configurePreset": "default", + "configuration": "Debug", + "inherits": "conan-debug" + }, + { + "name": "release", + "configurePreset": "release", + "configuration": "Release", + "inherits": "conan-release" + }, + { + "name": "debug", + "configurePreset": "debug", + "configuration": "Debug", + "inherits": "conan-debug" + } + ] + } + +Note how the ``"include": ["./ConanPresets.json"],`` and that every preset ``inherits`` a +Conan generated one. + +We can now install for both Release and Debug (and other configurations also, with the +help of ``build_folder_vars`` if we want): + +.. code-block:: bash + + $ conan install . + $ conan install . -s build_type=Debug + +And build and run our application, by using **our own presets** that extend the Conan generated ones: + +.. code-block:: bash + + # Linux (single-config, 2 configure, 2 builds) + $ cmake --preset debug + $ cmake --build --preset debug + $ ./build/Debug/foo + > Hello World Debug! + + $ cmake --preset release + $ cmake --build --preset release + $ ./build/Release/foo + > Hello World Release! + + # Windows VS (Multi-config, 1 configure 2 builds) + $ cmake --preset default + + $ cmake --build --preset multi-debug + $ build\\Debug\\foo + > Hello World Debug! + + $ cmake --build --preset multi-release + $ build\\Release\\foo + > Hello World Release! diff --git a/2.1/_sources/examples/tools/cmake/cmake_toolchain/inject_cmake_variables.rst.txt b/2.1/_sources/examples/tools/cmake/cmake_toolchain/inject_cmake_variables.rst.txt new file mode 100644 index 000000000000..8f89f888dec0 --- /dev/null +++ b/2.1/_sources/examples/tools/cmake/cmake_toolchain/inject_cmake_variables.rst.txt @@ -0,0 +1,87 @@ +.. _examples-tools-cmake-toolchain-inject-variables: + +CMakeToolchain: Inject arbitrary CMake variables into dependencies +================================================================== + +You can find the sources to recreate this project in the `examples2.0 repository +`_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/cmake/cmake_toolchain/user_toolchain_profile + + +In the general case, Conan package recipes provide the necessary abstractions via settings, confs, and options +to control different aspects of the build. Many recipes define ``options`` to activate or deactivate features, +optional dependencies, or binary characteristics. Configurations like ``tools.build:cxxflags`` can be used to +inject arbitrary C++ compile flags. + +In some exceptional cases, it might be desired to inject CMake variables directly into dependencies doing CMake +builds. This is possible when these dependencies use the ``CMakeToolchain`` integration. Let's check it in this +simple example. + +If we have the following package recipe, with a simple ``conanfile.py`` and a ``CMakeLists.txt`` printing a variable: + +.. code-block:: python + :caption: conanfile.py + + from conan import ConanFile + from conan.tools.cmake import CMake + + class AppConan(ConanFile): + name = "foo" + version = "1.0" + settings = "os", "compiler", "build_type", "arch" + exports_sources = "CMakeLists.txt" + + generators = "CMakeToolchain" + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + + +.. code-block:: cmake + :caption: CMakeLists.txt + + cmake_minimum_required(VERSION 3.15) + project(foo LANGUAGES NONE) + message(STATUS "MYVAR1 ${MY_USER_VAR1}!!") + +We can define a profile file and a ``myvars.cmake`` file (both in the same folder) like the following: + +.. code-block:: ini + :caption: myprofile + + include(default) + [conf] + tools.cmake.cmaketoolchain:user_toolchain+={{profile_dir}}/myvars.cmake + +Note the ``{{profile_dir}}`` is a jinja template expression that evaluates to the current profile folder, allowing +to compute the necessary path to ``myvars.cmake`` file. The ``tools.cmake.cmaketoolchain:user_toolchain`` is a **list** +of files to inject to the generated ``conan_toolchain.cmake``, so the ``+=`` operator is used to append to it. + +The ``myvars.cmake`` can define as many variables as we want: + +.. code-block:: cmake + :caption: myvars.cmake + + set(MY_USER_VAR1 "MYVALUE1") + + +Applying this profile, we can see that the package CMake build effectively uses the variable provided in the +external ``myvars.cmake`` file: + +.. code-block:: bash + + $ conan create . -pr=myprofile + ... + -- MY_USER_VAR1 MYVALUE1 + +Note that using ``user_toolchain`` while defining values for confs like ``tools.cmake.cmaketoolchain:system_name`` is supported. + +The ``tools.cmake.cmaketoolchain:user_toolchain`` conf value might also be passed in the command line ``-c`` argument, +but the location of the ``myvars.cmake`` needs to be absolute to be found, as jinja replacement doesn't happen in the +command line. diff --git a/2.1/_sources/examples/tools/files/files.rst.txt b/2.1/_sources/examples/tools/files/files.rst.txt new file mode 100644 index 000000000000..49d15df2653a --- /dev/null +++ b/2.1/_sources/examples/tools/files/files.rst.txt @@ -0,0 +1,12 @@ +.. _examples_files: + + +tools.files +=========== + + +.. toctree:: + :maxdepth: 1 + + + patches/patch_sources \ No newline at end of file diff --git a/2.1/_sources/examples/tools/files/patches/patch_sources.rst.txt b/2.1/_sources/examples/tools/files/patches/patch_sources.rst.txt new file mode 100644 index 000000000000..5a6a71757bb8 --- /dev/null +++ b/2.1/_sources/examples/tools/files/patches/patch_sources.rst.txt @@ -0,0 +1,254 @@ +.. _examples_tools_files_patches: + +Patching sources +================ + +In this example we are going to see how to patch the source code. This is necessary sometimes, specially when you are +creating a package for a third party library. A patch might be required in the build system scripts or even in the +source code of the library if you want, for example, to apply a security patch. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples/tools/files/patches + + +Patching using 'replace_in_file' +-------------------------------- + +The simplest way to patch a file is using the ``replace_in_file`` tool in your recipe. It searches in a file the specified +string and replaces it with another string. + +in source() method +^^^^^^^^^^^^^^^^^^ + +The source() method is called only once for all the configurations (different calls to :command:`conan create` for different settings/options) +so you should patch only in the ``source()`` method if the changes are common for all the configurations. + +Look at the ``source()`` method at the ``conanfile.py``: + + +.. code-block:: python + + import os + from conan import ConanFile + from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout + from conan.tools.files import get, replace_in_file + + + class helloRecipe(ConanFile): + name = "hello" + version = "1.0" + + # Binary configuration + settings = "os", "compiler", "build_type", "arch" + options = {"shared": [True, False], "fPIC": [True, False]} + default_options = {"shared": False, "fPIC": True} + + def source(self): + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", strip_root=True) + replace_in_file(self, os.path.join(self.source_folder, "src", "hello.cpp"), "Hello World", "Hello Friends!") + + ... + +We are replacing the ``"Hello World"`` string with "Hello Friends!". +We can run ``conan create .`` and verify that if the replace was done: + +.. code-block:: bash + + $ conan create . + ... + -------- Testing the package: Running test() -------- + hello/1.0: Hello Friends! Release! + ... + +in build() method +^^^^^^^^^^^^^^^^^ + +In this case, we need to apply a different patch depending on the configuration (`self.settings`, `self.options`...), +so it has to be done in the ``build()`` method. Let's modify the recipe to introduce a change that depends on the +``self.options.shared``: + + +.. code-block:: python + + class helloRecipe(ConanFile): + + ... + + def source(self): + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", strip_root=True) + + def build(self): + replace_in_file(self, os.path.join(self.source_folder, "src", "hello.cpp"), + "Hello World", + "Hello {} Friends!".format("Shared" if self.options.shared else "Static")) + cmake = CMake(self) + cmake.configure() + cmake.build() + + ... + +If we call ``conan create`` with different ``option.shared`` we can check the output: + +.. code-block:: bash + + $ conan create . + ... + hello/1.0: Hello Static Friends! Release! + ... + + $ conan create . -o shared=True + ... + hello/1.0: Hello Shared Friends! Debug! + ... + + +Patching using "patch" tool +--------------------------- + +If you have a patch file (diff between two versions of a file), you can use the ``conan.tools.files.patch`` tool to apply it. +The rules about where to apply the patch (``source()`` or ``build()`` methods) are the same. + +We have this patch file, where we are changing again the message to say "Hello Patched World Release!": + + +.. code-block:: text + + --- a/src/hello.cpp + +++ b/src/hello.cpp + @@ -3,9 +3,9 @@ + + void hello(){ + #ifdef NDEBUG + - std::cout << "hello/1.0: Hello World Release!\n"; + + std::cout << "hello/1.0: Hello Patched World Release!\n"; + #else + - std::cout << "hello/1.0: Hello World Debug!\n"; + + std::cout << "hello/1.0: Hello Patched World Debug!\n"; + #endif + + // ARCHITECTURES + + +Edit the ``conanfile.py`` to: + +1. Import the ``patch`` tool. +2. Add ``exports_sources`` to the patch file so we have it available in the cache. +3. Call the ``patch`` tool. + + +.. code-block:: python + :emphasize-lines: 4, 15, 19, 20 + + import os + from conan import ConanFile + from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout + from conan.tools.files import get, replace_in_file, patch + + + class helloRecipe(ConanFile): + name = "hello" + version = "1.0" + + # Binary configuration + settings = "os", "compiler", "build_type", "arch" + options = {"shared": [True, False], "fPIC": [True, False]} + default_options = {"shared": False, "fPIC": True} + exports_sources = "*.patch" + + def source(self): + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", strip_root=True) + patch_file = os.path.join(self.export_sources_folder, "hello_patched.patch") + patch(self, patch_file=patch_file) + + ... + +We can run "conan create" and see that the patch worked: + +.. code-block:: bash + + $ conan create . + ... + -------- Testing the package: Running test() -------- + hello/1.0: Hello Patched World Release! + ... + + +We can also use the ``conandata.yml`` :ref:`introduced in the tutorial` so we +can declare the patches to apply for each version: + + +.. code-block:: yaml + + patches: + "1.0": + - patch_file: "hello_patched.patch" + + +And there are the changes we introduce in the ``source()`` method: + + +.. code-block:: python + + .. code-block:: python + + def source(self): + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", strip_root=True) + patches = self.conan_data["patches"][self.version] + for p in patches: + patch_file = os.path.join(self.export_sources_folder, p["patch_file"]) + patch(self, patch_file=patch_file) + + +Check :ref:`patch ` for more details. + + +If we run the :command:`conan create`, the patch is also applied: + +.. code-block:: bash + + $ conan create . + ... + -------- Testing the package: Running test() -------- + hello/1.0: Hello Patched World Release! + ... + +Patching using "apply_conandata_patches" tool +--------------------------------------------- + +The example above works but it is a bit complex. If you follow the same yml structure (check the +:ref:`apply_conandata_patches ` to see the full supported yml) you +only need to call ``apply_conandata_patches``: + + +.. code-block:: python + + from conan import ConanFile + from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout + from conan.tools.files import get, apply_conandata_patches + + + class helloRecipe(ConanFile): + name = "hello" + version = "1.0" + + ... + + def source(self): + get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", strip_root=True) + apply_conandata_patches(self) + + +Let's check if the patch is also applied: + +.. code-block:: bash + + $ conan create . + ... + -------- Testing the package: Running test() -------- + hello/1.0: Hello Patched World Release! + ... diff --git a/2.1/_sources/examples/tools/google/bazel.rst.txt b/2.1/_sources/examples/tools/google/bazel.rst.txt new file mode 100644 index 000000000000..d18cb9564763 --- /dev/null +++ b/2.1/_sources/examples/tools/google/bazel.rst.txt @@ -0,0 +1,10 @@ +.. _examples_tools_bazel: + + +tools.google +============ + +.. toctree:: + :maxdepth: 2 + + bazeltoolchain/build_simple_bazel_project diff --git a/2.1/_sources/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst.txt b/2.1/_sources/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst.txt new file mode 100644 index 000000000000..47b41f833b62 --- /dev/null +++ b/2.1/_sources/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst.txt @@ -0,0 +1,135 @@ +.. _examples_tools_bazel_toolchain_build_simple_bazel_project: + +Build a simple Bazel project using Conan +======================================== + +In this example, we are going to create a Hello World program +that uses one of the most popular C++ libraries: `fmt `_. + +.. note:: + + This example is based on the main :ref:`Build a simple CMake project using Conan` + tutorial. So we highly recommend reading it before trying out this one. + + +We'll use Bazel as the build system and helper tool in this case, so you should get it installed +before going forward with this example. See `how to install Bazel `_. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/google/bazeltoolchain/string_formatter + + +We start from a very simple C++ language project with this structure: + +.. code-block:: text + + . + ├── WORKSPACE + ├── conanfile.txt + └── main + ├── BUILD + └── demo.cpp + +This project contains a *WORKSPACE* file loading the Conan dependencies (in this case only ``fmt``) +and a *main/BUILD* file which defines the *demo* bazel target and it's in charge of using ``fmt`` to build a +simple Hello World program. + +Let's have a look at each file's content: + +.. code-block:: cpp + :caption: **main/demo.cpp** + + #include + #include + + int main() { + fmt::print("{} - The C++ Package Manager!\n", "Conan"); + return EXIT_SUCCESS; + } + +.. code-block:: python + :caption: **WORKSPACE** + + load("@//conan:dependencies.bzl", "load_conan_dependencies") + load_conan_dependencies() + + +.. code-block:: python + :caption: **main/BUILD** + + load("@rules_cc//cc:defs.bzl", "cc_binary") + + cc_binary( + name = "demo", + srcs = ["demo.cpp"], + deps = [ + "@fmt//:fmt" + ], + ) + + +.. code-block:: ini + :caption: **conanfile.txt** + + [requires] + fmt/10.1.1 + + [generators] + BazelDeps + BazelToolchain + + [layout] + bazel_layout + + +Conan uses the :ref:`conan_tools_google_bazeltoolchain` to generate a ``conan_bzl.rc`` file which defines the +``conan-config`` bazel-build configuration. This file and the configuration are passed as parameters to the +``bazel build`` command. Apart from that, Conan uses the :ref:`conan_tools_google_bazeldeps` generator +to create all the bazel files (*[DEP]/BUILD.bazel* and *dependencies.bzl*) which define all the dependencies +as public bazel targets. The *WORKSPACE* above is already ready to load the *dependencies.bzl* which will tell the +*main/BUILD* all the information about the ``@fmt//:fmt`` bazel target. + +As the first step, we should install all the dependencies listed in the ``conanfile.txt``. +The command :ref:`conan install` does not only install the ``fmt`` package, +it also builds it from sources in case your profile does not match with a pre-built binary in your remotes. +Furthermore, it will save all the files created by the generators listed in the ``conanfile.txt`` +in a folder named *conan/* (default folder defined by the ``bazel_layout``). + +.. code-block:: bash + + $ conan install . --build=missing + # ... + ======== Finalizing install (deploy, generators) ======== + conanfile.txt: Writing generators to /Users/franchuti/develop/examples2/examples/tools/google/bazeltoolchain/string_formatter/conan + conanfile.txt: Generator 'BazelDeps' calling 'generate()' + conanfile.txt: Generator 'BazelToolchain' calling 'generate()' + conanfile.txt: Generating aggregated env files + conanfile.txt: Generated aggregated env files: ['conanbuild.sh', 'conanrun.sh'] + Install finished successfully + +Now we are ready to build and run our application: + +.. code-block:: bash + + $ bazel --bazelrc=./conan/conan_bzl.rc build --config=conan-config //main:demo + Starting local Bazel server and connecting to it... + INFO: Analyzed target //main:demo (38 packages loaded, 272 targets configured). + INFO: Found 1 target... + INFO: From Linking main/demo: + ld: warning: ignoring duplicate libraries: '-lc++' + Target //main:demo up-to-date: + bazel-bin/main/demo + INFO: Elapsed time: 60.180s, Critical Path: 7.68s + INFO: 6 processes: 4 internal, 2 darwin-sandbox. + INFO: Build completed successfully, 6 total actions + + +.. code-block:: bash + + $ ./bazel-bin/main/demo + Conan - The C++ Package Manager! diff --git a/2.1/_sources/examples/tools/meson/meson.rst.txt b/2.1/_sources/examples/tools/meson/meson.rst.txt new file mode 100644 index 000000000000..cd31baf9d940 --- /dev/null +++ b/2.1/_sources/examples/tools/meson/meson.rst.txt @@ -0,0 +1,12 @@ +.. _examples_tools_meson: + + +tools.meson +=========== + + +.. toctree:: + :maxdepth: 2 + + + mesontoolchain/build_simple_meson_project diff --git a/2.1/_sources/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst.txt b/2.1/_sources/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst.txt new file mode 100644 index 000000000000..64c98ce51901 --- /dev/null +++ b/2.1/_sources/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst.txt @@ -0,0 +1,132 @@ +.. _examples_tools_meson_toolchain_build_simple_meson_project: + +Build a simple Meson project using Conan +======================================== + +In this example, we are going to create a string compressor application +that uses one of the most popular C++ libraries: `Zlib `__. + +.. note:: + + This example is based on the main :ref:`Build a simple CMake project using Conan` + tutorial. So we highly recommend reading it before trying out this one. + +We'll use Meson as build system and pkg-config as helper tool in this case, so you should get them installed +before going forward with this example. + +Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/meson/mesontoolchain/simple_meson_project + + +We start from a very simple C language project with this structure: + +.. code-block:: text + + . + ├── meson.build + └── src + └── main.c + +This project contains a basic *meson.build* including the **zlib** dependency and the +source code for the string compressor program in *main.c*. + +Let's have a look at the *main.c* file: + +.. code-block:: cpp + :caption: **main.c** + + #include + #include + #include + + #include + + int main(void) { + char buffer_in [256] = {"Conan is a MIT-licensed, Open Source package manager for C and C++ development " + "for C and C++ development, allowing development teams to easily and efficiently " + "manage their packages and dependencies across platforms and build systems."}; + char buffer_out [256] = {0}; + + z_stream defstream; + defstream.zalloc = Z_NULL; + defstream.zfree = Z_NULL; + defstream.opaque = Z_NULL; + defstream.avail_in = (uInt) strlen(buffer_in); + defstream.next_in = (Bytef *) buffer_in; + defstream.avail_out = (uInt) sizeof(buffer_out); + defstream.next_out = (Bytef *) buffer_out; + + deflateInit(&defstream, Z_BEST_COMPRESSION); + deflate(&defstream, Z_FINISH); + deflateEnd(&defstream); + + printf("Uncompressed size is: %lu\n", strlen(buffer_in)); + printf("Compressed size is: %lu\n", strlen(buffer_out)); + + printf("ZLIB VERSION: %s\n", zlibVersion()); + + return EXIT_SUCCESS; + } + +Also, the contents of *meson.build* are: + +.. code-block:: text + :caption: **meson.build** + + project('tutorial', 'c') + zlib = dependency('zlib', version : '1.2.11') + executable('compressor', 'src/main.c', dependencies: zlib) + + +Let's create a *conanfile.txt* with the following content to install **Zlib**: + +.. code-block:: ini + :caption: **conanfile.txt** + + [requires] + zlib/1.2.11 + + [generators] + PkgConfigDeps + MesonToolchain + +In this case, we will use :ref:`PkgConfigDeps` to generate information about where the **Zlib** library +files are installed thanks to the `*.pc` files and :ref:`MesonToolchain` to pass build information +to *Meson* using a `conan_meson_[native|cross].ini` file that describes the native/cross compilation environment, which in +this case is a `conan_meson_native.ini` one. + +We will use Conan to install **Zlib** and generate the files that Meson needs to find this library and build our project. +We will generate those files in the folder *build*. To do that, run: + +.. code-block:: bash + + $ conan install . --output-folder=build --build=missing + +Now we are ready to build and run our **compressor** app: + +.. code-block:: bash + :caption: Windows + + $ cd build + $ meson setup --native-file conan_meson_native.ini .. meson-src + $ meson compile -C meson-src + $ meson-src\compressor.exe + Uncompressed size is: 233 + Compressed size is: 147 + ZLIB VERSION: 1.2.11 + +.. code-block:: bash + :caption: Linux, macOS + + $ cd build + $ meson setup --native-file conan_meson_native.ini .. meson-src + $ meson compile -C meson-src + $ ./meson-src/compressor + Uncompressed size is: 233 + Compressed size is: 147 + ZLIB VERSION: 1.2.11 diff --git a/2.1/_sources/examples/tools/scm/git/capture_scm/git_capture_scm.rst.txt b/2.1/_sources/examples/tools/scm/git/capture_scm/git_capture_scm.rst.txt new file mode 100644 index 000000000000..37d527816755 --- /dev/null +++ b/2.1/_sources/examples/tools/scm/git/capture_scm/git_capture_scm.rst.txt @@ -0,0 +1,169 @@ +.. _examples_tools_scm_git_capture: + +Capturing Git scm information +============================= + +There are 2 main strategies to handle source code in recipes: + +- **Third-party code**: When the ``conanfile.py`` recipe is packaging third party code, like an open source library, it is typically better to use the ``source()`` method to download or clone the sources of that library. This is the approach followed by the ``conan-center-index`` repository for ConanCenter. +- **Your own code**: When the ``conanfile.py`` recipe is packaging your own code, it is typically better to have the ``conanfile.py`` in the same repository as the sources. Then, there are 2 alternatives for achieving reproducibility: + + - Using the ``exports_sources`` (or ``export_source()`` method) to capture a copy of the sources together with the recipe in the Conan package. This is very simple and pragmatic and would be recommended for the majority of cases. + - For cases when it is not possible to store the sources beside the Conan recipe, for example when the package is to be consumed for someone that shouldn't have access to the source code at all, then the current **scm capture** method would be the way. + + +In the **scm capture** method, instead of capturing a copy of the code itself, the "coordinates" for that code are captured instead, in the ``Git`` case, the ``url`` of the repository and the ``commit``. If the recipe needs to build from source, it will use that information to get a clone, and if the user who tries that is not authorized, the process will fail. They will still be able to use the pre-compiled binaries that we distribute, but not build from source or have access to the code. + +Let's see how it works with an example. Please, first clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ on GitHub: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/scm/git/capture_scm + + +There we will find a small "hello" project, containing this ``conanfile.py``: + +.. code-block:: python + + from conan import ConanFile + from conan.tools.cmake import CMake, cmake_layout + from conan.tools.scm import Git + from conan.tools.files import load, update_conandata + + + class helloRecipe(ConanFile): + name = "hello" + version = "0.1" + + # Binary configuration + settings = "os", "compiler", "build_type", "arch" + options = {"shared": [True, False], "fPIC": [True, False]} + default_options = {"shared": False, "fPIC": True} + generators = "CMakeDeps", "CMakeToolchain" + + def export(self): + git = Git(self, self.recipe_folder) + scm_url, scm_commit = git.get_url_and_commit() + self.output.info(f"Obtained URL: {scm_url} and {scm_commit}") + # we store the current url and commit in conandata.yml + update_conandata(self, {"sources": {"commit": scm_commit, "url": scm_url}}) + + def source(self): + # we recover the saved url and commit from conandata.yml and use them to get sources + git = Git(self) + sources = self.conan_data["sources"] + self.output.info(f"Cloning sources from: {sources}") + git.clone(url=sources["url"], target=".") + git.checkout(commit=sources["commit"]) + + ... + + +We need this code to be in its own Git repository, to see how it works in the real case, so +please create a folder outside of the ``examples2`` repository, and copy the contents of the current folder there, then: + +.. code-block:: text + + $ mkdir /home/myuser/myfolder # or equivalent in other OS + $ cp -R . /home/myuser/myfolder # or equivalent in other OS + $ cd /home/myuser/myfolder # or equivalent in other OS + + # Initialize the git repo + $ git init . + $ git add . + $ git commit . -m wip + # Finally create the package + $ conan create . + ... + hello/0.1: WARN: Current commit 8e8764c40bebabbe3ec57f9a0816a2c8e691f559 doesn't exist in remote origin + This revision will not be buildable in other computer + hello/0.1: Obtained URL: /capture_scm and 8e8764c40bebabbe3ec57f9a0816a2c8e691f559 + hello/0.1: Copied 1 '.yml' file: conandata.yml + hello/0.1: Copied 1 '.py' file: conanfile.py + ... + hello/0.1: Cloning sources from: {'commit': '8e8764c40bebabbe3ec57f9a0816a2c8e691f559', 'url': '/capture_scm'} + +Let's explain step by step what is happening: + +- When the recipe is exported to the Conan cache, the ``export()`` method executes, running ``scm_url, scm_commit = git.get_url_and_commit()``. See the :ref:`Git reference` for more information about these methods. +- This obtains the URL of the repo pointing to the local ``/capture_scm`` and the commit ``8e8764c40bebabbe3ec57f9a0816a2c8e691f559`` +- It warns that this information will **not** be enough to re-build from source this recipe once the package is uploaded to the server and is tried to be built from source in other computer, which will not contain the path pointed by ``/capture_scm``. This is expected, as the repository that we created doesn't have any remote defined. If our local clone had a remote defined and that remote contained the ``commit`` that we are building, the ``scm_url`` would point to the remote repository instead, making the build from source fully reproducible. +- The ``export()`` method stores the ``url`` and ``commit`` information in the ``conandata.yml`` for future reproducibility. +- When the package needs to be built from sources and it calls the ``source()`` method, it recovers the information from the ``conandata.yml`` file, and calls ``git.clone()`` with it to retrieve the sources. In this case, it will be cloning from the local checkout in ``/capture_scm``, but if it had a remote defined, it will clone from it. + + +.. warning:: + + To achieve reproducibility, it is very important for this **scm capture** technique that the current checkout is not dirty. If it was dirty, it would be impossible to guarantee future reproducibility of the build, so ``git.get_url_and_commit()`` can raise errors, and require to commit changes. If more than 1 commit is necessary, it would be recommended to squash those commits before pushing changes to upstream repositories. + +If we do now a second ``conan create .``, as the repo is dirty we would get: + +.. code-block:: text + + $ conan create . + hello/0.1: Calling export() + ERROR: hello/0.1: Error in export() method, line 19 + scm_url, scm_commit = git.get_url_and_commit() + ConanException: Repo is dirty, cannot capture url and commit: .../capture_scm + +This could be solved by cleaning the repo with ``git clean -xdf``, or by adding a ``.gitignore`` file to the repo with the following contents +(which might be a good practice anyway for source control): + +.. code-block:: text + :caption: .gitignore + + test_package/build + test_package/CMakeUserPresets.json + + + + + +Credentials management +---------------------- + +In the example above, credentials were not necessary, because our local repo didn't require them. But in real world scenarios, the credentials can be required. + +The first important bit is that ``git.get_url_and_commit()`` will capture the url of the ``origin`` remote. This url must not encode tokens, users or passwords, for several reasons. First because that will make the process not repeatable, and different builds, different users would get different urls, and consequently different recipe revisions. The ``url`` should always be the same. The recommended approach is to manage the credentials in an orthogonal way, for example using ssh keys. The provided example contains a Github action that does this: + +.. code-block:: yaml + :caption: .github/workflows/hello-demo.yml + + name: Build "hello" package capturing SCM in Github actions + run-name: ${{ github.actor }} checking hello-ci Git scm capture + on: [push] + jobs: + Build: + runs-on: ubuntu-latest + steps: + - name: Check out repository code + uses: actions/checkout@v3 + with: + ssh-key: ${{ secrets.SSH_PRIVATE_KEY }} + - uses: actions/setup-python@v4 + with: + python-version: '3.10' + - uses: webfactory/ssh-agent@v0.7.0 + with: + ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} + - run: pip install conan + - run: conan profile detect + - run: conan create . + +This ``hello-demo.yml`` takes care of the following: + +- The checkout ``actions/checkout@v3`` action receives the ``ssh-key`` to checkout as ``git@`` instead of ``https`` +- The ``webfactory/ssh-agent@v0.7.0`` action takes care that the ssh key is also activated during the execution of the following tasks, not only during the checkout. +- It is necessary to setup the ``SSH_PRIVATE_KEY`` secret in the Github interface, as well as the ``deploy key`` for the repo (with the private and public parts of the ssh-key) + +In this way, it is possible to keep completely separated the authentication and credentials from the recipe functionality, without any risk to leaking credentials. + + +.. note:: + + **Best practices** + + - Do not use an authentication mechanism that encodes information in the urls. This is risky, can easily disclose credentials in logs. It is recommended to use system mechanisms like ssh keys. + - Doing ``conan create`` is not recommended for local development, but instead running ``conan install`` and building locally, to avoid too many unnecessary commits. Only when everything works locally, it is time to start checking the ``conan create`` flow. diff --git a/2.1/_sources/index.rst.txt b/2.1/_sources/index.rst.txt new file mode 100644 index 000000000000..299591582ce3 --- /dev/null +++ b/2.1/_sources/index.rst.txt @@ -0,0 +1,24 @@ +Conan 2.0 - C and C++ Package Manager Documentation +=================================================== + +Welcome! This is the user documentation for Conan, an open source, decentralized C/C++ package manager that works in all platforms and with all build systems and compilers. Other relevant resources: + +- `Conan home page `_. Entry point to the project, with links to docs, blog, social, downloads, release mailing list, etc. +- `Github project and issue tracker `_. The main support channel, file issues here for questions, bug reports and feature requests. + +Table of contents: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + introduction + whatsnew + installation + tutorial + devops + integrations + examples + reference + knowledge + changelog diff --git a/2.1/_sources/installation.rst.txt b/2.1/_sources/installation.rst.txt new file mode 100644 index 000000000000..20f3fe3860f2 --- /dev/null +++ b/2.1/_sources/installation.rst.txt @@ -0,0 +1,182 @@ +.. _install: + +Install +======= + +Conan can be installed in many Operating Systems. It has been extensively used and tested in Windows, Linux (different distros), OSX, and is +also actively used in FreeBSD and Solaris SunOS. There are also several additional operating systems on which it has been reported to work. + +There are different ways to install Conan: + +1. The preferred and **strongly recommended way to install Conan** is from PyPI, the Python Package Index, using the ``pip`` command. +2. Use a system installer, or create your own self-contained Conan executable, to not require Python in your system. +3. Running Conan from sources. + +Install with pip (recommended) +------------------------------ + +To install latest Conan 2.0 pre-release version using ``pip``, you need a Python >= 3.6 +distribution installed on your machine. Modern Python distros come with pip pre-installed. +However, if necessary you can install pip by following the instructions in `pip docs`_. + + +Install Conan: + +.. code-block:: bash + + $ pip install conan + +.. important:: + + **Please READ carefully** + + - Make sure that your **pip** installation matches your **Python (>= 3.6)** version. + - In **Linux**, you may need **sudo** permissions to install Conan globally. + - We strongly recommend using **virtualenvs** (virtualenvwrapper works great) for everything related to Python. + (check https://virtualenvwrapper.readthedocs.io/en/stable/, or https://pypi.org/project/virtualenvwrapper-win/ in Windows) + With Python 3, the built-in module ``venv`` can also be used instead (check https://docs.python.org/3/library/venv.html). + If not using a **virtualenv** it is possible that conan dependencies will conflict with previously existing dependencies, + especially if you are using Python for other purposes. + - In **OSX**, especially the latest versions that may have **System Integrity Protection**, pip may fail. Try using virtualenvs, or + install it to the Python user install directory with ``$ pip install --user conan``. + - Some Linux distros, such as Linux Mint, require a restart (shell restart, or logout/system if not enough) after + installation, so Conan is found in the path. + + +Known installation issues with pip +++++++++++++++++++++++++++++++++++ + +When Conan is installed with :command:`pip install --user conan`, a new directory is usually created for it. However, the directory is not appended automatically to the `PATH` and the :command:`conan` commands do not work. This can usually be solved by restarting the session of the terminal or running the following command: + + .. code-block:: bash + + $ source ~/.profile + + +.. _conan_update: + +Update +++++++ + +If installed via ``pip``, Conan version can be updated with: + +.. code-block:: bash + + $ pip install conan --upgrade # Might need sudo or --user + +The upgrade shouldn't affect the installed packages or cache information. If the cache becomes inconsistent somehow, you may want to remove its content by deleting it (``/.conan2``). + + +Install with pipx +----------------- + +In certain scenarios, attempting to install with ``pip`` may yield the following error: + +.. code-block:: bash + + error: externally-managed-environment + + x This environment is externally managed + To install Python packages system-wide, try apt install + python3-xyz, where xyz is the package you are trying to + install. + ... + +This is because some modern Linux distributions have started marking their Python +installations as "externally managed", which means that the system's package manager is +responsible for managing Python packages. Installing packages globally or even in the user +space can interfere with system operations and potentially break system tools (check +`PEP-668 `_ for more detailed information). + +For those cases, it's recommended to use ``pipx`` to install Conan. ``pipx`` creates a virtual +environment for each Python application, ensuring that dependencies do not conflict. The +advantage is that it isolates Conan and its dependencies from the system Python and avoids +potential conflicts with system packages while providing a clean environment for Conan to +run. + +To install Conan with ``pipx``: + +1. Ensure ``pipx`` is installed on your system. If it isn't, check the installation + guidelines `in the pipx documentation `_. For + Debian-based distributions, you can install ``pipx`` using the system package manager: + +.. code-block:: bash + + $ apt-get install pipx + $ pipx ensurepath + +(Note: The package name might vary depending on the distribution) + +2. Restart your terminal and then install Conan using ``pipx``: + +.. code-block:: bash + + $ pipx install conan + +3. Now you can use Conan as you typically would. + + +Use a system installer or create a self-contained executable +------------------------------------------------------------ + +There will be a number of existing installers in `Conan downloads`_ for OSX Brew, Debian, Windows, Linux Arch, that will not require Python first. + +We also distribute `Conan binaries`_ for Windows, Linux, and macOS in a compressed file +that you can uncompress in your system and run directly. + +.. warning:: + + If you are using **macOS**, please be aware of the Gatekeeper feature that may + quarantine the compressed binaries if downloaded directly using a web browser. To + avoid this issue, download them using a tool such as `curl`, `wget`, or similar. + + +If there is no installer for your platform, you can create your own Conan executable, with the ``pyinstaller.py`` utility in the repo. This process is able to create a self-contained Conan executable that contains all it needs, +including the Python interpreter, so it wouldn't be necessary to have Python installed in the system. + +You can do it with: + +.. code-block:: bash + + $ git clone https://github.com/conan-io/conan conan_src + $ cd conan_src + $ git checkout develop2 # or to the specific tag you want to + $ pip install -e . + $ python pyinstaller.py + + +It is important to install the dependencies and the project first with ``pip install -e .`` which configures the project as "editable", that is, to run from the current source folder. After creating the executable, it can be uninstalled with pip. + +This has to run in the same platform that will be using the executable, pyinstaller does not cross-build. The resulting executable can be just copied and put in the system PATH of the running machine to be able to run Conan. + + +Install from source +------------------- + +You can run Conan directly from source code. First, you need to install Python and pip. + +Clone (or download and unzip) the git repository and install it. + +Conan 2 is still in beta stage, so you must check the `develop2` branch of the repository: + +.. code-block:: bash + + # clone folder name matters, to avoid imports issues + $ git clone https://github.com/conan-io/conan.git conan_src + $ cd conan_src + $ git fetch --all + $ git checkout -b develop2 origin/develop2 + $ python -m pip install -e . + +And test your ``conan`` installation: + +.. code-block:: bash + + $ conan + +You should see the Conan commands help. + + +.. _`pip docs`: https://pip.pypa.io/en/stable/installing/ +.. _`Conan downloads`: https://conan.io/downloads +.. _`Conan binaries`: https://github.com/conan-io/conan/releases/latest diff --git a/2.1/_sources/integrations.rst.txt b/2.1/_sources/integrations.rst.txt new file mode 100644 index 000000000000..88e4848512b3 --- /dev/null +++ b/2.1/_sources/integrations.rst.txt @@ -0,0 +1,33 @@ +.. _integrations: + + +Integrations +============ + +Conan provides seamless integration with several platforms, build systems, and IDEs. Conan +brings off-the-shelf support for some of the most important operating systems, including +Windows, Linux, macOS, Android, and iOS. Some of the most important build systems +supported by Conan include CMake, MSBuild, Meson, Autotools and Make. In addition to build +systems, Conan also provides integration with popular IDEs, such as Visual Studio and +Xcode. + +.. toctree:: + :maxdepth: 2 + + integrations/cmake + integrations/clion + integrations/visual_studio + integrations/autotools + integrations/bazel + integrations/makefile + integrations/xcode + integrations/meson + integrations/android + integrations/jfrog + +.. warning:: + + Even though there is a plugin for the Visual Studio IDE, it is not recommended to use + it right now because it has not been updated for the 2.0 version yet. However, we + intend to resume working on this plugin and enhance its functionality soon after Conan 2.0 + is released. diff --git a/2.1/_sources/integrations/android.rst.txt b/2.1/_sources/integrations/android.rst.txt new file mode 100644 index 000000000000..4be9fa721a8b --- /dev/null +++ b/2.1/_sources/integrations/android.rst.txt @@ -0,0 +1,14 @@ +.. _integrations_android: + +|android_logo| Android +========================== + +Conan provides support for cross-building for Android, and it's easy to integrate with +Android Studio. Please check these examples for more information on how to build your +binaries for Android: + +- :ref:`Cross building to Android with the NDK` + +- :ref:`Integrating Conan in Android Studio` + +.. |android_logo| image:: ../images/integrations/conan-android-logo.png diff --git a/2.1/_sources/integrations/autotools.rst.txt b/2.1/_sources/integrations/autotools.rst.txt new file mode 100644 index 000000000000..9953a865a806 --- /dev/null +++ b/2.1/_sources/integrations/autotools.rst.txt @@ -0,0 +1,32 @@ +.. _integrations_autotools: + +|autotools_logo| Autotools +========================== + +Conan provides different tools to help manage your projects using Autotools. They can be +imported from ``conan.tools.gnu``. The most relevant tools are: + +- `AutotoolsDeps`: the dependencies generator for Autotools, which generates shell scripts + containing environment variable definitions that the Autotools build system can + understand. + +- `AutotoolsToolchain`: the toolchain generator for Autotools, which generates shell + scripts containing environment variable definitions that the Autotools build system can + understand. + +- `Autotools` build helper, a wrapper around the command line invocation of autotools that + abstracts calls like `./configure` or `make` into Python method calls. + +- `PkgConfigDeps`: the dependencies generator for `pkg-config` which generates + `pkg-config` files for all the required dependencies of a package. + +For the full list of tools under ``conan.tools.gnu`` please check the :ref:`reference +` section. + +.. seealso:: + + - Reference for :ref:`AutotoolsDeps`, + :ref:`AutotoolsToolchain`, :ref:`Autotools` and + :ref:`PkgConfigDeps`. + +.. |autotools_logo| image:: ../images/integrations/conan-autotools-logo.png diff --git a/2.1/_sources/integrations/bazel.rst.txt b/2.1/_sources/integrations/bazel.rst.txt new file mode 100644 index 000000000000..ac606d24551e --- /dev/null +++ b/2.1/_sources/integrations/bazel.rst.txt @@ -0,0 +1,26 @@ +.. _integrations_bazel: + +|bazel_logo| Bazel +================== + +Conan provides different tools to help manage your projects using Bazel. They can be +imported from ``conan.tools.google``. The most relevant tools are: + +- ``BazelDeps``: the dependencies generator for Bazel, which generates a *[DEPENDENCY]/BUILD.bazel* file for each dependency + and a *dependencies.bzl* file containing a Bazel function to load all those ones. That function must be loaded by your + *WORKSPACE* file. + +- ``BazelToolchain``: the toolchain generator for Bazel, which generates a ``conan_bzl.rc`` file that contains + a build configuration ``conan-config`` to inject all the parameters into the :command:`bazel build` command. + +- ``Bazel``: the Bazel build helper. It's simply a wrapper around the command line invocation of Bazel. + +.. seealso:: + + - Reference for :ref:`conan_tools_google_bazeldeps`. + - Reference for :ref:`conan_tools_google_bazeltoolchain`. + - Reference for :ref:`conan_tools_google_bazel`. + - :ref:`examples_tools_bazel_toolchain_build_simple_bazel_project` + + +.. |bazel_logo| image:: ../images/integrations/conan-bazel-logo.png diff --git a/2.1/_sources/integrations/clion.rst.txt b/2.1/_sources/integrations/clion.rst.txt new file mode 100644 index 000000000000..a24b42d919dc --- /dev/null +++ b/2.1/_sources/integrations/clion.rst.txt @@ -0,0 +1,124 @@ +.. _integrations_clion: + +|clion_logo| CLion +================== + +Introduction +------------ + +There's a plugin `available in the JetBrains Marketplace +`_ that's compatible with CLion versions +higher than *2022.3*. With this plugin, you can browse Conan packages available in `Conan +Center `_, add them to your project, and install them directly +from the CLion IDE interface. + +This plugin utilizes `cmake-conan +`_, a `CMake dependency provider +`_ +for Conan. It injects ``conan_provider.cmake`` using the +``CMAKE_PROJECT_TOP_LEVEL_INCLUDES`` definition. This dependency provider translates the +CMake configuration to Conan. For instance, if you select a *Debug* profile in CLion, +Conan will install and use the packages for *Debug*. + +Bear in mind that *cmake-conan* activates the Conan integration every time CMake calls +``find_package()``. This means that no library will be installed until the CMake configure +step runs. At that point, Conan will attempt to install the required libraries and build +them if necessary. + +Also, note that dependency providers are a relatively new feature in CMake. Therefore, you +will need CMake version >= 3.24 and Conan >= 2.0.5. + +Installing the plugin +--------------------- + +To install the new Conan CLion plugin, navigate to the JetBrains marketplace. Open CLion, +go to *Settings > Plugins*, then select the *Marketplace* tab. Search for the Conan plugin +and click on the Install button. + +|clion_install_plugin| + +After restarting CLion, a new “Conan” tool tab will appear at the bottom of the IDE. + +Configuring the plugin +---------------------- + +Open a CMake project or create a new one in CLion. Then, go to the “Conan” tool tab at the +bottom of the IDE. The only enabled action in the toolbar of the plugin will be the one +with the "wheel" (configuration) symbol. Click on it. + +|clion_configuration_1| + +The first thing you should do is configure the Conan client executable that will be used. +You can point to a specific installation in an arbitrary location on your system, or you +can select "Use Conan installed in the system" to use the system-level installation. + +|clion_configuration_2| + +Several options are marked as default. Let's review them: + +- You'll see checkboxes indicating which configurations Conan should manage. In our case, + since we only have the Debug configuration, it's the only one checked. Below that, + "Automatically add Conan support for all configurations" is checked by default. This + means you don't need to manually add Conan support to new build configurations; the + plugin will do it automatically. + +- There's also a checkbox allowing Conan to modify the default CLion settings and run + CMake sequentially instead of in parallel. This is necessary because the Conan cache + isn't concurrent yet in Conan 2.0. + +If you're using the Conan plugin, you typically wouldn't uncheck these options. After +setting your preferences, click the OK button to finalize the configuration. + +**Note:** At this point, CLion will run the configure step for CMake automatically. Since +the plugin sets up the *conan.cmake* dependency provider, a warning will appear in the +CMake output. This warning indicates that we haven't added a `find_package()` to our +*CMakeLists.txt* yet. This warning will disappear once we add the necessary +`find_package()` calls to the *CMakeLists.txt* file. + +After the initial configuration, you'll notice that the list of libraries is enabled. The +"update" and "inspect" buttons are also active. We'll explain these in detail +later. + +Using the plugin +---------------- + +With the plugin configured, you can browse available libraries and install them from +CLion. For example, if you want to use `libcurl `_ to download +an image from the Internet, navigate to the library list and search for *libcurl*. +Information on how to add it to CMake will be displayed, along with a "Use in project" +button. Select the version you want and click the button. + +|clion_use_libcurl| + +If you click on the "eye" (inspect) icon, you'll see all the libraries added to the project +(assuming you added more than one). This view includes basic target information for CMake +and the necessary code snippets to integrate them into CMake. + +|clion_inspect| + +Conan stores information about the used packages in a *conandata.yml* file in your project +folder. This file is read by a *conanfile.py*, which is also created during this process. +You can customize these files for advanced plugin usage, but ensure you read the +information in the corresponding files to do this correctly. Modify your *CMakeLists.txt* +according to the instructions, which should look something like this: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.15) project(project_name) set(CMAKE_CXX_STANDARD 17) + find_package(CURL) add_executable(project_name main.cpp) + target_link_libraries(project_name CURL::libcurl) + +After reloading the CMake project, you should see Conan installing the libraries in the +CMake output tab. + +.. seealso:: + + - For more details, check the `entry in the Conan blog about the plugin + `_. + +.. |clion_logo| image:: ../images/integrations/clion/conan-icon-clion.png +.. |clion_install_plugin| image:: ../images/integrations/clion/clion-install-plugin.png +.. |clion_configuration_1| image:: ../images/integrations/clion/clion-configuration-1.png +.. |clion_configuration_2| image:: ../images/integrations/clion/clion-configuration-2.png +.. |clion_inspect| image:: ../images/integrations/clion/clion-inspect.png +.. |clion_use_libcurl| image:: ../images/integrations/clion/clion-use-libcurl.png diff --git a/2.1/_sources/integrations/cmake.rst.txt b/2.1/_sources/integrations/cmake.rst.txt new file mode 100644 index 000000000000..5c4254ee8988 --- /dev/null +++ b/2.1/_sources/integrations/cmake.rst.txt @@ -0,0 +1,38 @@ +.. _integrations_cmake: + +|cmake_logo| CMake +================== + +Conan provides different tools to integrate with CMake in a transparent way. Using these +tools, the consuming ``CMakeLists.txt`` file does not need to be aware of Conan at all. The +CMake tools also provide better IDE integration via cmake-presets. + +To learn how to integrate Conan with your current CMake project you can follow the +:ref:`Conan tutorial ` that uses CMake along all the sections. + +Please also check the reference for the CMakeDeps, CMakeToolchain, and CMake tools: + +- `CMakeDeps`: responsible for generating the CMake config files for all the required + dependencies of a package. + +- `CMakeToolchain`: generates all the information needed for CMake to build the packages + according to the information passed to Conan about things like the operating system, the + compiler to use, architecture, etc. It will also generate `cmake-presets` files for easy + integration with some IDEs that support this CMake feature off-the-shelf. + +- `CMake` build helper is the tool used by Conan to run CMake and will pass all the + arguments that CMake needs to build successfully, such as the toolchain file, build type + file, and all the CMake definitions set in the recipe. + + +.. seealso:: + + - Check the :ref:`Building your project using CMakePresets + ` example + - Reference for :ref:`CMakeDeps `, :ref:`CMakeToolchain + ` and :ref:`CMake build helper + ` + - :ref:`Conan tutorial ` + + +.. |cmake_logo| image:: ../images/integrations/conan-cmake-logo.png diff --git a/2.1/_sources/integrations/jfrog.rst.txt b/2.1/_sources/integrations/jfrog.rst.txt new file mode 100644 index 000000000000..0b52332a3f8b --- /dev/null +++ b/2.1/_sources/integrations/jfrog.rst.txt @@ -0,0 +1,70 @@ +.. _integrations_jfrog: + +|jfrog_logo| JFrog +================== + +Artifactory Build Info +---------------------- + +.. warning:: + + The support of Artifactory Build Info via extension commands is not covered by :ref:`the Conan stability commitment`. + +The `Artifactory build info `_ is a recollection of the metadata of a build. +This json-formatted file includes all the details about the build broken down into segments like version history, artifacts, project +modules, dependencies, and everything that was required to create the build. + +Build infos are identified with a ``build name`` and a ``build number``, similar to how many CI services identify the builds. +They are conveniently stored in Artifactory to keep track of the build metadata to later perform different operations. + +Conan does not offer built-in support for the build info format. However, we have developed some :ref:`custom commands` at +at the `extensions repository `_ using the feature, that provides support to create and manage the build info files. + +How to install the build info extension commands +++++++++++++++++++++++++++++++++++++++++++++++++ + +Using the dedicated repository for Conan extensions https://github.com/conan-io/conan-extensions, it is as easy as: + +.. code-block:: bash + + $ conan config install https://github.com/conan-io/conan-extensions.git -sf=extensions/commands/art -tf=extensions/commands/art + +Generating a Build Info ++++++++++++++++++++++++ + +A Build Info can be generated from a create or install command: + +.. code-block:: bash + + $ conan create . --format json -s build_type=Release > create_release.json + +Then upload the created package to your repository: + +.. code-block:: bash + + $ conan upload ... -c -r ... + +Now, using the JSON output from the create/install commands, a build info file can be generated: + +.. code-block:: bash + + $ conan art:build-info create create_release.json mybuildname_release 1 --server my_artifactory --with-dependencies > mybuildname_release.json + +And then uploaded to Artifactory: + +.. code-block:: bash + + $ conan art:build-info upload mybuildname_aggregated.json --server my_artifactory + +For more reference, see the full example at https://github.com/conan-io/conan-extensions/tree/main/extensions/commands/art#how-to-manage-build-infos-in-artifactory + +.. seealso:: + + - JFrog Artifactory has a `dedicated API + `_ to manage build infos that + has been integrated into the custom commands for Artifactory. + - Check the ``conan art:build-info`` documentation for reference: + https://github.com/conan-io/conan-extensions/blob/main/extensions/commands/art/readme_build_info.md + + +.. |jfrog_logo| image:: ../images/integrations/conan-jfrog-logo.png diff --git a/2.1/_sources/integrations/makefile.rst.txt b/2.1/_sources/integrations/makefile.rst.txt new file mode 100644 index 000000000000..efc7c92aa8fb --- /dev/null +++ b/2.1/_sources/integrations/makefile.rst.txt @@ -0,0 +1,22 @@ +.. _integrations_makefile: + +|gnu_make_logo| Makefile +======================== + +Conan provides different tools to help manage your projects using Make. They can be +imported from ``conan.tools.gnu``. Besides the most popular variant, GNU Make, Conan also +supports other variants like BSD Make. The most relevant tools are: + +- `MakeDeps`: the dependencies generator for Make, which generates a Makefile containing + definitions that the Make build tool can understand. + +Currently, there is no ``MakeToolchain`` generator, it should be added in the future. + +For the full list of tools under ``conan.tools.gnu`` please check the :ref:`reference +` section. + +.. seealso:: + + - Reference for :ref:`MakeDeps`. + +.. |gnu_make_logo| image:: ../images/integrations/conan-autotools-logo.png diff --git a/2.1/_sources/integrations/meson.rst.txt b/2.1/_sources/integrations/meson.rst.txt new file mode 100644 index 000000000000..38193a3e7754 --- /dev/null +++ b/2.1/_sources/integrations/meson.rst.txt @@ -0,0 +1,25 @@ +.. _integrations_meson: + +|meson_logo| Meson +================== + +Conan provides different tools to help manage your projects using Meson. They can be +imported from ``conan.tools.meson``. The most relevant tools are: + +- `MesonToolchain`: generates the .ini files for Meson with the definitions of all the + Meson properties related to the Conan options and settings for the current package, + platform, etc. MesonToolchain normally works together with + :ref:`PkgConfigDeps` to manage all the dependencies. + +- `Meson` build helper, a wrapper around the command line invocation of Meson. + +.. seealso:: + + - Reference for :ref:`MesonToolchain` and + :ref:`Meson`. + - Build a simple Meson project using Conan + :ref:`example` + +Build a simple Meson project using Conan + +.. |meson_logo| image:: ../images/integrations/conan-meson-logo.png diff --git a/2.1/_sources/integrations/visual_studio.rst.txt b/2.1/_sources/integrations/visual_studio.rst.txt new file mode 100644 index 000000000000..6c8486258930 --- /dev/null +++ b/2.1/_sources/integrations/visual_studio.rst.txt @@ -0,0 +1,36 @@ +.. _integrations_visual_studio: + +|visual_studio_logo| Visual Studio +================================== + +Conan provides several tools to help manage your projects using Microsoft Visual Studio. +These tools can be imported from ``conan.tools.microsoft`` and allow for native +integration with Microsoft Visual Studio, without the need to use CMake and instead +directly using Visual Studio solutions, projects, and property files. The most relevant +tools are: + +- `MSBuildDeps`: the dependency information generator for Microsoft MSBuild build system. + It will generate multiple ``xxxx.props`` properties files, one per dependency of a + package, to be used by consumers using MSBuild or Visual Studio, just by adding the + generated properties files to the solution and projects. + +- `MSBuildToolchain`: the toolchain generator for MSBuild. It will generate MSBuild + properties files that can be added to the Visual Studio solution projects. This + generator translates the current package configuration, settings, and options, into + MSBuild properties files syntax. + +- `MSBuild` build helper is a wrapper around the command line invocation of MSBuild. It + will abstract the calls like ``msbuild "MyProject.sln" /p:Configuration= + /p:Platform=`` into Python method calls. + +For the full list of tools under ``conan.tools.microsoft`` please check the +:ref:`reference ` section. + + +.. seealso:: + + - Reference for :ref:`MSBuildDeps`, + :ref:`MSBuildToolchain` and + :ref:`MSBuild`. + +.. |visual_studio_logo| image:: ../images/integrations/conan-visual_studio-logo.png diff --git a/2.1/_sources/integrations/xcode.rst.txt b/2.1/_sources/integrations/xcode.rst.txt new file mode 100644 index 000000000000..47ea7cf83412 --- /dev/null +++ b/2.1/_sources/integrations/xcode.rst.txt @@ -0,0 +1,35 @@ +.. _integrations_xcode: + +|xcode_logo| Xcode +================== + +Conan provides different tools to integrate with Xcode IDE, providing all the necessary +information about the dependencies, build options and also to build projects created with +Xcode in recipes. They can be imported from ``conan.tools.apple``. The most relevant tools are: + +Please also check the reference for the CMakeDeps, CMakeToolchain, and CMake tools: + +- `XcodeDeps`: the dependency information generator for Xcode. It will generate multiple + `.xcconfig` configuration files, that can be used by consumers using xcodebuild in the + command line or adding them to the Xcode IDE. + +- `XcodeToolchain`: the toolchain generator for Xcode. It will generate .xcconfig + configuration files that can be added to Xcode projects. This generator translates the + current package configuration, settings, and options, into Xcode .xcconfig files syntax. + +- `XcodeBuild` build helper is a wrapper around the command line invocation of Xcode. It + will abstract the calls like ``xcodebuild -project app.xcodeproj -configuration + -arch ...`` + + +For the full list of tools under ``conan.tools.apple`` please check the :ref:`reference +` section. + +.. seealso:: + + - Reference for :ref:`XcodeDeps`, :ref:`XcodeToolchain + ` and :ref:`XcodeBuild build helper + ` + + +.. |xcode_logo| image:: ../images/integrations/conan-xcode-logo.jpg diff --git a/2.1/_sources/introduction.rst.txt b/2.1/_sources/introduction.rst.txt new file mode 100644 index 000000000000..5c10ac397bd3 --- /dev/null +++ b/2.1/_sources/introduction.rst.txt @@ -0,0 +1,148 @@ +.. _introduction: + + +Introduction +============ + +Conan is a dependency and package manager for C and C++ languages. It is `free and open-source `_, works in all platforms ( Windows, Linux, OSX, FreeBSD, Solaris, etc.), and can be used to develop for all targets including embedded, mobile (iOS, Android), and bare metal. It also integrates with all build systems like CMake, Visual Studio (MSBuild), Makefiles, SCons, etc., including proprietary ones. + +It is specifically designed and optimized for accelerating the development and Continuous Integration of C and C++ projects. With full binary management, it can create and reuse any number of different binaries (for different configurations like architectures, compiler versions, etc.) for any number of different versions of a package, using exactly the same process in all platforms. As it is decentralized, it is easy to run your own server to host your own packages and binaries privately, without needing to share them. The free `JFrog Artifactory Community Edition (CE) `_ is the recommended Conan server to host your own packages privately under your control. + +Conan is mature and stable, with a strong commitment to forward compatibility (non-breaking policy), and has a complete team dedicated full time to its improvement and support. It is backed and used by a great community, from open source contributors and package creators in `ConanCenter `_ to thousands of teams and companies using it. + + +Open Source +----------- + +Conan is Free and Open Source, with a permissive MIT license. Check out the source code and issue tracking (for questions and support, reporting bugs and suggesting feature requests and improvements) at https://github.com/conan-io/conan + + +Decentralized package manager +----------------------------- + +Conan is a decentralized package manager with a client-server architecture. This means that clients can fetch packages from, as well as upload packages to, different servers (“remotes”), similar to the “git” push-pull model to/from git remotes. + +At a high level, the servers are just storing packages. They do not build nor create the packages. The packages are created by the client, and if binaries are built from sources, that compilation is also done by the client application. + + +.. image:: images/conan-systems.png + :width: 70% + :align: center + + +The different applications in the image above are: + +- The Conan client: this is a console/terminal command-line application, containing the heavy logic for package creation and consumption. Conan client has a local cache for package storage, and so it allows you to fully create and test packages offline. You can also work offline as long as no new packages are needed from remote servers. +- `JFrog Artifactory Community Edition (CE) `_ is the recommended Conan server to host your own packages privately under your control. It is a free community edition of JFrog Artifactory for Conan packages, including a WebUI, multiple auth protocols (LDAP), Virtual and Remote repositories to create advanced topologies, a Rest API, and generic repositories to host any artifact. +- The conan_server is a small server distributed together with the Conan client. It is a simple open-source implementation and provides basic functionality, but no WebUI or other advanced features. +- `ConanCenter `_ is a central public repository where the community contributes packages for popular open-source libraries like Boost, Zlib, OpenSSL, Poco, etc. + + +Binary management +----------------- + +One of the most powerful features of Conan is that it can create and manage pre-compiled binaries for any possible platform and configuration. By using pre-compiled binaries and avoiding repeated builds from source, it saves significant time for developers and Continuous Integration servers, while also improving the reproducibility and traceability of artifacts. + +A package is defined by a "conanfile.py". This is a file that defines the package's dependencies, sources, how to build the binaries from sources, etc. One package “conanfile.py” recipe can generate any arbitrary number of binaries, one for each different platform and configuration: operating system, architecture, compiler, build type, etc. These binaries can be created and uploaded to a server with the same commands in all platforms, having a single source of truth for all packages and not requiring a different solution for every different operating system. + + +.. image:: images/conan-binary_mgmt.png + :width: 70% + :align: center + +Installation of packages from servers is also very efficient. Only the necessary binaries for the current platform and configuration are downloaded, not all of them. If the compatible binary is not available, the package can be built from sources in the client too. + + +All platforms, all build systems and compilers +---------------------------------------------- + +Conan works on Windows, Linux (Ubuntu, Debian, RedHat, ArchLinux, Raspbian), OSX, FreeBSD, and SunOS, and, as it is portable, it might work in any other platform that can run +Python. It can target any existing platform: ranging from bare metal to desktop, mobile, embedded, servers, and cross-building. + +Conan works with any build system too. There are built-in integrations to support the most popular ones like CMake, Visual Studio (MSBuild), Autotools and Makefiles, Meson, SCons, etc., but it is not a requirement to use any of them. It is not even necessary that all packages use the same build system: each package can use their own build system, and depend on other packages using different build systems. It is also possible to integrate with any build system, including proprietary ones. + +Likewise, Conan can manage any compiler and any version. There are default definitions for the most popular ones: gcc, cl.exe, clang, apple-clang, intel, with different configurations of versions, runtimes, C++ standard library, etc. This model is also extensible to any custom configuration. + + + +.. _stability: + +Stable +------ + +From Conan 2.0 and onwards, there is a commitment to stability, with the goal of not breaking user space while evolving the tool and the platform. This means: + +- Moving forward to following minor versions 2.1, 2.2, …, 2.X should never break existing recipes, packages or command line flows +- If something is breaking, it will be considered a regression and reverted. +- Bug fixes will not be considered breaking, recipes and packages relying on the incorrect behavior of such bugs will be considered already broken. +- Only documented features in https://docs.conan.io are considered part of the public interface of Conan. Private implementation details, and everything not included in the documentation is subject to change. +- The compatibility is always considered forward. New APIs, tools, methods, helpers can be added in following 2.X versions. Recipes and packages created with these features will be backwards incompatible with earlier Conan versions. +- Only the latest released patch (major.minor.patch) of every minor version is supported and stable. + +There are some things that are not included in this commitment: + +- Public repositories, like **ConanCenter**, assume the use of the latest version of the Conan client, and using an older version may result in failure of packages and recipes created with a newer version of the client. It is recommended to use your own private repository to store your own copy of the packages for production, or as a secondary alternative, to use some locking mechanism to avoid possible disruption from packages in ConanCenter that are updated and require latest Conan version. +- Configuration and automatic tools detection, like the detection of the default profile (``conan profile detect``) can and will change at any time. Users are encouraged to define their configurations in their own profiles files for repeatability. New versions of Conan might detect different default profiles. +- Builtin default implementation of extension points as plugins or hooks can also change with every release. Users can provide their own ones for stability. +- Output of packages templates with ``conan new`` can update at any time to use latest features. +- The output streams stdout, stderr, i.e. the terminal output can change at any time. Do not parse the terminal output for automation. +- Anything that is explicitly labeled as ``experimental`` or ``preview`` in the documentation, or in the Conan cli output. Read the section below for a detailed definition of these labels. +- Anything that is labeled as ``deprecated`` in the documentation should not get new usages, as it will not get new fixes and it will be removed in the next major version. +- Other tools and repositories outside of the Conan client + + +Conan needs Python>=3.6 to run. Conan will deprecate support for Python versions 1 year after those versions have been declared End Of Life (EOL). + +If you have any question regarding Conan updates, stability, or any clarification about this definition of stability, please report in the documentation issue tracker: https://github.com/conan-io/docs. + + + +Community +--------- + +Conan is being used in production by thousands of companies like TomTom, Audi, RTI, Continental, Plex, Electrolux and Mercedes-Benz and many thousands of developers around the world. + +But an essential part of Conan is that many of those users will contribute back, creating an amazing and helpful community: + +- The https://github.com/conan-io/conan project has around 6.5K stars in Github and counts with contributions from more than 300 different users (this is just the client tool). +- Many other users contribute recipes for ConanCenter via the https://github.com/conan-io/conan-center-index repo, creating packages for popular Open Source libraries, contributing many thousands of Pull Requests per year. +- More than two thousands Conan users hang around the `CppLang Slack #conan channel `_, and help responding to questions, discussing problems and approaches, making it one of the most active channels in the whole CppLang slack. +- There is a Conan channel in `#include discord `_. + + +Navigating the documentation +------------------------------ + +This documentation has very different sections: + +- The **tutorial** is an actual hands-on tutorial, with examples and real code, intended to be played sequentially from beginning to end, + running the exercises in your own computer. There is a "narrative" to this section and the exercises might depend on some previous explanations and code - building on the previous example. + This is the recommended approach for learning Conan. +- The **examples** also contain hands-on, fully operational examples with code, aimed to explain some very specific feature, tool or behavior. + They do not have a conducting thread, they should be navigated by topic. +- The **reference** is the source of truth for the interfaces of every public command, class, method, helper, API and configuration file that can + be used. It is not designed to be read fully, but to check for individual items when necessary. +- The **knowledge** base contains things like the FAQ, a very important section about general guidelines, good practices and bad practices, videos + from conference talks, etc. + +Features in this documentation might be labeled as: + +- **experimental**: This feature is released and can be used, but it is under active development and the interfaces, APIs or behavior might change + as a result of evolution, and this will not be considered breaking. If you are interested in these features you are encouraged to try them + and give feedback, because that is exactly what allows to stabilize them. +- **preview**: When a feature is released in preview mode, this means it aims to be as final and stable as possible. Users are encouraged to use them, + and the maintainers team will try not to break them unless necessary. But if necessary, they might change and break. +- **deprecated**: This feature should no longer be used, and it will be fully removed in next major release. Other alternatives or approaches should + be used instead of it, and if using it, migrating to the other alternatives should be done as soon as possible. They will not be maintained or + get fixes. + +Everything else that is not labeled should be considered stable, and won't be broken, unless something that +is declared a bugfix. + + + +Have any questions? Please check out our :ref:`FAQ section ` or |write_us|. + +.. |write_us| raw:: html + + write to us diff --git a/2.1/_sources/knowledge.rst.txt b/2.1/_sources/knowledge.rst.txt new file mode 100644 index 000000000000..cc35428dc4da --- /dev/null +++ b/2.1/_sources/knowledge.rst.txt @@ -0,0 +1,15 @@ +.. _knowledge: + +Knowledge +========= + + +.. toctree:: + :maxdepth: 2 + + + knowledge/cheatsheet + knowledge/guidelines + knowledge/faq + knowledge/videos + diff --git a/2.1/_sources/knowledge/cheatsheet.rst.txt b/2.1/_sources/knowledge/cheatsheet.rst.txt new file mode 100644 index 000000000000..ed5756d45b28 --- /dev/null +++ b/2.1/_sources/knowledge/cheatsheet.rst.txt @@ -0,0 +1,21 @@ +*********** +Cheat sheet +*********** + +This is a visual cheat sheet for basic Conan commands and +concepts which users can print out and use as a handy reference. It is available +as both a PDF and PNG. + +.. tip:: + + There is a `blog post `_ + which goes over the changes from Conan 1.x and 2.0 as well. + +:download:`PDF Format <../images/cheatsheet/conan2-cheatsheet-v5.pdf>` + +:download:`PNG Format <../images/cheatsheet/conan2-cheatsheet-v5.png>` + +.. image:: ../images/cheatsheet/conan2-cheatsheet-v5.png + :height: 600 px + :width: 800 px + :align: center diff --git a/2.1/_sources/knowledge/faq.rst.txt b/2.1/_sources/knowledge/faq.rst.txt new file mode 100644 index 000000000000..c702fc93c3ad --- /dev/null +++ b/2.1/_sources/knowledge/faq.rst.txt @@ -0,0 +1,128 @@ +.. _faq: + +FAQ +=== + +.. seealso:: + + There is a great community behind Conan with users helping each other in `Cpplang Slack`_. + Please join us in the ``#conan`` channel! + +Troubleshooting +--------------- + +ERROR: Missing prebuilt package +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When installing packages (with :command:`conan install` or :command:`conan create`) it is possible +that you get an error like the following one: + +.. code-block:: text + + ERROR: Missing binary: zlib/1.2.11:b1d267f77ddd5d10d06d2ecf5a6bc433fbb7eeed + + zlib/1.2.11: WARN: Can't find a 'zlib/1.2.11' package binary 'b1d267f77ddd5d10d06d2ecf5a6bc433fbb7eeed' for the configuration: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu11 + compiler.libcxx=libc++ + compiler.version=14 + os=Macos + [options] + fPIC=True + shared=False + + ERROR: Missing prebuilt package for 'zlib/1.2.11'. You can try: + - List all available packages using 'conan list {ref}:* -r=remote' + - Explain missing binaries: replace 'conan install ...' with 'conan graph explain ...' + - Try to build locally from sources using the '--build=zlib/1.2.11' argument + + More Info at 'https://docs.conan.io/en/2/knowledge/faq.html#error-missing-prebuilt-package' + +This means that the package recipe ``zlib/1.2.11`` exists, but for some reason there is no +precompiled package for your current settings or options. Maybe the package creator didn't build and +shared pre-built packages at all and only uploaded the package recipe, or they are only +providing packages for some platforms or compilers. E.g. the package creator built +packages from the recipe for apple-clang 11, but you are using apple-clang 14. +Also you may want to check your `package ID mode` as it may +have an influence on the packages available for it. + +By default, Conan doesn't build packages from sources. There are several possibilities to +overcome this error: + +- You can try to build the package for your settings from sources, indicating some build + policy as argument, like :command:`--build zlib*` or :command:`--build missing`. If the + package recipe and the source code work for your settings you will have your binaries + built locally and ready for use. + +- If building from sources fails, and you are using the `conancenter` remote, you can open + an issue in `the Conan Center Index repository + `_ + + + +.. _error_invalid_setting: + +ERROR: Invalid setting +^^^^^^^^^^^^^^^^^^^^^^ + +It might happen sometimes, when you specify a setting not present in the defaults +that you receive a message like this: + +.. code-block:: bash + + $ conan install . -s compiler.version=4.19 ... + + ERROR: Invalid setting '4.19' is not a valid 'settings.compiler.version' value. + Possible values are ['4.4', '4.5', '4.6', '4.7', '4.8', '4.9', '5.1', '5.2', '5.3', '5.4', '6.1', '6.2'] + + +This doesn't mean that such compiler version is not supported by Conan, it is just that it is not present in the actual +defaults settings. You can find in your user home folder ``~/.conan2/settings.yml`` a settings file that you +can modify, edit, add any setting or any value, with any nesting if necessary. See :ref:`reference_config_files_settings_yml` to learn +how you can customize your settings to model your binaries at your will. + +As long as your team or users have the same settings (``settings.yml`` and ``settings_user.yml`` an be easily shared with the +``conan config install`` command), everything will work. The *settings.yml* file is just a +mechanism so users agree on a common spelling for typical settings. Also, if you think that some settings would +be useful for many other conan users, please submit it as an issue or a pull request, so it is included in future +releases. + +It is possible that some built-in helper or integrations, like ``CMake`` or ``CMakeToolchain`` will not understand the new added settings, +don't use them or even fail if you added some new unexpected value to existing settings. +Such helpers as ``CMake`` are simple utilities to translate from conan settings to the respective +build system syntax and command line arguments, so they can be extended or replaced with your own +one that would handle your own private settings. + +.. _`Cpplang Slack`: https://cppalliance.org/slack/ + + +ERROR: AuthenticationException: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This error can happen, if there are no or false authentication credentials in the HTTP request from conan. To get more information try enabling the debug level for HTTP connections: + +.. code-block:: python + + import http.client + http.client.HTTPConnection.debuglevel = 1 + +One source of error can be the ``.netrc`` file, which is `honored by the requests library `_. + +.. _faq_different_revisions: + +ERROR: Obtaining different revisions in Linux and Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Git will (by default) checkout files in Windows systems using ``CRLF`` line endings, effectively producing different files than in Linux that files will use ``LF`` line endings. As files are different, the Conan recipe revision will be different from the revisions computed in other platforms such as Linux, resulting in missing the respective binaries in the other revision. + +Conan will not normalize or change in any way the source files, it is not its responsibility and there are risks of breaking things. The source control is the application changing the files, so that is a more correct place to handle this. It is necessary to instruct Git to do the checkout with the same line endings. This can be done several ways, for example, by adding a ``.gitattributes`` file to the project repository: + +.. code-block:: ini + + [auto] + crlf = false + +Other approach would be to change the ``.gitconfig`` to change it globally. Modern editors (even Notepad) in Windows can perfectly work with files with ``LF``, it is no longer necessary to change the line endings. diff --git a/2.1/_sources/knowledge/guidelines.rst.txt b/2.1/_sources/knowledge/guidelines.rst.txt new file mode 100644 index 000000000000..9ac2c45eedc4 --- /dev/null +++ b/2.1/_sources/knowledge/guidelines.rst.txt @@ -0,0 +1,73 @@ +Core guidelines +=============== + + +Good practices +-------------- + +- **build() should be simple, prepare the builds in generate() instead**: + The recipes' ``generate()`` method purpose is to prepare the build as much as possible. + Users calling ``conan install`` will execute this method, and the generated files should + allow users to do "native" builds (calling directly "cmake", "meson", etc.) as easy as possible. + Thus, avoiding as much as possible any logic in the ``build()`` method, and moving it to + the ``generate()`` method helps developers achieve the same build locally as the one that + would be produced by a ``conan create`` build in the local cache. +- **Always use your own profiles in production**, instead of relying on the auto-detected profile, + as the output of such auto detection can vary over time, resulting in unexpected results. + Profiles (and many other configuration), can be managed with ``conan config install``. +- **Developers should not be able to upload to "development" and "production" repositories** in the server. + Only CI builds have write permissions in the server. Developers should only have read permissions and + at most to some "playground" repositories used to work and share things with colleagues, + but which packages are never used, moved or copied to the development or production repositories. +- **The test_package purpose is to validate the correct creation of the package, not for functional testing**. The ``test_package`` purpose is to check that the package has been correctly created (that is, + that it has correctly packaged the headers, the libraries, etc, in the right folders), not that + the functionality of the package is correct. Then, it should be kept as simple as possible, like + building and running an executable that uses the headers and links against a packaged library + should be enough. Such execution should be as simple as possible too. Any kind of + unit and functional tests should be done in the ``build()`` method. +- **All input sources must be common for all binary configurations**: All the "source" inputs, including the ``conanfile.py``, the ``conandata.yml``, the ``exports`` and ``exports_source``, the ``source()`` method, patches applied in the ``source()`` method, cannot be conditional to anything, platform, OS or compiler, as they are shared among all configurations. Furthermore, the line endings for all these things should be the same, it is recommended to use always just line-feeds in all platforms, and do not convert or checkout to ``crlf`` in Windows, as that will cause different recipe revisions. +- **Keep ``python_requires`` as simple as possible**. Avoid transitive ``python_requires``, keep them + as reduced as possible, and at most, require them explicitly in a "flat" structure, without + ``python_requires`` requiring other ``python_requires``. Avoid inheritance (via ``python_requires_extend``) + if not strictly necessary, and avoid multiple inheritance at all costs, as it is extremely + complicated, and it does not work the same as the built-in Python one. +- At the moment the **Conan cache is not concurrent**. Avoid any kind of concurrency or parallelism, + for example different parallel CI jobs should use different caches (with CONAN_HOME env-var). This might + change in the future and we will work on providing concurrency in the cache, but until then, + use isolated caches for concurrent tasks. +- **Avoid 'force' and 'override' traits as a versioning mechanism.** The ``force`` and ``override`` traits to + solve conflicts are not recommended as a general versioning solution, just as a temporary workaround to solve + a version conflict. Its usage should be avoided whenever possible, and updating versions or version ranges in + the graph to avoid the conflicts without overrides and forces is the recommended approach. +- **Please, do not abuse 'tool_requires'**. Those are intended only for executables like ``cmake`` and ``ninja`` running in the "build" + context, not for libraries or library-like dependencies, that must use ``requires`` or ``test_requires``. + +Forbidden practices +------------------- + +- **Conan is not re-entrant**: Calling the Conan process from Conan itself cannot be done. That includes calling + Conan from recipe code, hooks, plugins, and basically every code that already executes when + Conan is called. Doing it will result in undefined behavior. For example it is not valid + to run ``conan search`` from a ``conanfile.py``. This includes indirect calls, like running + Conan from a build script (like ``CMakeLists.txt``) while this build script is already being + executed as a result of a Conan invocation. For the same reason **Conan Python API cannot be used from recipes**: The Conan Python API can only be called from Conan custom commands or from user Python scripts, + but never from ``conanfile.py`` recipes, hooks, extensions, plugins, or any other code + executed by Conan. +- **Settings and configuration (conf) are read-only in recipes**: The settings and configuration cannot be defined or assigned values in recipes. Something like ``self.settings.compiler = "gcc"`` in recipes shouldn't be done. That is undefined behavior and can crash at any time, or just be ignored. Settings and configuration can only be defined in profiles, in command line arguments or in the ``profile.py`` plugin. +- **Recipes reserved names**: Conan ``conanfile.py`` recipes user attributes and methods should always start with ``_``. + Conan reserves the "public" namespace for all attributes and methods, and ``_conan`` for + private ones. Using any non-documented Python function, method, class, attribute, even if + it is "public" in the Python sense, is undefined behavior if such element is not documented + in this documentation. +- **Conan artifacts are immutable**: Conan packages and artifacts, once they are in the Conan cache, they are assumed to be immutable. + Any attempt to modify the exported sources, the recipe, the conandata.yml or any of the exported + or the packaged artifacts, is undefined behavior. For example, it is not possible to modify the + contents of a package inside the ``package_info()`` method or the ``package_id()`` method, those + methods should never modify, delete or create new files inside the packages. If you need to modify + some package, you might use your own custom ``deployer``. +- **Conan cache paths are internal implementation detail**: The Conan cache paths are an internal implementation detail. Conan recipes provide abstractions + like ``self.build_folder`` to represent the necessary information about folders, and commands + like ``conan cache path`` to get information of the current folders. The Conan cache might + be checked while debugging, as read-only, but it is not allowed to edit, modify or delete + artifacts or files from the Conan cache by any other means that Conan command line or public API. +- **Sources used in recipes must be immutable**. Once a recipe is exported to the Conan cache, it is expected that the sources are immutable, that is, that retrieving the sources in the future will always retrieve the exact same sources. It is not allowed to use moving targets like a ``git`` branch or a download of a file that is continuously rewritten in the server. ``git`` checkouts must be of an immutable tag or a commit, and ``download()/get()`` must use checksums to verify the server files doesn't change. Not using immutable sources will be undefined behavior. diff --git a/2.1/_sources/knowledge/videos.rst.txt b/2.1/_sources/knowledge/videos.rst.txt new file mode 100644 index 000000000000..807e990b0778 --- /dev/null +++ b/2.1/_sources/knowledge/videos.rst.txt @@ -0,0 +1,55 @@ +.. _videos: + +Videos +====== + +.. warning:: + + This section presents some conference talks and presentations regarding Conan. + While they can be very informative and educational, please note that some of them might + be outdated. Always use the documentation and reference as the source of truth, not the + videos. + + +- ACCU 2022: Advanced Dependencies Model in Conan 2.0 C, C++ Package Manager by Diego Rodriguez-Losada + + Conan 2.0 introduces a new dependencies model with requirements "traits" like visibility, + definition and propagation of headers and libraries independently, and more that allow modeling all these advanced use cases. + This talk will present this new model, and apply it to solve different advanced use cases, with real life examples + +.. youtube:: kKGglzm5ous + +- CppCon 2022: What's New in Conan 2.0 C/C++ Package Manager - Diego Rodriguez-Losada + + During the years since Conan 1.0 was released, we have continued to learn from the C++ ecosystem as we watched it grow; + learning many lessons, challenges and trends in the industry from the feedback from tens of thousands of conversations with users and customers, + including many of the largest C++ related companies in the world. This talk summarizes some of these lessons + and how they have been used to create the new major version of Conan. + +.. youtube:: NM-xp3tob2Q + +- Using std::cpp: Why you shouldn’t write your own C++ package manager Luis Caro Campos JFrog + + This talk will provide a quick overview of how Conan deals with intrinsic C++ complexities: + Headers vs binary symbols + Shared and static library + Symbol visibilityBinary compatibility: is there a one-size fits all approach to modeling it? + Build-time dependency resolution is only half the battle, what about runtime dependencies? + +- Meeting C++ 2023: CMake and Conan: past, present and future - Diego Rodriguez-Losada + +.. youtube:: s0q6s5XzIrA + + This talk will quickly review the past approaches, their pitfalls, and how modern CMake and Conan integrations have improved over them: + + From variables, to targets, to transparent targets integration with modern Conan generators + Better separation of concerns to align binary configurations using CMake toolchains + Improving the developer experience with CMake presets + + The new CMake-Conan integration using CMake’s new dependency providers feature for transparent installation of dependencies + +.. youtube:: 8Go5g2jVJWo + +- Meeting C++ online book & tool fair: Conan 2.0 demo - Chris McArthur + +.. youtube:: 1q5oIOupwjg diff --git a/2.1/_sources/reference.rst.txt b/2.1/_sources/reference.rst.txt new file mode 100644 index 000000000000..9c303c0f857a --- /dev/null +++ b/2.1/_sources/reference.rst.txt @@ -0,0 +1,19 @@ +.. _reference: + +Reference +========= + + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + reference/commands + reference/conanfile + reference/conanfile_txt + reference/tools + reference/config_files + reference/extensions + reference/environment + reference/binary_model + reference/conan_server diff --git a/2.1/_sources/reference/binary_model.rst.txt b/2.1/_sources/reference/binary_model.rst.txt new file mode 100644 index 000000000000..812b154d14ad --- /dev/null +++ b/2.1/_sources/reference/binary_model.rst.txt @@ -0,0 +1,19 @@ +.. _reference_binary_model: + +The binary model +================ + +This section introduces first how the ``package_id``, the package binaries identifier is computed, hashing the configuration (settings + options + dependencies versions). While the effect of ``settings`` and ``options`` is more straightforward, understanding the effects of the dependencies requires more explanations, so that will be done in its own section. + +Conan binary model is extensible, and users can define their custom settings, options and configuration to model their own binaries characteristics. + +Finally, the default binary compatibility model will be described, and how it can be customized to adapt to different needs. + + +.. toctree:: + :maxdepth: 1 + + binary_model/package_id + binary_model/dependencies + binary_model/extending + binary_model/custom_compatibility diff --git a/2.1/_sources/reference/binary_model/custom_compatibility.rst.txt b/2.1/_sources/reference/binary_model/custom_compatibility.rst.txt new file mode 100644 index 000000000000..bdc16666787d --- /dev/null +++ b/2.1/_sources/reference/binary_model/custom_compatibility.rst.txt @@ -0,0 +1,166 @@ +Customizing the binary compatibility +==================================== + +The default binary compatibility requires an almost exact match of settings and options, and a versioned match +of dependencies versions, as explained in the :ref:`previous section about dependencies`. + +In summary, the required binaries ``package_id`` when installing dependencies should match by default: + +- All the settings in the ``package_id`` except ``compiler.cppstd`` should match exactly the ones provided in the input profiles, including the compiler version. So ``compiler.version=9`` is different than ``compiler.version=9.1``. +- The default behavior will assume binary compatibility among different ``compiler.cppstd`` values for C++ packages, being able to fall back to other values rather than the one specified in the input profiles, if the ``cppstd`` required by the input profile does not exist. This is controlled by the ``compatibility.py`` plugin, that can be customized by users. +- All the options in the ``package_id`` should match exactly the ones provided in the input profiles. +- The versions of the dependencies should match: + + - In case of "embedding dependencies", should match the exact version, including the recipe-revision and the dependency ``package_id``. The ``package_revision`` is never included as it is assumed to be ill-formed to have more than one ``package_revision`` for the same ``package_id``. + - In case of "non-embedding dependencies", the versions of the dependencies should match down to the ``minor`` version, being the ``patch``, ``recipe_revision`` and further information not taken into account. + - In case of "tool dependencies", the versions of the dependencies do not affect at all by default to the consumer ``package_id``. + + +These rules can be customized and changed using different approaches, depending on the needs, as explained in following sections + +Customizing binary compatibility of settings and options +-------------------------------------------------------- + +Information erasure in package_id() method +++++++++++++++++++++++++++++++++++++++++++ + +Recipes can **erase** information from their ``package_id`` using their ``package_id()`` method. For example, a package containing only an executable can decide to remove the information from ``settings.compiler`` and ``settings.build_type`` from their ``package_id``, assuming that an executable built with any compiler will be valid, and that it is not necessary to store different binaries built with different compilers: + +.. code-block:: python + + def package_id(self): + del self.info.settings.compiler + del self.info.settings.build_type + +It is also possible to assign a value for a given setting, for example if we want to have one single binary for all gcc versions included in the [>=5 <7>] range, we could do: + +.. code-block:: python + + def package_id(self): + if self.info.settings.compiler == "gcc": + version = Version(self.info.settings.compiler.version) + if version >= "5.0" and version < "7.0": + self.info.settings.compiler.version = "gcc5-6" + + +.. note:: + + **Best practice** + + Note that information erasure in ``package_id()`` means that 1 single ``package_id`` will represent a whole range of different settings, but the information of what exact setting was used to create the binary will be lost, and only 1 binary can be created for that range. Re-creating the package with different settings in the range, will create a new binary that overwrites the previous one (with a new package-revision). + + If we want to be able to create, store and manage different binaries for different input settings, information erasure can't be used, and using the below ``compatibility`` approaches is recommended. + +Read more about ``package_id()`` in: + +- :ref:`creating_packages_configure_options_settings` +- :ref:`package_id() method reference` + + +The compatibility() method +++++++++++++++++++++++++++ + +Recipes can define their binary compatibility rules, using their ``compatibility()`` method. +For example, if we want that binaries +built with gcc versions 4.8, 4.7 and 4.6 to be considered compatible with the ones compiled +with 4.9 we could declare a ``compatibility()`` method like this: + +.. code-block:: python + + def compatibility(self): + if self.settings.compiler == "gcc" and self.settings.compiler.version == "4.9": + return [{"settings": [("compiler.version", v)]} + for v in ("4.8", "4.7", "4.6")] + + +Read more about the ``compatibility()`` method in :ref:`the compatibility() method reference` + + +The ``compatibility.py`` plugin ++++++++++++++++++++++++++++++++ + +Compatibility can be defined globally via the ``compatibility.py`` plugin, in the same way that the ``compatibility()`` method does for one recipe, but for all packages globally. + +Check the binary compatibility :ref:`compatibility.py extension `. + + + +Customizing binary compatibility of dependencies versions +--------------------------------------------------------- + +Global default package_id modes ++++++++++++++++++++++++++++++++ + +The ``core.package_id:default_xxx`` configurations defined in ``global.conf`` can be used to globally change the defaults of how dependencies affect their consumers + +.. code-block:: ini + + core.package_id:default_build_mode: By default, 'None' + core.package_id:default_embed_mode: By default, 'full_mode' + core.package_id:default_non_embed_mode: By default, 'minor_mode' + core.package_id:default_python_mode: By default, 'minor_mode' + core.package_id:default_unknown_mode: By default, 'semver_mode' + +.. note:: + + **Best practices** + + It is strongly recommended that the ``core.package_id:default_xxx`` should be global, consistent and immutable accross organizations. It can be confusing to change these defaults for different projects or teams, because it will result in missing binaries. + + It should also be consistent and shared with the consumers of generated packages if those packages are + shared outside the organization, in that case sharing the ``global.conf`` file via ``conan config install`` + could be recommended. + + Consider using the Conan defaults, they should be a good balance between efficiency and safety, ensuring exact re-building for embed cases, and good control via versions for non-embed cases. + + +Custom package_id modes for recipe consumers +++++++++++++++++++++++++++++++++++++++++++++ + +Recipes can define their default effect to their consumers, via some ``package_id_xxxx_mode`` attributes. + +The ``package_id_embed_mode, package_id_non_embed_mode, package_id_unknown_mode`` are class attributes that can be defined in recipes to define the effect they have on their consumers ``package_id``. Can be declared as: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + ... + package_id_embed_mode = "full_mode" + package_id_non_embed_mode = "patch_mode" + package_id_unknown_mode = "minor_mode" + + +Read more in :ref:`reference_conanfile_attributes_package_id_modes` + +Custom package_id from recipe dependencies +++++++++++++++++++++++++++++++++++++++++++ + +Recipes can define how their dependencies affect their ``package_id``, using the ``package_id_mode`` trait: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + def requirements(self): + self.requires("mydep/1.0", package_id_mode="patch_mode") + + +Using ``package_id_mode`` trait does not differentiate between the "embed" and "non-embed" cases, it is up to the user to define the correct value. It is likely that this approach should only be used for very special cases that do not have variability of shared/static libraries controlled via ``options``. + +Note that the ``requirements()`` method is evaluated while the graph is being expanded, the dependencies do not exist yet (haven't been computed), so it is not possible to know the dependencies options. +In this case it might be preferred to use the ``package_id()`` method. + +The ``package_id()`` method can define how the dependencies affect the current package with: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + def package_id(self): + self.info.requires["mydep"].major_mode() + +The different modes that can be used are defined in :ref:`reference_conanfile_attributes_package_id_modes` diff --git a/2.1/_sources/reference/binary_model/dependencies.rst.txt b/2.1/_sources/reference/binary_model/dependencies.rst.txt new file mode 100644 index 000000000000..086f5099b7ad --- /dev/null +++ b/2.1/_sources/reference/binary_model/dependencies.rst.txt @@ -0,0 +1,154 @@ +.. _reference_binary_model_dependencies: + +The effect of dependencies on ``package_id`` +============================================ + +When a given package depends on a another package and uses it, the effect of dependencies can be different based on the package types: + +For libraries: + +- **Non-embed mode**: When an application or a shared library depends on another shared library, or when a static library depends on another static library, the "consumer" library does not do a copy of the binary artifacts of the "dependency" at all. We call it non-embed mode, the dependency binaries are not being linked or embedded in the consumer. This assumes that there are not inlined functionalities in the dependency headers, and the headers are pure interface and not implementation. +- **Embed mode**: When an application or a shared library depends on a header-only or a static-library, the dependencies binaries are copied or partially copied (depending on the linker) in the consumer binary. Also when a static library depends on a header-only library, it is considered that there will be embedding in the consumer binary of such headers, as they will also contain the implementation, it is impossible that they are a pure interface. + +For applications (``tool_requires``): + +- **Build mode**: When some package uses a ``tool_requires`` of another package, the binary artifacts in the dependency are never copied or embedded. + +Non-embed mode +-------------- + +When we list the binaries of a package like ``openssl`` with dependencies: + +.. code-block:: bash + :emphasize-lines: 13,14 + + $ conan list openssl/3.1.2:* -r=conancenter + conancenter + openssl + openssl/3.1.2 + revisions + 8879e931d726a8aad7f372e28470faa1 (2023-09-13 18:52:54 UTC) + packages + 0348efdcd0e319fb58ea747bb94dbd88850d6dd1 # package_id + info + options + shared: True + ... + requires + zlib/1.3.Z + +This binary was a ``shared`` library, linking with ``zlib`` as a shared library. +This means it was using "non-embed" mode. The default of non-embed mode is ``minor_mode``, which means: + +- All ``zlib`` patch versions will be mapped to the same ``zlib/1.3.Z``. This means that if our ``openssl/3.1.2`` package binary ``0348efdcd0e319fb58ea747bb94dbd88850d6dd1`` binary is considered binary compatible with all ``zlib/1.3.Z`` versions (for any ``Z``), and will not require to rebuild the ``openssl`` binary. +- New ``zlib`` minor versions, like ``zlib/1.4.0`` will result in a "minor-mode" identifier like ``zlib/1.4.Z``, and then, it will require a new ``openssl/3.1.2`` package binary, with a new ``package_id`` + + +Embed mode +---------- + +The following commands illustrate the concept of embed-mode. We create a ``dep/0.1`` package with a static library, and then we create a ``app/0.1`` package with an executable that links with static library inside ``dep/0.1``. We can use the ``conan new`` command for quickly creating these two packages: + + +.. code-block:: bash + + $ mkdir dep && cd dep + $ conan new cmake_lib -d name=dep -d version=0.1 + $ conan create . -tf="" + $ cd .. && mkdir app && cd app + $ conan new cmake_exe -d name=app -d version=0.1 -d requires=dep/0.1 + $ conan create . + dep/0.1: Hello World Release! + ... + app/0.1: Hello World Release! + +If we now list the ``app/0.1`` binaries, we will see the binary just created: + + +.. code-block:: bash + :emphasize-lines: 11,12 + + $ conan list app/0.1:* + Local Cache + app/0.1 + revisions + 632e236936211ac2293ec33339ce582b (2023-09-25 22:34:17 UTC) + packages + 3ca530d20914cf632eb00efbccc564da48190314 + info + settings + ... + requires + dep/0.1#d125304fb1fb088d5b92d4f8135f4dff:9bdee485ef71c14ac5f8a657202632bdb8b4482b + +It is now visible that the ``app/0.1`` package-id depends on the full identifier of the ``dep/0.1`` dependency, that includes both its recipe revision and ``package_id``. + +If we do a change now to the ``dep`` code, and re-create the ``dep/0.1`` package , even if we don't bump the version, it will create a new recipe revision: + + +.. code-block:: bash + + $ cd ../dep + # Change the "src/dep.cpp" code to print a new message, like "Hello Moon" + $ conan create . -tf="" + # New recipe revision dep/0.1#1c90e8b8306c359b103da31faeee824c + +So if we try now to install ``app/0.1`` binary, it will fail with a "missing binary" error: + + +.. code-block:: text + :emphasize-lines: 7,8 + + $ conan install --requires=app/0.1 + ERROR: Missing binary: app/0.1:ef2b5ed33d26b35b9147c90b27b217e2c7bde2d0 + + app/0.1: WARN: Can't find a 'app/0.1' package binary 'ef2b5ed33d26b35b9147c90b27b217e2c7bde2d0' for the configuration: + [settings] + ... + [requires] + dep/0.1#1c90e8b8306c359b103da31faeee824c:9bdee485ef71c14ac5f8a657202632bdb8b4482b + + ERROR: Missing prebuilt package for 'app/0.1' + + +As the ``app`` executable links with the ``dep`` static library, it needs to be rebuilt to include the latest changes, even if ``dep/0.1`` didn't bump its version, ``app/0.1`` depends on "embed-mode" on ``dep/0.1``, so it wil use down to the ``package_id`` of such dependency identifier. + +Let's build the new ``app/0.1`` binary: + +.. code-block:: bash + :emphasize-lines: 3 + + $ cd ../app + $ conan create . + dep/0.1: Hello Moon Release! # Message changed to Moon + ... + app/0.1: Hello World Release! + +Now we will have two ``app/0.1`` different binaries: + +.. code-block:: bash + :emphasize-lines: 12,13,18,19 + + $ conan list app/0.1:* + Local Cache + app + app/0.1 + revisions + 632e236936211ac2293ec33339ce582b (2023-09-25 22:49:32 UTC) + packages + 3ca530d20914cf632eb00efbccc564da48190314 + info + settings + ... + requires + dep/0.1#d125304fb1fb088d5b92d4f8135f4dff:9bdee485ef71c14ac5f8a657202632bdb8b4482b + ef2b5ed33d26b35b9147c90b27b217e2c7bde2d0 + info + settings + ... + requires + dep/0.1#1c90e8b8306c359b103da31faeee824c:9bdee485ef71c14ac5f8a657202632bdb8b4482b + +We will have these two different binaries, one of them linking with the first revision of the ``dep/0.1`` dependency (with the "Hello World" message), and the other binary with the other ``package_id`` linked with the second revision of the ``dep/0.1`` dependency (with the "Hello Moon" message). + +The above described mode is called ``full_mode``, and it is the default for the ``embed_mode``. diff --git a/2.1/_sources/reference/binary_model/extending.rst.txt b/2.1/_sources/reference/binary_model/extending.rst.txt new file mode 100644 index 000000000000..2a2fc4f7e1db --- /dev/null +++ b/2.1/_sources/reference/binary_model/extending.rst.txt @@ -0,0 +1,156 @@ +Extending the binary model +========================== + +There are a few mechanisms to extend the default Conan binary model: + +Custom settings +--------------- + +It is possible to add new settings or subsettings in the *settings.yml* file, something like: + +.. code-block:: yaml + + os: + Windows: + new_subsetting: [null, "subvalue1", "subvalue2"] + new_root_setting: [null, "value1", "value2"] + + +Where the ``null`` value allows leaving the setting undefined in profiles. If not including, it will be mandatory that profiles define a value for them. + +The custom settings will be used explicitly or implictly in recipes and packages: + +.. code-block:: python + + class Pkg(ConanFile): + # If we explicilty want this package binaries to vary according to 'new_root_setting' + settings = "os", "compiler", "build_type", "arch", "new_root_setting" + # While all packages with 'os=Windows' will implicitly vary according to 'new_subsetting' + +.. seealso:: + + For the full reference of how ``settings.yml`` file can be customized :ref:`visit the settings section`. + In practice, it is not necessary to modify the ``settings.yml`` file, and instead, it is possible to provide ``settings_user.yml`` file to extend the existing settings. See :ref:`the settings_user.yml documentation`. + + +Custom options +-------------- +``Options`` are custom to every recipe, there is no global definition of options like the ``settings.yml`` one. + +Package ``conanfile.py`` recipes define their own options, with their own range of valid values and their own defaults: + +.. code-block:: python + + class MyPkg(ConanFile): + ... + options = {"build_tests": [True, False], + "option2": ["ANY"]} + default_options = {"build_tests": True, + "option1": 42, + "z*:shared": True} + + +The options ``shared``, ``fPIC`` and ``header_only`` have special meaning for Conan, and are considered automatically by most built-in build system integrations. +They are also the recommended default to represent when a library is shared, static or header-only. + +.. seealso:: + + - :ref:`documentation for options` + - :ref:`documentation for default_options`. + + +Settings vs options vs conf +--------------------------- + +When to use settings or options or configuration? + +- **Settings** are a project-wide configuration, something that typically affects the whole project that + is being built and affects the resulting package binaries. For example, the operating system or the architecture would be naturally the same for all + packages in a dependency graph, linking a Linux library to build a Windows app, or + mixing architectures is impossible. + Settings cannot be defaulted in a package recipe. A recipe for a given library cannot say that its default is + ``os=Windows``. The ``os`` will be given by the environment in which that recipe is processed. It is + a mandatory input to be defined in the input profiles. +- On the other hand, **options** are a package-specific configuration that affects the resulting package binaries. Static or shared library are not + settings that apply to all packages. Some can be header only libraries while other packages can be just data, + or package executables. For example, ``shared`` is a common option (the default for specifying if a library can be static or shared), + but packages can define and use any options they want. + Options are defined in the package ``conanfile.py`` recipe, including their supported and default values with ``options`` and ``default_options``. +- Configuration via ``conf`` is intended for configuration that does not affect the resulting package binaries in the general case. For example, + building one library with the ``tools.cmake.cmaketoolchain:generator=Ninja`` shouldn't result in a binary different than if built with Visual Studio + (just a typically faster build thanks to Ninja). + +There are some exceptions to the above. For example, settings can be defined per-package using the ``setting=value``, both in profiles and +command line: + +.. code-block:: bash + + $ conan install . -s mypkg/*:compiler=gcc -s compiler=clang .. + +This will use ``gcc`` for "mypkg" and ``clang`` for the rest of the dependencies (in most cases it is recommended to use the same compiler for the whole dependency graph, but some scenarios when strong binary compatibility is guaranteed, it is possible to mix libraries built with different compilers). + +There are situations whereby many packages use the same option value, thereby allowing you to set its value once using patterns, like: + +.. code-block:: bash + + $ conan install . -o *:shared=True + + +Custom configuration +-------------------- + +As commented above, the Conan ``conf`` configuration system is intended to tune some of the tools and behaviors, but without really affecting the resulting package binaries. Some typical ``conf`` items are activating parallel builds, configuring "retries" when uploading to servers, or changing the CMake generator. +Read more about :ref:`the Conan configuration system in this section`. + +There is also the possibility to define ``user.xxxx:conf=value`` for user-defined configuration, that in the same spirit as core and tools built-in configurations, do not affect the ``package_id`` of binaries. + +But there might be some special situations in which it is really desired that some ``conf`` defines different ``package_ids``, creating different package binaries. It is possible to do this in two different places: + +- Locally, in the recipe's ``package_id`` method, via the ``self.info.conf`` attribute: + + .. code-block:: python + + def package_id(self): + # We can get the value from the actual current conf value, or define a new value + value = self.conf.get("user.myconf:myitem") + # This ``self.info.conf`` will become part of the ``package_id`` + self.info.conf.define("user.myconf:myitem", value) + +- Globally, with the ``tools.info.package_id:confs`` configuration, receiving as argument a list of existing configuration to be part of the package ID, so you can define in profiles: + + .. code-block:: ini + + tools.info.package_id:confs=["tools.build:cxxflags", ...] + + The value of the ``package_id`` will contain the value provided in the ``tools.build:cxxflags`` and other configurations. Note that this value is managed as a string, changing the string, will produce a different result and a different ``package_id``, so if this approach is used, it is very important to be very consistent with the provided values for different configurations like ``tools.build:cxxflags``. + + It is also possible to use regex expressions to match several ``confs``, instead of listing all of them, for example ``.*cmake`` could match any configuration that contains "cmake" in its name (not that this is recommended, see best practices below). + +.. note:: + + **Best practices** + + In general, defining variability of binaries ``package_id`` via ``conf`` should be reserved for special situations and always managed with care. Passing many different ``confs`` to the ``tools.info.package_id:confs`` can easily result in issues like missing binaries or unnecessarily building too many binaries. If that is the case, consider building higher level abstraction over your binaries with new custom settings or options. + + +Cross build target settings +--------------------------- + +The ``self.settings_target`` is a ``conanfile.py`` attribute that becomes relevant in cross-compilation scenarios for the ``tool_requires`` tools in the "build" context. When we have a ``tool_requires`` like CMake, lets say the ``cmake/3.25.3``, the package binary is independent of the possible platform that cross-compiling will target, it is the same ``cmake`` executable for all different target platforms. The ``settings`` for a cross-building from Windows-X64 to Linux-armv8 scenario for the ``cmake`` conanfile recipe would be: + +- ``self.settings``: The settings where the current ``cmake/3.25.3`` will run. As it is a tool-require, it will run in the Windows machine, so ``self.settings.os = Windows`` and ``self.settings.arch = x86_64``. +- ``self.settings_build``: The settings of the current build machine that would build this package if necessary. This is also the Windows-x64 machine, so ``self.settings_build.os = Windows`` and ``self.settings_build.arch = x86_64`` too. +- ``self.settings_target``: The settings that the current application outcome will target. In this case it will be ``self.settings_target.os = Linux`` and ``self.settings_target.arch = armv8`` + +In the ``cmake`` package scenario, as we pointed out, the target is irrelevant. It is not used in the ``cmake`` conanfile recipe at all, and it doesn't affect the ``package_id`` of the ``cmake`` binary package. + +But there are situations when the binary package can be different based on the target platform. For example a cross-compiler ``gcc`` that has a different ``gcc`` executable based on the target it will compile for. This is typical in the GNU ecosystem where we can find ``arm-gcc`` toolchains, for example, specific for a given architecture. +This scenario can be reflected by Conan, extending the ``package_id`` with the value of these ``settings_target``: + +.. code-block:: python + + def package_id(self): + self.info.settings_target = self.settings_target + # If we only want the ``os`` and ``arch`` settings, then we remove the other: + self.info.settings_target.rm_safe("compiler") + self.info.settings_target.rm_safe("build_type") diff --git a/2.1/_sources/reference/binary_model/package_id.rst.txt b/2.1/_sources/reference/binary_model/package_id.rst.txt new file mode 100644 index 000000000000..c5f807381a62 --- /dev/null +++ b/2.1/_sources/reference/binary_model/package_id.rst.txt @@ -0,0 +1,109 @@ +How the ``package_id`` is computed +================================== + +Let's take some package and list its binaries, for example: + +.. code-block:: bash + :emphasize-lines: 8,19 + + $ conan list zlib/1.2.13:* -r=conancenter + + zlib + zlib/1.2.13 + revisions + 97d5730b529b4224045fe7090592d4c1 (2023-08-22 02:51:57 UTC) + packages + d62dff20d86436b9c58ddc0162499d197be9de1e # package_id + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.version: 13 + os: Macos + options + fPIC: True + shared: False + abe5e2b04ea92ce2ee91bc9834317dbe66628206 # package_id + info + settings + arch: x86_64 + build_type: Release + compiler: gcc + compiler.version: 11 + os: Linux + options + shared: True + + +We can see several binaries for the latest recipe revision of ``zlib/1.2.13``. Every binary is identified by its own ``package_id``, and below it we can see some information for that binary under ``info``. This information is the one used to compute the ``package_id``. Every time something changes in this information, like the architecture, or being a static or a shared library, a new ``package_id`` is computed because it represents a different binary. + +.. image:: /images/conan_package_id.png + :width: 680 px + :align: center + +The ``package_id`` is computed as the sha1 hash of the ``conaninfo.txt`` file, containing the ``info`` displayed above. It is relatively easy to display such file: + +.. code-block:: bash + + $ conan install --requires=zlib/1.2.13 --build=missing + # Use the listed in the install + $ conan cache path zlib/1.2.13: + # cat the conaninfo.txt in the returned path + $ cat /conaninfo.txt + [settings] + arch=x86_64 + build_type=Release + compiler=msvc + compilerruntime=dynamic + compilerruntime_type=Release + compiler.version=193 + os=Windows + [options] + shared=False + $ sha1sum /conaninfo.txt + # Should be the "package_id"! + +The ``package_id`` is the sha1 checksum of the ``conaninfo.txt`` file inside the package. You can validate it with the ``sha1sum`` utility. + + +If now we have a look to the binaries of ``openssl`` we can see something like: + + + +.. code-block:: bash + :emphasize-lines: 8,20,21 + + $ conan list openssl/3.1.2:* -r=conancenter + conancenter + openssl + openssl/3.1.2 + revisions + 8879e931d726a8aad7f372e28470faa1 (2023-09-13 18:52:54 UTC) + packages + 0348efdcd0e319fb58ea747bb94dbd88850d6dd1 # package_id + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.version: 13 + os: Macos + options + 386: False + ... + shared: True + requires + zlib/1.3.Z + +We see now that the ``conaninfo.txt`` contains a new section the ``requires`` section. +This happens because ``openssl`` depends on ``zlib``, and due to the C and C++ compilation model, the dependencies can affect the binaries that use them. Some examples are when using inline or templates from ``#include`` header files of the dependency. + +Expanding the image above: + +.. image:: /images/conan_package_id_full.png + :width: 680 px + :align: center + +As it can be seen, even if the ``settings`` and the ``options`` are the same, different binaries will be obtained if the dependencies versions change. +In the next section :ref:`how the versions affect the package_id ` is explained. diff --git a/2.1/_sources/reference/commands.rst.txt b/2.1/_sources/reference/commands.rst.txt new file mode 100644 index 000000000000..98568dcb2c88 --- /dev/null +++ b/2.1/_sources/reference/commands.rst.txt @@ -0,0 +1,93 @@ +.. _reference_commands: + +Commands +======== + +This section describe the Conan built-in commands, like ``conan install`` or ``conan search``. + +It is also possible to create user custom commands, visit :ref:`custom commands reference ` +and these :ref:`custom command examples ` + + +**Consumer commands:** + +.. toctree:: + :caption: Consumer commands + :maxdepth: 1 + :hidden: + + commands/cache + commands/config + commands/graph + commands/inspect + commands/install + commands/list + commands/lock + commands/profile + commands/remove + commands/remote + commands/search + commands/version + +- :doc:`conan cache `: Return the path of recipes and packages in the cache +- :doc:`conan config `: Manage Conan configuration (remotes, settings, plugins, etc) +- :doc:`conan graph `: Obtain information about the dependency graph without fetching binaries +- :doc:`conan inspect `: Inspect a conanfile.py to return the public fields +- :doc:`conan install `: Install dependencies +- :doc:`conan list `: List recipes, revisions and packages in the local cache or in remotes +- :doc:`conan lock `: Create and manage lockfiles +- :doc:`conan profile `: Display and manage profile files +- :doc:`conan remove `: Remove packages from the local cache or from remotes +- :doc:`conan remote `: Add, remove, login/logout and manage remote server +- :doc:`conan search `: Search packages matching a name +- :doc:`conan version `: Give information about the Conan client version + + +**Creator commands:** + +.. toctree:: + :caption: Creator commands + :maxdepth: 1 + :hidden: + + commands/build + commands/create + commands/download + commands/editable + commands/export + commands/export-pkg + commands/new + commands/source + commands/test + commands/upload + +- :doc:`conan build `: Install package and call its build method +- :doc:`conan create `: Create a package from a recipe +- :doc:`conan download `: Download (without install) a single conan package from a remote server. +- :doc:`conan editable `: Allows working with a package in user folder +- :doc:`conan export `: Export a recipe to the Conan package cache +- :doc:`conan export-pkg `: Create a package directly from pre-compiled binaries +- :doc:`conan new `: Create a new recipe from a predefined template +- :doc:`conan source `: Calls the source() method +- :doc:`conan test `: Test a package +- :doc:`conan upload `: Upload packages from the local cache to a specified remote + + +Command formatters +------------------ + +Almost all the commands have the parameter ``--format xxxx`` which is used to apply an output conversion. +The command formatters help users see the command output in a different way that could fit better with their needs. +Here, there are only some of the most important ones whose details are worthy of having a separate section. + + +.. toctree:: + :caption: Command formatters + :maxdepth: 1 + :hidden: + + commands/formatters/graph_info_json_formatter + + +- :doc:`graph-info formatter `: Show the graph information in JSON + format. It's used by several commands. diff --git a/2.1/_sources/reference/commands/build.rst.txt b/2.1/_sources/reference/commands/build.rst.txt new file mode 100644 index 000000000000..13a56a4205ae --- /dev/null +++ b/2.1/_sources/reference/commands/build.rst.txt @@ -0,0 +1,14 @@ +.. _reference_commands_build: + +conan build +=========== + +.. autocommand:: + :command: conan build -h + + +The ``conan build`` command installs the recipe specified in ``path`` and calls its ``build()`` method. + +.. seealso:: + + - Read the tutorial about the :ref:`local package development flow `. diff --git a/2.1/_sources/reference/commands/cache.rst.txt b/2.1/_sources/reference/commands/cache.rst.txt new file mode 100644 index 000000000000..f924a8c45b29 --- /dev/null +++ b/2.1/_sources/reference/commands/cache.rst.txt @@ -0,0 +1,236 @@ +.. _reference_commands_cache: + +conan cache +=========== + +Perform file operations in the local cache (of recipes and/or packages). + + +conan cache path +---------------- + +.. autocommand:: + :command: conan cache path -h + + +The ``conan cache path`` returns the path in the cache of a given reference. Depending on the reference, it +could return the path of a recipe, or the path to a package binary. + +Let's say that we have created a package in our current cache with: + +.. code-block:: text + + $ conan new cmake_lib -d name=pkg -d version=0.1 + $ conan create . + ... + Requirements + pkg/0.1#cdc0d9d0e8f554d3df2388c535137d77 - Cache + + Requirements + pkg/0.1#cdc0d9d0e8f554d3df2388c535137d77:2401fa1d188d289bb25c37cfa3317e13e377a351 - Build + + +And now we are interested in obtaining the path where our ``pkg/0.1`` recipe ``conanfile.py`` has been exported: + +.. code-block:: text + + $ conan cache path pkg/0.1 + /p/5cb229164ec1d245/e + + $ ls /p/5cb229164ec1d245/e + conanfile.py conanmanifest.txt + +By default, if the recipe revision is not specified, it means the "latest" revision in the cache. This can +also be made explicit by the literal ``#latest``, and also any recipe revision can be explicitly defined, +these commands are equivalent to the above: + +.. code-block:: text + + $ conan cache path pkg/0.1#latest + /p/5cb229164ec1d245/e + + # The recipe revision might be different in your case. + # Check the "conan create" output to get yours + $ conan cache path pkg/0.1#cdc0d9d0e8f554d3df2388c535137d77 + /p/5cb229164ec1d245/e + + +Together with the recipe folder, there are a two other folders that are common to all the binaries +produced with this recipe: the "export_source" folder and the "source" folder. Both can be +obtained with: + +.. code-block:: text + + $ conan cache path pkg/0.1 --folder=export_source + /p/5cb229164ec1d245/es + + $ ls /p/5cb229164ec1d245/es + CMakeLists.txt include/ src/ + + $ conan cache path pkg/0.1 --folder=source + /p/5cb229164ec1d245/s + + $ ls /p/5cb229164ec1d245/s + CMakeLists.txt include/ src/ + + +In this case the contents of the "source" folder are identical to the ones of the "export_source" folder +because the recipe did not implement any ``source()`` method that could retrieve code or do any other operation +over the code, like applying patches. + +The recipe revision by default will be ``#latest``, this follows the same rules as above. + +Note that these two folders will not exist if the package has not been built from source, like when a precompiled +binary is retrieve from a server. + + +It is also possible to obtain the folders of the binary packages providing the ``package_id``: + +.. code-block:: text + + # Your package_id might be different, it depends on the platform + # Check the "conan create" output to obtain yours + $ conan cache path pkg/0.1:2401fa1d188d289bb25c37cfa3317e13e377a351 + /p/1cae77d6250c23b7/p + + $ ls /p/1cae77d6250c23b7/p + conaninfo.txt conanmanifest.txt include/ lib/ + +As above, by default it will resolve to the "latest" recipe revision and package revision. +The command above is equal to explicitly defining ``#latest`` or the exact revisions. +All the commands below are equivalent to the above one: + +.. code-block:: text + + $ conan cache path pkg/0.1#latest:2401fa1d188d289bb25c37cfa3317e13e377a351 + /p/1cae77d6250c23b7/p + + $ conan cache path pkg/0.1#latest:2401fa1d188d289bb25c37cfa3317e13e377a351#latest + /p/1cae77d6250c23b7/p + + $ conan cache path pkg/0.1#cdc0d9d0e8f554d3df2388c535137d77:2401fa1d188d289bb25c37cfa3317e13e377a351 + /p/1cae77d6250c23b7/p + + +It is possible to access the "build" folder with all the temporary build artifacts: + +.. code-block:: text + + $ conan cache path pkg/0.1:2401fa1d188d289bb25c37cfa3317e13e377a351 --folder=build + /p/1cae77d6250c23b7/b + + ls -al /p/1cae77d6250c23b7/b + build/ CMakeLists.txt CMakeUserPresets.json conaninfo.txt include/ src/ + +Again, the "build" folder will only exist if the package was built from source. + + +.. note:: + + **Best practices** + + - This ``conan cache path`` command is intended for eventual inspection of the cache, but the cache + package storage must be considered **read-only**. Do not modify, change, remove or add files from the cache. + - If you are using this command to obtain the path to artifacts and then copying them, consider the usage of a ``deployer`` + instead. In the general case, extracting artifacts from the cache manually is discouraged. + - Developers can use the ``conan list ... --format=compact`` to get the full references in a compact way that can + be copied and pasted into the ``conan cache path`` command + + +conan cache clean +----------------- + +.. autocommand:: + :command: conan cache clean -h + + +This command will remove all temporary folders, along with the source, build and download folder +that Conan generates in its execution. It will do so for every matching reference passed in *pattern*, +unless a specific flag is supplied, in which case only the specified folders will be removed. + + +**Examples**: + + +- Remove all non-critical files: + + .. code-block:: text + + $ conan cache clean "*" + + +- Remove all temporary files: + + .. code-block:: text + + $ conan cache clean "*" --temp + + +- Remove the download folders for the ``zlib`` recipe: + + .. code-block:: text + + $ conan cache clean "zlib*" --download + + +- Remove everything but the download folder for the ``zlib`` recipe: + + .. code-block:: text + + $ conan cache clean "*" --source --build --temp + + +conan cache check-integrity +--------------------------- + +.. autocommand:: + :command: conan cache check-integrity -h + + +The ``conan cache check-integrity`` command checks the integrity of Conan packages in the +local cache. This means that it will throw an error if any file included in the +``conanmanifest.txt`` is missing or does not match the declared checksum in that file. + +For example, to verify the integrity of the whole Conan local cache, do: + +.. code-block:: text + + $ conan cache check-integrity "*" + mypkg/1.0: Integrity checked: ok + mypkg/1.0:454923cd42d0da27b9b1294ebc3e4ecc84020747: Integrity checked: ok + mypkg/1.0:454923cd42d0da27b9b1294ebc3e4ecc84020747: Integrity checked: ok + zlib/1.2.11: Integrity checked: ok + zlib/1.2.11:6fe7fa69f760aee504e0be85c12b2327c716f9e7: Integrity checked: ok + + +conan cache backup-upload +------------------------- + +.. autocommand:: + :command: conan cache backup-upload -h + + +The ``conan cache backup-upload`` will upload all source backups present in the local cache to the backup server, +(excluding those which have been fetched from the excluded urls listed in the ``core.sources:exclude_urls`` conf), +regardless of which package they belong to, if any. + + + +conan cache save +---------------- + +.. autocommand:: + :command: conan cache save -h + + +Read more in :ref:`devops_save_restore`. + + +conan cache restore +------------------- + +.. autocommand:: + :command: conan cache restore -h + + +Read more in :ref:`devops_save_restore`. diff --git a/2.1/_sources/reference/commands/config.rst.txt b/2.1/_sources/reference/commands/config.rst.txt new file mode 100644 index 000000000000..1b152f0655fe --- /dev/null +++ b/2.1/_sources/reference/commands/config.rst.txt @@ -0,0 +1,194 @@ +conan config +============ + +Manage the Conan configuration in the Conan home. + + +conan config home +----------------- + +.. autocommand:: + :command: conan config home -h + + +The ``conan config home`` command returns the path of the Conan home folder. + +.. code-block:: text + + $ conan config home + + /home/user/.conan2 + + +.. _reference_commands_conan_config_install: + +conan config install +-------------------- + +.. autocommand:: + :command: conan config install -h + + +The ``conan config install`` command is intended to install in the current home a common shared Conan +configuration, like the definitions of ``remotes``, ``profiles``, ``settings``, ``hooks``, ``extensions``, etc. + +The command can use as source any of the following: + +- A URL pointing to a zip archive containing the configuration files +- A git repository containing the files +- A local folder +- Just one file + +Files in the current Conan home will be replaced by the ones from the installation source. +All the configuration files can be shared and installed this way: + +- ``remotes.json`` for the definition of remotes +- Any custom profile files inside a ``profiles`` subfolder +- Custom ``settings.yml`` +- Custom ``global.conf`` +- All the extensions, including plugins, hooks. +- Custom user commands. + +This command reads a ``.conanignore`` file which, if present, filters which files and folders +are copied over to the user's Conan home folder. +This file uses `fnmatch `_ patterns +to match over the folder contents, excluding those entries that match from the config installation. +See `conan-io/command-extensions's .conanignore `_ for an example of such a file. + + +**Examples**: + +- Install the configuration from a URL: + + .. code-block:: text + + $ conan config install http://url/to/some/config.zip + + +- Install the configuration from a URL, but only getting the files inside a *origin* folder + inside the zip file, and putting them inside a *target* folder in the local cache: + + .. code-block:: text + + $ conan config install http://url/to/some/config.zip -sf=origin -tf=target + +- Install configuration from 2 different zip files from 2 different urls, using different source + and target folders for each one, then update all: + + .. code-block:: text + + $ conan config install http://url/to/some/config.zip -sf=origin -tf=target + $ conan config install http://url/to/some/config.zip -sf=origin2 -tf=target2 + $ conan config install http://other/url/to/other.zip -sf=hooks -tf=hooks + +- Install the configuration from a Git repository with submodules: + + .. code-block:: text + + $ conan config install http://github.com/user/conan_config/.git --args "--recursive" + + You can also force the git download by using :command:`--type git` (in case it is not deduced from the URL automatically): + + .. code-block:: text + + $ conan config install http://github.com/user/conan_config/.git --type git + +- Install from a URL skipping SSL verification: + + .. code-block:: text + + $ conan config install http://url/to/some/config.zip --verify-ssl=False + + This will disable the SSL check of the certificate. + +- Install a specific file from a local path: + + .. code-block:: text + + $ conan config install my_settings/settings.yml + +- Install the configuration from a local path: + + .. code-block:: text + + $ conan config install /path/to/some/config.zip + + +conan config list +----------------- + +.. autocommand:: + :command: conan config list -h + + +Displays all the Conan built-in configurations. There are 2 groups: + +- ``core.xxxx``: These can only be defined in ``global.conf`` and are used by Conan internally +- ``tools.xxxx``: These can be defined both in ``global.conf`` and profiles, and will be used by + recipes and tools used within recipes, like ``CMakeToolchain`` + + +.. autocommand:: + :command: conan config list + + +.. seealso:: + + - :ref:`Conan configuration files ` + + +conan config show +----------------- + +.. autocommand:: + :command: conan config show -h + + +Shows the values of the conf items that match the given pattern. + +For a *global.conf* consisting of + +.. code-block:: text + + tools.build:jobs=42 + tools.files.download:retry_wait=10 + tools.files.download:retry=7 + core.net.http:timeout=30 + core.net.http:max_retries=5 + zlib*/:tools.files.download:retry_wait=100 + zlib*/:tools.files.download:retry=5 + +You can get all the values: + +.. code-block:: text + + $ conan config show "*" + + core.net.http:max_retries: 5 + core.net.http:timeout: 30 + tools.files.download:retry: 7 + tools.files.download:retry_wait: 10 + tools.build:jobs: 42 + zlib*/:tools.files.download:retry: 5 + zlib*/:tools.files.download:retry_wait: 100 + +Or just those referring to the ``tools.files`` section: + +.. code-block:: text + + $ conan config show "*tools.files*" + + tools.files.download:retry: 7 + tools.files.download:retry_wait: 10 + zlib*/:tools.files.download:retry: 5 + zlib*/:tools.files.download:retry_wait: 100 + +Notice the first ``*`` in the pattern. This will match all the package patterns. +Removing it will make the command only show global confs: + +.. code-block:: text + + $ conan config show "tools.files*" + + tools.files.download:retry: 7 + tools.files.download:retry_wait: 10 diff --git a/2.1/_sources/reference/commands/create.rst.txt b/2.1/_sources/reference/commands/create.rst.txt new file mode 100644 index 000000000000..52eaccd07d06 --- /dev/null +++ b/2.1/_sources/reference/commands/create.rst.txt @@ -0,0 +1,63 @@ +conan create +============ + +.. autocommand:: + :command: conan create -h + + +The ``conan create`` command creates a package from the recipe specified in ``path``. + +This command will first :command:`export` the recipe to the local cache and then build +and create the package. If a ``test_package`` folder (you can change the folder name with +the ``-tf`` argument) is found, the command will run the consumer project to ensure that +the package has been created correctly. Check :ref:`testing Conan packages +` section to know more about how to test your Conan packages. + +.. tip:: + + Sometimes you want to **skip/disable the test stage**. In that case you can skip/disable + the test package stage by passing an empty value as the ``-tf`` argument: + + .. code-block:: bash + + $ conan create . --test-folder= + + +Using conan create with build requirements +------------------------------------------ + +The ``--build-require`` argument allows to create the package using the configuration and +settings of the "build" context, as it was a ``build_require``. This feature allows to +create packages in a way that is consistent with the way they will be used later. + +.. code-block:: bash + + $ conan create . --name=cmake --version=3.23.1 --build-require + + +Conan create output +------------------- + +The ``conan create ... --format=json`` creates a json output containing the full dependency graph information. +This json is the same as the one created with ``conan graph info`` (see the :ref:`graph info json format`) +with extended information about the binaries, like a more complete ``cpp_info`` field. +This resulting json is the dependency graph of the package recipe being created, excluding all the ``test_package`` and other possible dependencies of the ``test_package/conanfile.py``. These dependencies only exist in the ``test_package`` functionality, and as such, are not part of the "main" product or package. If you are interested in capturing the dependency graph including the ``test_package`` (most likely not necessary in most cases), then you can do it running the ``conan test`` command separately. + +The same happens for lockfiles created with ``--lockfile-out`` argument. The lockfile will only contain the created package and its transitive dependencies versions, but it will not contain the ``test_package`` or the transitive dependencies of the ``test_package/conanfile.py``. It is possible to capture a lockfile which includes those with the ``conan test`` command (though again, this might not be really necessary) + +.. note:: + + **Best practice** + + In general, having ``test_package/conanfile.py`` with dependencies other than the tested + one should be avoided. The ``test_package`` functionality should serve as a simple check + to ensure the package is correctly created. Adding extra dependencies to + ``test_package`` might indicate that the check is not straightforward or that its + functionality is being misused. If, for any reason, your ``test_package`` has additional + dependencies, you can control their build using the ``--build-test`` argument. + + +.. seealso:: + + - Read more about creating packages in the :ref:`dedicated + tutorial` diff --git a/2.1/_sources/reference/commands/download.rst.txt b/2.1/_sources/reference/commands/download.rst.txt new file mode 100644 index 000000000000..6c4bec0a2c9e --- /dev/null +++ b/2.1/_sources/reference/commands/download.rst.txt @@ -0,0 +1,82 @@ +.. _reference_commands_download: + +conan download +============== + +.. autocommand:: + :command: conan download -h + + +Downloads recipe and binaries to the local cache from the specified remote. + +.. note:: + + Please, be aware that :command:`conan download` unlike :command:`conan install`, will not + download any of the transitive dependencies of the downloaded package. + + +The ``conan download`` command can download packages to 1 server repository specified by the ``-r=myremote`` argument. + +It has 2 possible and mutually exclusive inputs: + +- The ``conan download `` pattern-based matching of recipes, with a pattern similar to the ``conan list ``. +- The ``conan download --list=`` that will upload the artifacts specified in the ``pkglist`` json file + + + +You can use patterns to download specific references just like in other commands like +:command:`conan list` (see the patterns documentation there :ref:`reference_commands_list`) or :command:`conan upload`: + +.. code-block:: bash + + # download latest revision and packages for all openssl versions in foo remote + $ conan download "openssl/*" -r foo + +.. note:: + + :command:`conan download` will download only the latest revision by default. If you want + to download more revisions other than the latest one you can use wildcards in the + revisions part of the reference pattern argument + +You may also just download recipes (in this case selecting all the revisions in the +pattern, not just the latest one): + +.. code-block:: bash + + # download all recipe revisions for zlib/1.2.13 + $ conan download "zlib/1.2.13#*" -r foo --only-recipe + + +If you just want to download the packages belonging to a specific setting, use the ``--package-query`` argument: + +.. code-block:: bash + + $ conan download "zlib/1.2.13#*" -r foo --package-query="os=Linux and arch=x86" + + +If the ``--format=json`` formatter is specified, the result will be a "PackageList", compatible with other Conan commands, for example the ``conan upload`` command, so it is possible to concatenate a ``download + upload``, using the generated json file. See the :ref:`Packages Lists examples`. + + +Downloading metadata +-------------------- + +The metadata files of the recipes and packages are not downloaded by default. It is possible to explicitly retrieve them with the ``conan download --metadata=xxx`` argument. +The main arguments are the same as above, and Conan will download the specified packages, or skip them if they are already in the cache: + +.. code-block:: bash + + $ conan download pkg/0.1 -r=default --metadata="*" + # will download pgkg/0.1 recipe with all the recipe metadata + # And also all package binaries (latest package revision) + # with all the binaries metadata + + +If only one or several metadata folders or sets of files are desired, it can also be specified: + + +.. code-block:: bash + + $ conan download pkg/0.1 -r=default --metadata="logs/*" --metadata="tests/*" + # Will download only the logs and tests metadata, but not other potential metadata files + +For more information see the :ref:`metadata section`. diff --git a/2.1/_sources/reference/commands/editable.rst.txt b/2.1/_sources/reference/commands/editable.rst.txt new file mode 100644 index 000000000000..b40e7646b710 --- /dev/null +++ b/2.1/_sources/reference/commands/editable.rst.txt @@ -0,0 +1,31 @@ +.. _reference_commands_editable: + +conan editable +============== + +Allow working with a package that resides in user folder. + +conan editable add +------------------ + +.. autocommand:: + :command: conan editable add -h + + +conan editable remove +--------------------- + +.. autocommand:: + :command: conan editable remove -h + + +conan editable list +------------------- + +.. autocommand:: + :command: conan editable list -h + + +.. seealso:: + + - Read the tutorial about editable packages :ref:`editable package`. diff --git a/2.1/_sources/reference/commands/export-pkg.rst.txt b/2.1/_sources/reference/commands/export-pkg.rst.txt new file mode 100644 index 000000000000..fa48fd474f49 --- /dev/null +++ b/2.1/_sources/reference/commands/export-pkg.rst.txt @@ -0,0 +1,21 @@ +.. _reference_commands_export-pkg: + +conan export-pkg +================ + +.. autocommand:: + :command: conan export-pkg -h + + +The ``conan export-pkg`` command creates a package binary directly from pre-compiled binaries in a user folder. This command can be useful in different cases: + +- When creating a package for some closed source or pre-compiled binaries provided by a vendor. In this case, it is not necessary that the ``conanfile.py`` recipe contains a ``build()`` method, and providing the ``package()`` and ``package_info()`` method are enough to package those pre-compiled binaries. In this case the ``build_policy = "never"`` could make sense to indicate it is not possible to ``conan install --build=this_pkg``, as it doesn't know how to build from sources when it is a dependency. +- When testing some recipe locally in the :ref:`local development flow`, it can be used to quickly put the locally built binaries in the cache to make them available to other packages for testing, without needing to go through a full ``conan create`` that would be slower. + +In general, it is expected that when ``conan export-pkg`` executes, the possible Conan dependencies that were necessary to build this package had already been installed via ``conan install``, so it is not necessary to download dependencies at ``export-pkg`` time. But if for some reason this is not the case, the command defines ``--remote`` and ``--no-remote`` arguments, similar to other commands, as well as the ``--skip-binaries`` optimization that could save some time installing dependencies binaries if they are not strictly necessary for the current ``export-pkg``. But this is the responsibility of the user, as it is possible that such binaries are actually necessary, for example, if a ``tool_requires = "cmake/x.y"`` is used and the ``package()`` method implements a ``cmake.install()`` call, this will definitely need the binaries for the dependencies installed in the current machine to execute. + + +.. seealso:: + + - Check the :ref:`JSON format output ` for this command. + - Read the tutorial about the :ref:`local package development flow `. diff --git a/2.1/_sources/reference/commands/export.rst.txt b/2.1/_sources/reference/commands/export.rst.txt new file mode 100644 index 000000000000..4be70816629d --- /dev/null +++ b/2.1/_sources/reference/commands/export.rst.txt @@ -0,0 +1,19 @@ +conan export +============ + +.. autocommand:: + :command: conan export -h + + +The ``conan export`` command exports the recipe specified in ``path`` to the Conan package cache. + + +Output Formats +-------------- + +The :command:`conan export` command accepts two types of formats for the ``--format`` argument: + +* ``json``: Creates a JSON file containing the information of the exported recipe reference. +* ``pkglist``: Generates a JSON file in the :ref:`pkglist` + format, which can be utilized as input for various commands such as :command:`upload`, + :command:`download`, and :command:`remove`. diff --git a/2.1/_sources/reference/commands/formatters/graph_info_json_formatter.rst.txt b/2.1/_sources/reference/commands/formatters/graph_info_json_formatter.rst.txt new file mode 100644 index 000000000000..fe8f645a971d --- /dev/null +++ b/2.1/_sources/reference/commands/formatters/graph_info_json_formatter.rst.txt @@ -0,0 +1,265 @@ +.. _reference_commands_graph_info_json_format: + +Formatter: Graph-info JSON +========================== + +This section is aimed to show one example of the JSON format output when using any of these commands: + + * ``conan graph info xxxx --format=json`` + * ``conan create xxxx --format=json`` + * ``conan install xxxx --format=json`` + * ``conan export-pkg xxxx --format=json`` + + +The output shows the graph information processed by Conan in each command. + +.. warning:: + + This json output is **experimental** and subject to change. + + +The JSON output generated by :command:`conan graph info --require=zlib/1.2.11 -r=conancenter --format=json > graph.json` +for instance: + +.. code-block:: json + :caption: **graph.json** + + { + "graph": { + "nodes": { + "0": { + "ref": "conanfile", + "id": "0", + "recipe": "Cli", + "package_id": null, + "prev": null, + "rrev": null, + "rrev_timestamp": null, + "prev_timestamp": null, + "remote": null, + "binary_remote": null, + "build_id": null, + "binary": null, + "invalid_build": false, + "info_invalid": null, + "name": null, + "user": null, + "channel": null, + "url": null, + "license": null, + "author": null, + "description": null, + "homepage": null, + "build_policy": null, + "upload_policy": null, + "revision_mode": "hash", + "provides": null, + "deprecated": null, + "win_bash": null, + "win_bash_run": null, + "default_options": null, + "options_description": null, + "version": null, + "topics": null, + "package_type": "unknown", + "settings": { + "os": "Macos", + "arch": "x86_64", + "compiler": "apple-clang", + "compiler.cppstd": "gnu17", + "compiler.libcxx": "libc++", + "compiler.version": "12.0", + "build_type": "Release" + }, + "options": {}, + "options_definitions": {}, + "generators": [], + "python_requires": null, + "system_requires": {}, + "recipe_folder": null, + "source_folder": null, + "build_folder": null, + "generators_folder": null, + "package_folder": null, + "cpp_info": { + "root": { + "includedirs": [ + "include" + ], + "srcdirs": null, + "libdirs": [ + "lib" + ], + "resdirs": null, + "bindirs": [ + "bin" + ], + "builddirs": null, + "frameworkdirs": null, + "system_libs": null, + "frameworks": null, + "libs": null, + "defines": null, + "cflags": null, + "cxxflags": null, + "sharedlinkflags": null, + "exelinkflags": null, + "objects": null, + "sysroot": null, + "requires": null, + "properties": null + } + }, + "conf_info": {}, + "label": "cli", + "dependencies": { + "1": { + "ref": "zlib/1.2.11", + "run": false, + "libs": true, + "skip": false, + "test": false, + "force": false, + "direct": true, + "build": false, + "transitive_headers": null, + "transitive_libs": null, + "headers": true, + "package_id_mode": null, + "visible": true + } + }, + "context": "host", + "test": false + }, + "1": { + "ref": "zlib/1.2.11#ffa77daf83a57094149707928bdce823", + "id": "1", + "recipe": "Cache", + "package_id": "d0599452a426a161e02a297c6e0c5070f99b4909", + "prev": "1440f4f447208c8e6808936b4c6ff282", + "rrev": "dc0e384f0551386cd76dc29cc964c95e", + "rrev_timestamp": 1703667991.3458598, + "prev_timestamp": 1703668372.8517942, + "remote": null, + "binary_remote": null, + "build_id": null, + "binary": "Missing", + "invalid_build": false, + "info_invalid": null, + "name": "zlib", + "user": null, + "channel": null, + "url": "https://github.com/conan-io/conan-center-index", + "license": "Zlib", + "author": null, + "description": "A Massively Spiffy Yet Delicately Unobtrusive Compression Library (Also Free, Not to Mention Unencumbered by Patents)", + "homepage": "https://zlib.net", + "build_policy": null, + "upload_policy": null, + "revision_mode": "hash", + "provides": null, + "deprecated": null, + "win_bash": null, + "win_bash_run": null, + "default_options": { + "shared": false, + "fPIC": true + }, + "options_description": null, + "version": "1.2.11", + "topics": [ + "zlib", + "compression" + ], + "package_type": "static-library", + "settings": { + "os": "Macos", + "arch": "x86_64", + "compiler": "apple-clang", + "compiler.cppstd": "gnu17", + "compiler.libcxx": "libc++", + "compiler.version": "12.0", + "build_type": "Release" + }, + "options": { + "fPIC": "True", + "shared": "False" + }, + "options_definitions": { + "shared": [ + "True", + "False" + ], + "fPIC": [ + "True", + "False" + ] + }, + "generators": [], + "python_requires": null, + "system_requires": {}, + "recipe_folder": "/Users/franchuti/.conan2/p/zlib774aa77541f8b/e", + "source_folder": null, + "build_folder": null, + "generators_folder": null, + "package_folder": null, + "cpp_info": { + "root": { + "includedirs": [ + "include" + ], + "srcdirs": null, + "libdirs": [ + "lib" + ], + "resdirs": null, + "bindirs": [ + "bin" + ], + "builddirs": null, + "frameworkdirs": null, + "system_libs": null, + "frameworks": null, + "libs": null, + "defines": null, + "cflags": null, + "cxxflags": null, + "sharedlinkflags": null, + "exelinkflags": null, + "objects": null, + "sysroot": null, + "requires": null, + "properties": null + } + }, + "conf_info": {}, + "label": "zlib/1.2.11", + "info": { + "settings": { + "os": "Macos", + "arch": "x86_64", + "compiler": "apple-clang", + "compiler.cppstd": "gnu17", + "compiler.libcxx": "libc++", + "compiler.version": "12.0", + "build_type": "Release" + }, + "options": { + "fPIC": "True", + "shared": "False" + } + }, + "dependencies": {}, + "context": "host", + "test": false + } + }, + "root": { + "0": "None" + }, + "overrides": {}, + "resolved_ranges": {}, + "replaced_requires": {} + } + } diff --git a/2.1/_sources/reference/commands/graph.rst.txt b/2.1/_sources/reference/commands/graph.rst.txt new file mode 100644 index 000000000000..0cb2a34d888f --- /dev/null +++ b/2.1/_sources/reference/commands/graph.rst.txt @@ -0,0 +1,14 @@ +conan graph +=========== + + +The ``conan graph`` command contains several subcommands that return information of a dependency graph +without needing to download the package binaries. + +.. toctree:: + :maxdepth: 1 + + conan graph info: Computes a dependency graph and displays information about it + conan graph build-order: Computes the detailed sequence of packages that need to be built from source + conan graph build-order-merge: Merge 2 existing build-order sequences into one + conan graph explain: Explain what is wrong with the dependency graph, showing missing binaries, closest alternatives, and why they do not match diff --git a/2.1/_sources/reference/commands/graph/build_order.rst.txt b/2.1/_sources/reference/commands/graph/build_order.rst.txt new file mode 100644 index 000000000000..581f30a7b898 --- /dev/null +++ b/2.1/_sources/reference/commands/graph/build_order.rst.txt @@ -0,0 +1,189 @@ +conan graph build-order +======================= + +.. autocommand:: + :command: conan graph build-order -h + + +The ``conan graph build-order`` command computes the build order of the dependency graph for the recipe specified in ``path`` or in ``--requires/--tool-requires``. + +There are 2 important arguments that affect how this build order is computed: + +- The ``--order-by`` argument can take 2 values ``recipe`` and ``configuration``, depending how we want to + structure and parallelize our CI. +- The ``--reduce`` argument will strip all packages in the order that doesn't need to be built from source. + +By default, the ``conan graph build-order`` will return the order for the full dependency graph, and it will annotate +in each element what needs to be done, for example ``"binary": "Cache"`` if the binary is already in the Conan Cache +and doesnt need to be built from source, and ``"binary": "Build"``, if it needs to be built from source. +Having the full order is necessary if we want to ``conan graph build-order-merge`` several build-orders into a single +one later, because having the full information allows to preserve the relative order that would otherwise be lost and +broken. +Consequently, the ``--reduce`` argument should only be used when we are directly going to use the result to do the +build, but not if we plan to later do a merge of the resulting build-order with other ones. + + +Let's consider installing `libpng` and wanting to see the build order for this requirement ordered by recipe: + +.. warning:: + + Please be aware that starting with Conan 2.1.0, using the `--order-by` argument is + recommended, and its absence is deprecated. This argument will be removed in the near + future. It is maintained for backward compatibility. Note that the JSON output will + differ if you use the `--order-by` argument, changing from a simple list to a + dictionary with extended information. + + +.. code-block:: text + + $ conan graph build-order --requires=libpng/1.5.30 --format=json --order-by=recipe + ... + ======== Computing the build order ======== + { + "order_by": "recipe", + "reduced": false, + "order": [ + [ + { + "ref": "zlib/1.3#06023034579559bb64357db3a53f88a4", + "depends": [], + "packages": [ + [ + { + "package_id": "d62dff20d86436b9c58ddc0162499d197be9de1e", + "prev": "54b9c3efd9ddd25eb6a8cbf01860b499", + "context": "host", + "binary": "Cache", + "options": [], + "filenames": [], + "depends": [], + "overrides": {}, + "build_args": null + } + ] + ] + } + ], + [ + { + "ref": "libpng/1.5.30#ed8593b3f837c6c9aa766f231c917a5b", + "depends": [ + "zlib/1.3#06023034579559bb64357db3a53f88a4" + ], + "packages": [ + [ + { + "package_id": "60778dfa43503cdcda3636d15124c19bf6546ae3", + "prev": "ad092d2e4aebcd9d48a5b1f3fd51ba9a", + "context": "host", + "binary": "Download", + "options": [], + "filenames": [], + "depends": [], + "overrides": {}, + "build_args": null + } + ] + ] + } + ] + ] + } + + +Firstly, we can see the `zlib` package, as `libpng` depends on it. The output is sorted by +recipes as we passed with the `--order-by` argument; however, we might prefer to see it +sorted by configurations instead. For that purpouse use the `--order-by` argument with +value `configuration`. + +.. code-block:: text + + $ conan graph build-order --requires=libpng/1.5.30 --format=json --order-by=configuration + ... + ======== Computing the build order ======== + { + "order_by": "configuration", + "reduced": false, + "order": [ + [ + { + "ref": "zlib/1.3#06023034579559bb64357db3a53f88a4", + "pref": "zlib/1.3#06023034579559bb64357db3a53f88a4:d62dff20d86436b9c58ddc0162499d197be9de1e#54b9c3efd9ddd25eb6a8cbf01860b499", + "package_id": "d62dff20d86436b9c58ddc0162499d197be9de1e", + "prev": "54b9c3efd9ddd25eb6a8cbf01860b499", + "context": "host", + "binary": "Cache", + "options": [], + "filenames": [], + "depends": [], + "overrides": {}, + "build_args": null + } + ], + [ + { + "ref": "libpng/1.5.30#ed8593b3f837c6c9aa766f231c917a5b", + "pref": "libpng/1.5.30#ed8593b3f837c6c9aa766f231c917a5b:60778dfa43503cdcda3636d15124c19bf6546ae3#ad092d2e4aebcd9d48a5b1f3fd51ba9a", + "package_id": "60778dfa43503cdcda3636d15124c19bf6546ae3", + "prev": "ad092d2e4aebcd9d48a5b1f3fd51ba9a", + "context": "host", + "binary": "Download", + "options": [], + "filenames": [], + "depends": [ + "zlib/1.3#06023034579559bb64357db3a53f88a4:d62dff20d86436b9c58ddc0162499d197be9de1e#54b9c3efd9ddd25eb6a8cbf01860b499" + ], + "overrides": {}, + "build_args": null + } + ] + ] + } + +If we now apply the ``--reduce``: + +.. code-block:: text + + $ conan graph build-order --requires=libpng/1.5.30 --reduce --format=json --order-by=configuration + ... + ======== Computing the build order ======== + { + "order_by": "configuration", + "reduced": false, + "order": [] + } + +As there are no binaries to build here, all binaries already exist. If we explicitly force to build some, +the result would be only those that are going to be built: + + +.. code-block:: text + + $ conan graph build-order --requires=libpng/1.5.30 --build="libpng/*" --reduce --format=json --order-by=configuration + ... + ======== Computing the build order ======== + { + "order_by": "configuration", + "reduced": false, + "order": [ + [ + { + "ref": "libpng/1.5.30#ed8593b3f837c6c9aa766f231c917a5b", + "pref": "libpng/1.5.30#ed8593b3f837c6c9aa766f231c917a5b:60778dfa43503cdcda3636d15124c19bf6546ae3#ad092d2e4aebcd9d48a5b1f3fd51ba9a", + "package_id": "60778dfa43503cdcda3636d15124c19bf6546ae3", + "prev": null, + "context": "host", + "binary": "Build", + "options": [], + "filenames": [], + "depends": [], + "overrides": {}, + "build_args": "--require=libpng/1.5.30 --build=libpng/1.5.30" + } + ] + ] + } + +Then it will contain exclusively the ``binary=Build`` nodes, but not the rest. +Note that it will also provide a ``build_args`` field with the arguments needed for a ``conan install `` to fire the build of this package +in the CI agent. diff --git a/2.1/_sources/reference/commands/graph/build_order_merge.rst.txt b/2.1/_sources/reference/commands/graph/build_order_merge.rst.txt new file mode 100644 index 000000000000..f027a0eb2e50 --- /dev/null +++ b/2.1/_sources/reference/commands/graph/build_order_merge.rst.txt @@ -0,0 +1,15 @@ +conan graph build-order-merge +============================= + +.. autocommand:: + :command: conan graph build-order-merge -h + + +As described in the ``conan graph build-order`` command, there are 2 types of order ``recipe`` and ``configuration``. +Only build-orders of the same type can be merged together, otherwise the command will return an error. + +Note that only build-orders that haven't been reduced with ``--reduce`` can be merged. + +The result of merging the different input files can be also reduced with the ``conan graph build-order-merge --reduce`` +argument, and the behavior will be the same, leave only the elements that need to be built from source. + \ No newline at end of file diff --git a/2.1/_sources/reference/commands/graph/explain.rst.txt b/2.1/_sources/reference/commands/graph/explain.rst.txt new file mode 100644 index 000000000000..090c2e7cc3d3 --- /dev/null +++ b/2.1/_sources/reference/commands/graph/explain.rst.txt @@ -0,0 +1,82 @@ +.. _reference_graph_explain: + +conan graph explain +=================== + +.. autocommand:: + :command: conan graph explain -h + +The ``conan graph explain`` tries to give a more detailed explanation for a package that might be missing with the configuration provided and show the differences between the expected binary package and the available ones. +It helps to understand what is missing from the package requested, whether it is different options, different settings or different dependencies. + +**Example**: + +Imagine that we want to install the `lib/1.0.0` that depends on `dep/2.0.0` but we don't have a binary yet, as the latest CI run only generated a binary for lib/1.0.0 using the previous version of `dep`. +When we try to install the refere `lib/1.0.0` it says: + +.. code-block:: text + + $ conan install --requires=lib/1.0.0 + ... + ERROR: Missing prebuilt package for 'lib/1.0.0' + +Now we can try to find a explanation for this: + +.. code-block:: text + + $ conan graph explain --requires=lib/1.0.0 + requires: dep/1.Y.Z + diff + dependencies + expected: dep/2.Y.Z + existing: dep/1.Y.Z + explanation: This binary has same settings and options, but different dependencies + +In the same way, it can report when a package has a different option value and the output is also available in JSON format: + +.. code-block:: text + + $conan graph explain --requires=lib/1.0.0 -o shared=True --format=json + ... + { + "closest_binaries": { + "lib/1.0.0": { + "revisions": { + "dc0e384f0551386cd76dc29cc964c95e": { + "timestamp": 1692672717.68, + "packages": { + "b647c43bfefae3f830561ca202b6cfd935b56205": { + "info": { + "settings": { + "arch": "x86_64", + "build_type": "Release", + "compiler": "gcc", + "compiler.version": "11", + "os": "Linux" + }, + "options": { + "shared": "False" + } + }, + "diff": { + "platform": {}, + "options": { + "expected": [ + "shared=True" + ], + "existing": [ + "shared=False" + ] + }, + "settings": {}, + "dependencies": {}, + "explanation": "This binary was built with same settings but different options." + }, + "remote": "conancenter" + } + } + } + } + } + } + } diff --git a/2.1/_sources/reference/commands/graph/info.rst.txt b/2.1/_sources/reference/commands/graph/info.rst.txt new file mode 100644 index 000000000000..c988c3cf7c9e --- /dev/null +++ b/2.1/_sources/reference/commands/graph/info.rst.txt @@ -0,0 +1,275 @@ +.. _reference_graph_info: + +conan graph info +================ + +.. autocommand:: + :command: conan graph info -h + + +The ``conan graph info`` command shows information about the dependency graph for the recipe specified in ``path``. + + +**Examples**: + +.. code-block:: bash + + $ conan graph info . + $ conan graph info myproject_folder + $ conan graph info myproject_folder/conanfile.py + $ conan graph info --requires=hello/1.0@user/channel + +The output will look like: + +.. code-block:: text + + $ conan graph info --require=binutils/2.38 -r=conancenter + + ... + + ======== Basic graph information ======== + conanfile: + ref: conanfile + id: 0 + recipe: Cli + package_id: None + prev: None + build_id: None + binary: None + invalid_build: False + info_invalid: None + revision_mode: hash + package_type: unknown + settings: + os: Macos + arch: armv8 + compiler: apple-clang + compiler.cppstd: gnu17 + compiler.libcxx: libc++ + compiler.version: 14 + build_type: Release + options: + system_requires: + recipe_folder: None + source_folder: None + build_folder: None + generators_folder: None + package_folder: None + cpp_info: + root: + includedirs: ['include'] + srcdirs: None + libdirs: ['lib'] + resdirs: None + bindirs: ['bin'] + builddirs: None + frameworkdirs: None + system_libs: None + frameworks: None + libs: None + defines: None + cflags: None + cxxflags: None + sharedlinkflags: None + exelinkflags: None + objects: None + sysroot: None + requires: None + properties: None + label: cli + context: host + test: False + requires: + 1: binutils/2.38#0dc90586530d3e194d01d17cb70d9461 + binutils/2.38#0dc90586530d3e194d01d17cb70d9461: + ref: binutils/2.38#0dc90586530d3e194d01d17cb70d9461 + id: 1 + recipe: Downloaded + package_id: 5350e016ee8d04f418b50b7be75f5d8be9d79547 + prev: None + build_id: None + binary: Invalid + invalid_build: False + info_invalid: cci does not support building binutils for Macos since binutils is degraded there (no as/ld + armv8 does not build) + url: https://github.com/conan-io/conan-center-index/ + license: GPL-2.0-or-later + description: The GNU Binutils are a collection of binary tools. + topics: ('gnu', 'ld', 'linker', 'as', 'assembler', 'objcopy', 'objdump') + homepage: https://www.gnu.org/software/binutils + revision_mode: hash + package_type: application + settings: + os: Macos + arch: armv8 + compiler: apple-clang + compiler.version: 14 + build_type: Release + options: + multilib: True + prefix: aarch64-apple-darwin- + target_arch: armv8 + target_os: Macos + target_triplet: aarch64-apple-darwin + with_libquadmath: True + system_requires: + recipe_folder: /Users/barbarian/.conan2/p/binut53bd9b3ee9490/e + source_folder: None + build_folder: None + generators_folder: None + package_folder: None + cpp_info: + root: + includedirs: ['include'] + srcdirs: None + libdirs: ['lib'] + resdirs: None + bindirs: ['bin'] + builddirs: None + frameworkdirs: None + system_libs: None + frameworks: None + libs: None + defines: None + cflags: None + cxxflags: None + sharedlinkflags: None + exelinkflags: None + objects: None + sysroot: None + requires: None + properties: None + label: binutils/2.38 + context: host + test: False + requires: + 2: zlib/1.2.13#416618fa04d433c6bd94279ed2e93638 + zlib/1.2.13#416618fa04d433c6bd94279ed2e93638: + ref: zlib/1.2.13#416618fa04d433c6bd94279ed2e93638 + id: 2 + recipe: Cache + package_id: 76f7d863f21b130b4e6527af3b1d430f7f8edbea + prev: 866f53e31e2d9b04d49d0bb18606e88e + build_id: None + binary: Skip + invalid_build: False + info_invalid: None + url: https://github.com/conan-io/conan-center-index + license: Zlib + description: A Massively Spiffy Yet Delicately Unobtrusive Compression Library (Also Free, Not to Mention Unencumbered by Patents) + topics: ('zlib', 'compression') + homepage: https://zlib.net + revision_mode: hash + package_type: static-library + settings: + os: Macos + arch: armv8 + compiler: apple-clang + compiler.version: 14 + build_type: Release + options: + fPIC: True + shared: False + system_requires: + recipe_folder: /Users/barbarian/.conan2/p/zlibbcf9063fcc882/e + source_folder: None + build_folder: None + generators_folder: None + package_folder: None + cpp_info: + root: + includedirs: ['include'] + srcdirs: None + libdirs: ['lib'] + resdirs: None + bindirs: ['bin'] + builddirs: None + frameworkdirs: None + system_libs: None + frameworks: None + libs: None + defines: None + cflags: None + cxxflags: None + sharedlinkflags: None + exelinkflags: None + objects: None + sysroot: None + requires: None + properties: None + label: zlib/1.2.13 + context: host + test: False + requires: + + +:command:`conan graph info` builds the complete dependency graph, like :command:`conan install` does. +The main difference is that it doesn't try to install or build the binaries, but the package recipes +will be retrieved from remotes if necessary. + +It is very important to note that the :command:`conan graph info` command outputs the dependency graph for a +given configuration (settings, options), as the dependency graph can be different for different +configurations. This means that the input to the :command:`conan graph info` command +is the same as :command:`conan install`, the configuration can be specified directly with settings and options, +or using profiles,and querying the graph of a specific recipe is possible by using the ``--requires`` flag as shown above. + + +You can additionally filter the output, both by filtering by fields (``--filter``) and by package (``--filter-package``). +For example, to get the options of zlib, the following command could be run: + +.. code-block:: text + + $ conan graph info --require=binutils/2.38 -r=conancenter --filter=options --package-filter="zlib*" + + ... + + ======== Basic graph information ======== + zlib/1.2.13#13c96f538b52e1600c40b88994de240f: + ref: zlib/1.2.13#13c96f538b52e1600c40b88994de240f + options: + fPIC: True + shared: False + + +You can generate a graph of your dependencies in ``json``, ``dot`` or ``html`` formats: + +Now, let's try the ``dot`` format for instance: + +.. code-block:: bash + :caption: **binutils/2.38 graph info to DOT** + + $ conan graph info --require=binutils/2.38 -r=conancenter --format=dot > graph.dot + +Which generates the following file: + +.. code-block:: dot + :caption: **graph.dot** + + digraph { + "cli" -> "binutils/2.38" + "binutils/2.38" -> "zlib/1.2.13" + } + +.. graphviz:: + + digraph { + "cli" -> "binutils/2.38" + "binutils/2.38" -> "zlib/1.2.13" + } + + +.. note:: + If using ``format=html``, the generated html contains links to a third-party resource, + the *vis.js* library with 2 files: *vis.min.js*, *vis.min.css*. + By default they are retrieved from Cloudfare. However, for environments without internet connection, + you'll need to create a template for the file and place it in ``CONAN_HOME/templates/graph.html``. + to point to a local version of these files: + + - *vis.min.js*: "https://cdnjs.cloudflare.com/ajax/libs/vis/4.18.1/vis.min.js" + - *vis.min.css*: "https://cdnjs.cloudflare.com/ajax/libs/vis/4.18.1/vis.min.css" + + You can use the template found in ``cli/formatters/graph/info_graph.html`` as a basis for your own. + + +.. seealso:: + + - Check the :ref:`JSON format output ` for this command. diff --git a/2.1/_sources/reference/commands/inspect.rst.txt b/2.1/_sources/reference/commands/inspect.rst.txt new file mode 100644 index 000000000000..4bc05cc8e45a --- /dev/null +++ b/2.1/_sources/reference/commands/inspect.rst.txt @@ -0,0 +1,147 @@ +.. _reference_commands_inspect: + +conan inspect +============= + +.. include:: ../../common/experimental_warning.inc + +.. autocommand:: + :command: conan inspect -h + + +The :command:`conan inspect` command shows the public attributes of any recipe (`conanfile.py`) as follows: + +.. code-block:: text + + $ conan inspect . + default_options: + shared: False + fPIC: True + neon: True + msa: True + sse: True + vsx: True + api_prefix: + description: libpng is the official PNG file format reference library. + generators: [] + homepage: http://www.libpng.org + label: + license: libpng-2.0 + name: libpng + options: + api_prefix: + fPIC: True + msa: True + neon: True + shared: False + sse: True + vsx: True + options_definitions: + shared: ['True', 'False'] + fPIC: ['True', 'False'] + neon: ['True', 'check', 'False'] + msa: ['True', 'False'] + sse: ['True', 'False'] + vsx: ['True', 'False'] + api_prefix: ['ANY'] + package_type: None + requires: [] + revision_mode: hash + settings: ['os', 'arch', 'compiler', 'build_type'] + topics: ['png', 'graphics', 'image'] + url: https://github.com/conan-io/conan-center-index + + +``conan inspect`` evaluates recipe methods such as ``set_name()`` and ``set_version()``, +and is capable of resolving ``python_requires`` dependencies (which can be locked with the ``--lockfile`` argument), +so its base methods will also be properly executed. + +.. note:: + The ``--remote`` argument is used *only* for fetching remote ``python_requires`` in cases where they are needed, + **not** to inspect recipes from a remote. Use :ref:`conan graph info` for such cases. + + +The :command:`conan inspect ... --format=json` returns a JSON output format in ``stdout`` (which can be redirected to a file) with the following structure: + +.. code-block:: text + + $ conan inspect . --format=json + { + "name": "libpng", + "url": "https://github.com/conan-io/conan-center-index", + "license": "libpng-2.0", + "description": "libpng is the official PNG file format reference library.", + "homepage": "http://www.libpng.org", + "revision_mode": "hash", + "default_options": { + "shared": false, + "fPIC": true, + "neon": true, + "msa": true, + "sse": true, + "vsx": true, + "api_prefix": "" + }, + "topics": [ + "png", + "graphics", + "image" + ], + "package_type": "None", + "settings": [ + "os", + "arch", + "compiler", + "build_type" + ], + "options": { + "api_prefix": "", + "fPIC": "True", + "msa": "True", + "neon": "True", + "shared": "False", + "sse": "True", + "vsx": "True" + }, + "options_definitions": { + "shared": [ + "True", + "False" + ], + "fPIC": [ + "True", + "False" + ], + "neon": [ + "True", + "check", + "False" + ], + "msa": [ + "True", + "False" + ], + "sse": [ + "True", + "False" + ], + "vsx": [ + "True", + "False" + ], + "api_prefix": [ + "ANY" + ] + }, + "generators": [], + "requires": [], + "source_folder": null, + "build_folder": null, + "generators_folder": null, + "package_folder": null, + "label": "" + } + +.. note:: + ``conan inspect`` does not list any requirements listed in the ``requirements()`` method, + only those present in the ``requires`` attribute will be shown. diff --git a/2.1/_sources/reference/commands/install.rst.txt b/2.1/_sources/reference/commands/install.rst.txt new file mode 100644 index 000000000000..b36b71dddad4 --- /dev/null +++ b/2.1/_sources/reference/commands/install.rst.txt @@ -0,0 +1,221 @@ +.. _reference_commands_install: + +conan install +============= + +.. autocommand:: + :command: conan install -h + + +The ``conan install`` command is one of the main Conan commands, and it is used to resolve and install dependencies. + +This command does the following: + +- Compute the whole dependency graph, for the current configuration defined by settings, options, profiles and configuration. + It resolves version ranges, transitive dependencies, conditional requirements, etc, to build the dependency graph. +- Evaluate the existence of binaries for every package in the graph, whether or not there are precompiled binaries to download, or if + they should be built from sources (as directed by the ``--build`` argument). If binaries are missing, it will not recompute + the dependency graph to try to fallback to previous versions that contain binaries for that configuration. If a certain + dependency version is desired, it should be explicitly required. +- Download precompiled binaries, or build binaries from sources in the local cache, in the right order for the dependency graph. +- Create the necessary files as requested by the "generators", so build systems and other tools can locate the locally installed dependencies +- Optionally, execute the desired ``deployers``. + + +.. seealso:: + + - Check the :ref:`JSON format output ` for this command. + + +Conanfile path or --requires +---------------------------- + +The ``conan install`` command can use 2 different origins for information. The first one is using a local ``conanfile.py`` +or ``conanfile.txt``, containing definitions of the dependencies and generators to be used. + +.. code-block:: text + + $ conan install . # there is a conanfile.txt or a conanfile.py in the cwd + $ conan install conanfile.py # also works, direct reference file + $ conan install myconan.txt # explicit custom name + $ conan install myfolder # there is a conanfile in "myfolder" folder + + +Even if it is possible to use a custom name, in the general case, it is recommended to use the default ``conanfile.py`` +name, located in the repository root, so users can do a straightforward ``git clone ... `` + ``conan install .`` + + +The other possibility is to not have a ``conanfile`` at all, and define the requirements to be installed directly in the +command line: + +.. code-block:: text + + # Install the zlib/1.2.13 library + $ conan install --requires=zlib/1.2.13 + # Install the zlib/1.2.13 and bzip2/1.0.8 libraries + $ conan install --requires=zlib/1.2.13 --requires=bzip2/1.0.8 + # Install the cmake/3.23.5 and ninja/1.11.0 tools + $ conan install --tool-requires=cmake/3.23.5 --tool-requires=ninja/1.11.0 + # Install the zlib/1.2.13 library and ninja/1.11.0 tool + $ conan install --requires=zlib/1.2.13 --tool-requires=ninja/1.11.0 + + +In the general case, it is recommended to use a ``conanfile`` instead of defining things in the command line. + + +.. _reference_commands_install_composition: + +Profiles, Settings, Options, Conf +--------------------------------- + +There are several arguments that are used to define the effective profiles that will be used, both for the "build" +and "host" contexts. + +By default the arguments refer to the "host" context, so ``--settings:host, -s:h`` is totally equivalent to +``--settings, -s``. Also, by default, the ``conan install`` command will use the ``default`` profile both for the +"build" and "host" context. That means that if a profile with the "default" name has not been created, it will error. + +Multiple definitions of profiles can be passed as arguments, and they will compound from left to right (right has the +highest priority) + +.. code-block:: text + + # The values of myprofile3 will have higher priority + $ conan install . -pr=myprofile1 -pr=myprofile2 -pr=myprofile3 + +If values for any of ``settings``, ``options`` and ``conf`` are provided in the command line, they create a profile that +is composed with the other provided ``-pr`` (or the "default" one if not specified) profiles, with higher priority, +not matter what the order of arguments is. + +.. code-block:: text + + # the final "host" profile will always be build_type=Debug, even if "myprofile" + # says "build_type=Release" + $ conan install . -pr=myprofile -s build_type=Debug + + +.. _reference_commands_install_generators_deployers: + +Generators and deployers +------------------------ + +The ``-g`` argument allows to define in the command line the different built-in generators to be used: + +.. code-block:: text + + $ conan install --requires=zlib/1.2.13 -g CMakeDeps -g CMakeToolchain + +Note that in the general case, the recommended approach is to have the ``generators`` defined in the ``conanfile``, +and only for the ``--requires`` use case, it would be more necessary as command line argument. + +Generators are intended to create files for the build systems to locate the dependencies, while the ``deployers`` +main use case is to copy files from the Conan cache to user space, and performing any other custom operations over the dependency graph, +like collecting licenses, generating reports, deploying binaries to the system, etc. The syntax for deployers is: + +.. code-block:: text + + # does a full copy of the dependencies binaries to the current user folder + $ conan install . --deployer=full_deploy + + +There are 2 built-in deployers: + +- ``full_deploy`` does a complete copy of the dependencies binaries in the local folder, with a minimal folder + structure to avoid conflicts between files and artifacts of different packages +- ``direct_deploy`` does a copy of only the immediate direct dependencies, but does not include the transitive + dependencies. + + +Some generators might have the capability of redefining the target "package folder". That means that if some other +generator like ``CMakeDeps`` is used that is pointing to the packages, it will be pointing to the local deployed +copy, and not to the original packages in the Conan cache. See the full example in :ref:`examples_extensions_builtin_deployers_development`. + +It is also possible, and it is a powerful extension point, to write custom user deployers. +Read more about custom deployers in :ref:`reference_extensions_deployers`. + +It is possible to also invoke the package recipes ``deploy()`` method with the ``--deployer-package``: + +.. code-block:: bash + + # Execute deploy() method of every recipe that defines it + $ 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/* + +The ``--deployer-package`` argument is a pattern and accept multiple values, all package references matching any of the defined patterns will execute its ``deploy()`` method. The ``--deployer-folder`` argument will also affect the output location of this deployment. See the :ref:`deploy() method`. + +If multiple deployed packages deploy to the same location, it is their responsibility to not mutually overwrite their binaries if they have the same filenames. For example if multiple packages ``deploy()`` a file called "License.txt", each recipe is responsible for creating an intermediate folder with the package name and/or version that makes it unique, so other recipes ``deploy()`` method do not overwrite previously deployed "License.txt" files. + + +Name, version, user, channel +---------------------------- + +The ``conan install`` command provides optional arguments for ``--name, --version, --user, --channel``. These +arguments might not be necessary in the majority of cases. Never for ``conanfile.txt`` and for ``conanfile.py`` +only in the case that they are not defined in the recipe: + +.. code-block:: python + + from conan import ConanFile + from conan.tools.scm import Version + + class Pkg(ConanFile): + name = "mypkg" + + def requirements(self): + if Version(self.version) >= "3.23": + self.requires("...") + + + +.. code-block:: text + + # If we don't specify ``--version``, it will be None and it will fail + $ conan install . --version=3.24 + + +Lockfiles +--------- + +The ``conan install`` command has several arguments to load and produce lockfiles. +By default, if a ``conan.lock`` file is located beside the recipe or in the current working directory +if no path is provided, will be used as an input lockfile. + +Lockfiles are strict by default, that means that +if there is some ``requires`` and it cannot find a matching locked reference in the lockfile, it will error +and stop. For cases where it is expected that the lockfile will not be complete, as there might be new +dependencies, the ``--lockfile-partial`` argument can be used. + +By default, ``conan install`` will not generate an output lockfile, but if the ``--lockfile-out`` argument +is provided, pointing to a filename, like ``--lockfile-out=result.lock``, then a lockfile will be generated +from the current dependency graph. If ``--lockfile-clean`` argument is provided, all versions and revisions +not used in the current dependency graph will be dropped from the resulting lockfile. + +Let's say that we already have a ``conan.lock`` input lockfile, but we just added a new ``requires = "newpkg/1.0"`` +to a new dependency. We could resolve the dependencies, locking all the previously locked versions, while allowing +to resolve the new one, which was not previously present in the lockfile, and store it in a new location, or overwrite the existing lockfile: + +.. code-block:: text + + # --lockfile=conan.lock is the default, not necessary + $ conan install . --lockfile=conan.lock --lockfile-partial --lockfile-out=conan.lock + + +Also, it is likely that the majority of lockfile operations are better managed by the ``conan lock`` command. + + +Read more about lockfiles in :ref:`tutorial_consuming_packages_versioning_lockfiles`. + +.. seealso:: + + - Read the tutorial about the :ref:`local package development flow `. + + +Update +------ + +The ``conan install`` command has a ``--update`` argument that will force the re-evaluation of the selected items of the dependency graph, +allowing for the update of the dependencies to the latest version if using version ranges, or to the latest revision of the same version, +when those versions are not locked in the given lockfile. Passing ``--update`` will check every package in the dependency graph, +but it is also possible to pass a package name to the ``--update`` argument (it can be added to the command more than once with different names), +to only update those packages, which avoids the re-evaluation of the whole graph. diff --git a/2.1/_sources/reference/commands/list.rst.txt b/2.1/_sources/reference/commands/list.rst.txt new file mode 100644 index 000000000000..32cb34c4e4c6 --- /dev/null +++ b/2.1/_sources/reference/commands/list.rst.txt @@ -0,0 +1,408 @@ +.. _reference_commands_list: + +conan list +========== + +.. autocommand:: + :command: conan list -h + + +The ``conan list`` command can list recipes and packages from the local cache, from the +specified remotes or from both. This command uses a *reference pattern* as input. The +structure of this pattern is based on a complete Conan reference that looks like: + +``name/version@user/channel#rrev:pkgid#prev`` + +This pattern supports using ``*`` as wildcard as well as ``#latest`` to specify the latest revision +(though that might not be necessary in most cases, by default Conan will be listing the latest revisions). + +Using it you can list: + +* Recipe references (``name/version@user/channel``). +* Recipe revisions (``name/version@user/channel#rrev``). +* Package IDs and their configurations (``name/version@user/channel#rrev:pkgids``). +* Package revisions (``name/version@user/channel#rrev:pkgids#prev``). + +.. warning:: + + The json output of the ``conan list --format=json`` is in **preview**. + See :ref:`the Conan stability` section for more information. + + +Let's see some examples on how to use this pattern: + +Listing recipe references +------------------------- + +.. code-block:: text + :caption: *list all references on local cache* + + # Make sure to quote the argument + $ conan list "*" + Local Cache + hello + hello/2.26.1@mycompany/testing + hello/2.20.2@mycompany/testing + hello/1.0.4@mycompany/testing + hello/2.3.2@mycompany/stable + hello/1.0.4@mycompany/stable + string-view-lite + string-view-lite/1.6.0 + zlib + zlib/1.2.11 + + +.. code-block:: text + :caption: *list all versions of a reference* + + $ conan list zlib + Local Cache + zlib + zlib/1.2.11 + zlib/1.2.12 + + +As we commented, you can also use the ``*`` wildcard inside the reference you want to +search. + +.. code-block:: text + :caption: *list all versions of a reference, equivalent to the previous one* + + # Make sure to quote the argument + $ conan list "zlib/*" + Local Cache + zlib + zlib/1.2.11 + zlib/1.2.12 + +You can also use version ranges in the version field to define the versions you want: + +.. code-block:: text + :caption: *list version ranges* + + # Make sure to quote the argument + $ conan list "zlib/[<1.2.12]" -r=conancenter + Local Cache + zlib + zlib/1.2.11 + $ conan list "zlib/[>1.2.11]" -r=conancenter + Local Cache + zlib + zlib/1.2.12 + zlib/1.2.13 + +Use the pattern for searching only references matching a specific channel: + +.. code-block:: text + :caption: *list references with 'stable' channel* + + $ conan list "*/*@*/stable" + Local Cache + hello + hello/2.3.2@mycompany/stable + hello/1.0.4@mycompany/stable + +Use the ``...@`` pattern for searching only references that don't have *user* and *channel*: + +.. code-block:: text + :caption: *list references without user and channel* + + $ conan list "*/*@" + Local Cache + string-view-lite + string-view-lite/1.6.0 + zlib + zlib/1.2.11 + +Listing recipe revisions +------------------------ + +The shortest way of listing the latest recipe revision for a recipe is using the +``name/version@user/channel`` as the pattern: + +.. code-block:: text + :caption: *list latest recipe revision* + + $ conan list zlib/1.2.11 + Local Cache + zlib + zlib/1.2.11 + revisions + ffa77daf83a57094149707928bdce823 (2022-11-02 13:46:53 UTC) + +This is equivalent to specify explicitly that you want to list the latest recipe revision +using the ``#latest`` placeholder: + +.. code-block:: text + :caption: *list latest recipe revision* + + $ conan list zlib/1.2.11#latest + Local Cache + zlib + zlib/1.2.11 + revisions + ffa77daf83a57094149707928bdce823 (2022-11-02 13:46:53 UTC) + +To list all recipe revisions use the ``*`` wildcard: + +.. code-block:: text + :caption: *list all recipe revisions* + + $ conan list "zlib/1.2.11#*"" + Local Cache + zlib + zlib/1.2.11 + revisions + ffa77daf83a57094149707928bdce823 (2022-11-02 13:46:53 UTC) + 8b23adc7acd6f1d6e220338a78e3a19e (2022-10-19 09:19:10 UTC) + ce3665ce19f82598aa0f7ac0b71ee966 (2022-10-14 11:42:21 UTC) + 31ee767cb2828e539c42913a471e821a (2022-10-12 05:49:39 UTC) + d77ee68739fcbe5bf37b8a4690eea6ea (2022-08-05 17:17:30 UTC) + + +Listing package IDs +------------------- + +The shortest way of listing all the package IDs belonging to the latest recipe revision is +using ``name/version@user/channel:*`` as the pattern: + +.. code-block:: text + :caption: *list all package IDs for latest recipe revision* + + # Make sure to quote the argument + $ conan list "zlib/1.2.11:*" + Local Cache + zlib + zlib/1.2.11 + revisions + d77ee68739fcbe5bf37b8a4690eea6ea (2022-08-05 17:17:30 UTC) + packages + d0599452a426a161e02a297c6e0c5070f99b4909 + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.version: 12.0 + os: Macos + options + fPIC: True + shared: False + ebec3dc6d7f6b907b3ada0c3d3cdc83613a2b715 + info + settings + arch: x86_64 + build_type: Release + compiler: gcc + compiler.version: 11 + os: Linux + options + fPIC: True + shared: False + +.. note:: + + Here the ``#latest`` for the recipe revision is implicit, i.e., that pattern is + equivalent to ``zlib/1.2.11#latest:*`` + + +To list all the package IDs for all the recipe revisions use the ``*`` wildcard in the +revision ``#`` part: + +.. code-block:: text + :caption: *list all the package IDs for all the recipe revisions* + + # Make sure to quote the argument + $ conan list "zlib/1.2.11#*:*" + zlib + zlib/1.2.11 + revisions + d77ee68739fcbe5bf37b8a4690eea6ea (2022-08-05 17:17:30 UTC) + packages + d0599452a426a161e02a297c6e0c5070f99b4909 + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.version: 12.0 + os: Macos + options + fPIC: True + shared: False + e4e1703f72ed07c15d73a555ec3a2fa1 (2022-07-04 21:21:45 UTC) + packages + d0599452a426a161e02a297c6e0c5070f99b4909 + info + settings + arch: x86_64 + build_type: Release + compiler: apple-clang + compiler.version: 12.0 + os: Macos + options + fPIC: True + shared: False + + +Listing package revisions +------------------------- + +The shortest way of listing the latest package revision for a specific recipe revision and +package ID is using the pattern ``name/version@user/channel#rrev:pkgid`` + +.. code-block:: text + :caption: *list latest package revision for a specific recipe revision and package ID* + + $ conan list zlib/1.2.11#8b23adc7acd6f1d6e220338a78e3a19e:fdb823f07bc228621617c6397210a5c6c4c8807b + Local Cache + zlib + zlib/1.2.11 + revisions + 8b23adc7acd6f1d6e220338a78e3a19e (2022-08-05 17:17:30 UTC) + packages + fdb823f07bc228621617c6397210a5c6c4c8807b + revisions + 4834a9b0d050d7cf58c3ab391fe32e25 (2022-11-18 12:33:31 UTC) + + +To list all the package revisions for for the latest recipe revision: + +.. code-block:: text + :caption: *list all the package revisions for all package-ids the latest recipe revision* + + # Make sure to quote the argument + $ conan list "zlib/1.2.11:*#*" + Local Cache + zlib + zlib/1.2.11 + revisions + 6a6451bbfcb0e591333827e9784d7dfa (2022-12-29 11:51:39 UTC) + packages + b1d267f77ddd5d10d06d2ecf5a6bc433fbb7eeed + revisions + 67bb089d9d968cbc4ef69e657a03de84 (2022-12-29 11:47:36 UTC) + 5e196dbea832f1efee1e70e058a7eead (2022-12-29 11:47:26 UTC) + 26475a416fa5b61cb962041623748d73 (2022-12-29 11:02:14 UTC) + d15c4f81b5de757b13ca26b636246edff7bdbf24 + revisions + a2eb7f4c8f2243b6e80ec9e7ee0e1b25 (2022-12-29 11:51:40 UTC) + +.. note:: + + Here the ``#latest`` for the recipe revision is implicit, i.e., that pattern is + equivalent to ``zlib/1.2.11#latest:*#*`` + + +Listing graph artifacts +----------------------- + +When the ``conan list --graph=`` graph json file is provided, the command will list the binaries in it. +By default, it will list all recipes and binaries included in the dependency graph. But the ``--graph-recipes=`` +and ``--graph-binaries=`` allow specifying what artifacts have to be listed in the final result, some examples: + +- ``conan list --graph=graph.json --graph-binaries=build`` list exclusively the recipes and binaries that have been built from sources +- ``conan list --graph=graph.json --graph-recipes=*`` list exclusively the recipes, all recipes, but no binaries +- ``conan list --graph=graph.json --graph-binaries=download`` list exclusively the binaries that have been downloaded in the last ``conan create`` or ``conan install`` + + +List json output format +----------------------- + +.. note:: + + **Best practices** + + The text output in the terminal should never be parsed or relied on for automation, and + it is intended for human reading only. For any automation, the recommended way is using + the formatted output as *json* + +The ``conan list ... --format=json`` will return a json output in ``stdout`` (which can be redirected to a file) +with the following structure: + + +.. code-block:: text + + # Make sure to quote the argument + $ conan list "zlib/1.2.11:*#*" --format=json + { + "Local Cache": { + "zli/1.0.0": { + "revisions": { + "b58eeddfe2fd25ac3a105f72836b3360": { + "timestamp": "2023-01-10 16:30:27 UTC", + "packages": { + "9a4eb3c8701508aa9458b1a73d0633783ecc2270": { + "revisions": { + "d9b1e9044ee265092e81db7028ae10e0": { + "timestamp": "2023-01-10 22:45:49 UTC" + } + }, + "info": { + "settings": { + "os": "Linux" + } + } + }, + "ebec3dc6d7f6b907b3ada0c3d3cdc83613a2b715": { + "revisions": { + "d9b1e9044ee265092e81db7028ae10e0": { + "timestamp": "2023-01-10 22:45:49 UTC" + } + }, + "info": { + "settings": { + "os": "Windows" + } + } + } + } + } + } + } + } + } + + +List html output format +----------------------- + +The ``conan list ... --format=html`` will return a html output in ``stdout`` (which can be redirected to a file) +with the following structure: + +.. code-block:: text + + $ conan list "zlib/1.2.13#*:*#*" --format=html -c > list.html + +Here is the rendered generated HTML. + +.. image:: ../../images/conan-list-html.png + + +List compact output format +-------------------------- + +For developers, it can be convenient to use the ``--format=compact`` output, because it allows to copy and paste +full references into other commands (like for example ``conan cache path``): + +.. code-block:: text + + $ conan list "zlib/1.2.13:*" -r=conancenter --format=compact + conancenter + zlib/1.2.13 + zlib/1.2.13#97d5730b529b4224045fe7090592d4c1%1692672717.68 (2023-08-22 02:51:57 UTC) + zlib/1.2.13#97d5730b529b4224045fe7090592d4c1:d62dff20d86436b9c58ddc0162499d197be9de1e + settings: Macos, x86_64, Release, apple-clang, 13 + options(diff): fPIC=True, shared=False + zlib/1.2.13#97d5730b529b4224045fe7090592d4c1:abe5e2b04ea92ce2ee91bc9834317dbe66628206 + settings: Linux, x86_64, Release, gcc, 11 + options(diff): shared=True + zlib/1.2.13#97d5730b529b4224045fe7090592d4c1:ae9eaf478e918e6470fe64a4d8d4d9552b0b3606 + settings: Windows, x86_64, Release, msvc, dynamic, Release, 192 + options(diff): shared=True + ... + + +The ``--format=compact`` will show the list of values for ``settings``, and it will only show the differences ("diff") +for options, that is, it will compute the common denominator of options for all displayed packages, and will print +only those values that deviate from that common denominator. diff --git a/2.1/_sources/reference/commands/lock.rst.txt b/2.1/_sources/reference/commands/lock.rst.txt new file mode 100644 index 000000000000..b1ded5a17620 --- /dev/null +++ b/2.1/_sources/reference/commands/lock.rst.txt @@ -0,0 +1,24 @@ +conan lock +========== + +The ``conan lock`` command contains several subcommands. +In addition to these commands, most of the Conan commands that compute a graph, like ``create``, ``install``, +``graph``, can both receive lockfiles as input and produce lockfiles as output. + + +.. toctree:: + :maxdepth: 1 + :hidden: + :glob: + + lock/* + + +- :doc:`conan lock add `: Manually add items to a lockfile +- :doc:`conan lock remove `: Manually remove items from a lockfile +- :doc:`conan lock create `: Evaluates a dependency graph and save a lockfile +- :doc:`conan lock merge `: Merge several existing lockfiles into one. + + +.. autocommand:: + :command: conan lock -h diff --git a/2.1/_sources/reference/commands/lock/add.rst.txt b/2.1/_sources/reference/commands/lock/add.rst.txt new file mode 100644 index 000000000000..d90a6d7db306 --- /dev/null +++ b/2.1/_sources/reference/commands/lock/add.rst.txt @@ -0,0 +1,95 @@ +conan lock add +============== + +.. autocommand:: + :command: conan lock add -h + + +The ``conan lock add`` command is able to add a package version to an existing or new lockfile ``requires``, ``build_requires`` or ``python_requires``. + +For example, the following is able to create a lockfile (by default, named ``conan.lock``): + +.. code-block:: bash + + $ conan lock add --requires=pkg/1.1 --build-requires=tool/2.2 --python-requires=mypytool/3.3 + Generated lockfile: ...conan.lock + + $cat conan.lock + { + "version": "0.5", + "requires": [ + "pkg/1.1" + ], + "build_requires": [ + "tool/2.2" + ], + "python_requires": [ + "mypytool/3.3" + ] + } + + +The ``conan lock add`` command also allows to provide an existing lockfile as an input, +and it will add the arguments to the existing lockfile, maintaining the +package versions sorted: + +.. code-block:: bash + + $ conan lock add --build-requires=tool/2.3 --lockfile=conan.lock + Using lockfile: '.../conan.lock' + Generated lockfile: .../conan.lock + + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "pkg/1.1" + ], + "build_requires": [ + "tool/2.3", + "tool/2.2" + ], + "python_requires": [ + "mypytool/3.3" + ] + } + + +The ``conan lock add`` command does not perform any checking on the lockfile, the packages, the existence of packages, +the existence of package versions, or the existence of those packages in a given dependency graph, it is a basic manipulation of the json information. +When that lockfile is applied to resolve a dependency graph, it is possible that the added versions do not exist, +or do not resolve for the ``conanfile.py`` recipes defined version ranges. + +Moreover, the list of versions is still sorted. Adding an older version like ``tool/2.1`` to the previous lockfile +won't make that version being used automatically if the recipes contain the version range ``tool/[>=2.0 <3]``, because +the ``tool/2.2`` version is listed there and the range will resolve to it, not to the older ``tool/2.1``. + +Note that a lockfile created with ``conan lock add`` can be incomplete and not contain all necessary locked versions +that a full dependency graph would need. For those cases, recall that the ``--lockfile-partial`` argument can be applied. +Note also that if a ``conan.lock`` file exist in the current folder, Conan commands like ``conan install`` will automatically use it. +Please have a look to the :ref:`lockfiles tutorial`. + +If explicitly adding revisions, please recall that the revisions are timestamp sorted. If more than one revision exists in the lockfile, +it is mandatory to provide the timestamps of those revisions, so the sorting makes sense, which can be done with: + + +.. code-block:: bash + + $ conan lock add --requires=pkg/1.1#revision%timestamp + + +.. warning:: + + - It is forbidden to manually manipulate a Conan lockfile, changing the strict sorting of references, and that could result in + any arbitrary undefined behavior. + - Recall that it is not possible to ``conan lock add`` a version range. The version might be not fully complete (like not providing + the revision), but it must be an exact version. + + +.. note:: + + **Best practices** + + This command will not be necessary in many situations. The existing ``conan install``, ``conan create``, ``conan lock``, ``conan export``, + ``conan graph`` commands can directly update or produce new lockfiles with the new information of the packages they are creating, and + those new or updated lockfiles can be used to continue with the processing. diff --git a/2.1/_sources/reference/commands/lock/create.rst.txt b/2.1/_sources/reference/commands/lock/create.rst.txt new file mode 100644 index 000000000000..f421b063db0a --- /dev/null +++ b/2.1/_sources/reference/commands/lock/create.rst.txt @@ -0,0 +1,104 @@ +conan lock create +================= + +.. autocommand:: + :command: conan lock create -h + + +The ``conan lock create`` command creates a lockfile for the recipe or reference specified in ``path`` or ``--requires``. +This command will compute the dependency graph, evaluate which binaries do exist or need to be built, but it will +not try to install or build from source those binaries. In that regard, it is equivalent to the ``conan graph info`` command. +Most of the arguments accepted by this command are the same as ``conan graph info`` (and ``conan install``, ``conan create``), +because the ``conan lock create`` creates or update a lockfile for a given configuration. + +A lockfile can be created from scratch, computing a new dependency graph from a local conanfile, or from +requires, for example for this ``conanfile.txt``: + +.. code-block:: text + :caption: conanfile.txt + + [requires] + fmt/9.0.0 + + [tool_requires] + cmake/3.23.5 + +We can run: + +.. code-block:: bash + + $ conan lock create . + + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "fmt/9.0.0#ca4ae2047ef0ccd7d2210d8d91bd0e02%1675126491.773" + ], + "build_requires": [ + "cmake/3.23.5#5f184bc602682bcea668356d75e7563b%1676913225.027" + ], + "python_requires": [] + } + +``conan lock create`` accepts a ``--lockfile`` input lockfile (if a ``conan.lock`` default one is found, it will +be automatically used), and then it will add new information in the ``--lockfile-out`` (by default, also ``conan.lock``). +For example if we change the above ``conanfile.txt``, removing the ``tool_requires``, updating ``fmt`` to ``9.1.0`` +and adding a new dependency to ``zlib/1.2.13``: + +.. code-block:: text + :caption: conanfile.txt + + [requires] + fmt/9.1.0 + zlib/1.2.13 + + [tool_requires] + +We will see how ``conan lock create`` **extends** the existing lockfile with the new configuration, but it doesn't +remove unused versions or packages from it: + +.. code-block:: bash + + $ conan lock create . # will use the existing conan.lock as base, and rewrite it + # use --lockfile and --lockfile-out to change that behavior + + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "zlib/1.2.13#13c96f538b52e1600c40b88994de240f%1667396813.733", + "fmt/9.1.0#e747928f85b03f48aaf227ff897d9634%1675126490.952", + "fmt/9.0.0#ca4ae2047ef0ccd7d2210d8d91bd0e02%1675126491.773" + ], + "build_requires": [ + "cmake/3.23.5#5f184bc602682bcea668356d75e7563b%1676913225.027" + ], + "python_requires": [] + } + +This behavior is very important to be able to capture multiple different configurations (Linux/Windows, shared/static, +Debug/Release, etc) that might have different dependency graphs. See the :ref:`lockfiles tutorial`, +to read more about lockfiles for multiple configurations. + +If we want to trim unused versions and packages we can force it with the ``--lockfile-clean`` argument: + +.. code-block:: bash + + $ conan lock create . --lockfile-clean + # will use the existing conan.lock as base, and rewrite it, cleaning unused versions + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "zlib/1.2.13#13c96f538b52e1600c40b88994de240f%1667396813.733", + "fmt/9.1.0#e747928f85b03f48aaf227ff897d9634%1675126490.952" + ], + "build_requires": [], + "python_requires": [] + } + +.. seealso:: + + The :ref:`lockfiles tutorial section` has more examples and hands on + explanations of lockfiles. diff --git a/2.1/_sources/reference/commands/lock/merge.rst.txt b/2.1/_sources/reference/commands/lock/merge.rst.txt new file mode 100644 index 000000000000..b141fdf31da3 --- /dev/null +++ b/2.1/_sources/reference/commands/lock/merge.rst.txt @@ -0,0 +1,136 @@ +conan lock merge +================ + +.. autocommand:: + :command: conan lock merge -h + + +The ``conan lock merge`` command takes 2 or more lockfiles and aggregate them, producing one final lockfile. +For example, if we have 2 lockfiles ``lock1.lock`` and ``lock2.lock``, we can merge both in a final ``conan.lock`` one: + +.. code-block:: bash + + # we have 2 lockfiles lock1.lock and lock2.lock + $ conan lock add --requires=pkg/1.1 --lockfile-out=lock1.lock + $ cat lock1.lock + { + "version": "0.5", + "requires": [ + "pkg/1.1", + ], + "build_requires": [], + "python_requires": [] + } + + $ conan lock add --requires=other/2.1 --build-requires=tool/3.2 --lockfile-out=lock2.lock + $ cat lock2.lock + { + "version": "0.5", + "requires": [ + "other/2.1" + ], + "build_requires": [ + "tool/3.2" + ], + "python_requires": [] + } + + # we can merge both + $ conan lock merge --lockfile=lock1.lock --lockfile=lock2.lock + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "pkg/1.1", + "other/2.1" + ], + "build_requires": [ + "tool/3.2" + ], + "python_requires": [] + } + +Similar to the ``conan lock add`` command, the ``conan lock merge``: + +- Does keep strict sorting of the lists of versions +- It does not perform any kind of validation if the packages or versions exist or not, or if they belong to a given dependency graph +- It is a basic processing of the json files, aggregating them. +- It doesn't guarantee that the lockfile will be complete, might require ``--lockfile-partial`` if not +- Recipe revisions, if defined, must contain the timestamp to be sorted correctly. + + +.. warning:: + + - It is forbidden to manually manipulate a Conan lockfile, changing the strict sorting of references, and that could result in + any arbitrary undefined behavior. + - Recall that it is not possible to ``conan lock add`` a version range. The version might be not fully complete (like not providing + the revision), but it must be an exact version. + +.. seealso:: + + To better understand ``conan lock merge``, it is recommended to first understand lockfiles in general, + visit the :ref:`lockfiles tutorial` for a practical introduction to lockfiles. + + +This ``conan lock merge`` command can be useful to consolidate in a single lockfile when for some reasons there are several lockfiles +that have diverged. A use case would be to create a multi-configuration lockfile that contains all necessary locked versions for +all OSs (Linux, Windows, etc), even if there are conditional dependencies in the graph for the different OSs. At some point when +testing a new dependency version, for example, ``pkg/3.4`` new version, when previously ``pkg/3.3`` was already in the graph, we +might want to have such a new lockfile cleaning the previous ``pkg/3.3``. If we apply the ``--lockfile-clean`` argument that will +remove the non-used versions in the lockfile, but that will also remove the OS-dependant dependencies. So something like this could be +done: lets say that we have this lockfile (simplified, removed revisions for simplicity) as the result of testing a new ``pkgb/0.2`` version +for our main product ``app1/0.1``: + +.. code-block:: json + :caption: app.lock + + { + "version": "0.5", + "requires": [ + "pkgb/0.2", + "pkgb/0.1", + "pkgawin/0.1", + "pkganix/0.1", + "app1/0.1" + ] + } + +The ``pkgawin`` and ``pkganix`` are dependencies that exist exclusively in Windows and Linux respectively. Everything looks good, +``pkgb/0.2`` new version works fine with our app, and we want to clean the unused things from the lockfile: + +.. code-block:: bash + + $ conan lock create --requires=app1/0.1 --lockfile=app.lock --lockfile-out=win.lock -s os=Windows --lockfile-clean + # Note how both pkgb/0.1 and pkganix are gone + $ cat win.lock + { + "version": "0.5", + "requires": [ + "pkgb/0.2", + "pkgawin/0.1", + "app1/0.1" + ] + } + $ conan lock create --requires=app1/0.1 --lockfile=app.lock --lockfile-out=nix.lock -s os=Linux --lockfile-clean + # Note how both pkgb/0.1 and pkgawin are gone + $ cat win.lock + { + "version": "0.5", + "requires": [ + "pkgb/0.2", + "pkganix/0.1", + "app1/0.1" + ] + } + # Finally, merge the 2 clean lockfiles, for keeping just 1 for next iteration + $ conan lock merge --lockfile=win.lock --lockfile=nix.lock --lockfile-out=final.lock + $ cat final.lock + { + "version": "0.5", + "requires": [ + "pkgb/0.2", + "pkgawin/0.1", + "pkganix/0.1", + "app1/0.1" + ] + } diff --git a/2.1/_sources/reference/commands/lock/remove.rst.txt b/2.1/_sources/reference/commands/lock/remove.rst.txt new file mode 100644 index 000000000000..59e1d7a5eb1a --- /dev/null +++ b/2.1/_sources/reference/commands/lock/remove.rst.txt @@ -0,0 +1,68 @@ +conan lock remove +================= + +.. autocommand:: + :command: conan lock remove -h + + +The ``conan lock remove`` command is able to remove ``requires``, ``build_requires`` or ``python_requires`` items from an existing lockfile. + +For example, if we have the following ``conan.lock``: + +.. code-block:: bash + + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "math/1.0#85d927a4a067a531b1a9c7619522c015%1702683583.3411012", + "engine/1.0#fd2b006646a54397c16a1478ac4111ac%1702683583.3544693" + ], + "build_requires": [ + "cmake/1.0#85d927a4a067a531b1a9c7619522c015%1702683583.3411012", + "ninja/1.0#fd2b006646a54397c16a1478ac4111ac%1702683583.3544693" + ], + "python_requires": [ + "mytool/1.0#85d927a4a067a531b1a9c7619522c015%1702683583.3411012", + "othertool/1.0#fd2b006646a54397c16a1478ac4111ac%1702683583.3544693" + ] + } + + + +The ``conan lock remove`` command: + +.. code-block:: bash + + $ conan lock remove --requires="math/*" --build-requires=cmake/1.0 --python-requires="*tool/*" + +Will result in the following ``conan.lock``: + +.. code-block:: bash + + $ cat conan.lock + { + "version": "0.5", + "requires": [ + "engine/1.0#fd2b006646a54397c16a1478ac4111ac%1702683583.3544693" + ], + "build_requires": [ + "ninja/1.0#fd2b006646a54397c16a1478ac4111ac%1702683583.3544693" + ], + "python_requires": [ + ] + } + +It is possible to specify different patterns: + +- Remove by version-ranges with expressions like ``--requires="math/[>=1.0 <2]"``, and also +- Remove a specific revision: ``--requires=math/1.0#revision`` +- Remove locked dependencies for a given "team" user ``--requires=*/*@team*`` + +The ``conan lock remove`` can be useful for: + +- In combination with ``conan lock add``, it can be used to force the downgrade of a locked version to an older one. As ``conan lock add`` + always adds and sorts the order, resulting in newer versions with high priority, it is not possible to force going back to an older + version with just ``add``. But first using ``conan lock remove``, then ``conan lock add``, it is possible to do so. +- ``conan lock remove`` can unlock certain dependencies, resulting in an incomplete lockfile, that can be used with ``--lockfile-partial`` + to resolve to the latest available versions for the unlocked dependencies, while keeping locked the rest. diff --git a/2.1/_sources/reference/commands/new.rst.txt b/2.1/_sources/reference/commands/new.rst.txt new file mode 100644 index 000000000000..aa8367e172f3 --- /dev/null +++ b/2.1/_sources/reference/commands/new.rst.txt @@ -0,0 +1,229 @@ +.. _reference_commands_new: + +conan new +========= + +Create a new recipe (with a conanfile.py and other associated files) from either a predefined or a user-defined template. + +conan new +--------- + +.. autocommand:: + :command: conan new -h + + +The ``conan new`` command creates a new recipe in the current working directory, +plus extra example files such as *CMakeLists.txt* or the *test_package* folder (as necessary), +to either be used as a basis for your own project or aiding in the debugging process. + +Note that each template has some required and some [optional] user-defined variables used to customize the resulting files. + +The available templates are: + +- **basic**: + Creates a simple recipe with some example code and helpful comments, + and is a good starting point to avoid writing boilerplate code. + + Its variables are: [name], [version], [description], [requires1, requires2, ...], [tool_requires1, tool_requires2, ...] + +- **alias**: + Creates the minimal recipe needed to define an alias to a target recipe + + Its variables are: name, [version], target + +- **cmake_lib**: + Creates a cmake library target that defines a function called ``name``, + which will print some information about the compilation environment to stdout. + You can add requirements to this template in the form of + + ``conan new cmake_lib -d name=ai -d version=1.0 -d requires=math/3.14 -d requires=magic/0.0`` + + This will add requirements for both ``math/3.14`` and ``magic/0.0`` to the `requirements()` method, + will add the necessary ``find_package``s in CMake, and add a call to ``math()`` and ``magic()`` + inside the generated ``ai()`` function. + + Its variables are: name, version, [requires1, requires2, ...], [tool_requires1, tool_requires2, ...] + +- **cmake_exe**: + Creates a cmake executable target that defines a function called ``name``, + which will print some information about the compilation environment to stdout. + You can add requirements to this template in the form of + + ``conan new cmake_exe -d name=game -d version=1.0 -d requires=math/3.14 -d requires=ai/1.0`` + + This will add requirements for both ``math/3.14`` and ``ai/1.0`` to the `requirements()` method, + will add the necessary ``find_package``s in CMake, and add a call to ``math()`` and ``ai()`` + inside the generated ``game()`` function. + + Its variables are: name, version, [requires1, requires2, ...], [tool_requires1, tool_requires2, ...] + +- **autotools_lib**: + Creates an Autotools library. + + Its variables are: ``name``, ``version`` + +- **autotools_exe**: + Creates an Autotools executable + + Its variables are: ``name``, ``version`` + +- **bazel_lib**: + **Bazel integration BazelDeps, BazelToolchain, Bazel is experimental**. + Creates a Bazel library. + + Its variables are: ``name``, ``version`` + +- **bazel_exe**: + **Bazel integration BazelDeps, BazelToolchain, Bazel is experimental**. + Creates a Bazel executable + + Its variables are: ``name``, ``version`` + +- **meson_lib**: + Creates a Meson library. + + Its variables are: ``name``, ``version`` + +- **meson_exe**: + Creates a Meson executable + + Its variables are: ``name``, ``version`` + +- **msbuild_lib**: + Creates a MSBuild library. + + Its variables are: ``name``, ``version`` + +- **msbuild_exe**: + Creates a MSBuild executable + + Its variables are: ``name``, ``version`` + + +.. warning:: + + The output of the predefined built-in templates is **not stable**. It might + change in future releases to adapt to the latest tools or good practices. + + +Examples +-------- + +.. code-block:: text + + $ conan new basic + + +Generates a basic *conanfile.py* that does not implement any custom functionality + +.. code-block:: text + + $ conan new basic -d name=mygame -d requires=math/1.0 -d requires=ai/1.3 + +Generates a *conanfile.py* for ``mygame`` that depends on the packages ``math/1.0`` and ``ai/1.3`` + + +.. code-block:: text + + $ conan new cmake_exe -d name=game -d version=1.0 -d requires=math/3.14 -d requires=ai/1.0 + +Generates the necessary files for a CMake executable target. +This will add requirements for both ``math/3.14`` and ``ai/1.0`` to the ``requirements()`` method, +will add the necessary ``find_package`` in CMake, and add a call to ``math()`` and ``ai()`` +inside the generated ``game()`` function. + + +Custom templates +---------------- + +There's also the possibility of creating your templates. Templates in the Conan home should be +located in the ``templates/command/new`` folder, and each template should have a folder named like the template one. If we create the ``templates/command/new/mytemplate`` +folder, the command will be called with the following: + + +.. code-block:: bash + + $ conan new mytemplate + + +As with other files in the Conan home, you can manage these templates with ``conan config install ``, putting them +in a git repo or an http server and sharing them with your team. It is also possible to use templates from +any folder, just passing the full path to the template in the ``conan new ``, but in general it +is more convenient to manage them in the Conan home. + +The folder can contain as many files as desired. Both the filenames and the contents of the files can be +templatized using Jinja2 syntax. The command ``-d/--define`` arguments will define the ``key=value`` inputs +to the templates. + +The file contents will be like (Jinja2 syntax): + +.. code-block:: python + + # File "templates/command/new/mytemplate/conanfile.py" + from conan import ConanFile + + class Conan(ConanFile): + name = "{{name}}" + version = "{{version}}" + license = "{{license}}" + + +And it will require passing these values: + +.. code-block:: bash + + $ conan new mytemplate -d name=pkg -d version=0.1 -d license=MIT + +and it will generate in the current folder a file: + +.. code-block:: python + + # File "/conanfile.py" + from conan import ConanFile + + class Conan(ConanFile): + name = "pkg" + version = "0.1" + license = "MIT" + + +There are some special ``-d/--defines`` names. The ``name`` one is always mandatory. The ``conan_version`` +definition will always be automatically defined. The ``requires`` and ``tool_requires`` definitions, if existing, +will be automatically converted to lists. The ``package_name`` will always be defined, by default equals to ``name``. + + +For parametrized filenames, the filenames themselves support Jinja2 syntax. For example if we store a file +named literally ``{{name}}`` with the brackes in the template folder ``templates/command/new/mytemplate/``, +instead of the ``conanfile.py`` above: + + +.. code-block:: python + :caption: File: "templates/command/new/mytemplate/{{name}}" + + {{contents}} + +Then, executing + +.. code-block:: bash + + $ conan new mytemplate -d name=file.txt -d contents=hello! + + +will create a file called ``file.txt`` in the current dir containing the string ``hello!``. + +If there are files in the template not to be rendered with Jinja2, like image files, then their names should be +added to a file called ``not_templates`` inside the template directory, one filename per line. +So we could have a folder with: + + +.. code-block:: text + + templates/command/new/mytemplate + |- not_templates + |- conanfile.py + |- image.png + |- image2.png + + +And the ``not_templates`` contains the string ``*.png``, then ``conan new mytemplate ...`` will only render the +``conanfile.py`` through Jinja2, but both images will be copied as-is. diff --git a/2.1/_sources/reference/commands/profile.rst.txt b/2.1/_sources/reference/commands/profile.rst.txt new file mode 100644 index 000000000000..d544b566f474 --- /dev/null +++ b/2.1/_sources/reference/commands/profile.rst.txt @@ -0,0 +1,205 @@ +.. _reference_commands_profile: + +conan profile +============= + +Manage profiles + + +conan profile detect +-------------------- + +.. autocommand:: + :command: conan profile detect -h + + +.. warning:: + + The output of ``conan profile detect`` is **not stable**. It can change at any time in future Conan releases + to adapt to latest tools, latest versions, or other changes in the environment. + See :ref:`the Conan stability` section for more information. + +You can create a new auto-detected profile for your configuration using: + +.. code-block:: text + :caption: *auto-detected profile* + + $ conan profile detect + Found apple-clang 14.0 + apple-clang>=13, using the major as version + Detected profile: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu17 + compiler.libcxx=libc++ + compiler.version=14 + os=Macos + + WARN: This profile is a guess of your environment, please check it. + WARN: Defaulted to cppstd='gnu17' for apple-clang. + WARN: The output of this command is not guaranteed to be stable and can change in future Conan versions. + WARN: Use your own profile files for stability. + Saving detected profile to /Users/barbarians/.conan2/profiles/default + + +Be aware that if the profile already exists you have to use ``--force`` to overwrite it. Otherwise it will fail + +.. code-block:: text + :caption: *force overwriting already existing default profile* + + $ conan profile detect + ERROR: Profile '/Users/carlosz/.conan2/profiles/default' already exists + $ conan profile detect --force + Found apple-clang 14.0 + ... + Saving detected profile to /Users/carlosz/.conan2/profiles/default + +.. note:: + + **Best practices** + It is not recommended to use ``conan profile detect`` in production. To guarantee reproducibility, + it is recommended to define your own profiles, store them in a git repo or in a zip in a server, + and distribute it to your team and CI machines with ``conan config install``, together with other + configuration like custom settings, custom remotes definition, etc. + + +conan profile list +------------------ + +.. autocommand:: + :command: conan profile list -h + + +.. code-block:: text + :caption: *force overwriting already existing default profile* + + $ conan profile list + Profiles found in the cache: + default + ios_base + ios_simulator + clang_15 + + +conan profile path +------------------ + +.. autocommand:: + :command: conan + + +Use to get the profile location in your ``[CONAN_HOME]`` folder: + +.. code-block:: text + + $ conan profile path default + /Users/barbarians/.conan2/profiles/default + + +conan profile show +------------------ + +.. autocommand:: + :command: conan profile show -h + + +Use :command:`conan profile show` to compute the resulting build and host profiles from +the command line arguments. For example, combining different options and settings with the +default profile or with any other profile using the ``pr:b`` or ``pr:h`` arguments: + +.. code-block:: text + :emphasize-lines: 5,12 + + $ conan profile show -s:h build_type=Debug -o:h shared=False + Host profile: + [settings] + arch=x86_64 + build_type=Debug + compiler=apple-clang + compiler.cppstd=gnu17 + compiler.libcxx=libc++ + compiler.version=14 + os=Macos + [options] + shared=False + [conf] + + + Build profile: + [settings] + arch=x86_64 + build_type=Release + compiler=apple-clang + compiler.cppstd=gnu17 + compiler.libcxx=libc++ + compiler.version=14 + os=Macos + [conf] + +It's also useful to show the result of the evaluation of :ref:`jinja2 templates in the +profiles`. For example, a profile like this: + +.. code-block:: text + :caption: *myprofile* + + [settings] + os = {{ {"Darwin": "Macos"}.get(platform.system(), platform.system()) }} + +Check the evaluated profile: + +.. code-block:: text + + $ conan profile show -pr:h=myprofile + Host profile: + [settings] + os=Macos + [conf] + ... + + +The command can also output a json with the results: + +.. code-block:: text + + $ conan profile show --format=json + + { + "host": { + "settings": { + "arch": "armv8", + "build_type": "Release", + "compiler": "apple-clang", + "compiler.cppstd": "gnu17", + "compiler.libcxx": "libc++", + "compiler.version": "15", + "os": "Macos" + }, + "package_settings": {}, + "options": {}, + "tool_requires": {}, + "conf": {}, + "build_env": "" + }, + "build": { + "settings": { + "arch": "armv8", + "build_type": "Release", + "compiler": "apple-clang", + "compiler.cppstd": "gnu17", + "compiler.libcxx": "libc++", + "compiler.version": "15", + "os": "Macos" + }, + "package_settings": {}, + "options": {}, + "tool_requires": {}, + "conf": {}, + "build_env": "" + } + } + +.. seealso:: + + - Read more about :ref:`profiles` diff --git a/2.1/_sources/reference/commands/remote.rst.txt b/2.1/_sources/reference/commands/remote.rst.txt new file mode 100644 index 000000000000..720c603f006a --- /dev/null +++ b/2.1/_sources/reference/commands/remote.rst.txt @@ -0,0 +1,103 @@ +.. _reference_commands_remote: + +conan remote +============ + +Use this command to add, edit and remove Conan repositories from the Conan remote +registry and also manage authentication to those remotes. For more information on how to +work with Conan repositories, please check the :ref:`dedicated section `. + +.. autocommand:: + :command: conan remote -h + + +conan remote add +---------------- + +.. autocommand:: + :command: conan remote add -h + + +conan remote auth +----------------- + +.. autocommand:: + :command: conan remote auth -h + + +conan remote disable +-------------------- + +.. autocommand:: + :command: conan remote disable -h + + +conan remote enable +------------------- + +.. autocommand:: + :command: conan remote enable -h + + +conan remote list +----------------- + +.. autocommand:: + :command: conan remote list -h + + +conan remote list-users +----------------------- + +.. autocommand:: + :command: conan remote list-users -h + + +conan remote login +------------------ + +.. autocommand:: + :command: conan remote login -h + + +conan remote logout +------------------- + +.. autocommand:: + :command: conan remote logout -h + + +conan remote remove +------------------- + +.. autocommand:: + :command: conan remote remove -h + + +conan remote rename +------------------- + +.. autocommand:: + :command: conan remote rename -h + + +conan remote set-user +--------------------- + +.. autocommand:: + :command: conan remote set-user -h + + +conan remote update +------------------- + +.. autocommand:: + :command: conan remote update -h + + +Read more +--------- + +- :ref:`Uploading packages tutorial ` +- :ref:`Working with Conan repositories ` +- :ref:`Upload Conan packages to remotes using conan upload command ` diff --git a/2.1/_sources/reference/commands/remove.rst.txt b/2.1/_sources/reference/commands/remove.rst.txt new file mode 100644 index 000000000000..f18d1f0a97d7 --- /dev/null +++ b/2.1/_sources/reference/commands/remove.rst.txt @@ -0,0 +1,104 @@ +.. _reference_commands_remove: + +conan remove +============ + +.. autocommand:: + :command: conan remove -h + + +The ``conan remove`` command removes recipes and packages from the local cache or from a +specified remote. Depending on the patterns specified as argument, it is possible to +remove a complete package, or just remove the binaries, leaving still the recipe +available. You can also use the keyword ``!latest`` in the revision part of the pattern to +avoid removing the latest recipe or package revision of a certain Conan package. + +Use ``--dry-run`` to avoid performing actual deletions, and instead get a list of the elements that would have been removed. + +It has 2 possible and mutually exclusive inputs: + +- The ``conan remove `` pattern-based matching of recipes. +- The ``conan remove --list=`` that will remove the artifacts specified in the ``pkglist`` json file + + +There are other commands like :command:`conan list` (see the patterns documentation there :ref:`reference_commands_list`), :command:`conan upload` and :command:`conan download`, that take the same patterns. + +To remove recipes and their associated package binaries from the local cache: + + +.. code-block:: text + + $ conan remove "*" + # Removes everything from the cache + + $ conan remove "zlib/*"" + # Remove all possible versions of zlib, including all recipes, revisions and packages + + $ conan remove zlib/1.2.11 + # Remove zlib/1.2.11, all its revisions and package binaries. Leave other zlib versions + + $ conan remove "zlib/[<1.2.13]" + # Remove zlib/1.2.11 and zlib/1.2.12, all its revisions and package binaries. + + $ conan remove zlib/1.2.11#latest + # Remove zlib/1.2.11, only its latest recipe revision and binaries of that revision + # Leave the other zlib/1.2.11 revisions intact + + $ conan remove zlib/1.2.11#!latest + # Remove all the recipe revisions from zlib/1.2.11 but the latest one + # Leave the latest zlib/1.2.11 revision intact + + $ conan remove zlib/1.2.11# + # Remove zlib/1.2.11, only its exact and binaries of that revision + # Leave the other zlib/1.2.11 revisions intact + + +To remove only package binaries, but leaving the recipes, it is necessary to specify the +pattern including the ``:`` separator of the ``package_id``: + +.. code-block:: text + + $ conan remove "zlib/1.2.11:*" + # Removes all the zlib/1.2.11 package binaries from all the recipe revisions + + $ conan remove "zlib/*:*" + # Removes all the binaries from all the recipe revisions from all zlib versions + + $ conan remove "zlib/1.2.11#latest:*" + # Removes all the zlib/1.2.11 package binaries only from the latest zlib/1.2.11 recipe revision + + $ conan remove "zlib/1.2.11#!latest:*" + # Removes all the zlib/1.2.11 package binaries from all the recipe revisions but the latest one + + $ conan remove zlib/1.2.11: + # Removes the package binary from all the zlib/1.2.11 recipe revisions + + $ conan remove zlib/1.2.11:#latest#latest + # Removes only the latest package revision of the binary identified with + # from the latest recipe revision of zlib/1.2.11 + # WARNING: Recall that having more than 1 package revision is a smell and shouldn't happen + # in normal situations + + +Note that you can filter which packages will be removed using the ``--package-query`` argument: + +.. code-block:: text + + $ conan remove zlib/1.2.11:* -p compiler=clang + # Removes all the zlib/1.2.11 packages built with Clang compiler + + +You can query packages by both their settings and options, including custom ones. +To query for options you need to explicitly add the `options.` prefix, so that +`-p options.shared=False` will work but `-p shared=False` won't. + + + +All the above commands, by default, operate in the Conan cache. +To remove artifacts from a server, use the ``-r=myremote`` argument: + +.. code-block:: text + + $ conan remove zlib/1.2.11:* -r=myremote + # Removes all the zlib/1.2.11 package binaries from all the recipe revisions in + # the remote diff --git a/2.1/_sources/reference/commands/search.rst.txt b/2.1/_sources/reference/commands/search.rst.txt new file mode 100644 index 000000000000..b6fc07c78514 --- /dev/null +++ b/2.1/_sources/reference/commands/search.rst.txt @@ -0,0 +1,45 @@ +.. _reference_commands_search: + +conan search +============ + +Search existing recipes in remotes. +This command is equivalent to ``conan list -r=*``, and is provided for simpler UX. + +.. autocommand:: + :command: conan search -h + + +.. code-block:: text + + $ conan search zlib + conancenter + zlib + zlib/1.2.8 + zlib/1.2.11 + zlib/1.2.12 + zlib/1.2.13 + + $ conan search zlib -r=conancenter + conancenter + zlib + zlib/1.2.8 + zlib/1.2.11 + zlib/1.2.12 + zlib/1.2.13 + + $ conan search zlib/1.2.1* -r=conancenter + conancenter + zlib + zlib/1.2.11 + zlib/1.2.12 + zlib/1.2.13 + + $ conan search zlib/1.2.1* -r=conancenter --format=json + { + "conancenter": { + "zlib/1.2.11": {}, + "zlib/1.2.12": {}, + "zlib/1.2.13": {} + } + } diff --git a/2.1/_sources/reference/commands/source.rst.txt b/2.1/_sources/reference/commands/source.rst.txt new file mode 100644 index 000000000000..82d0171fef7e --- /dev/null +++ b/2.1/_sources/reference/commands/source.rst.txt @@ -0,0 +1,12 @@ +.. _reference_commands_source: + +conan source +============ + +.. autocommand:: + :command: conan source -h + + +.. seealso:: + + - Read the tutorial about the :ref:`local package development flow `. diff --git a/2.1/_sources/reference/commands/test.rst.txt b/2.1/_sources/reference/commands/test.rst.txt new file mode 100644 index 000000000000..4e24503bf5d7 --- /dev/null +++ b/2.1/_sources/reference/commands/test.rst.txt @@ -0,0 +1,14 @@ +.. _reference_commands_test: + +conan test +=========== + +.. autocommand:: + :command: conan test -h + + +The ``conan test`` command uses the *test_package* folder specified in ``path`` to tests the package reference specified in ``reference``. + +.. seealso:: + + - Read the tutorial about :ref:`testing Conan packages `. diff --git a/2.1/_sources/reference/commands/upload.rst.txt b/2.1/_sources/reference/commands/upload.rst.txt new file mode 100644 index 000000000000..dafb82d3b24a --- /dev/null +++ b/2.1/_sources/reference/commands/upload.rst.txt @@ -0,0 +1,35 @@ +.. _reference_commands_upload: + +conan upload +============ + +Use this command to upload recipes and binaries to Conan repositories. For more +information on how to work with Conan repositories, please check the :ref:`dedicated +section `. + +.. autocommand:: + :command: conan upload -h + + +The ``conan upload`` command can upload packages to 1 server repository specified by the ``-r=myremote`` argument. + +It has 2 possible and mutually exclusive inputs: +- The ``conan upload `` pattern-based matching of recipes, with a pattern similar to the ``conan list ``. +- The ``conan upload --list=`` that will upload the artifacts specified in the ``pkglist`` json file + + +If the ``--format=json`` formatter is specified, the result will be a "PackageList", compatible with other Conan commands, for example the ``conan remove`` command, so it is possible to concatenate different commands using the generated json file. See the :ref:`Packages Lists examples`. + +The ``--dry-run`` argument will prepare the packages for upload, zip files if necessary, check in the server to see what needs to be uploaded and what is already in the server, but it will not execute the actual upload. + +Using the ``core.upload:parallel`` conf, it is possible to upload packages in parallel. +By default, or when set to a value less than ``2``, no parallelization will take place, +and any other value will be the number of parallel threads to utilize. + +Read more +--------- + +- :ref:`Uploading packages tutorial ` +- :ref:`Working with Conan repositories ` +- :ref:`Managing remotes with conan remote command ` +- :ref:`Uploading metadata files`. diff --git a/2.1/_sources/reference/commands/version.rst.txt b/2.1/_sources/reference/commands/version.rst.txt new file mode 100644 index 000000000000..6fd7a352180d --- /dev/null +++ b/2.1/_sources/reference/commands/version.rst.txt @@ -0,0 +1,34 @@ +.. _reference_commands_version: + +conan version +============= + +.. include:: ../../common/experimental_warning.inc + +.. autocommand:: + :command: conan version -h + + +The :command:`conan version` command shows the conan version as well the python version from the system: + +.. code-block:: text + + $ conan version + version: 2.0.6 + python + version: 3.10.4 + sys_version: 3.10.4 (main, May 17 2022, 10:53:07) [Clang 13.1.6 (clang-1316.0.21.2.3)] + + +The :command:`conan version --format=json` returns a JSON output format in ``stdout`` (which can be redirected to a file) with the following structure: + +.. code-block:: text + + $ conan version --format=json + { + "version": "2.0.6", + "python": { + "version": "3.10.4", + "sys_version": "3.10.4 (main, May 17 2022, 10:53:07) [Clang 13.1.6 (clang-1316.0.21.2.3)]" + } + } diff --git a/2.1/_sources/reference/conan_server.rst.txt b/2.1/_sources/reference/conan_server.rst.txt new file mode 100644 index 000000000000..9a3f34f013cc --- /dev/null +++ b/2.1/_sources/reference/conan_server.rst.txt @@ -0,0 +1,376 @@ +.. _reference_conan_server: + +Conan Server +============ + +.. important:: + + This server is mainly used for testing (though it might work fine for small teams). We + recommend using the free :ref:`Artifactory Community Edition for C/C++ ` + for private development or **Artifactory Pro** as Enterprise solution. + +Configuration +------------- + +By default your server configuration is saved under ``~/.conan_server/server.conf``, +however you can modify this behaviour by either setting the ``CONAN_SERVER_HOME`` +environment variable or launching the server with ``-d`` or ``--server_dir`` command line +argument followed by desired path. In case you use one of the options your configuration +file will be stored under ``server_directory/server.conf`` Please note that command line +argument will override the environment variable. You can change configuration values in +``server.conf``, prior to launching the server. Note that the server does not support +hot-reload, and thus in order to see configuration changes you will have to manually +relaunch the server. + +The server configuration file is by default: + +.. code-block:: ini + + [server] + jwt_secret: IJKhyoioUINMXCRTytrR + jwt_expire_minutes: 120 + + ssl_enabled: False + port: 9300 + + public_port: + host_name: localhost + + authorize_timeout: 1800 + + disk_storage_path: ./data + disk_authorize_timeout: 1800 + updown_secret: HJhjujkjkjkJKLUYyuuyHJ + + [write_permissions] + # "opencv/2.3.4@lasote/testing": default_user,default_user2 + + [read_permissions] + */*@*/*: * + + [users] + demo: demo + + +Server Parameters ++++++++++++++++++ + +.. note:: + + The Conan server supports relative URLs, allowing you to avoid setting ``host_name``, + ``public_port`` and ``ssl_enabled``. The URLs used to upload/download packages will be + automatically generated in the client following the URL of the remote. This allows + accessing the Conan server from different networks. + +* ``port``: Port where **conan_server** will run. + +* The client server authorization is done with JWT. ``jwt_secret`` is a random string used + to generate authentication tokens. You can change it safely anytime (in fact it is a + good practice). The change will just force users to log in again. ``jwt_expire_minutes`` + is the amount of time that users remain logged-in within the client without having to + introduce their credentials again. + +* ``host_name``: If you set ``host_name``, you must use the machine's IP where you are + running your server (or domain name), something like **host_name: 192.168.1.100**. This + IP (or domain name) has to be visible (and resolved) by the Conan client, so take it + into account if your server has multiple network interfaces. + +* ``public_port``: Might be needed when running virtualized, Docker or any other kind of + port redirection. File uploads/downloads are served with their own URLs, generated by + the system, so the file storage backend is independent. Those URLs need the public port + they have to communicate from the outside. If you leave it blank, the ``port`` value is + used. + + **Example:** Use conan_server in a Docker container that internally runs in the 9300 + port but exposes the 9999 port (where the clients will connect to): + + .. code-block:: bash + + docker run ... -p9300:9999 ... # Check Docker docs for that + + + **server.conf** + + .. code-block:: text + + + [server] + + ssl_enabled: False + port: 9300 + public_port: 9999 + host_name: localhost + +* ``ssl_enabled`` Conan doesn't handle the SSL traffic by itself, but you can use a proxy + like :ref:`Nginx to redirect the SSL traffic to your Conan server `. If your Conan clients are + connecting with "https", set `ssl_enabled` to True. This way the conan_server will + generate the upload/download urls with "https" instead of "http". + +.. note:: + + **Important**: The Conan client, by default, will validate the server SSL certificates + and won't connect if it's invalid. If you have self signed certificates you have two + options: + + 1. Use the :command:`conan remote` command to disable the SSL certificate checks. E.g., + *conan remote add/update myremote https://somedir False* + 2. If using the *core.net.http:cacert_path* configuration in the Conan client, append + the server *.crt* file contents to the *cacert.pem* location. + +The folder in which the uploaded packages are stored (i.e., the folder you would want to +backup) is defined in the ``disk_storage_path``. The storage backend might use a different +channel, and uploads/downloads are authorized up to a maximum of ``authorize_timeout`` +seconds. The value should sufficient so that large downloads/uploads are not rejected, but +not too big to prevent hanging up the file transfers. The value ``disk_authorize_timeout`` +is not currently used. File transfers are authorized with their own tokens, generated with +the secret ``updown_secret``. This value should be different from the above +``jwt_secret``. + +Permissions Parameters +++++++++++++++++++++++ + +By default, the server configuration when set to Read can be done anonymous, but uploading +requires you to be registered users. Users can easily be registered in the ``[users]`` +section, by defining a pair of ``login: password`` for each one. Plain text passwords are +used at the moment, but as the server is on-premises (behind firewall), you just need to +trust your sysadmin :) + +If you want to restrict read/write access to specific packages, configure the +``[read_permissions]`` and ``[write_permissions]`` sections. These sections specify the +sequence of patterns and authorized users, in the form: + +.. code-block:: text + + # use a comma-separated, no-spaces list of users + package/version@user/channel: allowed_user1,allowed_user2 + +E.g.: + +.. code-block:: text + + */*@*/*: * # allow all users to all packages + PackageA/*@*/*: john,peter # allow john and peter access to any PackageA + */*@project/*: john # Allow john to access any package from the "project" user + +The rules are evaluated in order. If the left side of the pattern matches, the rule is +applied and it will not continue searching for matches. + +Authentication +++++++++++++++ + +By default, Conan provides a simple ``user: password`` users list in the ``server.conf`` +file. + +There is also a plugin mechanism for setting other authentication methods. The process to +install any of them is a simple two-step process: + +1. Copy the authenticator source file into the ``.conan_server/plugins/authenticator`` + folder. +2. Add ``custom_authenticator: authenticator_name`` to the ``server.conf`` [server] + section. + +This is a list of available authenticators, visit their URLs to retrieve them, but also to +report issues and collaborate: + +- **htpasswd**: Use your server Apache htpasswd file to authenticate users. Get it: + https://github.com/d-schiffner/conan-htpasswd +- **LDAP**: Use your LDAP server to authenticate users. Get it: + https://github.com/uilianries/conan-ldap-authentication + +Create Your Own Custom Authenticator +____________________________________ + +If you want to create your own Authenticator, create a Python module in +``~/.conan_server/plugins/authenticator/my_authenticator.py`` + +**Example:** + +.. code-block:: python + + def get_class(): + return MyAuthenticator() + + + class MyAuthenticator(object): + def valid_user(self, username, plain_password): + return username == "foo" and plain_password == "bar" + +The module has to implement: + +- A factory function ``get_class()`` that returns a class with a ``valid_user()`` method + instance. +- The class containing the ``valid_user()`` that has to return True if the user and + password are valid or False otherwise. + +Authorizations +++++++++++++++ + +By default, Conan uses the contents of the ``[read_permissions]`` and +``[write_permissions]`` sections to authorize or reject a request. + +A plugin system is also available to customize the authorization mechanism. The +installation of such a plugin is a simple two-step process: + +1. Copy the authorizer's source file into the ``.conan_server/plugins/authorizer`` folder. +2. Add ``custom_authorizer: authorizer_name`` to the ``server.conf`` [server] section. + +Create Your Own Custom Authorizer +_________________________________ + +If you want to create your own Authorizer, create a Python module in +``~/.conan_server/plugins/authorizer/my_authorizer.py`` + +**Example:** + +.. code-block:: python + + from conans.errors import AuthenticationException, ForbiddenException + + def get_class(): + return MyAuthorizer() + + class MyAuthorizer(object): + def _check_conan(self, username, ref): + if ref.user == username: + return + + if username: + raise ForbiddenException("Permission denied") + else: + raise AuthenticationException() + + def _check_package(self, username, pref): + self._check(username, pref.ref) + + check_read_conan = _check_conan check_write_conan = _check_conan + check_delete_conan = _check_conan check_read_package = _check_package + check_write_package = _check_package check_delete_package = _check_package + +The module has to implement: + +- A factory function ``get_class()`` that returns an instance of a class conforming to the + Authorizer's interface. +- A class that implements all the methods defined in the Authorizer interface: + - ``check_read_conan()`` is used to decide whether to allow read access to a recipe. + - ``check_write_conan()`` is used to decide whether to allow write access to a recipe. + - ``check_delete_conan()`` is used to decide whether to allow a recipe's deletion. + - ``check_read_package()`` is used to decide whether to allow read access to a + package. + - ``check_write_package()`` is used to decide whether to allow write access to a + package. + - ``check_delete_package()`` is used to decide whether to allow a package's deletion. + +The ``check_*_conan()`` methods are called with a username and +``conans.model.ref.ConanFileReference`` instance as their arguments. Meanwhile the +``check_*_package()`` methods are passed a username and +``conans.model.ref.PackageReference`` instance as their arguments. These methods should +raise an exception, unless the user is allowed to perform the requested action. + +.. _reference_conan_server_nginx: + +Running the Conan Server with SSL using Nginx +--------------------------------------------- + + **server.conf** + + .. code-block:: text + + [server] port: 9300 + + + **nginx conf file** + + .. code-block:: text + + server { + listen 443; server_name myservername.mydomain.com; + + location / { + proxy_pass http://0.0.0.0:9300; + } ssl on; ssl_certificate /etc/nginx/ssl/server.crt; ssl_certificate_key + /etc/nginx/ssl/server.key; + } + + **remote configuration in Conan client** + + .. code-block:: text + + $ conan remote add myremote https://myservername.mydomain.com + +Running the Conan Server with SSL using Nginx in a Subdirectory +--------------------------------------------------------------- + + **server.conf** + + .. code-block:: text + + [server] port: 9300 + + **nginx conf file** + + .. code-block:: text + + server { + + listen 443; ssl on; ssl_certificate /usr/local/etc/nginx/ssl/server.crt; + ssl_certificate_key /usr/local/etc/nginx/ssl/server.key; server_name + myservername.mydomain.com; + + location /subdir/ { + proxy_pass http://0.0.0.0:9300/; + } + } + + **remote configuration in Conan client** + + .. code-block:: text + + $ conan remote add myremote https://myservername.mydomain.com/subdir/ + +Running Conan Server using Apache +--------------------------------- + + You need to install ``mod_wsgi``. If you want to use Conan installed from ``pip``, the + conf file should be similar to the following example: + + **Apache conf file** (e.g., /etc/apache2/sites-available/0_conan.conf) + + .. code-block:: text + + + WSGIScriptAlias / + /usr/local/lib/python3.6/dist-packages/conans/server/server_launcher.py + WSGICallableObject app WSGIPassAuthorization On + + + Require all granted + + + + + If you want to use Conan checked out from source in, for example in `/srv/conan`, the + conf file should be as follows: + + **Apache conf file** (e.g., /etc/apache2/sites-available/0_conan.conf) + + .. code-block:: text + + + WSGIScriptAlias / /srv/conan/conans/server/server_launcher.py + WSGICallableObject app WSGIPassAuthorization On + + + Require all granted + + + + The directive ``WSGIPassAuthorization On`` is needed to pass the HTTP basic + authentication to Conan. + + Also take into account that the server config files are located in the home of the + configured Apache user, e.g., var/www/.conan_server, so remember to use that directory + to configure your Conan server. + +.. seealso:: + + * :ref:`Setting-up a Conan Server ` diff --git a/2.1/_sources/reference/conanfile.rst.txt b/2.1/_sources/reference/conanfile.rst.txt new file mode 100644 index 000000000000..a37639fd59c4 --- /dev/null +++ b/2.1/_sources/reference/conanfile.rst.txt @@ -0,0 +1,36 @@ +.. _conanfile_reference: + +conanfile.py +============ + + +The ``conanfile.py`` is the recipe file of a package, responsible for defining how to build it and consume it. + + .. code-block:: python + + from conan import ConanFile + + class HelloConan(ConanFile): + ... + + +.. important:: + + *conanfile.py* recipes use a variety of attributes and methods to operate. In order to avoid + collisions and conflicts, follow these rules: + + - Public attributes and methods, like ``build()``, ``self.package_folder``, are reserved for Conan. + Don't use public members for custom fields or methods in the recipes. + - Use "protected" access for your own members, like ``self._my_data`` or ``def _my_helper(self):``. + Conan only reserves "protected" members starting with ``_conan``. + + + +Contents: + +.. toctree:: + :maxdepth: 2 + + conanfile/attributes + conanfile/methods + conanfile/running_and_output diff --git a/2.1/_sources/reference/conanfile/attributes.rst.txt b/2.1/_sources/reference/conanfile/attributes.rst.txt new file mode 100644 index 000000000000..dc084cdbea99 --- /dev/null +++ b/2.1/_sources/reference/conanfile/attributes.rst.txt @@ -0,0 +1,258 @@ +.. spelling:: + + ing + ver + +.. _conan_conanfile_attributes: + +Attributes +========== + +.. contents:: + :local: + +.. include:: ./attributes/references.inc +.. include:: ./attributes/metadata.inc +.. include:: ./attributes/requirements.inc +.. include:: ./attributes/sources.inc +.. include:: ./attributes/binary_model.inc +.. include:: ./attributes/build.inc +.. include:: ./attributes/folders.inc +.. include:: ./attributes/layout.inc +.. include:: ./attributes/consumers.inc + + + +Other ++++++ + +dependencies +------------ + +Conan recipes provide access to their dependencies via the ``self.dependencies`` attribute. + + +.. code-block:: python + + class Pkg(ConanFile): + requires = "openssl/0.1" + + def generate(self): + openssl = self.dependencies["openssl"] + # access to members + openssl.ref.version + openssl.ref.revision # recipe revision + openssl.options + openssl.settings + +.. seealso:: + + Read here :ref:`the complete reference of self.dependencies `. + + +conf +---- + +In the ``self.conf`` attribute we can find all the conf entries declared in the :ref:`[conf]` section of the profiles. +in addition of the declared :ref:`self.conf_info` entries from the first level tool requirements. +The profile entries have priority. + + +.. code-block:: python + + from conan import ConanFile + + class MyConsumer(ConanFile): + + tool_requires = "my_android_ndk/1.0" + + def generate(self): + # This is declared in the tool_requires + self.output.info("NDK host: %s" % self.conf.get("tools.android:ndk_path")) + # This is declared in the profile at [conf] section + self.output.info("Custom var1: %s" % self.conf.get("user.custom.var1")) + + +.. note:: + + The ``conf`` attribute is a **read-only** attribute. It can only be defined in profiles and command lines, but it should never be set by recipes. + Recipes can only read its value via ``self.conf.get()`` method. + + +Output +------ + +.. _conanfile_output_attribute: + +Output contents +--------------- + +Use the ``self.output`` to print contents to the output. + +.. code-block:: python + + self.output.success("This is good, should be green") + self.output.info("This is neutral, should be white") + self.output.warning("This is a warning, should be yellow") + self.output.error("Error, should be red") + +Additional output methods are available and you can produce different outputs with different colors. +See :ref:`the output documentation` for the list of available output methods. + + +.. _revision_mode_attribute: + +revision_mode +------------- + +This attribute allow each recipe to declare how the revision for the recipe itself should +be computed. It can take three different values: + +- ``"hash"`` (by default): Conan will use the checksum hash of the recipe manifest to + compute the revision for the recipe. +- ``"scm"``: if the project is inside a Git repository the commit ID will be used as the + recipe revision. If there is no repository it will raise an error. +- ``"scm_folder"``: This configuration applies when you have a mono-repository project, but + still want to use *scm* revisions. In this scenario, the revision of the exported + `conanfile.py` will correspond to the commit ID of the folder where it's located. This + approach allows multiple `conanfile.py` files to exist within the same Git repository, + with each file exported under its distinct revision. + +When ``scm`` or ``scm_folder`` is selected, the Git commit will be used, but by default +the repository must be clean, otherwise it would be very likely that there are uncommitted +changes and the build wouldn't be reproducible. So if there are dirty files, Conan will raise +an error. If there are files that can be dirty in the repo, but do not belong at all to the +recipe or the package, then it is possible to exclude them from the check with the ``core.scm:excluded`` +configuration, which is a list of patterns (fnmatch) to exclude. + + + +upload_policy +------------- + +Controls when the current package built binaries are uploaded or not + +- ``"skip"``: The precompiled binaries are not uploaded. This is useful for "installer" + packages that just download and unzip something heavy (e.g. android-ndk), and is useful + together with the ``build_policy = "missing"`` + + .. code-block:: python + :emphasize-lines: 2 + + class Pkg(ConanFile): + upload_policy = "skip" + + +required_conan_version +---------------------- + +Recipes can define a module level ``required_conan_version`` that defines a valid version range of +Conan versions that can load and understand the current ``conanfile.py``. The syntax is: + +.. code-block:: python + + from conan import ConanFile + + required_conan_version = ">=2.0" + + class Pkg(ConanFile): + pass + +Version ranges as in ``requires`` are allowed. +Also there is a ``global.conf`` file ``core:required_conan_version`` configuration that can +define a global minimum, maximum or exact Conan version to run, which can be very convenient +to maintain teams of developers and CI machines to use the desired range of versions. + +.. _conan_conanfile_attributes_implements: + +implements +---------- + +A list is used to define a series of option configurations that Conan will handle +automatically. This is especially handy for avoiding boilerplate code that tends to repeat +in most of the recipes. The syntax is as follows: + +.. code-block:: python + + from conan import ConanFile + + class Pkg(ConanFile): + implements = ["auto_shared_fpic", "auto_header_only", ...] + + +Currently these are the automatic implementations provided by Conan: + +- ``"auto_shared_fpic"``: automatically manages ``fPIC`` and ``shared`` options. Adding this + implementation will have both effect in the + :ref:`configure` and + :ref:`config_options` steps + when those methods are not explicitly defined in the recipe. + +- ``"auto_header_only"``: automatically manages the package ID clearing settings. Adding this + implementation will have effect in the + :ref:`package_id` step + when the method is not explicitly defined in the recipe. + +.. warning:: + + This is a 2.0-only feature, and it will not work in 1.X + + +alias +----- + +.. warning:: + + While aliases can technically still be used in Conan 2.0, their usage is not recommended + and they may be fully removed in future releases. Users are encouraged to adapt to the + :ref:`newer versioning features` for a more standardized and efficient + package management experience. + +In Conan 2.0, the `alias` attribute remains a part of the recipe, allowing users to define +an alias for a package version. Normally, you would create one using the ``conan new`` +command with the ``alias`` template and the exporting the recipe with conan export: + +.. code-block:: shell + + $ conan new alias -d name=mypkg -d version=latest -d target=1.0 + $ conan export . + +Note that when requiring the alias, you must place the version in parentheses ``()`` to +explicitly declare the use of an alias as a requirement: + +.. code-block:: python + + class Consumer(ConanFile): + + ... + requires = "mypkg/(latest)" + ... + + +.. _conan_conanfile_attributes_extension_properties: + +extension_properties +-------------------- + +The ``extensions_properties`` attribute is a dictionary intended to define and pass information from the +recipes to the Conan extensions. + +At the moment, the only defined property is ``compatibility_cppstd``, that allows disabling the behavior +of :ref:`the default compatibility.py extension `, that considers +binaries built with different ``compiler.cppstd`` values ABI-compatible among them. +To disable this behavior for the current package, it is possible to do it with: + +.. code-block:: python + + class Pkg(ConanFile): + extension_properties = {"compatibility_cppstd": False} + +If it is necessary to do it conditionally, it is also possible to define its value inside recipe ``compatibility()`` +method: + +.. code-block:: python + + class Pkg(ConanFile): + + def compatibility(self): + self.extension_properties = {"compatibility_cppstd": False} diff --git a/2.1/_sources/reference/conanfile/methods.rst.txt b/2.1/_sources/reference/conanfile/methods.rst.txt new file mode 100644 index 000000000000..4fb3e146ee41 --- /dev/null +++ b/2.1/_sources/reference/conanfile/methods.rst.txt @@ -0,0 +1,59 @@ +.. _reference_conanfile_methods: + +Methods +======= + +What follows is a list of methods that you can define in your recipes to customize the package creation & consumption processes: + +.. toctree:: + :maxdepth: 1 + :hidden: + + methods/build + methods/build_id + methods/build_requirements + methods/compatibility + methods/configure + methods/config_options + methods/deploy + methods/export + methods/export_sources + methods/generate + methods/init + methods/layout + methods/package + methods/package_id + methods/package_info + methods/requirements + methods/set_name + methods/set_version + methods/source + methods/system_requirements + methods/test + methods/validate + methods/validate_build + + +- :doc:`build() `: Contains the build instructions to build a package from source +- :doc:`build_id() `: Allows reusing the same build to create different package binaries +- :doc:`build_requirements() `: Defines ``tool_requires`` and ``test_requires`` +- :doc:`compatibility() `: Defines binary compatibility at the recipe level +- :doc:`configure() `: Allows configuring settings and options while computing dependencies +- :doc:`config_options() `: Configure options while computing dependency graph +- :doc:`deploy() `: Deploys (copy from package to user folder) the desired artifacts +- :doc:`export() `: Copies files that are part of the recipe +- :doc:`export_sources() `: Copies files that are part of the recipe sources +- :doc:`generate() `: Generates the files that are necessary for building the package +- :doc:`init() `: Special initialization of recipe when extending from ``python_requires`` +- :doc:`layout() `: Defines the relative project layout, source folders, build folders, etc. +- :doc:`package() `: Copies files from build folder to the package folder. +- :doc:`package_id() `: Defines special logic for computing the binary ``package_id`` identifier +- :doc:`package_info() `: Provide information for consumers of this package about libraries, folders, etc. +- :doc:`requirements() `: Define the dependencies of the package +- :doc:`set_name() `: Dynamically define the name of a package +- :doc:`set_version() `: Dynamically define the version of a package. +- :doc:`source() `: Contains the commands to obtain the source code used to build +- :doc:`system_requirements() `: Call system package managers like Apt to install system packages +- :doc:`test() `: Run some simple package test (exclusive of ``test_package``) +- :doc:`validate() `: Define if the current package is invalid (cannot work) with the current configuration. +- :doc:`validate_build() `: Define if the current package cannot be created with the current configuration. diff --git a/2.1/_sources/reference/conanfile/methods/build.rst.txt b/2.1/_sources/reference/conanfile/methods/build.rst.txt new file mode 100644 index 000000000000..597d9990ad3d --- /dev/null +++ b/2.1/_sources/reference/conanfile/methods/build.rst.txt @@ -0,0 +1,66 @@ +.. _reference_conanfile_methods_build: + +build() +======= + +The ``build()`` method is used to define the build from source of the package. In practice this means calling some build system, which could be done explicitly or using any of the build helpers provided by Conan: + + +.. code-block:: python + + from conan.tools.cmake import CMake + + class Pkg(ConanFile): + + def build(self): + # Either using some of the Conan built-in helpers + cmake = CMake(self) + cmake.configure() # equivalent to self.run("cmake . ") + cmake.build() # equivalent to self.run("cmake --build . ") + cmake.test() # equivalent to self.run("cmake --target=RUN_TESTS") + + # Or it could run your own build system or scripts + self.run("mybuildsystem . --configure") + self.run("mybuildsystem . --build") + + +For more information about the existing built-in build system integrations, visit :ref:`conan_tools`. + +The ``build()`` method should be as simple as possible, just wrapping the command line invocations +that a developer would do in the simplest possible way. The ``generate()`` method is the one responsible +for preparing the build, creating toolchain files, CMake presets, or any other files which are necessary +so developers could easily call the build system by hand. This allows for much better integrations with IDEs and +improves the developer experience. The result is that in practice the ``build()`` method should be relatively simple. + +The ``build()`` method runs once per unique configuration, so if there are some source operations like applying patches that are done conditionally to different configurations, they could be also applied in the +``build()`` method, before the actual build. It is important to note that in this case the :ref:`no_copy_source ` attribute cannot be set to ``True``. + +The ``build()`` method is the right place to build and run unit tests, before packaging, and raising errors if those tests fail, interrupting the process, and not even packaging the final binaries. +The built-in helpers will skip the unit tests if the ``tools.build:skip_test`` configuration is defined. For custom integrations, it is expected that the method checks this ``conf`` value in order to skip building and running tests, which can be useful for some CI scenarios. + +**Running Tests in Cross-Building Scenarios**: There may be some cases where you want to +build tests but cannot run them, such as in cross-building scenarios. For these rare +situations, you can use the :ref:`conan.tools.build.can_run` +tool as follows: + +.. code-block:: python + + ... + + def build(self): + cmake = CMake(self) + cmake.configure() + cmake.build() + if can_run(self): + cmake.test() + +.. note:: + + **Best practices** + + - The ``build()`` method should be as simple as possible, the heavy lifting of preparing the build should happen in the ``generate()`` method in order to achieve a good developer experience that can easily build locally with just ``conan install .``, plus directly calling the build system or opening their IDE. + + +.. seealso:: + + Follow the :ref:`tutorial about building packages` for more information about building from sources. \ No newline at end of file diff --git a/2.1/_sources/reference/conanfile/methods/build_id.rst.txt b/2.1/_sources/reference/conanfile/methods/build_id.rst.txt new file mode 100644 index 000000000000..6b103bf2a0db --- /dev/null +++ b/2.1/_sources/reference/conanfile/methods/build_id.rst.txt @@ -0,0 +1,58 @@ +.. _reference_conanfile_methods_build_id: + +build_id() +========== + +The ``build_id()`` method allows to re-use the same build to create different binary packages in the cache, +potentially saving build time as it can avoid some unnecessary re-builds. It is therefore an optimization method. + +In the general case, there is one build folder for each binary package, with the exact same ``package_id`` of the package. However this behavior +can be changed, there are a couple of scenarios that this might be useful: + +- The package build scripts generate several different configurations at once (like both debug and release artifacts) in the same run, without the possibility of building each configuration separately. +- The package build scripts generate one binary configuration, but different artifacts that can be packaged separately. For example if there are some test executables, you might want to create two packages: one just containing the library for general usage, and another one also containing the tests (for compliance, later reproducibility, debugging, etc). + +In the first case, we could for example write: + +.. code-block:: python + + settings = "os", "compiler", "arch", "build_type" + + def build_id(self): + self.info_build.settings.build_type = "Any" + +This recipe will generate a final different package with a different ``package_id`` for debug and release configurations. But as the ``build_id()`` will generate the +same ``build_id`` for any ``build_type``, then just one folder and one ``build()`` will be done, building both debug and release artifacts, +and then the ``package()`` method will be called for each configuration, and it should package the artifacts conditionally to the ``self.settings.build_type`` value. Different builds will still be +executed if using different compilers or architectures. + +Other information like custom package options can also be changed: + +.. code-block:: python + + def build_id(self): + self.info_build.options.myoption = 'MyValue' # any value possible + self.info_build.options.fullsource = 'Always' + +If the ``build_id()`` method does not modify the ``info_build`` data, and it still produces a different id than +the ``package_id``, then the standard behavior will be applied. Consider the following: + +.. code-block:: python + + settings = "os", "compiler", "arch", "build_type" + + def build_id(self): + if self.settings.os == "Windows": + self.info_build.settings.build_type = "Any" + +This will only produce a different ``build_id`` if the package is for Windows, thus running ``build()`` just +once for all ``build_type`` values. The behavior +in any other OS will be the standard one, as if the ``build_id()`` method was not defined, running +one different ``build()`` for each ``build_type``. + + +.. note:: + + **Best practices** + + Conan strongly recommends to use one package binary with its own ``package_id`` for each different configuration. The goal of the ``build_id()`` method is to deal with legacy build scripts that cannot easily be changed to do the build of one configuration each time. diff --git a/2.1/_sources/reference/conanfile/methods/build_requirements.rst.txt b/2.1/_sources/reference/conanfile/methods/build_requirements.rst.txt new file mode 100644 index 000000000000..8cadace8cc48 --- /dev/null +++ b/2.1/_sources/reference/conanfile/methods/build_requirements.rst.txt @@ -0,0 +1,132 @@ +.. _reference_conanfile_methods_build_requirements: + +build_requirements() +==================== + +The ``build_requirements()`` method is functionally equivalent to the ``requirements()`` one, it is executed just after it. It is not strictly necessary, in theory everything that is inside this method, could be done in the end of the ``requirements()`` one. Still, ``build_requirements()`` is good for having a dedicated place to define ``tool_requires`` and ``test_requires``: + +.. code-block:: python + + def build_requirements(self): + self.tool_requires("cmake/3.23.5") + self.test_requires("gtest/1.13.0") + + +For simple cases the attribute syntax can be enough, like ``tool_requires = "cmake/3.23.5"`` and ``test_requires = "gtest/1.13.0"``. The method form can be necessary for conditional or parameterized requirements. + +The ``tool_requires`` and ``test_requires`` methods are just a specialized instance of ``requires`` with some predefined trait values. See the :ref:`requires() reference` for more information about traits. + +.. _reference_conanfile_methods_build_requirements_tool_requires: + +tool_requires() +--------------- + +The ``tool_requires`` is equivalent to ``requires()`` with the following traits: + +- ``build=True``. This dependency is in the "build" context, being necessary at build time, but not at application runtime, and will receive the "build" profile and configuration. +- ``visible=False``. The dependency to a tool requirement is not propagated downstream. For example, one package can call ``tool_requires("cmake/3.23.5")``, but that doesn't mean that the consumer packages also use ``cmake``, they could even use a different build system, or a different version, without causing conflicts. +- ``run=True``. This dependency has some executables or runtime that needs to be ran at build time. +- ``headers=False`` A tool requirement does not have headers. +- ``libs=False``: A tool requirement does not have libraries to be linked by the consumer (if it had libraries they would be in the "build" context and could be incompatible with the "host" context of the consumer package). + + +Recall that ``tool_requires`` are intended exclusively for depending on tools like ``cmake`` or ``ninja``, which run in the "build" context, but not for library-like dependencies that would be linked into binaries. For libraries or library-like dependencies, use ``requires`` or ``test_requires``. + + +.. _reference_conanfile_build_requirements_host_version: + + +************** + +.. include:: ../../../common/experimental_warning.inc + +This syntax is useful when you're using the same package recipe as a *requires* and as a *tool_requires* and you want to avoid +conflicting downstream if any user decides to override the original *requires* version in the *host* context, i.e., the user could end up with +two different versions in the host and build contexts of the same dependency. + +In a nutshell, the ```` specifier allows us to ensure that the version resolved for the *tool_requires* +always matches the one for the host requirement. + +For instance, let's show a simple recipe using *protobuf*: + +.. code-block:: python + + from conan import ConanFile + + class mylibRecipe(ConanFile): + name = "mylib" + version = "0.1" + def requirements(self): + self.requires("protobuf/3.18.1") + def build_requirements(self): + self.tool_requires("protobuf/") + +Then, if any user wants to use *mylib/0.1*, but another version of *protobuf*, there shouldn't be any problems overriding it: + +.. code-block:: python + + from conan import ConanFile + + class myappRecipe(ConanFile): + name = "myapp" + version = "0.1" + def requirements(self): + self.requires("mylib/0.1") + self.requires("protobuf/3.21.9", override=True) + +The ```` defined upstream is ensuring that the host and build contexts are using the same version of that requirement. + +Additionally, the syntax ```` can be used to specify the name of the package to be tracked, +should the *requires* and *tool_requires* have different names. For instance: + +.. code-block:: python + + from conan import ConanFile + + class mylibRecipe(ConanFile): + name = "mylib" + version = "0.1" + def requirements(self): + self.requires("gettext/2.31") + def build_requirements(self): + self.tool_requires("libgettext/") + + +.. seealso:: + + - :ref:`examples_graph_tool_requires_protobuf` + +.. _reference_conanfile_methods_build_requirements_test_requires: + +test_requires +------------- + +The ``test_requires`` is equivalent to ``requires()`` with the following traits: + +- ``test=True``. This dependency is a "test" dependency, existing in the "host" context, but not aiming to be part of the final product. +- ``visible=False``. The dependency to a test requirement is not propagated downstream. For example, one package can call ``self.test_requires("gtest/1.13.0")``, but that doesn't mean that the consumer packages also use ``gtest``, they could even use a different test framework, or the same ``gtest`` with a different version, without causing conflicts. + + +It is possible to further modify individual traits of ``tool_requires()`` and ``test_requires()`` if necessary, for example: + +.. code-block:: python + + def build_requirements(self): + self.tool_requires("cmake/3.23.5", options={"shared": False}) + + +The ``test_requires()`` allows the ``force=True`` trait in case there are transitive test requirements with conflicting versions, and likewise ``tool_requires()`` support the ``override=True`` trait, for overriding possible transitive dependencies of the direct tool requirements. + +.. note:: + + **Best practices** + + - ``tool_requires`` are exclusively for build time **tools**, not for libraries that would be included and linked into the consumer package. For libraries with some special characteristics, use a ``requires()`` with custom trait values. + - The ``self.test_requires()`` and ``self.tool_requires()`` methods should exclusively be used in the ``build_requirements()`` method, with the only possible exception being the ``requirements()`` method. Using them in any other method is forbidden. To access information about dependencies when necessary in some methods, the :ref:`self.dependencies` attribute should be used. + + +.. seealso:: + + - Follow the :ref:`tutorial about consuming Conan packages as tools`. + - Read the :ref:`tutorial about creating tool_requires packages`. + - :ref:`examples_graph_tool_requires_protobuf` diff --git a/2.1/_sources/reference/conanfile/methods/compatibility.rst.txt b/2.1/_sources/reference/conanfile/methods/compatibility.rst.txt new file mode 100644 index 000000000000..2d09aa6020db --- /dev/null +++ b/2.1/_sources/reference/conanfile/methods/compatibility.rst.txt @@ -0,0 +1,51 @@ +.. _reference_conanfile_methods_compatibility: + +compatibility() +=============== + +.. warning:: + + This is a **preview** feature + + +The ``compatibility()`` method implements the same binary compatibility mechanism than the +:ref:`compatibility plugin`, but at the recipe +level. In general, the global compatibility plugin should be good for most cases, and only +require the recipe method for exceptional cases. + +This method can be used in a *conanfile.py* to define packages that are compatible between +each other. If there are no binaries available for the requested settings and options, +this mechanism will retrieve the compatible package's binaries if they exist. This method +should return a list of compatible configurations. + +For example, if we want that binaries +built with gcc versions 4.8, 4.7 and 4.6 to be considered compatible with the ones compiled +with 4.9 we could declare a ``compatibility()`` method like this: + +.. code-block:: python + + def compatibility(self): + if self.settings.compiler == "gcc" and self.settings.compiler.version == "4.9": + return [{"settings": [("compiler.version", v)]} + for v in ("4.8", "4.7", "4.6")] + +The format of the list returned is as shown below: + +.. code-block:: python + + [ + { + "settings": [(, ), (, ), ...], + "options": [(