diff --git a/examples/conanfile/layout/conanfile_in_subfolder.rst b/examples/conanfile/layout/conanfile_in_subfolder.rst index 992b5fa0292e..c645211d4cf7 100644 --- a/examples/conanfile/layout/conanfile_in_subfolder.rst +++ b/examples/conanfile/layout/conanfile_in_subfolder.rst @@ -3,7 +3,7 @@ Declaring the layout when the Conanfile is inside a subfolder ------------------------------------------------------------- -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/conanfile/layout/editable_components.rst b/examples/conanfile/layout/editable_components.rst index 0e5e34dae275..a0fdfcd9ebe0 100644 --- a/examples/conanfile/layout/editable_components.rst +++ b/examples/conanfile/layout/editable_components.rst @@ -8,7 +8,7 @@ That is, if we want to put a package in ``editable`` mode, and that package defi necessary to define the components layout correctly in the ``layout()`` method. Let's see it in a real example. -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/conanfile/layout/multiple_subprojects.rst b/examples/conanfile/layout/multiple_subprojects.rst index a8a62f40bd48..63e009540bb6 100644 --- a/examples/conanfile/layout/multiple_subprojects.rst +++ b/examples/conanfile/layout/multiple_subprojects.rst @@ -3,7 +3,7 @@ Declaring the layout when we have multiple subprojects ------------------------------------------------------ -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/conanfile/layout/third_party_libraries.rst b/examples/conanfile/layout/third_party_libraries.rst index 0f881b99c648..c7feb9c59af1 100644 --- a/examples/conanfile/layout/third_party_libraries.rst +++ b/examples/conanfile/layout/third_party_libraries.rst @@ -3,7 +3,7 @@ Declaring the layout when creating packages for third-party libraries --------------------------------------------------------------------- -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/conanfile/package_info/components.rst b/examples/conanfile/package_info/components.rst index 7ca2e3e225d8..c360ea2c55e3 100644 --- a/examples/conanfile/package_info/components.rst +++ b/examples/conanfile/package_info/components.rst @@ -33,7 +33,7 @@ component. network; } -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/config_files/settings/settings_user.rst b/examples/config_files/settings/settings_user.rst index e5c354bf28b5..19b786f112b8 100644 --- a/examples/config_files/settings/settings_user.rst +++ b/examples/config_files/settings/settings_user.rst @@ -3,7 +3,7 @@ Customize your settings: create your settings_user.yml ====================================================== -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/dev_flow/debug/step_into_dependencies.rst b/examples/dev_flow/debug/step_into_dependencies.rst index acf65acf37f6..83fbd0c682d3 100644 --- a/examples/dev_flow/debug/step_into_dependencies.rst +++ b/examples/dev_flow/debug/step_into_dependencies.rst @@ -17,7 +17,7 @@ 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 +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 diff --git a/examples/extensions/commands/clean/custom_command_clean_revisions.rst b/examples/extensions/commands/clean/custom_command_clean_revisions.rst index 48ece89d9ce8..95c27831658a 100644 --- a/examples/extensions/commands/clean/custom_command_clean_revisions.rst +++ b/examples/extensions/commands/clean/custom_command_clean_revisions.rst @@ -10,7 +10,7 @@ Custom command: Clean old recipe and package revisions without needing this custom command. -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/extensions/deployers/sources/custom_deployer_sources.rst b/examples/extensions/deployers/sources/custom_deployer_sources.rst index a3de2396970d..560cc698a9c6 100644 --- a/examples/extensions/deployers/sources/custom_deployer_sources.rst +++ b/examples/extensions/deployers/sources/custom_deployer_sources.rst @@ -5,7 +5,7 @@ Copy sources from all your dependencies -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/graph/tool_requires/different_options.rst b/examples/graph/tool_requires/different_options.rst index cc1e11142e0d..2040369196b7 100644 --- a/examples/graph/tool_requires/different_options.rst +++ b/examples/graph/tool_requires/different_options.rst @@ -18,7 +18,7 @@ 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 +``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 diff --git a/examples/graph/tool_requires/different_versions.rst b/examples/graph/tool_requires/different_versions.rst index 1ca498c03ca8..01e2dcec40e5 100644 --- a/examples/graph/tool_requires/different_versions.rst +++ b/examples/graph/tool_requires/different_versions.rst @@ -18,7 +18,7 @@ Will generate a "conflict", showing an error like ``Duplicated requirement``. Th 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 +scenario. Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ on GitHub: .. code-block:: shell diff --git a/examples/graph/tool_requires/using_protobuf.rst b/examples/graph/tool_requires/using_protobuf.rst index a0b05f72ad28..a6d39e2fc448 100644 --- a/examples/graph/tool_requires/using_protobuf.rst +++ b/examples/graph/tool_requires/using_protobuf.rst @@ -33,7 +33,7 @@ should look like: 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 +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ on GitHub: .. code-block:: shell diff --git a/examples/tools.rst b/examples/tools.rst index 08e335d36dac..422c7b169661 100644 --- a/examples/tools.rst +++ b/examples/tools.rst @@ -9,5 +9,6 @@ Conan recipe tools examples 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/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst b/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst index 25fbfa601fd1..c6722283cce3 100644 --- a/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst +++ b/examples/tools/autotools/autotools_toolchain/build_project_autotools_toolchain.rst @@ -9,7 +9,7 @@ that uses one of the most popular C++ libraries: `fmt `_ 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 +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ on GitHub: .. code-block:: shell diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst index ae25a2eb6e3f..f40525f4777b 100644 --- a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst +++ b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst @@ -8,7 +8,7 @@ generated ones. .. include:: ../../../../tutorial/cmake_presets_note.inc -Please, first of all, clone the sources to recreate this project. You can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/examples/tools/google/bazel.rst b/examples/tools/google/bazel.rst new file mode 100644 index 000000000000..d18cb9564763 --- /dev/null +++ b/examples/tools/google/bazel.rst @@ -0,0 +1,10 @@ +.. _examples_tools_bazel: + + +tools.google +============ + +.. toctree:: + :maxdepth: 2 + + bazeltoolchain/build_simple_bazel_project diff --git a/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst b/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst new file mode 100644 index 000000000000..47b41f833b62 --- /dev/null +++ b/examples/tools/google/bazeltoolchain/build_simple_bazel_project.rst @@ -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/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst b/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst index 355b4f094a08..64c98ce51901 100644 --- a/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst +++ b/examples/tools/meson/mesontoolchain/build_simple_meson_project.rst @@ -14,7 +14,7 @@ that uses one of the most popular C++ libraries: `Zlib `__. 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, at first, clone the sources to recreate this project, you can find them in the +Please, first clone the sources to recreate this project. You can find them in the `examples2.0 repository `_ in GitHub: .. code-block:: bash diff --git a/images/integrations/conan-bazel-logo.png b/images/integrations/conan-bazel-logo.png new file mode 100644 index 000000000000..4c331b2cdfaa Binary files /dev/null and b/images/integrations/conan-bazel-logo.png differ diff --git a/integrations.rst b/integrations.rst index 663dc92bfc22..88e4848512b3 100644 --- a/integrations.rst +++ b/integrations.rst @@ -18,6 +18,7 @@ Xcode. integrations/clion integrations/visual_studio integrations/autotools + integrations/bazel integrations/makefile integrations/xcode integrations/meson diff --git a/integrations/bazel.rst b/integrations/bazel.rst new file mode 100644 index 000000000000..ac606d24551e --- /dev/null +++ b/integrations/bazel.rst @@ -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/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst index cdc9ce4abba1..fb4ddc8d61f1 100644 --- a/reference/conanfile/attributes.rst +++ b/reference/conanfile/attributes.rst @@ -189,3 +189,34 @@ Currently these are the automatic implementations provided by Conan: .. 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)" + ... diff --git a/reference/conanfile/attributes/binary_model.inc b/reference/conanfile/attributes/binary_model.inc index ff585b8c8075..0149730fcfc1 100644 --- a/reference/conanfile/attributes/binary_model.inc +++ b/reference/conanfile/attributes/binary_model.inc @@ -113,7 +113,7 @@ For example, in the ``configure()`` method a typical pattern for a C library wou .. seealso:: - :ref:`reference_config_files_settings_yml`. - - Removing settings in the ``package_id()`` method. + - :ref:`Removing settings in the package_id() method`. .. _conan_conanfile_properties_options: @@ -233,7 +233,7 @@ Take into account that if a value is assigned in the ``configure()`` method it c .. seealso:: - Read more about the method_configure_config_options method. + Read more about the :ref:`config_options() method`. default_build_options --------------------- diff --git a/reference/conanfile/attributes/build.inc b/reference/conanfile/attributes/build.inc index 6b68cb652bbd..8fa24e4eecd5 100644 --- a/reference/conanfile/attributes/build.inc +++ b/reference/conanfile/attributes/build.inc @@ -13,7 +13,7 @@ List or tuple of strings with names of generators. generators = "CMakeDeps", "CMakeToolchain" -The generators can also be instantiated explicitly in the generate() method. +The generators can also be instantiated explicitly in the :ref:`generate() method`. .. code-block:: python diff --git a/reference/conanfile/attributes/folders.inc b/reference/conanfile/attributes/folders.inc index bc0ffe7eaac2..743b3ab09921 100644 --- a/reference/conanfile/attributes/folders.inc +++ b/reference/conanfile/attributes/folders.inc @@ -30,8 +30,8 @@ The value depends on the method you access it: .. seealso:: - - Read ``export_sources`` method. - - Read ``source`` method. + - :ref:`Read about the export_sources() method`. + - :ref:`Read about the source() method`. .. _attribute_build_folder: @@ -50,7 +50,8 @@ package_folder The folder to copy the final artifacts for the binary package. In the local cache a package folder is created for every different package ID. -The most common usage of ``self.package_folder`` is to ``copy`` the files at the package() method: +The most common usage of ``self.package_folder`` is to ``copy`` the files +at the :ref:`package() method`: .. code-block:: python diff --git a/reference/conanfile/attributes/requirements.inc b/reference/conanfile/attributes/requirements.inc index 2f50c505ba29..975dac50fa1a 100644 --- a/reference/conanfile/attributes/requirements.inc +++ b/reference/conanfile/attributes/requirements.inc @@ -85,7 +85,7 @@ won't be retrieved. They cannot conflict. tool_requires = "tool_a/0.2", "tool_b/0.2@user/testing" -This is the declarative way to add ``tool_requires``. Check the tool_requires() +This is the declarative way to add ``tool_requires``. Check the :ref:`tool_requires()` conanfile.py method to learn a more flexible way to add them. @@ -115,8 +115,9 @@ won't be retrieved. They cannot conflict. test_requires = "gtest/1.11.0", "other_test_tool/0.2@user/testing" -This is the declarative way to add ``test_requires``. Check the test_requires() -conanfile.py method to learn a more flexible way to add them. +This is the declarative way to add ``test_requires``. +Check the :ref:`test_requires() method` +to learn a more flexible way to add them. python_requires --------------- diff --git a/reference/conanfile/attributes/sources.inc b/reference/conanfile/attributes/sources.inc index 31a181a1bdeb..8c5bfdc08dfb 100644 --- a/reference/conanfile/attributes/sources.inc +++ b/reference/conanfile/attributes/sources.inc @@ -30,7 +30,7 @@ Exclude patterns are also possible, with the ``!`` prefix: .. seealso:: - - Check exports() conanfile.py method. + - :ref:`Check the export() conanfile.py method`. .. _exports_sources_attribute: @@ -91,7 +91,8 @@ or even better, from ``self.export_sources_folder``. conan_data ---------- -Read only attribute with a dictionary with the keys and values provided in a conandata_yml file format placed +Read only attribute with a dictionary with the keys and values provided in a +:ref:`conandata.yml` file format placed next to the *conanfile.py*. This YAML file is automatically exported with the recipe and automatically loaded with it too. You can declare information in the *conandata.yml* file and then access it inside any of the methods of the recipe. diff --git a/reference/conanfile/methods/build_requirements.rst b/reference/conanfile/methods/build_requirements.rst index 5ead063b3703..8cadace8cc48 100644 --- a/reference/conanfile/methods/build_requirements.rst +++ b/reference/conanfile/methods/build_requirements.rst @@ -16,6 +16,8 @@ For simple cases the attribute syntax can be enough, like ``tool_requires = "cma 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() --------------- @@ -94,6 +96,7 @@ should the *requires* and *tool_requires* have different names. For instance: - :ref:`examples_graph_tool_requires_protobuf` +.. _reference_conanfile_methods_build_requirements_test_requires: test_requires ------------- diff --git a/reference/conanfile/methods/layout.rst b/reference/conanfile/methods/layout.rst index 7ec124235e49..e248832313a3 100644 --- a/reference/conanfile/methods/layout.rst +++ b/reference/conanfile/methods/layout.rst @@ -63,28 +63,38 @@ Properties to declare all the information needed by the consumers of a package: library names, library paths... Used both for :ref:`editable packages` and regular packages in the cache. -There are four instances available, only while running the following methods: +There are three objects available in the ``layout()`` method: -- At ``layout(self)`` method: - - **self.cpp.package**: For a regular package being used from the Conan cache. - - **self.cpp.source**: For "editable" packages, to describe the artifacts under ``self.source_folder``. - - **self.cpp.build**: For "editable" packages, to describe the artifacts under ``self.build_folder``. +- **self.cpp.package**: For a regular package being used from the Conan cache. Describes the contents of the final package. + Exactly the same as in the ``package_info()`` ``self.cpp_info``, but in the ``layout()`` method. +- **self.cpp.source**: For "editable" packages, to describe the artifacts under ``self.source_folder``. These can cover: - .. code-block:: python + - ``self.cpp.source.includedirs``: To specify where the headers are at development time, like the typical ``src`` folder, + before being packaged in the ``include`` package folder. + - ``self.cpp.source.libdirs`` and ``self.cpp.source.libs`` could describe the case where libraries are committed to source + control (hopefully exceptional case), so they are not part of the build results, but part of the source. +- **self.cpp.build**: For "editable" packages, to describe the artifacts under ``self.build_folder``. - def layout(self): - ... - self.folders.source = "src" - self.folders.build = "build" + - ``self.cpp.build.libdirs`` will express the location of the built libraries before being packaged. They can often be found + in a folder like ``x64/Release``, or ``release64`` or similar. + - ``self.cpp.build.includedirs`` can define the location of headers that are generated at build time, like headers stubs + generated by some tools. - # In the local folder (before a conan create) the artifacts can be found: - self.cpp.source.includedirs = ["my_includes"] - self.cpp.build.libdirs = ["lib/x86_64"] - self.cpp.build.libs = ["foo"] +.. code-block:: python - # In the Conan cache, we packaged everything at the default standard directories, the library to link - # is "foo" - self.cpp.package.libs = ["foo"] + def layout(self): + ... + self.folders.source = "src" + self.folders.build = "build" + + # In the local folder (when the package is in development, or "editable") the artifacts can be found: + self.cpp.source.includedirs = ["my_includes"] + self.cpp.build.libdirs = ["lib/x86_64"] + self.cpp.build.libs = ["foo"] + + # In the Conan cache, we packaged everything at the default standard directories, the library to link + # is "foo" + self.cpp.package.libs = ["foo"] .. seealso:: diff --git a/reference/conanfile/methods/package_id.rst b/reference/conanfile/methods/package_id.rst index 93713fd8ba9a..058b284a9ed4 100644 --- a/reference/conanfile/methods/package_id.rst +++ b/reference/conanfile/methods/package_id.rst @@ -58,6 +58,8 @@ must be explicitly declared: self.info.settings.rm_safe("compiler.cppstd") +.. _reference_conanfile_methods_package_id_clear: + Information erasure ------------------- diff --git a/reference/conanfile/methods/requirements.rst b/reference/conanfile/methods/requirements.rst index a616a71b7c73..ceb20630ac53 100644 --- a/reference/conanfile/methods/requirements.rst +++ b/reference/conanfile/methods/requirements.rst @@ -3,6 +3,17 @@ requirements() ============== +The ``requirements()`` method is used to specify the dependencies of a package. + +.. code-block:: python + + def requirements(self): + self.requires("zlib/1.2.11") + + +For simple cases the attribute syntax can be used, like ``requires = "zlib/1.2.11"``. + + Requirement traits ^^^^^^^^^^^^^^^^^^ diff --git a/reference/config_files/settings.rst b/reference/config_files/settings.rst index 09831db9879b..77fb18ac85b9 100644 --- a/reference/config_files/settings.rst +++ b/reference/config_files/settings.rst @@ -215,7 +215,7 @@ control is desired, you can just add the ``update`` part to your profiles: [settings] compiler=msvc compiler.version=191 - compiler.version.update=3 + compiler.update=3 This will be equivalent to the full version ``1913 (19.13)``. If even further details are desired, you could even add your own digits diff --git a/reference/tools/cpp_info.rst b/reference/tools/cpp_info.rst index 7daa65515d4e..53bf0844642f 100644 --- a/reference/tools/cpp_info.rst +++ b/reference/tools/cpp_info.rst @@ -47,4 +47,7 @@ The public documented interface (besides the defined one in :ref:`the package_in - ``CppInfo(conanfile)``: Constructor. Receives a ``conanfile`` as argument, typically ``self`` - ``aggregated_components()``: return a new ``CppInfo`` object resulting from the aggregation of all the components +- ``get_sorted_components()``: Get the ordered components of a package, prioritizing those + with fewer dependencies within the same package. Returns an ``OrderedDict`` of sorted + components in the format ``{component_name: component}``. - ``merge(other_cppinfo: CppInfo)``: modifies the current ``CppInfo`` object, updating it with the information of the parameter ``other_cppinfo``, allowing to aggregate information from multiple dependencies. diff --git a/reference/tools/env/environment.rst b/reference/tools/env/environment.rst index cb88b8ca9444..fc37831391e0 100644 --- a/reference/tools/env/environment.rst +++ b/reference/tools/env/environment.rst @@ -5,7 +5,7 @@ Environment ``Environment`` is a generic class that helps to define modifications to the environment variables. -This class is used by other tools like the `conan.tools.gnu` autotools helpers and +This class is used by other tools like the `conan.tools.gnu` :ref:`Autotools` helpers and the :ref:`VirtualBuildEnv` and :ref:`VirtualRunEnv` generator. It is important to highlight that this is a generic class, to be able to use it, a specialization for the current context (shell script, bat file, path separators, etc), a ``EnvVars`` object needs to be obtained diff --git a/reference/tools/env/virtualbuildenv.rst b/reference/tools/env/virtualbuildenv.rst index 85266ed88f79..75f9c3ab73bd 100644 --- a/reference/tools/env/virtualbuildenv.rst +++ b/reference/tools/env/virtualbuildenv.rst @@ -3,7 +3,7 @@ VirtualBuildEnv =============== -VirtualBuildEnv is a generator that produces a *conanbuildenv* .bat or .sh script containing the environment variables +VirtualBuildEnv is a generator that produces a *conanbuildenv* .bat, .ps1 or .sh script containing the environment variables of the build time context: - From the ``self.buildenv_info`` of the direct ``tool_requires`` in "build" context. @@ -49,20 +49,23 @@ Generated files This generator (for example the invocation of ``conan install --tool-require=cmake/3.20.0@ -g VirtualBuildEnv``) will create the following files: -- conanbuildenv-release-x86_64.(bat|sh): This file contains the actual definition of environment variables +- conanbuildenv-release-x86_64.(bat|ps1|sh): This file contains the actual definition of environment variables like PATH, LD_LIBRARY_PATH, etc, and any other variable defined in the dependencies ``buildenv_info`` corresponding to the ``build`` context, and to the current installed configuration. If a repeated call is done with other settings, a different file will be created. After the execution or sourcing of this file, a new deactivation script will be generated, capturing the current environment, so the environment can be restored when desired. The file will be named also following the current active configuration, like ``deactivate_conanbuildenv-release-x86_64.bat``. -- conanbuild.(bat|sh): Accumulates the calls to one or more other scripts, in case there are multiple tools +- conanbuild.(bat|ps1|sh): Accumulates the calls to one or more other scripts, in case there are multiple tools in the generate process that create files, to give one single convenient file for all. This only calls the latest specific configuration one, that is, if ``conan install`` is called first for Release build type, - and then for Debug, ``conanbuild.(bat|sh)`` script will call the Debug one. -- deactivate_conanbuild.(bat|sh): Accumulates the deactivation calls defined in the above ``conanbuild.(bat|sh)``. + and then for Debug, ``conanbuild.(bat|ps1|sh)`` script will call the Debug one. +- deactivate_conanbuild.(bat|ps1|sh): Accumulates the deactivation calls defined in the above ``conanbuild.(bat|ps1|sh)``. This file should only be called after the accumulated activate has been called first. +.. note:: + + To create ``.ps1`` files required for Powershell it is necessary to set to True the following conf: ``tools.env.virtualenv:powershell``. Reference --------- diff --git a/reference/tools/env/virtualrunenv.rst b/reference/tools/env/virtualrunenv.rst index f74f058538e8..64e1d660129a 100644 --- a/reference/tools/env/virtualrunenv.rst +++ b/reference/tools/env/virtualrunenv.rst @@ -3,7 +3,7 @@ VirtualRunEnv ============= -``VirtualRunEnv`` is a generator that produces a launcher *conanrunenv* .bat or .sh script containing environment variables +``VirtualRunEnv`` is a generator that produces a launcher *conanrunenv* .bat, .ps1 or .sh script containing environment variables of the run time environment. The launcher contains the runtime environment information, anything that is necessary in the environment to actually run @@ -48,17 +48,20 @@ And it can also be fully instantiated in the conanfile ``generate()`` method: Generated files --------------- -- conanrunenv-release-x86_64.(bat|sh): This file contains the actual definition of environment variables +- conanrunenv-release-x86_64.(bat|ps1|sh): This file contains the actual definition of environment variables like PATH, LD_LIBRARY_PATH, etc, and ``runenv_info`` of dependencies corresponding to the ``host`` context, and to the current installed configuration. If a repeated call is done with other settings, a different file will be created. -- conanrun.(bat|sh): Accumulates the calls to one or more other scripts to give one single convenient file +- conanrun.(bat|ps1|sh): Accumulates the calls to one or more other scripts to give one single convenient file for all. This only calls the latest specific configuration one, that is, if ``conan install`` is called first for Release build type, - and then for Debug, ``conanrun.(bat|sh)`` script will call the Debug one. + and then for Debug, ``conanrun.(bat|ps1|sh)`` script will call the Debug one. After the execution of one of those files, a new deactivation script will be generated, capturing the current environment, so the environment can be restored when desired. The file will be named also following the current active configuration, like ``deactivate_conanrunenv-release-x86_64.bat``. +.. note:: + + To create ``.ps1`` files required for Powershell it is necessary to set to True the following conf: ``tools.env.virtualenv:powershell``. Reference --------- diff --git a/reference/tools/google/bazel.rst b/reference/tools/google/bazel.rst index 217171d0dc7a..6cdf6aff7714 100644 --- a/reference/tools/google/bazel.rst +++ b/reference/tools/google/bazel.rst @@ -49,3 +49,8 @@ conf - ``tools.google.bazel:bazelrc_path``: List of paths to other bazelrc files to be used as :command:`bazel --bazelrc=rcpath1 ... build`. - ``tools.google.bazel:configs``: List of Bazel configurations to be used as :command:`bazel build --config=config1 ...`. + + +.. seealso:: + + - :ref:`examples_tools_bazel_toolchain_build_simple_bazel_project` diff --git a/reference/tools/google/bazeldeps.rst b/reference/tools/google/bazeldeps.rst index adb145a8d7e0..9c9e2c197e03 100644 --- a/reference/tools/google/bazeldeps.rst +++ b/reference/tools/google/bazeldeps.rst @@ -266,3 +266,8 @@ Example: self.cpp_info.set_property("bazel_target_name", "my_target") self.cpp_info.set_property("bazel_repository_name", "my_repo") self.cpp_info.components["mycomponent"].set_property("bazel_target_name", "component_name") + + +.. seealso:: + + - :ref:`examples_tools_bazel_toolchain_build_simple_bazel_project` diff --git a/reference/tools/google/bazeltoolchain.rst b/reference/tools/google/bazeltoolchain.rst index 50de828d681f..26b14155176d 100644 --- a/reference/tools/google/bazeltoolchain.rst +++ b/reference/tools/google/bazeltoolchain.rst @@ -76,3 +76,8 @@ conf - ``tools.build:sharedlinkflags`` list of extra linker flags that will be used by ``linkopt``. - ``tools.build:exelinkflags`` list of extra linker flags that will be used by ``linkopt``. - ``tools.build:linker_scripts`` list of linker scripts, each of which will be prefixed with ``-T`` and added to ``linkopt``. + + +.. seealso:: + + - :ref:`examples_tools_bazel_toolchain_build_simple_bazel_project` diff --git a/tutorial/consuming_packages/build_simple_cmake_project.rst b/tutorial/consuming_packages/build_simple_cmake_project.rst index e341df08e76e..6857c28e1bfa 100644 --- a/tutorial/consuming_packages/build_simple_cmake_project.rst +++ b/tutorial/consuming_packages/build_simple_cmake_project.rst @@ -269,6 +269,6 @@ Now we are ready to build and run our **compressor** app: Read more --------- +- :ref:`Getting started with Autotools` - :ref:`Getting started with Meson` -- Getting started with Autotools -- ... +- :ref:`Getting started with Bazel` diff --git a/tutorial/consuming_packages/use_tools_as_conan_packages.rst b/tutorial/consuming_packages/use_tools_as_conan_packages.rst index 02baa42899c4..5a12b0e14547 100644 --- a/tutorial/consuming_packages/use_tools_as_conan_packages.rst +++ b/tutorial/consuming_packages/use_tools_as_conan_packages.rst @@ -87,6 +87,12 @@ files the folder *build*. To do that, just run: $ conan install . --output-folder=build --build=missing +.. note:: + + **Powershell** users need to add ``--conf=tools.env.virtualenv:powershell=True`` to the previous command + to generate ``.ps1`` files instead of ``.bat`` files. + To avoid the need to add this line every time, we recommend configuring it in the ``[conf]`` section of your profile. For detailed information, please refer to the :ref:`profiles section`. + You can check the output: .. code-block:: bash @@ -142,6 +148,7 @@ have installed the new CMake version in the path. $ cd build $ conanbuild.bat + # conanbuild.ps1 if using Powershell .. code-block:: bash :caption: Linux, macOS diff --git a/tutorial/developing_packages/package_layout.rst b/tutorial/developing_packages/package_layout.rst index b4513a39e410..b790845460b6 100644 --- a/tutorial/developing_packages/package_layout.rst +++ b/tutorial/developing_packages/package_layout.rst @@ -253,6 +253,17 @@ use to find headers and binaries. We defined: - ``self.cpp.build.libdirs`` set to ``["."]``. This location is relative to the ``self.folders.build`` that we defined to **./build/**. In the case of editable packages, this location will point to **/build/**. + + +Note that other ``cpp.source`` and ``cpp.build`` definitions are also possible, with different +meanings and purposes, for example: + +- ``self.cpp.source.libdirs`` and ``self.cpp.source.libs`` could be used if we had pre-compiled + libraries in the source repo, committed to git, for example. They are not a product of the build, + but rather part of the sources. +- ``self.cpp.build.includedirs`` could be use for folders containing headers generated at build + time, as it usually happens by some code generators that are fired by the build before starting + to compile the project. To check how this information affects consumers, we are going to first put the ``say`` package in editable mode and build it locally.