conan.tools.files

conan.tools.files.patch()

def patch(conanfile, base_path=None, patch_file=None, patch_string=None, strip=0, fuzz=False, **kwargs):

Applies a diff from file (patch_file) or string (patch_string) in the conanfile.source_folder directory. The folder containing the sources can be customized with the self.folders attribute in the layout(self) method.

Parameters:

  • patch_file: Patch file that should be applied. The path is relative to the conanfile.source_folder unless an absolute path is provided.

  • base_path: The path is a relative path to conanfile.source_folder unless an absolute path is provided.

  • patch_string: Patch string that should be applied.

  • strip: Number of folders to be stripped from the path.

  • output: Stream object.

  • fuzz: Should accept fuzzy patches.

  • kwargs: Extra parameters that can be added and will contribute to output information.

from conan.tools.files import patch

def build(self):
    for it in self.conan_data.get("patches", {}).get(self.version, []):
        patch(self, **it)

conan.tools.files.apply_conandata_patches()

def apply_conandata_patches(conanfile):

Applies patches stored in conanfile.conan_data (read from conandata.yml file). It will apply all the patches under patches entry that matches the given conanfile.version. If versions are not defined in conandata.yml it will apply all the patches directly under patches keyword.

The key entries will be passed as kwargs to the patch function.

Example of conandata.yml without versions defined:

from conan.tools.files import apply_conandata_patches

def build(self):
    apply_conandata_patches(self)

patches:
- patch_file: "patches/0001-buildflatbuffers-cmake.patch"
- patch_file: "patches/0002-implicit-copy-constructor.patch"
  base_path: "subfolder"
  patch_type: backport
  patch_source: https://github.com/google/flatbuffers/pull/5650
  patch_description: Needed to build with modern clang compilers.

Example of conandata.yml with different patches for different versions:

patches:
  "1.11.0":
    - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
    - patch_file: "patches/0002-implicit-copy-constructor.patch"
      base_path: "subfolder"
      patch_type: backport
      patch_source: https://github.com/google/flatbuffers/pull/5650
      patch_description: Needed to build with modern clang compilers.
  "1.12.0":
    - patch_file: "patches/0001-buildflatbuffers-cmake.patch"
    - patch_string: |
        --- a/tests/misc-test.c
        +++ b/tests/misc-test.c
        @@ -1232,6 +1292,8 @@ main (int argc, char **argv)
              g_test_add_func ("/misc/pause-cancel", do_pause_cancel_test);
              g_test_add_data_func ("/misc/stealing/async", GINT_TO_POINTER (FALSE), do_stealing_test);
              g_test_add_data_func ("/misc/stealing/sync", GINT_TO_POINTER (TRUE), do_stealing_test);
        +     g_test_add_func ("/misc/response/informational/content-length", do_response_informational_content_length_test);
        +

        ret = g_test_run ();
    - patch_file: "patches/0003-fix-content-length-calculation.patch"

conan.tools.files.rename()

def rename(conanfile, src, dst)

Utility functions to rename a file or folder src to dst. On Windows, it is very common that os.rename() raises an “Access is denied” exception, so this tool uses:command:robocopy if available. If that is not the case, or the rename is done in a non-Windows machine, it falls back to the os.rename() implementation.

from conan.tools.files import rename

def source(self):
    rename(self, "lib-sources-abe2h9fe", "sources")  # renaming a folder

Parameters:

  • conanfile: Conanfile object.

  • src (Required): Path to be renamed.

  • dst (Required): Path to be renamed to.

conan.tools.files.get()

def get(conanfile, url, md5='', sha1='', sha256='', destination=".", filename="",
        keep_permissions=False, pattern=None, verify=True, retry=None, retry_wait=None,
        auth=None, headers=None, strip_root=False)

High level download and decompressing of a tgz, zip or other compressed format file. Just a high level wrapper for download, unzip, and remove the temporary zip file once unzipped. You can pass hash checking parameters: md5, sha1, sha256. All the specified algorithms will be checked. If any of them doesn’t match, it will raise a ConanException.

Parameters:

  • url, filename, md5, sha1, sha256, verify, retry, retry_wait, auth, headers: forwarded to download()

  • keep_permissions, pattern, strip_root: forwarded to tools.unzip() (legacy, will be updated).

Examples:

from conan.tools.files import get

def source(self):
    get(self, "http://url/file", md5='d2da0cd0756cd9da6560b9a56016a0cb')
    # also, specify a destination folder
    get(self, "http://url/file", destination="subfolder")

conan.tools.files.ftp_download()

def ftp_download(conanfile, ip, filename, login='', password='')

Ftp download of a file. Retrieves a file from an FTP server. This doesn’t support SSL, but you might implement it yourself using the standard Python FTP library.

Parameters:

  • conanfile: Conanfile object, use always self

  • ip (Required): The IP or address of the ftp server.

  • filename (Required): The filename, including the path/folder where it is located.

  • login (Optional, Defaulted to ""): Login credentials for the ftp server.

  • password (Optional, Defaulted to ""): Password credentials for the ftp server.

Examples:

from conan.tools.files import ftp_download

def source(self):
    ftp_download(self, 'ftp.debian.org', "debian/README")
    self.output.info(load("README"))

conan.tools.files.download()

Download a file

def download(conanfile, url, filename, verify=True, retry=None, retry_wait=None,
             auth=None, headers=None, md5='', sha1='', sha256='')

Retrieves a file from a given URL into a file with a given filename. It uses certificates from a list of known verifiers for https downloads, but this can be optionally disabled.

You can pass hash checking parameters: md5, sha1, sha256. All the specified algorithms will be checked. If any of them doesn’t match, the downloaded file will be removed and it will raise a ConanException.

Parameters:

  • conanfile (Required): Conanfile object, use self always

  • url (Required): URL to download. It can be a list, which only the first one will be downloaded, and the follow URLs will be used as mirror in case of download error.

  • filename (Required): Name of the file to be created in the local storage

  • verify (Optional, Defaulted to True): When False, disables https certificate validation.

  • retry (Optional, Defaulted to 1): Number of retries in case of failure.

  • retry_wait (Optional, Defaulted to 5): Seconds to wait between download attempts.

  • auth (Optional, Defaulted to None): A tuple of user and password to use HTTPBasic authentication. This is used directly in the requests Python library. Check other uses here: https://requests.readthedocs.io/en/master/user/authentication/#basic-authentication

  • headers (Optional, Defaulted to None): A dictionary with additional headers.

  • md5 (Optional, Defaulted to ""): MD5 hash code to check the downloaded file.

  • sha1 (Optional, Defaulted to ""): SHA-1 hash code to check the downloaded file.

  • sha256 (Optional, Defaulted to ""): SHA-256 hash code to check the downloaded file.

Configuration:

  • tools.files.download:retry: number of retries in case some error occurs.

  • tools.files.download:retry_wait: seconds to wait between retries.

Examples:

download(self, "http://someurl/somefile.zip", "myfilename.zip")

# to disable verification:
download(self, "http://someurl/somefile.zip", "myfilename.zip", verify=False)

# to retry the download 2 times waiting 5 seconds between them
download(self, "http://someurl/somefile.zip", "myfilename.zip", retry=2, retry_wait=5)

# Use https basic authentication
download(self, "http://someurl/somefile.zip", "myfilename.zip", auth=("user", "password"))

# Pass some header
download(self, "http://someurl/somefile.zip", "myfilename.zip", headers={"Myheader": "My value"})

# Download and check file checksum
download(self, "http://someurl/somefile.zip", "myfilename.zip", md5="e5d695597e9fa520209d1b41edad2a27")

# to add mirrors
download(self, ["https://ftp.gnu.org/gnu/gcc/gcc-9.3.0/gcc-9.3.0.tar.gz",
                "http://mirror.linux-ia64.org/gnu/gcc/releases/gcc-9.3.0/gcc-9.3.0.tar.gz"],
                "gcc-9.3.0.tar.gz",
               sha256="5258a9b6afe9463c2e56b9e8355b1a4bee125ca828b8078f910303bc2ef91fa6")

Available since: 1.42.0

conan.tools.files.AutoPackager

The AutoPackager together with the package layouts feature, allow to automatically package the files following the declared information in the layout() method:

It will copy:

  • Files from self.cpp.local.includedirs to self.cpp.package.includedirs

  • Files from self.cpp.local.libdirs to self.cpp.package.libdirs

  • Files from self.cpp.local.bindirs to self.cpp.package.bindirs

  • Files from self.cpp.local.srcdirs to self.cpp.package.srcdirs

  • Files from self.cpp.local.builddirs to self.cpp.package.builddirs

  • Files from self.cpp.local.resdirs to self.cpp.package.resdirs

  • Files from self.cpp.local.frameworkdirs to self.cpp.package.frameworkdirs

The patterns of the files to be copied can be defined with the .patterns property of the AutoPackager instance. The default patterns are:

packager = AutoPackager(self)
packager.patterns.include == ["*.h", "*.hpp", "*.hxx"]
packager.patterns.lib == ["*.so", "*.so.*", "*.a", "*.lib", "*.dylib"]
packager.patterns.bin == ["*.exe", "*.dll"]
packager.patterns.src == []
packager.patterns.build == []
packager.patterns.res == []
packager.patterns.framework == []

Usage:

from conans import ConanFile
from conan.tools.files import AutoPackager

class Pkg(ConanFile):

    def layout(self):
        ...

    def package(self):
        packager = AutoPackager(self)
        packager.patterns.include = ["*.hpp", "*.h", "include3.h"]
        packager.patterns.lib = ["*.a"]
        packager.patterns.bin = ["*.exe"]
        packager.patterns.src = ["*.cpp"]
        packager.patterns.framework = ["sframe*", "bframe*"]
        packager.run()