# Shren207 Nixos Config Understanding Nix > Nix 공통 이슈 - Skill: `tomevault-io/shren207-nixos-config-understanding-nix` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/shren207-nixos-config-understanding-nix` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/shren207-nixos-config-understanding-nix/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/shren207-nixos-config-understanding-nix --- # 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 명령어 ```bash nfu # fzf로 input 선택 → update → FOD fix → nrs (권장) nfu -a # 모든 input 일괄 업데이트 nix flake update # 수동: 특정 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 해제 | ### 에러 디버깅 ```bash nix build --show-trace # 상세 빌드 로그 nix derivation show .#darwinConfigurations..system # derivation 확인 ``` ## 핵심 절차 ### Flake 변경 반영 1. `git add .` — Nix flakes는 git-tracked 파일만 인식한다. 2. `nix flake update ` — 외부 input 갱신이 필요한 경우. 3. `nrs` 또는 `nrs --offline`으로 빌드. ### 빌드 실패 진단 1. `--show-trace`로 에러 원인 모듈을 좁힌다. 2. `nix derivation show`로 derivation 구조를 확인한다. 3. 수정 후 `nrs`로 재검증한다. ## direnv + nix-direnv 프로젝트 디렉토리 진입 시 devShell 환경을 자동 활성화한다. ```bash 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` 실행으로 해결. ## 자주 발생하는 문제 1. flake 인식 안 됨: `git add` 필요 (untracked 파일은 무시됨) 2. experimental features 비활성화: `nix-command flakes` 활성화 필요 3. 빌드 느림: `nrs --offline` 사용 또는 substituter 설정 확인 4. gitleaks/lefthook not found: direnv 환경 미활성 — `direnv allow` 실행 5. builtins.toJSON 한 줄 출력: `pkgs.formats.json` 사용으로 pretty-print ## 레퍼런스 - 트러블슈팅: [references/troubleshooting.md](references/troubleshooting.md) - 기능 목록: [references/features.md](references/features.md) --- > Source: [shren207/nixos-config](https://github.com/shren207/nixos-config) — distributed by [TomeVault](https://tomevault.io).