| name | understanding-nix |
| description | Resolve Nix fundamentals: flake, derivation, substituter, direnv.
Trigger: 'Nix 빌드 느림', 'flake 인식 안 됨', 'substituter', 'direnv', 'pre-commit hook 실패'.
NOT for NixOS MiniPC (use managing-minipc). NOT for nix-darwin (use managing-macos).
|
Nix 공통 이슈
NixOS와 nix-darwin 모두에 해당하는 Nix 공통 개념 및 이슈입니다.
목적과 범위
flake 평가, derivation 해석, substituter/빌드 성능, 공통 오류 복구 절차를 다룬다.
빠른 참조
주요 설정 파일
| 파일 | 용도 |
|---|
flake.nix | 입력과 출력 정의 (nixpkgs → nixos-unstable) |
flake.lock | 입력 버전 고정 |
modules/shared/configuration.nix | 공통 Nix 설정 (experimental-features, GC, substituter) |
modules/shared/programs/direnv/default.nix | direnv + nix-direnv 설정 |
lefthook.yml | Pre-commit hooks 정의 |
~/.config/nix/nix.conf | 사용자별 Nix 설정 |
Flake 명령어
nfu
nfu -a
nix flake update <input-name>
nix flake check --no-build --all-systems
Experimental Features
experimental-features = nix-command flakes가 modules/shared/configuration.nix에서 시스템 전역 설정됨.
부트스트랩 전에는 --extra-experimental-features "nix-command flakes" 플래그 필요.
빌드 속도 최적화
| 방법 | 명령어/설정 | 효과 |
|---|
| 오프라인 빌드 | nrs --offline | 네트워크 요청 없음 (~10초, 18배 빠름) |
| 병렬 다운로드 | max-substitution-jobs = 128 | 동시 128개 다운로드 (기본 16) |
| HTTP 연결 | http-connections = 50 | 동시 50 연결 (기본 25) |
| 다운로드 버퍼 | download-buffer-size = 256 * 1024 * 1024 | 기본 64 MiB → 256 MiB |
| GitHub 토큰 | access-tokens = github.com=... | rate limit 해제 |
에러 디버깅
nix build --show-trace
nix derivation show .#darwinConfigurations.<host>.system
핵심 절차
Flake 변경 반영
git add . — Nix flakes는 git-tracked 파일만 인식한다.nix flake update <input-name> — 외부 input 갱신이 필요한 경우.nrs 또는 nrs --offline으로 빌드.
빌드 실패 진단
--show-trace로 에러 원인 모듈을 좁힌다.nix derivation show로 derivation 구조를 확인한다.- 수정 후
nrs로 재검증한다.
direnv + nix-direnv
프로젝트 디렉토리 진입 시 devShell 환경을 자동 활성화한다.
echo "use flake" > .envrc
direnv allow
cd ~/Workspace/nixos-config
- nix-direnv가
.direnv/에 결과를 캐싱 (첫 로드 ~수 초, 이후 ~100ms)
- devShell 내 도구(gitleaks, lefthook 등)는 direnv 환경에서만 사용 가능
Pre-commit Hooks (lefthook)
Hook 상세 목록과 staged snapshot 정책은 repo 루트의 README.md와 lefthook.yml을 기준으로 확인한다.
요약:
- whole-repo / whole-corpus pre-commit hook은 staged index snapshot에서 실행된다.
gitleaks는 staged .gitleaks.toml / .gitleaksignore policy만 사용한다.- installed
git commit 경로는 worktree-local pre-Lefthook guard가 lefthook.yml drift와 unsupported merged config surface를 차단한다.
- direnv 환경이 비활성 상태에서 커밋하면 hook 도구가 없어 실패할 수 있다.
direnv allow 실행으로 해결.
자주 발생하는 문제
- flake 인식 안 됨:
git add 필요 (untracked 파일은 무시됨)
- experimental features 비활성화:
nix-command flakes 활성화 필요
- 빌드 느림:
nrs --offline 사용 또는 substituter 설정 확인
- gitleaks/lefthook not found: direnv 환경 미활성 —
direnv allow 실행
- builtins.toJSON 한 줄 출력:
pkgs.formats.json 사용으로 pretty-print
레퍼런스
