Nix 공통 이슈 Skill

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                                       # fzf로 input 선택 → update → FOD fix → nrs (권장)
nfu -a                                    # 모든 input 일괄 업데이트
nix flake update <input-name>             # 수동: 특정 input만 업데이트
nix flake check --no-build --all-systems  # flake 평가 오류 검사

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  # derivation 확인

핵심 절차

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    # .envrc 생성 (nixos-config은 이미 커밋됨)
direnv allow                 # 최초 1회 허용
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

레퍼런스

트러블슈팅: references/troubleshooting.md
기능 목록: references/features.md

Agent Skills: Nix 공통 이슈

Install this agent skill to your local

Skill Files