generate()¶
This method will run after the computation and installation of the dependency graph. This means that it will
run after a conan install command, or when a package is being built in the cache, it will be run before
calling the build()
method.
The purpose of generate()
is to prepare the build, generating the necessary files. These files would typically be:
Files containing information to locate the dependencies, as
xxxx-config.cmake
CMake config scripts, orxxxx.props
Visual Studio property files.Environment activation scripts, like
conanbuild.bat
orconanbuild.sh
, that define all the necessary environment variables necessary for the build.Toolchain files, like
conan_toolchain.cmake
, that contains a mapping between the current Conan settings and options, and the build system specific syntax.CMakePresets.json
for CMake users using modern versions.General purpose build information, as a
conanbuild.conf
file that could contain information for some toolchains like autotools to be used in thebuild()
method.Specific build system files, like
conanvcvars.bat
, that contains the necessary Visual Studio vcvars.bat call for certain build systems like Ninja when compiling with the Microsoft compiler.
The idea is that the generate()
method implements all the necessary logic, making both the user manual builds after a conan install
very straightforward, and also the build()
method logic simpler. The build produced by a user in their local flow should result in
exactly the same one as the build done in the cache with a conan create
without effort.
Generation of files happens in the generators_folder
as defined by the current layout.
In many cases, the generate()
method might not be necessary, and declaring the generators
attribute could be enough:
from conan import ConanFile
class Pkg(ConanFile):
generators = "CMakeDeps", "CMakeToolchain"
But the generate()
method can explicitly instantiate those generators, use them conditionally (like using one build system in Windows,
and another build system integration in other platforms), customize them, or provide a complete custom
generation.
from conan import ConanFile
from conan.tools.cmake import CMakeToolchain
class Pkg(ConanFile):
def generate(self):
tc = CMakeToolchain(self)
# customize toolchain "tc"
tc.generate()
# Or provide your own custom logic
The current working directory for the generate()
method will be the self.generators_folder
defined in the current layout.
For custom integrations, putting code in a common python_require
would be a good way to avoid repetition in
multiple recipes:
from conan import ConanFile
from conan.tools.cmake import CMakeToolchain
class Pkg(ConanFile):
python_requires = "mygenerator/1.0"
def generate(self):
mygen = self.python_requires["mygenerator"].module.MyGenerator(self)
# customize mygen behavior, like mygen.something= True
mygen.generate()
In case it is necessary to collect or copy some files from the dependencies, it is also possible to do it in the generate()
method, accessing self.dependencies
.
Listing the different include directories, lib directories from a dependency “mydep” would be possible like this:
from conan import ConanFile
class Pkg(ConanFile):
def generate(self):
info = self.dependencies["mydep"].cpp_info
self.output.info("**includedirs:{}**".format(info.includedirs))
self.output.info("**libdirs:{}**".format(info.libdirs))
self.output.info("**libs:{}**".format(info.libs))
And copying the shared libraries in Windows and OSX to the current build folder, could be done like:
from conan import ConanFile
class Pkg(ConanFile):
def generate(self):
for dep in self.dependencies.values():
copy(self, "*.dylib", dep.cpp_info.libdir, self.build_folder)
copy(self, "*.dll", dep.cpp_info.libdir, self.build_folder)
Note
Best practices
Accessing dependencies
self.dependencies["mydep"].package_folder
is possible, but it will beNone
when the dependency “mydep” is in “editable” mode. If you plan to use editable packages, make sure to always reference thecpp_info.xxxdirs
instead.
See also
self.dependencies¶
Conan recipes provide access to their dependencies via the self.dependencies
attribute.
This attribute is generally used by generators like CMakeDeps
or MSBuildDeps
to
generate the necessary files for the build.
This section documents the self.dependencies
attribute, as it might be used by users
both directly in recipe or indirectly to create custom build integrations and generators.
Dependencies interface¶
It is possible to access each one of the individual dependencies of the current recipe, with the following syntax:
class Pkg(ConanFile):
requires = "openssl/0.1"
def generate(self):
openssl = self.dependencies["openssl"]
# access to members
openssl.ref.version
openssl.ref.revision # recipe revision
openssl.options
openssl.settings
if "zlib" in self.dependencies:
# do something
Some important points:
All the information is read only. Any attempt to modify dependencies information is an error and can raise at any time, even if it doesn’t raise yet.
It is not possible either to call any methods or any attempt to reuse code from the dependencies via this mechanism.
This information does not exist in some recipe methods, only in those methods that evaluate after the full dependency graph has been computed. It will not exist in
configure()
,config_options
,export()
,export_source()
,set_name()
,set_version()
,requirements()
,build_requirements()
,system_requirements()
,source()
,init()
,layout()
. Any attempt to use it in these methods can raise an error at any time.At the moment, this information should only be used in
generate()
andvalidate()
methods. For any other use, please submit a Github issue.
Not all fields of the dependency conanfile are exposed, the current fields are:
package_folder: The folder location of the dependency package binary
recipe_folder: The folder containing the
conanfile.py
(and other exported files) of the dependencyref: An object that contains
name
,version
,user
,channel
andrevision
(recipe revision)pref: An object that contains
ref
,package_id
andrevision
(package revision)buildenv_info:
Environment
object with the information of the environment necessary to buildrunenv_info:
Environment
object with the information of the environment necessary to run the appcpp_info: includedirs, libdirs, etc for the dependency.
settings: The actual settings values of this dependency
settings_build: The actual build settings values of this dependency
options: The actual options values of this dependency
context: The context (build, host) of this dependency
conf_info: Configuration information of this dependency, intended to be applied to consumers.
dependencies: The transitive dependencies of this dependency
is_build_context: Return
True
ifcontext == "build"
.conan_data: The
conan_data
attribute of the dependency that comes from itsconandata.yml
filelicense: The
license
attribute of the dependencydescription: The
description
attribute of the dependencyhomepage: The
homepage
attribute of the dependencyurl: The
url
attribute of the dependency
Iterating dependencies¶
It is possible to iterate in a dict-like fashion all dependencies of a recipe.
Take into account that self.dependencies
contains all the current dependencies,
both direct and transitive. Every upstream dependency of the current one that has some
effect on it, will have an entry in this self.dependencies
.
Iterating the dependencies can be done as:
requires = "zlib/1.2.11", "poco/1.9.4"
def generate(self):
for require, dependency in self.dependencies.items():
self.output.info("Dependency is direct={}: {}".format(require.direct, dependency.ref))
will output:
conanfile.py (hello/0.1): Dependency is direct=True: zlib/1.2.11
conanfile.py (hello/0.1): Dependency is direct=True: poco/1.9.4
conanfile.py (hello/0.1): Dependency is direct=False: pcre/8.44
conanfile.py (hello/0.1): Dependency is direct=False: expat/2.4.1
conanfile.py (hello/0.1): Dependency is direct=False: sqlite3/3.35.5
conanfile.py (hello/0.1): Dependency is direct=False: openssl/1.1.1k
conanfile.py (hello/0.1): Dependency is direct=False: bzip2/1.0.8
Where the require
dictionary key is a “requirement”, and can contain specifiers of the relation
between the current recipe and the dependency. At the moment they can be:
require.direct
: boolean,True
if it is direct dependency orFalse
if it is a transitive one.require.build
: boolean,True
if it is abuild_require
in the build context, ascmake
.require.test
: boolean,True
if its abuild_require
in the host context (defined withself.test_requires()
), asgtest
.
The dependency
dictionary value is the read-only object described above that access the dependency attributes.
The self.dependencies
contains some helpers to filter based on some criteria:
self.dependencies.host
: Will filter out requires withbuild=True
, leaving regular dependencies likezlib
orpoco
.self.dependencies.direct_host
: Will filter out requires withbuild=True
ordirect=False
self.dependencies.build
: Will filter out requires withbuild=False
, leaving onlytool_requires
in the build context, ascmake
.self.dependencies.direct_build
: Will filter out requires withbuild=False
ordirect=False
self.dependencies.test
: Will filter out requires withbuild=True
or withtest=False
, leaving only test requirements asgtest
in the host context.
They can be used in the same way:
requires = "zlib/1.2.11", "poco/1.9.4"
def generate(self):
cmake = self.dependencies.direct_build["cmake"]
for require, dependency in self.dependencies.build.items():
# do something, only build deps here
Dependencies cpp_info
interface¶
The cpp_info
interface is heavily used by build systems to access the data.
This object defines global and per-component attributes to access information like the include
folders:
def generate(self):
cpp_info = self.dependencies["mydep"].cpp_info
cpp_info.includedirs
cpp_info.libdirs
cpp_info.components["mycomp"].includedirs
cpp_info.components["mycomp"].libdirs
All the paths declared in the cppinfo
object (like cpp_info.includedirs
) are absolute paths and works whether
the dependency is in the cache or is an editable package.
See also
CppInfo model.