new profile args in build-order files (#3884)

Co-authored-by: Abril Rincón Blanco <rubenrb@jfrog.com>

bo.json

@@ -0,0 +1,88 @@
+{
+    "order_by": "recipe",
+    "reduced": false,
+    "order": [
+        [
+            {
+                "ref": "zlib/1.3.1#f52e03ae3d251dec704634230cd806a2",
+                "depends": [],
+                "packages": [
+                    [
+                        {
+                            "package_id": "8b7e35f91e516e42ed736c6dd52a9263da3a5dad",
+                            "prev": null,
+                            "context": "host",
+                            "binary": "Missing",
+                            "options": [],
+                            "filenames": [],
+                            "depends": [],
+                            "overrides": {},
+                            "build_args": null,
+                            "info": {
+                                "settings": {
+                                    "os": "Windows",
+                                    "arch": "x86_64",
+                                    "compiler": "msvc",
+                                    "compiler.runtime": "dynamic",
+                                    "compiler.runtime_type": "Debug",
+                                    "compiler.version": "194",
+                                    "build_type": "Debug"
+                                },
+                                "options": {
+                                    "shared": "False"
+                                }
+                            }
+                        }
+                    ]
+                ]
+            }
+        ],
+        [
+            {
+                "ref": "libpng/1.5.30#efa4bfdf973993197dbaa85b8c320723",
+                "depends": [
+                    "zlib/1.3.1#f52e03ae3d251dec704634230cd806a2"
+                ],
+                "packages": [
+                    [
+                        {
+                            "package_id": "34b444759868b4ce4f04f81d4ad4927bd78d7d3e",
+                            "prev": null,
+                            "context": "host",
+                            "binary": "Missing",
+                            "options": [],
+                            "filenames": [],
+                            "depends": [],
+                            "overrides": {},
+                            "build_args": null,
+                            "info": {
+                                "settings": {
+                                    "os": "Windows",
+                                    "arch": "x86_64",
+                                    "compiler": "msvc",
+                                    "compiler.runtime": "dynamic",
+                                    "compiler.runtime_type": "Debug",
+                                    "compiler.version": "194",
+                                    "build_type": "Debug"
+                                },
+                                "options": {
+                                    "api_prefix": "",
+                                    "shared": "False",
+                                    "sse": "True"
+                                },
+                                "requires": [
+                                    "zlib/1.3.Z"
+                                ]
+                            }
+                        }
+                    ]
+                ]
+            }
+        ]
+    ],
+    "profiles": {
+        "self": {
+            "args": "-pr:h=\"default\" -s:h=\"build_type=Debug\""
+        }
+    }
+}

reference/commands/graph/build_order.rst

@@ -87,15 +87,25 @@ Let's consider installing `libpng` and wanting to see the build order for this r
                     ]
                 }
             ]
-        ]
+        ],
+        "profiles": {
+            "self": {
+                "args": ""
+            }
+        }
     }
 
 
-Firstly, we can see the `zlib` package, as `libpng` depends on it. The output is sorted by
+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`.
 
+At the end of the json, after the ``order`` field, we see a ``profiles`` field, which contains the profile related command line arguments for the current "build-order". As in this case we didn't provide any arguments, it is empty. But if we used something like ``conan graph build-order ... -pr=default -s build_type=Debug > bo.json``, the ``args`` will contain those arguments (with json character escaping): ``"args": "-pr:h=\"default\" -s:h=\"build_type=Debug\""``
+
+
+Using ``--order-by=configuration`` we will get a different build-order format:
+
 .. code-block:: text
 
     $ conan graph build-order --requires=libpng/1.5.30 --format=json --order-by=configuration

reference/commands/graph/build_order_merge.rst

@@ -12,4 +12,20 @@ Note that only build-orders that haven't been reduced with ``--reduce`` can be m
 
 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.
-
+
+
+When 2 or more "build-order" files are merged, the resulting merge contains a ``profiles`` section like:
+
+.. code-block:: json
+
+    "profiles": {
+        "build_order_win": {
+            "args": "-pr:h=\"profile1\" -s:h=\"os=Windows\" ..."
+        },
+        "build_order_nix": {
+            "args": "-pr:h=\"profile2\" -s:h=\"os=Linux\" ..."
+        }
+    }
+
+With the ``build_order_win`` and ``build_order_nix`` being the "build-order" filenames that were used as inputs to the merge, and which will be referenced in the ``filenames`` field of every ``package`` in the build order. This way, it is easier to obtain the necessary command line arguments to build a specific package binary in the build-order when building multiple configurations.
+