cardinal_pythonlib.buildfunc

Original code copyright (C) 2009-2022 Rudolf Cardinal (rudolf@pobox.com).

This file is part of cardinal_pythonlib.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Support for building software.

cardinal_pythonlib.buildfunc.download_if_not_exists(url: str, filename: str, skip_cert_verify: bool = True, mkdir: bool = True) → None[source]

Downloads a URL to a file, unless the file already exists.

cardinal_pythonlib.buildfunc.fetch(args: List[str], env: Dict[str, str] | None = None, encoding: str = 'utf-8') → str[source]

Run a command and returns its stdout.

Parameters:

  • args – the command-line arguments

  • env – the operating system environment to use

  • encoding – the encoding to use for stdout

Returns:

the command’s stdout output

cardinal_pythonlib.buildfunc.git_clone(prettyname: str, url: str, directory: str, branch: str | None = None, commit: str | None = None, clone_options: List[str] | None = None, run_func: Callable | None = None, git_executable: str | None = None) → bool[source]

Fetches a Git repository, unless we have it already.

Parameters:

  • prettyname – name to display to user

  • url – URL

  • directory – destination directory

  • branch – repository branch

  • commit – repository commit tag

  • clone_options – additional options to pass to git clone

  • run_func – function to use to call an external command

  • git_executable – name of git executable (default git)

Returns:

did we need to do anything?

cardinal_pythonlib.buildfunc.make_copy_paste_env(env: Dict[str, str]) → str[source]

Convert an environment into a set of commands that can be copied/pasted, on the build platform, to recreate that environment.

cardinal_pythonlib.buildfunc.run(args: List[str], env: Dict[str, str] | None = None, capture_stdout: bool = False, echo_stdout: bool = True, capture_stderr: bool = False, echo_stderr: bool = True, debug_show_env: bool = True, encoding: str = 'utf-8', allow_failure: bool = False, **kwargs) → Tuple[str, str][source]

Runs an external process, announcing it.

Optionally, retrieves its stdout and/or stderr output (if not retrieved, the output will be visible to the user).

Parameters:

  • args – list of command-line arguments (the first being the executable)

  • env – operating system environment to use (if None, the current OS environment will be used)

  • capture_stdout – capture the command’s stdout?

  • echo_stdout – allow the command’s stdout to go to sys.stdout?

  • capture_stderr – capture the command’s stderr?

  • echo_stderr – allow the command’s stderr to go to sys.stderr?

  • debug_show_env – be verbose and show the environment used before calling

  • encoding – encoding to use to translate the command’s output

  • allow_failure – if True, continues if the command returns a non-zero (failure) exit code; if False, raises an error if that happens

  • kwargs – additional arguments to teed_call()

Returns:

(stdout, stderr). If the output wasn’t captured, an empty string will take its place in this tuple.

Return type:

a tuple

cardinal_pythonlib.buildfunc.tar_supports_force_local_switch(tar_executable: str) → bool[source]

Does tar support the --force-local switch? We ask it.

cardinal_pythonlib.buildfunc.untar_to_directory(tarfile: str, directory: str, verbose: bool = False, gzipped: bool = False, skip_if_dir_exists: bool = True, run_func: Callable | None = None, chdir_via_python: bool = True, tar_executable: str | None = None, tar_supports_force_local: bool | None = None) → None[source]

Unpacks a TAR file into a specified directory.

Parameters:

  • tarfile – filename of the .tar file

  • directory – destination directory

  • verbose – be verbose?

  • gzipped – is the .tar also gzipped, e.g. a .tar.gz file?

  • skip_if_dir_exists – don’t do anything if the destrination directory exists?

  • run_func – function to use to call an external command

  • chdir_via_python – change directory via Python, not via tar. Consider using this via Windows, because Cygwin tar v1.29 falls over when given a Windows path for its -C (or --directory) option.

  • tar_executable – name of the tar executable (default is tar)

  • tar_supports_force_local – does tar support the --force-local switch? If you pass None (the default), this is checked directly via tar --help. Linux/GNU tar does; MacOS tar doesn’t; Cygwin tar does; Windows 10 (build 17063+) tar doesn’t.