Участник:HihinRuslan/Параметры Cargo

Перевод статьи главы Environment Variables из The Cargo Book

Переменные окружения Cargo

Список переменных Cargo

Cargo устанавливает и считывает ряд переменных среды, которые ваш код может обнаружить или переопределить. Вот список переменных наборов Cargo, упорядоченных по мере взаимодействия с ними: Вы можете переопределить эти переменные среды, чтобы изменить поведение Cargo в вашей системе:

• CARGO_LOG — Cargo использует модуль трассировки для отображения сообщений журнала отладки. Переменная среды CARGO_LOG может быть настроена на включение ведения журнала отладки с помощью таких значений, как trace, debug или warn. Обычно она используется только во время отладки. Для получения более подробной информации обратитесь к журналу отладки.
• CARGO_HOME — Cargo поддерживает локальный кэш индекса реестра и git-проверок ящиков. По умолчанию они хранятся в каталоге $HOME/.cargo (%USERPROFILE%\.cargo в Windows), но эта переменная переопределяет расположение этого каталога. После кэширования контейнера он не удаляется командой clean. Для получения более подробной информации обратитесь к руководству.
• CARGO_TARGET_DIR — Местоположение, в котором будут размещены все сгенерированные артефакты, относительно текущего рабочего каталога. Смотрите build.target-dir для настройки через config.
• CARGO — Если задано, Cargo будет перенаправлять это значение вместо установки его на свой собственный автоматически определяемый путь при сборке контейнеров и выполнении сценариев сборки и внешних подкоманд. Это значение не выполняется Cargo напрямую и всегда должно указывать на команду, которая ведет себя точно так же, как cargo, поскольку именно этого ожидают пользователи переменной.
• RUSTC — Вместо запуска rustc, Cargo выполнит этот указанный компилятор. Смотрите файл build.rustc для настройки через config.
• RUSTC_WRAPPER — Вместо простого запуска rustc, Cargo выполнит эту указанную оболочку, передав в качестве аргументов командной строки вызов rustc, причем первым аргументом будет путь к фактическому rustc. Полезно настроить инструмент кэширования сборки, такой как sccache. Смотрите раздел build.rustc-wrapper для настройки через config. Установка этого параметра в пустую строку перезаписывает конфигурацию и сбрасывает значение cargo, чтобы не использовать оболочку.
• RUSTC_WORKSPACE_WRAPPER — Вместо простого запуска rustc, для пользователей workspace Cargo выполнит эту указанную оболочку, передав в качестве аргументов командной строки вызов rustc, причем первым аргументом будет путь к фактическому rustc. Это влияет на хэш имени файла, так что артефакты, создаваемые оболочкой, кэшируются отдельно. Смотрите build.rustc-workspace-wrapper для настройки через config. Установка этого значения в пустую строку перезаписывает конфигурацию и сбрасывает значение cargo, чтобы не использовать оболочку для членов рабочей области.
• RUSTDOC — Вместо запуска rustdoc, Cargo выполнит этот указанный экземпляр rustdoc. Смотрите build.rustdoc для настройки через config.
• RUSTDOCFLAGS — Разделенный пробелами список пользовательских флагов, которые должны передаваться всем вызовам rustdoc, выполняемым Cargo. В отличие от cargo rustdoc, это полезно для передачи флага всем экземплярам rustdoc. Смотрите раздел build.rustdocflags для получения дополнительной информации о способах установки флагов. Эта строка разделяется пробелом; более надежное кодирование нескольких аргументов приведено в разделе CARGO_ENCODED_RUSTDOCFLAGS.
• CARGO_ENCODED_RUSTDOCFLAGS — Список пользовательских флагов, разделенных символом 0x1f (разделитель единиц ASCII), который передается всем вызовам rustdoc, выполняемым Cargo.
• RUSTFLAGS — Разделенный пробелами список пользовательских флагов, которые должны передаваться всем вызовам компилятора, выполняемым Cargo. В отличие от cargo rustc, это полезно для передачи флага всем экземплярам компилятора. Дополнительные способы установки флагов приведены в разделе build.rustflags. Эта строка разделяется пробелом; более надежное кодирование нескольких аргументов приведено в разделе CARGO_ENCODED_RUSTFLAGS.
• CARGO_ENCODED_RUSTFLAGS — Список пользовательских флагов, разделенных символом 0x1f (разделитель единиц ASCII), который передается всем вызовам компилятора, выполняемым Cargo.
• CARGO_INCREMENTAL — Если для этого параметра установлено значение 1, то Cargo принудительно включит инкрементную компиляцию для текущей компиляции, а при значении 0 принудительно отключит ее. Если этот параметр env отсутствует, то в противном случае будут использоваться значения по умолчанию для cargo. Смотрите также значение конфигурации build.incremental.
• CARGO_CACHE_RUSTC_INFO — Если для этого параметра установлено значение 0, то Cargo не будет пытаться кэшировать информацию о версии компилятора.
• HTTPS_PROXY или https_proxy или http_proxy — Используемый HTTP-прокси, подробнее смотрите в разделе http.proxy.
• HTTP_TIMEOUT — Время ожидания HTTP в секундах, подробнее смотрите в разделе http.timeout.
• TERM — Если для этого параметра установлено значение dumb, индикатор выполнения будет отключен.
• BROWSER — веб-браузер, который запускается для открытия документации с флагом cargo doc’ --открыть, более подробную информацию смотрите в doc.browser.
• RUSTFMT — Вместо запуска rustfmt, программа cargo fmt выполнит этот указанный экземпляр rustfmt.

Переменные среды конфигурации

Cargo считывает переменные среды для получения некоторых значений конфигурации. Более подробную информацию смотрите в главе о конфигурации. В общем, поддерживаются следующие переменные среды::

• CARGO_ALIAS_<имя> — псевдонимы команд, см. раздел псевдонимы.
• CARGO_BUILD_JOBS — количество параллельных заданий, см. build.jobs.
• CARGO_BUILD_RUSTC — исполняемый файл rustc, см. build.rustc.
• CARGO_BUILD_RUSTC_WRAPPER — Оболочка rustc, смотрите раздел build.rustc-wrapper.
• CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER — Оболочка rustc только для участников workspace, смотрите раздел build.rustc-workspace-wrapper.
• CARGO_BUILD_RUSTDOC — Исполняемый файл rustdoc, смотрите build.rustdoc.
• CARGO_BUILD_TARGET — Целевая платформа по умолчанию, смотрите build.target.
• CARGO_BUILD_TARGET_DIR — Выходной каталог по умолчанию, см. build.target-dir.
• CARGO_BUILD_RUSTFLAGS — Дополнительные флаги rustc, см. build.rustflags.
• CARGO_BUILD_RUSTDOCFLAGS — Дополнительные флаги rustdoc, см. build.rustdocflags.
• CARGO_BUILD_INCREMENTAL — Инкрементальная компиляция, см. build.incremental.
• CARGO_BUILD_DEP_INFO_BASEDIR — Относительный каталог Dep-info, см. build.dep-info-basedir
• CARGO_CARGO_NEW_VCS — Система управления версиями по умолчанию с cargo new, смотрите cargo-new.vcs.
• CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY — Как часто мы должны генерировать уведомление о несоответствии в будущем, смотрите в разделе future-incompat-report.frequency.
• CARGO_HTTP_DEBUG — Включает отладку HTTP, смотрите http.debug.
• CARGO_HTTP_PROXY — Включает HTTP-прокси, см. http.proxy.
• CARGO_HTTP_TIMEOUT — Время ожидания HTTP, см. http.timeout.
• CARGO_HTTP_CAINFO — Файл центра сертификации сертификатов TLS, смотрите http.cainfo.
• CARGO_HTTP_CHECK_REVOKE — Отключает проверку отзыва сертификата TLS, см. http.check-revoke.
• CARGO_HTTP_SSL_VERSION — Используемая версия TLS, см. http.ssl-версия.
• CARGO_HTTP_LOW_SPEED_LIMIT — Ограничение низкой скорости HTTP, смотрите http.low-speed-limit.
• CARGO_HTTP_MULTIPLEXING — Используется ли мультиплексирование HTTP/2, смотрите в разделе http.multiplexing.
• CARGO_HTTP_USER_AGENT - Заголовок HTTP user-agent, смотрите в разделе http.user-agent.
• CARGO_INSTALL_ROOT — Каталог по умолчанию для установки cargo, см. install.root.
• CARGO_NET_RETRY — Количество попыток повторения сетевых ошибок, см. net.retry.
• CARGO_NET_GIT_FETCH_WITH_CLI — Позволяет использовать исполняемый файл git для извлечения данных, см. net.git-fetch-with-cli.
• CARGO_NET_OFFLINE — Автономный режим, см. net.offline.
• CARGO_PROFILE_<имя>_BUILD_OVERRIDE_<ключ> — Переопределяет профиль скрипта сборки, смотрите профиль.<имя>.build-переопределение.
• CARGO_PROFILE_<имя>_CODEGEN_UNITS — задает единицы генерации кода, смотрите профиль.<имя>.codegen-единицы измерения.
• CARGO_PROFILE_<имя>_DEBUG — Какую отладочную информацию включить, смотрите в профиле.<имя>.debug.
• CARGO_PROFILE_<имя>_DEBUG_ASSERTIONS — включение/отключение отладочных утверждений, смотрите профиль.<имя>.debug-утверждения.
• CARGO_PROFILE_<имя>_INCREMENTAL — включение/отключение инкрементальной компиляции, смотрите профиль.<имя>.инкрементальный.
• CARGO_PROFILE_<имя>_LTO — оптимизация времени соединения, смотрите профиль.<имя>.lto.
• CARGO_PROFILE_<имя>_OVERFLOW_CHECKS — Включить/отключить проверку переполнения, смотрите профиль.<имя>.overflow-проверка.
• CARGO_PROFILE_<имя>_OPT_LEVEL — устанавливает уровень оптимизации, смотрите профиль.<имя>.opt-уровень.
• CARGO_PROFILE_<имя>_PANIC — Используемая стратегия паники, смотрите профиль.<имя>.panic.
• CARGO_PROFILE_<имя>_RPATH — параметр для привязки к rpath, смотрите профиль.<имя>.rpath.
• CARGO_PROFILE_<имя>_SPLIT_DEBUGINFO — управляет поведением при выводе отладочного файла, смотрите профиль.<имя>.split-debuginfo.
• CARGO_PROFILE_<имя>_STRIP — управляет удалением символов и/или отладочной информации, смотрите профиль.<имя>.strip.
• CARGO_REGISTRIES_<имя>_CREDENTIAL_PROVIDER — поставщик учетных данных для реестра, см. раздел реестры.<имя>.поставщик учетных данных.
• CARGO_REGISTRIES_<имя>_INDEX — URL-адрес индекса реестра, см. раздел реестры.<имя>.index.
• CARGO_REGISTRIES_<имя>_TOKEN — токен аутентификации реестра, см. раздел реестры.<имя>.токен.
• CARGO_REGISTRY_CREDENTIAL_PROVIDER — поставщик учетных данных для crates.io, смотрите registry.credential-provider.
• CARGO_REGISTRY_DEFAULT — Реестр по умолчанию для флага --registry, смотрите registry.default.
• CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS — Поставщики учетных данных для реестров, в которых не определен конкретный поставщик. Смотрите раздел registry.global-credential-providers.
• CARGO_REGISTRY_TOKEN — токен аутентификации для crates.io, см. registry.token.
• CARGO_TARGET_<triple>_LINKER — используемый компоновщик, см. target.<triple>.linker. Тройка должна быть преобразована в верхний регистр и символы подчеркивания.
• CARGO_TARGET_<triple>_RUNNER — исполняемый раннер, смотрите target.<triple>.runner.
• CARGO_TARGET_<triple>_RUSTFLAGS — Дополнительные флаги rustc для цели, см. цель.<triple>.rustflags.
• CARGO_TERM_QUIET — режим тишины, см. term.quiet.
• CARGO_TERM_VERBOSE — Детализация терминала по умолчанию, см. term.verbose.
• CARGO_TERM_COLOR — Цветовой режим по умолчанию, см. term.color.
• CARGO_TERM_PROGRESS_WHEN — Режим отображения индикатора выполнения по умолчанию, см. term.progress.when.
• CARGO_TERM_PROGRESS_WIDTH — Ширина индикатора выполнения по умолчанию, см. term.progress.width.

Наборы переменных среды Cargo для crates

Cargo предоставляет переменные среды вашему крейту при его компиляции. Обратите внимание, что это также относится к запуску двоичных файлов с запуском груза и тестом груза. Чтобы получить значение любой из этих переменных в программе Rust, сделайте следующее:

let version = env!("CARGO_PKG_VERSION");

Переменная version теперь будет содержать значение CARGO_PKG_VERSION.

Обратите внимание, что если одно из этих значений не указано в манифесте, соответствующей переменной среды присваивается значение пустой строки "".

• CARGO — путь к двоичному файлу cargo, выполняющему сборку.
• CARGO_MANIFEST_DIR — Каталог, содержащий манифест вашего пакета.
• CARGO_PKG_VERSION — Полная версия вашего пакета.
• CARGO_PKG_VERSION_MAJOR — Основная версия вашего пакета.
• CARGO_PKG_VERSION_MINOR — Дополнительная версия вашего пакета.
• CARGO_PKG_VERSION_PATCH — Исправленная версия вашего пакета.
• CARGO_PKG_VERSION_PRE — Предварительная версия вашего пакета.
• CARGO_PKG_AUTHORS — Список авторов, разделенный двоеточием, в манифесте вашего пакета.
• CARGO_PKG_NAME — Название вашего пакета.
• CARGO_PKG_DESCRIPTION — Описание из манифеста вашей посылки.
• CARGO_PKG_HOMEPAGE — Домашняя страница из манифеста вашей посылки.
• CARGO_PKG_REPOSITORY — Хранилище из манифеста вашего пакета.
• CARGO_PKG_LICENSE — Лицензия из манифеста вашего пакета.
• CARGO_PKG_LICENSE_FILE — Файл лицензии из манифеста вашего пакета.
• CARGO_PKG_RUST_VERSION — Версия Rust из манифеста вашего пакета. Обратите внимание, что это минимальная версия Rust, поддерживаемая пакетом, а не текущая версия Rust.
• CARGO_PKG_README — Путь к файлу README вашего пакета.
• CARGO_CRATE_NAME — Имя контейнера, который в данный момент компилируется. Это имя целевого объекта Cargo с преобразованием - в _, например, название библиотеки, двоичного файла, примера, интеграционного теста или бенчмарка.
• CARGO_BIN_NAME — Имя двоичного файла, который в данный момент компилируется. Задается только для двоичных файлов или двоичных примеров. Это имя не содержит какого-либо расширения файла, например .exe.
• OUT_DIR — Если в пакете есть скрипт сборки, он устанавливается в папку, в которую скрипт сборки должен помещать свои выходные данные. Дополнительную информацию смотрите ниже. (Устанавливается только во время компиляции).
• CARGO_BIN_EXE_<имя> — Абсолютный путь к исполняемому файлу двоичного объекта. Это значение задается только при создании интеграционного теста или бенчмарка. Его можно использовать с макросом env, чтобы найти исполняемый файл для запуска в целях тестирования. <Имя> - это имя двоичного целевого объекта, в точности как есть. Например, CARGO_BIN_EXE_my-program для двоичного файла с именем my-program. Двоичные файлы создаются автоматически при создании теста, если только в двоичном файле нет необходимых функций, которые не включены.
• CARGO_PRIMARY_PACKAGE — Эта переменная среды будет установлена, если создаваемый пакет является основным. Основные пакеты - это те, которые пользователь выбрал в командной строке, либо с флагами -p, либо со значениями по умолчанию, основанными на текущем каталоге и элементах рабочей области по умолчанию. Эта переменная среды не будет установлена при построении зависимостей. Она устанавливается только при компиляции пакета (не при запуске двоичных файлов или тестов).
• CARGO_TARGET_TMPDIR — Устанавливается только при создании кода интеграционного теста или бенчмарка. Это путь к каталогу внутри целевого каталога, в который интеграционные тесты или бенчмарки могут свободно помещать любые данные, необходимые для тестов/стендов. Cargo изначально создает этот каталог, но никак не управляет его содержимым, за это отвечает тестовый код.
• CARGO_RUSTC_CURRENT_DIR — Это путь, по которому вызывается rustc (только по ночам).

Пути к динамическим библиотекам

Cargo также задает путь к динамической библиотеке при компиляции и запуске двоичных файлов с помощью таких команд, как cargo run и cargo test. Это помогает находить общие библиотеки, которые являются частью процесса сборки. Имя переменной зависит от платформы:

Переменные определяющие путь к библиотекам

Windows:	PATH
macOS:	DYLD_FALLBACK_LIBRARY_PATH
Unix:	LD_LIBRARY_PATH
AIX:	LIBPATH

При запуске значение будет увеличено по сравнению с существующим значением. В macOS особое внимание уделяется тому, что если DYLD_FALLBACK_LIBRARY_PATH еще не задан, то он добавит значение по умолчанию $HOME/lib:/usr/local/lib:/usr/lib.

Cargo содержит следующие пути:

• Пути поиска, включенные в любой сценарий сборки с помощью инструкции rustc-link-search. Пути за пределами целевого каталога удаляются.
• Пользователь, запускающий Cargo, несет ответственность за правильную настройку среды, если в пути поиска требуются дополнительные библиотеки в системе.
• Базовый выходной каталог, такой как target/debug, и каталог “deps”. Это в основном для устаревшей поддержки плагинов компилятора rustc.
• Путь к библиотеке rustc sysroot. Для большинства пользователей это, как правило, не важно.

Переменные среды Cargo задают значения для сценариев сборки

Cargo задает несколько переменных среды при запуске сценариев сборки. Поскольку эти переменные еще не заданы при компиляции сценария сборки, приведенный выше пример с использованием env! не сработает, и вместо этого вам нужно будет получить значения при запуске сценария сборки:

use std::env;
let out_dir = env::var("OUT_DIR").unwrap();

out_dir теперь будет содержать значение OUT_DIR.

• CARGO — путь к двоичному файлу cargo, выполняющему сборку.
• CARGO_MANIFEST_DIR — Каталог, содержащий манифест для создаваемого пакета (пакет, содержащий сценарий сборки). Также обратите внимание, что это значение текущего рабочего каталога сценария сборки при его запуске.
• CARGO_MANIFEST_LINKS — значение ссылок в манифесте.
• CARGO_MAKEFLAGS — Содержит параметры, необходимые для реализации сервера заданий Cargo для распараллеливания подпроцессов. Вызовы Rustc или cargo из build.rs уже могут считывать CARGO_MAKEFLAGS, но GNU Make требует, чтобы флаги указывались либо непосредственно в качестве аргументов, либо через переменную окружения MAKEFLAGS. В настоящее время Cargo не устанавливает переменную MAKEFLAGS, но для сценариев сборки, вызывающих GNU Make, можно бесплатно установить ее в значение CARGO_MAKEFLAGS.
• CARGO_FEATURE_<имя> — Для каждой активированной функции создаваемого пакета будет присутствовать эта переменная среды, где <имя> - это название функции, написанное в верхнем регистре и переведенное в _.
• CARGO_CFG_<cfg> — Для каждого параметра конфигурации создаваемого пакета эта переменная среды будет содержать значение конфигурации, где <cfg> - это название конфигурации в верхнем регистре, переведенное в _. Логические конфигурации присутствуют, если они заданы, и не отображаются в противном случае. Конфигурации с несколькими значениями объединяются в одну переменную, значения которой разделены символом ,. Сюда входят значения, встроенные в компилятор (которые можно увидеть с помощью rustc --print=cfg), а также значения, заданные скриптами сборки, и дополнительные флаги, передаваемые в rustc (например, те, которые определены в RUSTFLAGS). Вот несколько примеров того, что представляют собой эти переменные:
  • CARGO_CFG_UNIX — Устанавливается на unix-подобных платформах.
  • CARGO_CFG_WINDOWS — Устанавливается на Windows-подобных платформах.
  • CARGO_CFG_TARGET_FAMILY=unix — Целевое семейство.
  • CARGO_CFG_TARGET_OS=macos — Целевая операционная система.
  • CARGO_CFG_TARGET_ARCH=x86_64 — Целевая архитектура процессора.
  • CARGO_CFG_TARGET_VENDOR=apple — Целевой поставщик.
  • CARGO_CFG_TARGET_ENV=gnu — Целевая среда ABI.
  • CARGO_CFG_TARGET_POINTER_WIDTH=64 — Размер в битах указателя ЦП.
  • CARGO_CFG_TARGET_ENDIAN=little — Порядок битов в регистрах ЦП.
  • CARGO_CFG_TARGET_FEATURE=mmx,sse — Список включенных целевых функций ЦП.

Примечание: Обратите внимание, что разные целевые тройки имеют разные наборы значений cfg, поэтому переменные, присутствующие в одной целевой тройке, могут быть недоступны в другой.

• OUT_DIR — папка, в которую должны быть помещены все выходные и промежуточные артефакты. Эта папка находится внутри каталога сборки для создаваемого пакета и является уникальной для данного пакета.
• TARGET — целевая тройка, для которой выполняется компиляция. Для этой тройки должен быть скомпилирован машинный код. Дополнительную информацию смотрите в описании целевой тройки.
• HOST — тройки хостов компилятора Rust.
• NUM_JOBS — параллелизм, указанный как параллелизм верхнего уровня. Это может быть полезно для передачи параметра -j в систему, подобную make. Обратите внимание, что при интерпретации этой переменной среды следует соблюдать осторожность. Для исторических целей это по-прежнему предусмотрено, но в последних версиях Cargo, например, не требуется запускать make -j, и вместо этого можно установить значение MAKEFLAGS env var для содержимого CARGO_MAKEFLAGS, чтобы активировать использование GNU Make-совместимого сервера заданий Cargo для вложенных вызовов make.
• OPT_LEVEL, DEBUG — значения соответствующих переменных для создаваемого в данный момент профиля.
• PROFILE — release для релизных сборок, debug - для других сборок. Это определяется в зависимости от того, наследуется ли профиль от профиля dev или release. Использование этой переменной среды не рекомендуется. Использование других переменных среды, таких как OPT_LEVEL, обеспечивает более корректное представление о фактических используемых настройках.
• DEP_<имя>_<ключ> — Для получения дополнительной информации об этом наборе переменных среды см. документацию по ссылкам для создания скрипта.
• RUSTC, RUSTDOC — компилятор и генератор документации, которые Cargo решила использовать, переданы в сценарий сборки, чтобы он также мог их использовать.
• RUSTC_WRAPPER — оболочка rustc, если таковая имеется, которую использует Cargo. Смотрите раздел build.rustc-wrapper.
• RUSTC_WORKSPACE_WRAPPER — оболочка rustc, если таковая имеется, которую Cargo использует для членов рабочей области. Смотрите раздел build.rustc-workspace-wrapper.
• RUSTC_LINKER — Путь к двоичному файлу компоновщика, который Cargo разрешила использовать для текущего целевого объекта, если он указан. Компоновщик можно изменить, отредактировав .cargo/config.toml; дополнительную информацию смотрите в документации о конфигурации cargo.
• CARGO_ENCODED_RUSTFLAGS — дополнительные флаги, с помощью которых Cargo вызывает rustc, разделенные символом 0x1f (разделитель ASCII-единиц измерения). Смотрите build.rustflags. Обратите внимание, что начиная с версии Rust 1.55, RUSTFLAGS удален из среды; вместо этого скрипты должны использовать CARGO_ENCODED_RUSTFLAGS.
• CARGO_PKG_ — переменные, содержащие информацию об упаковке, с теми же именами и значениями, которые указываются при сборке контейнера.

Переменные среды Cargo задаваемые для сторонних подкоманд

Cargo предоставляет переменные среды сторонним подкомандам (например, программам с именем cargo-foobar, помещенным в $PATH):

• CARGO — путь к двоичному файлу cargo, выполняющему сборку.

Для получения расширенной информации о вашей среде вы можете запустить метаданных в Cargo.