tomevault-io 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/.gitleaksignorepolicy만 사용한다.- installed
git commit경로는 worktree-local pre-Lefthook guard가lefthook.ymldrift와 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
Source: shren207/nixos-config — distributed by TomeVault.