Frm/workspaces (#4138)

* Added new commands. Renamed other ones. Changed conanws.yml format

* wip

Author: franramirez688

reference/commands/workspace.rst

@@ -83,15 +83,13 @@ Use this command to show information about the current workspace
    WARN: Workspace is a dev-only feature, exclusively for testing
    name: myfolder
    folder: /path/to/myfolder
-   products
-      app1
    packages
-      liba/0.1
-         path: liba
-      libb/0.1
-         path: libb
-      app1/0.1
-         path: app1
+     - path: liba
+       ref: liba/0.1
+     - path: libb
+       ref: libb/0.1
+     - path: app1
+       ref: app1/0.1
 
 
 conan workspace clean
@@ -128,33 +126,55 @@ the ``conandata.yml`` (with ``git.coordinates_to_conandata()``) can be automatic
 current workspace from their Conan recipe reference (including recipe revision).
 
 
+conan workspace root
+--------------------
+
+.. autocommand::
+    :command: conan workspace root -h
+
+
+Return the folder containing the conanws.py/conanws.yml workspace file.
+
+
+conan workspace source
+----------------------
+
+.. autocommand::
+    :command: conan workspace source -h
+
+The command ``conan workspace source`` performs the equivalent of ``conan source <package-path>`` for every ``package``
+defined within the workspace.
+
+
 conan workspace build
 ---------------------
 
 .. autocommand::
     :command: conan workspace build -h
 
 
-The command ``conan workspace build`` does the equivalent of ``conan build <product-path> --build=editable``,
-for every ``product`` defined within the workspace.
+The command ``conan workspace build`` performs the equivalent of ``conan build <package-path>`` for every ``package``
+defined within the workspace in the correct order.
 
-Products are the "downstream" consumers, the "root" and starting node of dependency graphs. They can be defined with the
-``conan workspace add <folder> --product`` new ``--product`` argument.
 
-The ``conan workspace build`` command just iterates all products, so it might repeat the build of editables dependencies
-of the products. In most cases, it will be a no-op as the projects would be already built, but might still take some time.
-This is pending for optimization, but that will be done later, the important thing now is to focus on tools, UX, flows,
-and definitions (of things like the ``products``).
+conan workspace create
+----------------------
+
+.. autocommand::
+    :command: conan workspace create -h
+
+The command ``conan workspace create`` performs the equivalent of ``conan create <package-path>`` for every ``package``
+defined within the workspace in the correct order. They will be created in the Conan cache, not locally.
 
 
-conan workspace install
------------------------
+conan workspace super-install
+-----------------------------
 
 .. autocommand::
     :command: conan workspace install -h
 
 
-The command ``conan workspace install`` is useful to install and build the current workspace
+The command ``conan workspace super-install`` is useful to install and build the current workspace
 as a monolithic super-project of the editables.
 
 By default it uses all the ``editable`` packages in the workspace. It is possible to select

reference/workspace_files.rst

@@ -10,17 +10,27 @@ Workspaces are defined by the ``conanws.yml`` and/or ``conanws.py`` files that w
 conanws.yml
 -----------
 
-The most basic implementation of a workspace is a ``conanws.yml`` file. It defines the workspace's ``packages`` (editable dependencies)
-and ``products`` (root consumers). For instance, a workspace ``conanws.yml`` defining 2 ``packages`` could be:
+The most basic implementation of a workspace is a ``conanws.yml`` file. It defines the workspace's ``packages`` (editable packages).
+For instance, a workspace ``conanws.yml`` defining 2 ``packages`` could be:
 
 .. code-block:: yaml
    :caption: conanws.yml
 
    packages:
-      dep1/0.1:
-         path: dep1
-      dep2/0.1:
-         path: dep2
+      - path: dep1
+        ref: dep1/0.1
+      - path: dep2
+        ref: dep2/0.1
+
+
+Moreover, it could not have the ``ref`` field, and let Conan read the *name/version* from the respective *path/conanfile.py*:
+
+.. code-block:: yaml
+   :caption: conanws.yml
+
+   packages:
+      - path: dep1
+      - path: dep2
 
 
 conanws.py
@@ -39,14 +49,14 @@ on the existence of some ``name.txt`` and ``version.txt`` files in folders, the
    class MyWorkspace(Workspace):
 
       def packages(self):
-         result = {}
+         result = []
          for f in os.listdir(self.folder):
             if os.path.isdir(os.path.join(self.folder, f)):
                with open(os.path.join(self.folder, f, "name.txt")) as fname:
                   name = fname.read().strip()
                with open(os.path.join(self.folder, f, "version.txt")) as fversion:
                   version = fversion.read().strip()
-               result[f"{name}/{version}"] = {"path": f}
+               result.append({"path": f, "ref": f"{name}/{version}"})
          return result
 
 
@@ -61,11 +71,11 @@ methods, using the ``Workspace.load_conanfile()`` helper:
 
    class MyWorkspace(Workspace):
       def packages(self):
-         result = {}
+         result = []
          for f in os.listdir(self.folder):
             if os.path.isdir(os.path.join(self.folder, f)):
                conanfile = self.load_conanfile(f)
-               result[f"{conanfile.name}/{conanfile.version}"] = {"path": f}
+               result.append({"path": f, "ref": f"{conanfile.name}/{conanfile.version}"})
          return result
 
 

tutorial/developing_packages/workspaces.rst

@@ -26,7 +26,7 @@ A Conan *workspace* gives you the chance to manage several packages as ``editabl
 * *monolithic*, we denote the editable packages built as a monolith, generating a single result (generators, etc) for the whole workspace.
 
 Notice that the packages added to the workspace are automatically resolved as ``editable`` ones. Those editable packages
-are named as workspace's ``packages``. Also, the root consumers of those ``packages`` are named as ``products``.
+are named as workspace's ``packages``.
 
 
 How to define a workspace
@@ -37,7 +37,7 @@ up the file system from the current working directory to the filesystem root, un
 define the "root" workspace folder. The paths in the ``conanws`` file are intended to be relative to be relocatable if
 necessary, or could be committed to Git in monorepo-like projects.
 
-Through the ``conan workspace`` command, we can open, add, and/or remove ``packages`` and ``products`` from the current workspace.
+Through the ``conan workspace`` command, we can open, add, and/or remove ``packages`` from the current workspace.
 
 .. seealso::
 
@@ -206,8 +206,8 @@ the same when there are external dependencies. This can be tested with:
 Orchestrated build
 ------------------
 
-Conan workspaces can also build the different ``packages`` separately, and taking into account if there are ``products``
-consuming them.
+Conan workspaces can also build the different ``packages`` separately, and taking into account if there are packages defined
+as consumers of the other ones.
 
 Let's use another structure to understand better how it works. Now, let's create it from scratch with the ``conan workspace init .`` that creates an almost empty conanws.py/conanws.yml, and using the ``conan new cmake_lib/cmake_exe`` basic templates, that create regular CMake-based conan packages:
 
@@ -249,16 +249,16 @@ Those commands created a file structure like this:
 
 
 Now, the ``conanws.yml`` is empty and the ``conanws.py`` has a quite minimal definition. Let's add the ``app`` application
-(consumes ``hello``) and the ``hello`` lib as a new ``products`` and ``packages`` respectively to the workspace:
+(consumes ``hello``) and the ``hello`` lib as new ``packages`` to the workspace:
 
 .. code-block:: bash
 
    $ conan workspace add hello
    Reference 'hello/1.0' added to workspace
-   $ conan workspace add app --product
+   $ conan workspace add app
    Reference 'app/1.0' added to workspace
 
-Defined the workspace's ``packages`` and ``products``, we can build them and execute the application:
+Defined the workspace's ``packages``, we can build them and execute the application:
 
 .. code-block:: bash