Building and Using |bpt| in Another Build System
##################################################

.. default-role:: term

One of |bpt|'s primary goals is to inter-operate with other build systems
cleanly. One of |bpt|'s primary outputs is machine-readable `JSON` summary of
its build results. |bpt| also supports emitting a ``include()-able`` CMake_
module for consumption by older CMake versions that cannot parse the JSON
natively.

.. _PMM: https://github.com/vector-of-bool/PMM

.. _CMakeCM: https://github.com/vector-of-bool/CMakeCM

.. _CMake: https://cmake.org

.. _lm-cmake: https://raw.githubusercontent.com/vector-of-bool/libman/develop/cmake/libman.cmake


Generating a Build for Importing
********************************

In order to import and link against libraries built by |bpt|, one needs to first
run a build and generate the appropriate build results manifest. **This manifest
is not generated globally**: It is generated on a per-build basis as part of the
build process. The manifest will describe in build-system-agnostic terms how to
include and link against as set of libraries generated by a build.

|bpt| has first-class support for generating this index. The ``build-deps``
subcommand of |bpt| will download and build a set of dependencies, and places
a `JSON` file that can be used to import the built results.

.. note::

  Alternatively, for CMake projects, one can use the
  :option:`--cmake <bpt-build-deps --cmake>` option to write a CMake script that
  defines the needed ``IMPORTED`` targets. Refer: :doc:`cmake`

The :doc:`build-deps </guide/cli/build-deps>` command accepts a list of
`dependency specifiers <dependency specifier>` as positional
`command-line arguments`. |bpt| will attempt to generate a dependency solution
using that set of dependencies and will then obtain and build their sources.


Declaring Dependencies in a File
================================

``bpt build-deps`` accepts a list of
`dependency specifiers <dependency specifier>` as command line arguments, but it
may be useful to specify those requirements in a file.

``bpt build-deps`` accepts a YAML file describing the dependencies of a project
as well. The only required property in the file is the ``dependencies`` key.
(The presence of any other key is an error.)

Here is a simple dependencies file that declares a single requirement:

.. code-block:: yaml
  :caption: ``dependencies.yaml``

  dependencies: [
    'neo-sqlite3^0.2.0'
  ]

.. seealso::

  The :yaml:`dependencies` array is an array of `dependency specifier` strings,
  the same as those that would be used in a |bpt.yaml| project file.


Building Dependencies and the Manifest
======================================

We can invoke ``bpt build-deps`` and give it the path to this file:

.. code-block:: bash

  $ bpt build-deps --deps-file dependencies.yaml

When finished, |bpt| will write the build results into a subdirectory called
``_deps`` and generate a file named ``_built.json``. This file is ready to be
imported into any build system that can understand its simple schema.

.. note::

  The output directory and manifest filepath can be controlled with the
  :option:`--out <bpt-build-deps --out>` and
  :option:`--built-json <bpt-build-deps --built-json>` flags, respectively.


CMake Integration
*****************

.. seealso::

  Using |bpt| libraries in CMake is a significant enough use case to warrant a
  dedicated page. Refer: :doc:`cmake`