[graph] JSON format reference

examples/extensions.rst

@@ -7,4 +7,5 @@ Conan extensions examples
    :maxdepth: 2
 
    extensions/commands/custom_commands
+   extensions/deployers/builtin_deployers
    extensions/deployers/custom_deployers

examples/extensions/commands/clean/custom_command_clean_revisions.rst

@@ -3,6 +3,13 @@
 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 of all, clone the sources to recreate this project. You can find them in the
 `examples2.0 repository <https://github.com/conan-io/examples2>`_ in GitHub:
 
@@ -173,6 +180,8 @@ Important classes to manage user input and user output:
 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:
 

examples/extensions/deployers/builtin_deployers.rst

@@ -0,0 +1,10 @@
+.. _examples_extensions_builtin_deployers:
+
+
+Builtin deployers
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   dev/development_deploy

examples/extensions/deployers/dev/development_deploy.rst

@@ -0,0 +1,134 @@
+.. _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.
+
+Let's see it with an example. All the source code is in the
+`examples2.0 Github repository <https://github.com/conan-io/examples2>`_
+
+.. 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 . --deploy=full_deploy --build=missing
+    $ conan install . --deploy=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
+
+
+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. 
+
+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 <https://stackoverflow.com/questions/29832037/how-to-get-script-directory-in-posix-sh/29835459#29835459>`_.
+
+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.

examples/extensions/deployers/sources/custom_deployer_sources.rst

@@ -31,7 +31,7 @@ Conan will look for the specified deployer in a few extra places in order, namel
 
 #. Absolute paths
 #. Relative to cwd
-#. In the ``[CONAN_HOME]/extensions/deploy`` folder
+#. In the ``[CONAN_HOME]/extensions/deployers`` folder
 #. Built-in deployers
 
 

knowledge.rst

@@ -8,6 +8,7 @@ Knowledge
    :maxdepth: 2
 
 
+   knowledge/cheatsheet
    knowledge/guidelines
    knowledge/faq
    knowledge/videos

knowledge/cheatsheet.rst

@@ -0,0 +1,16 @@
+***********
+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.
+
+  :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

reference/commands.rst

@@ -15,7 +15,7 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
    :caption: Consumer commands
    :maxdepth: 1
    :hidden:
-   
+
    commands/cache
    commands/config
    commands/graph
@@ -69,3 +69,23 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
 - :doc:`conan source <commands/source>`: Calls the source() method
 - :doc:`conan test <commands/test>`: Test a package
 - :doc:`conan upload <commands/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 <commands/formatters/graph_info_json_formatter>`: Show the graph information in JSON
+  format. It's used by several commands.

reference/commands/create.rst

@@ -118,13 +118,6 @@ conan create
 
 The ``conan create`` command creates a package from the recipe specified in ``path``.
 
-
-.. warning::
-
-  The json output of the ``conan create --format=json`` is **experimental** and subject to
-  change.
-
-
 This command will first ::comnand::`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
@@ -140,6 +133,12 @@ the package has been created correctly. Check :ref:`testing Conan packages
 
         $ conan create . --test-folder=
 
+
+.. seealso::
+
+    - Check the :ref:`JSON format output <reference_commands_graph_info_json_format>` for this command.
+
+
 Using conan create with build requirements
 ------------------------------------------
 

reference/commands/export-pkg.rst

@@ -77,11 +77,8 @@ The ``conan export-pkg`` command creates a package binary directly from pre-comp
 
 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.
 
-.. warning::
-
-  The json output of the ``conan export-pkg --format=json`` is **experimental** and subject to
-  change.
 
 .. seealso::
 
-    - Read the tutorial about the :ref:`local package developement flow <local_package_development_flow>`.
+    - Check the :ref:`JSON format output <reference_commands_graph_info_json_format>` for this command.
+    - Read the tutorial about the :ref:`local package development flow <local_package_development_flow>`.