new conan_build_info help

howtos/generic_ci_artifactory.rst

@@ -11,8 +11,11 @@ If you are using :ref:`Jenkins with Conan and Artifactory<jenkins_integration>`,
 any Conan package downloaded or uploaded during your build will be automatically recorded in
 the BuildInfo json file, that will be automatically uploaded to the specified Artifactory instance.
 
-However, you can gather and upload that information using other CI infrastructure with the following steps:
+However, using the `conan_build_info` command, you can gather and upload that information using other
+CI infrastructure. There are two possible ways of using this commmand:
 
+Extracting build-info from the Conan trace log
+##############################################
 
 1. Before calling Conan the first time in your build, set the environment variable `CONAN_TRACE_FILE` to a
    file path. The generated file will contain the `BuildInfo json <https://www.jfrog.com/confluence/display/RTF/Build+Integration#BuildIntegration-BuildInfoJSON>`_.
@@ -58,3 +61,74 @@ However, you can gather and upload that information using other CI infrastructur
 .. code-block:: bash
 
     curl -X PUT -u<username>:<password> -H "Content-type: application/json" -T /tmp/build_info.json "http://host:8081/artifactory/api/build"
+
+Generating build info from lockfiles information 
+################################################
+
+.. warning::
+
+    This is an **experimental** feature subject to breaking changes in future releases.
+
+To maintain compatibility with the current implementation of the ``conan_build_info`` command, this
+version must be invoked using the argument ``--v2`` before any subcommand.
+
+1. To begin associating the build information to the uploaded packages the first thing
+is calling to the ``start`` subcommand of ``conan_build_info``. This will set the
+`artifact_property_build.name` and `artifact_property_build.name` properties in the
+:ref:`artifacts.properties<artifacts.properties>`.
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 start MyBuildName 42
+
+2. Call Conan using :ref:`lockfiles<versioning_lockfiles>` to create information for the 
+`Build Info json format <https://github.com/jfrog/build-info>`_.
+
+.. code-block:: bash
+
+    $ cd mypackage
+    $ conan create . mypackage/1.0@user/stable # We create one package
+    $ cd .. && cd consumer
+    $ conan install . # Consumes mypackage, generates a lockfile
+    $ conan create . consumer/1.0@user/stable --lockfile conan.lock
+    $ conan upload * -c -r local # Upload all packages to local remotes
+
+3. Create build information based on the contents of the generated `conan.lock` lockfile and the
+information retrieved from the remote (the authentication is for the remote where you uploaded the
+packages).
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 create buildinfo.json --lockfile conan.lock --user admin --password password
+
+
+4. Publish the build information to Artifactory with the ``publish`` subcommand:
+
+Using user and password
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 publish buildinfo.json --url http://localhost:8081/artifactory --user admin --password password
+
+or an API key:
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 publish buildinfo.json --url http://localhost:8081/artifactory --apikey apikey
+
+5. If the whole process has finished and you don't want to continue associating the build number and
+build name to the files uploaded to Artifactory then you can use the ``stop`` subcommand:
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 stop
+
+It is also possible to merge different build info files using the ``update`` subcommand. This is
+useful in CI when `many slaves <https://github.com/conan-io/examples/tree/master/features/lockfiles/ci>`_ 
+are generating different build info files.
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 update buildinfo1.json buildinfo2.json --output-file mergedbuildinfo.json
+
+You can check the complete :ref:`conan_build_info reference<conan_build_info>`.

reference/commands.rst

@@ -69,6 +69,7 @@ Other useful commands:
   commands/misc/inspect.rst
   commands/misc/graph.rst
   commands/misc/help.rst
+  commands/misc/conan_build_info.rst
 
 
 

reference/commands/misc/conan_build_info.rst

@@ -0,0 +1,129 @@
+
+.. _conan_build_info:
+
+conan_build_info v1
+-------------------
+
+.. code-block:: bash
+
+    usage: conan_build_info [-h] [--output OUTPUT] trace_path
+
+    Extracts build-info from a specified conan trace log and return a valid JSON
+
+    positional arguments:
+      trace_path       Path to the conan trace log file e.g.: /tmp/conan_trace.log
+
+    optional arguments:
+      -h, --help       show this help message and exit
+      --output OUTPUT  Optional file to output the JSON contents, if not specified
+                      the JSON will be printed to stdout
+
+
+conan_build_info v2
+-------------------
+
+.. code-block:: bash
+
+    $ conan_build_info --v2 [-h] {start,stop,create,update,publish} ...
+
+.. code-block:: bash
+
+    Generates build info build info from lockfiles information
+
+    positional arguments:
+      {start,stop,create,update,publish}
+                            sub-command help
+        start               Command to incorporate to the artifacts.properties the
+                            build name and number
+        stop                Command to remove from the artifacts.properties the
+                            build name and number
+        create              Command to generate a build info json from a lockfile
+        update              Command to update a build info json with another one
+        publish             Command to publish the build info to Artifactory
+
+    optional arguments:
+      -h, --help            show this help message and exit
+
+**start subcommand**:
+
+.. code-block:: bash
+
+    usage: conan_build_info --v2 start [-h] build_name build_number
+
+    positional arguments:
+      build_name    build name to assign
+      build_number  build number to assign
+
+    optional arguments:
+      -h, --help    show this help message and exit
+
+**stop subcommand**:
+
+.. code-block:: bash
+
+    usage: conan_build_info --v2 stop [-h]
+
+    optional arguments:
+      -h, --help  show this help message and exit
+
+**create subcommand**:
+
+.. code-block:: bash
+
+    usage: conan_build_info --v2 create [-h] --lockfile LOCKFILE
+                                        [--multi-module [MULTI_MODULE]]
+                                        [--skip-env [SKIP_ENV]] [--user [USER]]
+                                        [--password [PASSWORD]] [--apikey [APIKEY]]
+                                        build_info_file
+
+    positional arguments:
+      build_info_file       build info json for output
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --lockfile LOCKFILE   input lockfile
+      --multi-module [MULTI_MODULE]
+                            if enabled, the module_id will be identified by the
+                            recipe reference plus the package ID
+      --skip-env [SKIP_ENV]
+                            capture or not the environment
+      --user [USER]         user
+      --password [PASSWORD]
+                            password
+      --apikey [APIKEY]     apikey
+
+**publish subcommand**:
+
+.. code-block:: bash
+
+    usage: conan_build_info --v2 publish [-h] --url URL [--user [USER]]
+                                         [--password [PASSWORD]] [--apikey [APIKEY]]
+                                         buildinfo
+
+    positional arguments:
+      buildinfo             build info to upload
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --url URL             url
+      --user [USER]         user
+      --password [PASSWORD]
+                            password
+      --apikey [APIKEY]     apikey
+
+
+**update subcommand**:
+
+.. code-block:: bash
+
+    usage: conan_build_info --v2 update [-h] [--output-file OUTPUT_FILE]
+                                        buildinfo [buildinfo ...]
+
+    positional arguments:
+      buildinfo             buildinfo files to merge
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --output-file OUTPUT_FILE
+                            path to generated build info file
+