🫐 Cyberries

Укрощение Nix в Firebase Studio — инженерный кейс по настройке Python-окружения

время чтения ~3 мин.

Дисклеймер от капитана (надеюсь) неочевидности

Я не Dev-гуру и не мастер Nix. Я — айтишник и решатель бизнес-задач. Этот гайд мини-бортовой журнал вылазки в дебри настройки IDE Firebase Studio. Просто рабочий путь, а не единственно верная карта. Если знаете маршрут элегантнее — делитесь в Киберлодках!

Постановка эксперимента

В системе EnMaTeS мы стремимся к созданию надежных, предсказуемых и системных решений. Если рассматривать прикладной уровен инструментария, то декларативное управление окружением с помощью Nix как раз про это. Я решил использовать Firebase Studio (IDX) — облачную среду разработки от Google, в качестве потенциальной площадки для работы над EnMaTeS и в рабочих группах наших «Киберлодок».

Теоретически, все просто: вы описываете в файле .idx/dev.nix необходимые пакеты, и среда волшебным образом их предоставляет. Но что делать, если этого не происходит?

Диагностика: обнаружение аномалии

Все началось с классической ошибки, знакомой Python-разработчику:

ModuleNotFoundError: No module named 'yaml'

При этом наш .idx/dev.nix был верен с точки зрения синтаксиса Nix. Пакет pyyaml был явно указан, и локальная проверка через nix-shell подтверждала его наличие. Но терминал внутри Firebase Studio его “не видел”.

Ключевая улика была найдена быстро: команда echo $PYTHONPATH возвращала пустую строку. Это означало, что окружение, описанное в dev.nix, было загружено, но не активировано для нашей терминальной сессии. Среда знала, что пакеты нужно скачать, но не сообщала интерпретатору Python, где их искать.

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

Здесь и начался стандартный инженерный процесс по проверке гипотез о том, как именно управляемая среда IDX взаимодействует с Nix.

  • Гипотеза №1: использовать стандартный shellHook Nix. Это идиоматичный способ для “чистого” Nix. Мы добавили shellHook для принудительной установки PYTHONPATH.
    • Результат: провал сборки окружения с ошибкой Unknown attr 'shellHook'.
    • Вывод: схема конфигурации IDX не является полной копией стандартной. Она имеет свою, более строгую структуру и не поддерживает этот хук на верхнем уровне.
  • Гипотеза №2: использовать хук idx.workspace.onStart. Это официальный способ IDX для запуска скриптов. Перенес нашу логику export PYTHONPATH... туда.
    • Результат: провал сборки с серией синтаксических ошибок (unexpected text, undefined variable).
    • Вывод: парсер Nix, который обрабатывает .idx/dev.nix, конфликтует со сложными строковыми конструкциями, предназначенными для shell. Пытаться “обмануть” его экранированием символов — путь к еще большему хаосу.

Решение: декларативная гармония

Провалы стандартных подходов привели к верному решению для данной среды — декларативному подходу. Вместо того чтобы пытаться приказать среде установить переменную (export...), нужно описать желаемое состояние.

Финальная, каноническая версия .idx/dev.nix использует для этого специальный блок env:

{ pkgs, ... }:

let
  # Создаем единое, именованное окружение
  python312Env = pkgs.python312.withPackages (ps: [
    ps.pip
    ps.pyyaml
  ]);
in
{
  channel = "stable-24.05";
  packages = [
    python312Env
  ];

  # ДЕКЛАРАТИВНОЕ ОПИСАНИЕ ПЕРЕМЕННЫХ ОКРУЖЕНИЯ
  # Это язык, который IDX понимает без искажений.
  env = {
    PYTHONPATH = "${python312Env}/lib/python3.12/site-packages";
  };

  # ... остальная часть idx конфигурации
}

Почему зафурычило?

Мы перестали “хакать” систему и начали говорить с ней на ее родном, декларативном языке. Мы не выполняем скрипт, а описываем факт: “В этом окружении PYTHONPATH должен быть равен вот этому пути”. Система сборки IDX видит это описание и сама, своими внутренними механизмами, корректно настраивает окружение. Простое следование документации Firebase не дало бы этого результата, так как оно не объясняет, какое именно значение нужно подставить для пакета, установленного через Nix.

Вывод: понимание логики системы

Этот кейс — не об ошибке, а о важном архитектурном принципе. Работая в сложных, интегрированных средах, таких как Firebase Studio, недостаточно знать “общие правила”. Необходимо понимать внутреннюю логику конкретной системы. Побеждает не тот, кто пытается “взломать” ее, а тот, кто системно исследует ее поведение и действует в гармонии с ним.

Именно такой подход — глубокое понимание систем и их взаимодействия — я и закладываю в основу инструмента Connectome Weaver, системы EnMaTeS (включая AI Layer) и метасистемы Membra.

Вид графа