From b7a8864a86dbc1878f36ebb22c94a2177fc6f984 Mon Sep 17 00:00:00 2001 From: memsharded Date: Tue, 25 Nov 2025 12:36:37 +0100 Subject: [PATCH 1/4] workspace packages --- reference/workspace_files.rst | 118 ++++++++++++++++++++++++++++++++-- 1 file changed, 113 insertions(+), 5 deletions(-) diff --git a/reference/workspace_files.rst b/reference/workspace_files.rst index c621297d4919..873977d3f300 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace_files.rst @@ -79,14 +79,121 @@ methods, using the ``Workspace.load_conanfile()`` helper: return result +conanws.py super-build ``ConanFile`` +++++++++++++++++++++++++++++++++++++ + +The ``conanws.py`` file can contain the definition of a ``ConanFile`` that represents the super-build. When the workspace dependency graph +is computed, all packages in the workspace are collapsed into a single node in the dependency graph, and that node will have dependencies +to the other packages external to the workspace, that is, installed in the Conan cache. + +The ``ConanFile`` that represents the workspace super-build project is defined as: + +.. code-block:: python + :caption: conanws.py + + from conan import ConanFile, Workspace + + class MyWs(ConanFile): + settings = "os", "compiler", "arch", "build_type" + generators = "CMakeToolchain", "CMakeDeps" + + class Ws(Workspace): + def root_conanfile(self): + return MyWs + + +To define that our super-build project will be a CMake project that uses the ``CMakeToolchain`` and ``CMakeDeps`` generators to integrate +and find the external package dependencies. +It is not necessary that the ``ConanFile`` defines ``requires`` at all, they will be computed by aggregating the requires of all packages +in the workspace. + + +conanws.py super-build workspace packages ++++++++++++++++++++++++++++++++++++++++++ + +With the ``workspace_packages`` attribute, the ``conanws.py`` super-build ``ConanFile`` can have access to the workspace packages, to +be able to reuse their functionality. +For example, if we wanted to collect the behavior of workspace packages toolchain definitions we could do the following. +Let's imagine that we have a workspace with 2 packages, ``pkga/1.2.3`` and ``pkgb/2.3.4`` + +.. code-block:: python + :caption: pkga/conanfile.py + + from conan import ConanFile + + class PkgA(ConanFile): + name = "pkga" + version = "1.2.3" + + def configure_toolchain(self, tc): + tc.preprocessor_definitions["PKGA_SOME_DEFINITION"] = self.version + + def generate(self): + tc = CMakeToolchain(self) + self.configure_toolchain(tc) + tc.generate() + + +.. code-block:: python + :caption: pkg/conanfile.py + + from conan import ConanFile + class PkgB(ConanFile): + name = "pkgb" + version = "2.3.4" + + def configure_toolchain(self, tc): + tc.preprocessor_definitions["SOME_PKGB_DEFINE"] = self.version + + def generate(self): + tc = CMakeToolchain(self) + self.configure_toolchain(tc) + tc.generate() + + +.. code-block:: python + :caption: conanws.py + + from conan import ConanFile + from conan import Workspace + from conan.tools.cmake import CMakeToolchain + + class MyWs(ConanFile): + settings = "arch", "build_type" + def generate(self): + tc = CMakeToolchain(self) + for ref, dep in self.workspace_packages.items(): + dep.configure_toolchain(tc) + tc.generate() + + class Ws(Workspace): + def root_conanfile(self): + return MyWs + + +Then, the ``workspace_packages.items()`` iteration will be able to call every package in the workspace ``configure_toolchain()`` and +collect all their behavior in the current super-build ``CMakeToolchain``. The resulting toolchain will contain the definitions for +``SOME_PKGB_DEFINE=2.3.4`` and ``PKGA_SOME_DEFINITION=1.2.3``. + +.. warning:: + + **Important** + + The access of ``workspace_packages`` to the workspace packages ``ConanFiles`` must be **read-only** and **pure**. It cannot modify + the workspace ``pkga`` and ``pkgb`` packages data, and it cannot have any side effect. For example it is forbidden to call any method such as ``.build()`` + or even the ``.generate()`` method. + If there is logic to be reused, it is the responsibility of the developer to define some convention, such as the ``configure_toolchain()`` + method that if called from the ``conanws.py`` will not modify at all (pure) the ``pkga`` or ``pkgb`` data. + conanws.py super-build options ++++++++++++++++++++++++++++++ +A particular case of the above ``workspace_packages`` access could be reading the individual workspace packages options. A ``conanws.py`` used for a super-build workspaces file can manage options in two different ways: - It can define its own ``options`` with the normal ``conanfile.py`` syntax, so the generated ``conan_toolchain.cmake`` for the super-project uses those inputs. -- It can collect the options of the workspace's packages with the ``workspace_packages_options`` and process them in any user-custom way. +- It can collect the options of the workspace's packages with the ``workspace_packages`` and process them in any user-custom way. **super-project options** @@ -117,9 +224,10 @@ Then, options can be provided with the usual syntax, via profiles or command lin Note there can be overlap with the ``options`` defined in the workspace packages, as for super-projects those options are simply ignored, and only the options of the super-project are taken into account to generate the ``conan_toolchain.cmake``. For example, the ``conanws.py`` can define a ``shared`` option if it is desired that the ``conan_toolchain.cmake`` will correctly define ``BUILD_SHARED_LIBS`` or not when defining something like ``-o "*:shared=True"``, as the workspace packages having the ``shared`` option information is discarded when the workspace packages are collapsed in the dependency graph to model the super-project. + **packages options** -The second alternative is to collect the ``options`` of the workspace packages that have been collapsed. Recall that in the final dependency graph, the workspace packages are no longer represented, as they are no longer individual packages but part as the current super-build. The way to access their options information is via the ``workspace_packages_options``, and that information can be used in the ``generate()`` method to do any desired action at the super-build project level. +The second alternative is to collect the ``options`` of the workspace packages that have been collapsed. Recall that in the final dependency graph, the workspace packages are no longer represented, as they are no longer individual packages but part as the current super-build. The way to access their options information is via the ``workspace_packages``, and that information can be used in the ``generate()`` method to do any desired action at the super-build project level. So let's say that a workspace containing a ``dep/0.1`` package that contains the standard ``shared`` options defines the following super-build ``ConanFile``: @@ -130,9 +238,9 @@ So let's say that a workspace containing a ``dep/0.1`` package that contains the class MyWs(ConanFile): def generate(self): - for pkg, options in self.workspace_packages_options.items(): - for k, v in options.items(): - self.output.info(f"Generating with opt {pkg}:{k}={v}!!!!") + for pkg, dep in self.workspace_packages.items(): + for k, v in dep.options.items(): + self.output.info(f"Generating with opt {pkg}:{k}={v}!!!!") class Ws(Workspace): def root_conanfile(self): From 0c64754b8d3769b41a0a634f454aa28805c84ca8 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 25 Nov 2025 13:18:34 +0100 Subject: [PATCH 2/4] Update reference/workspace_files.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Francisco Ramírez --- reference/workspace_files.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/workspace_files.rst b/reference/workspace_files.rst index 873977d3f300..fdf8c804a155 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace_files.rst @@ -102,7 +102,7 @@ The ``ConanFile`` that represents the workspace super-build project is defined a return MyWs -To define that our super-build project will be a CMake project that uses the ``CMakeToolchain`` and ``CMakeDeps`` generators to integrate +It defines that our super-build project will be a CMake project that uses the ``CMakeToolchain`` and ``CMakeDeps`` generators to integrate and find the external package dependencies. It is not necessary that the ``ConanFile`` defines ``requires`` at all, they will be computed by aggregating the requires of all packages in the workspace. From ecd4790cc9c047017b7abfdccb2a4d0f41f04d56 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 25 Nov 2025 13:18:47 +0100 Subject: [PATCH 3/4] Update reference/workspace_files.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Francisco Ramírez --- reference/workspace_files.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/workspace_files.rst b/reference/workspace_files.rst index fdf8c804a155..292a509bba48 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace_files.rst @@ -135,7 +135,7 @@ Let's imagine that we have a workspace with 2 packages, ``pkga/1.2.3`` and ``pkg .. code-block:: python - :caption: pkg/conanfile.py + :caption: pkgb/conanfile.py from conan import ConanFile class PkgB(ConanFile): From d57619d461cf9348eb42196bfa30113473cfcdcc Mon Sep 17 00:00:00 2001 From: memsharded Date: Tue, 25 Nov 2025 13:23:31 +0100 Subject: [PATCH 4/4] review --- reference/workspace_files.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/reference/workspace_files.rst b/reference/workspace_files.rst index 292a509bba48..70c6c5d30e5a 100644 --- a/reference/workspace_files.rst +++ b/reference/workspace_files.rst @@ -92,11 +92,16 @@ The ``ConanFile`` that represents the workspace super-build project is defined a :caption: conanws.py from conan import ConanFile, Workspace + from conan.tools.cmake import cmake_layout class MyWs(ConanFile): settings = "os", "compiler", "arch", "build_type" generators = "CMakeToolchain", "CMakeDeps" + def layout(self): + cmake_layout(self) + + class Ws(Workspace): def root_conanfile(self): return MyWs @@ -107,6 +112,13 @@ and find the external package dependencies. It is not necessary that the ``ConanFile`` defines ``requires`` at all, they will be computed by aggregating the requires of all packages in the workspace. +.. important:: + + The ``ConanFile`` inside ``conanws.py`` is a special conanfile, used exclusively for the workspace super-build definition of layout and + generators. It shouldn't have any kind of requirements, not regular ``requires``, ``tool_requires`` or ``test_requires``. It obtains + its dependencies collecting and aggregating the workspace packages requirements. + It shouldn't have ``build()`` or ``package()`` methods either. + conanws.py super-build workspace packages +++++++++++++++++++++++++++++++++++++++++