1. 도구를 실행할 환경부터 정합니다
이미 WSL이 설치된 Windows라면 PowerShell에서 아래 명령으로 배포판과 WSL 1·2 구분을 확인합니다. 네이티브 Linux에서 실행하는 명령이 아니며, 설치나 버전 변경을 수행하지 않습니다. Microsoft: WSL 기본 명령
wsl --list --verboseLinux 셸에서는 pwd로 현재 위치를 확인합니다. Linux 명령줄 도구로 주로 작업한다면 WSL 배포판 안의 /home/<user>/project 같은 Linux 파일 시스템을 쓰는 편이 파일 접근 성능에 유리합니다. Windows 도구를 주로 쓴다면 Windows 파일 시스템이 기준이 됩니다. 공유 폴더 사용을 금지한다는 뜻은 아닙니다. Microsoft: 작업 파일 위치와 상호 운용
- 소스: 실제 저장소 경로
어느 파일 시스템에 있는지, 설정 파일이 그 경로를 가리키는지 확인합니다.
- 도구: Windows 또는 Linux
컴파일러·런타임·테스트 도구가 실행되는 환경과 버전을 기록합니다.
- 산출물: 환경별 빌드 디렉터리
서로 다른 환경의 도구가 같은 빌드 결과를 번갈아 덮어쓰지 않게 합니다.
- 검증: 목표 환경에서 실행
빌드 성공뿐 아니라 테스트와 프로그램 시작까지 확인합니다.
프로젝트를 옮길 때의 점검 순서입니다. 저장소를 새로 복제하거나 기존 결과물을 삭제해야 한다는 뜻은 아닙니다.
2. 경로의 철자와 대소문자를 맞춥니다
WSL의 기본 마운트 설정에서는 Windows의 C: 드라이브가 /mnt/c에 나타납니다. WSL 안의 Linux 파일은 Windows에서 \\wsl$ 경로로 접근할 수 있습니다. 경로 문자열만 바꾸기 전에 스크립트·설정 파일이 실제 어느 위치를 참조하는지 확인합니다. Microsoft: Windows와 Linux 사이의 파일 접근
| 확인할 항목 | 흔히 어긋나는 부분 | 점검 방법 |
|---|---|---|
| 절대 경로 | Windows 경로를 Linux 설정에 그대로 사용 | 현재 작업 디렉터리와 설정에서 참조하는 파일 위치를 비교 |
| 파일 이름 | 코드는 Config.json, 실제 파일은 config.json | 저장소의 철자와 코드·설정의 철자를 일치시킴 |
| 빌드 디렉터리 | 다른 OS의 캐시·산출물을 재사용 | 도구와 대상 환경별 출력 경로를 구분 |
Windows 파일 시스템은 기본적으로 대소문자를 구별하지 않지만 디렉터리별 예외가 있고, Linux 파일 시스템은 대개 구별합니다. 따라서 다른 OS에서 통과했다는 사실만으로 파일 이름이 맞다고 볼 수 없습니다. 전역 설정을 바꾸기보다 실제 파일 이름과 참조 경로를 먼저 맞춥니다. Microsoft: WSL의 대소문자 구분
3. 줄끝과 문자 인코딩은 별개입니다
Linux에서 실행할 셸 스크립트를 LF 줄끝으로 체크아웃하려는 저장소라면 .gitattributes에 다음과 같은 규칙을 검토할 수 있습니다. 기존 프로젝트의 규칙과 충돌하지 않는지 먼저 확인합니다.
* text=auto
*.sh text eol=lftext=auto는 Git이 텍스트로 판단한 파일의 줄끝을 정규화하고, eol=lf는 해당 파일의 작업 트리 줄끝을 지정합니다. 이미 저장된 파일이 자동으로 모두 정리된다고 가정하지 않습니다. 적용 전후 git status와 diff를 확인해 의도하지 않은 대량 변경을 찾아야 합니다. Git: text와 eol 속성
줄끝 규칙은 문자 인코딩을 자동으로 변환하는 규칙이 아닙니다. Windows PowerShell 5.1과 PowerShell 6 이상은 텍스트 출력의 기본 인코딩도 다릅니다. 글자가 깨진다면 사용한 명령·PowerShell 버전·원본 파일 인코딩을 따로 확인합니다. 모든 Windows 파일이 같은 인코딩이라고 가정해서 일괄 변환하지 않습니다. Microsoft: PowerShell 문자 인코딩
4. 실행 권한은 파일 시스템에 따라 확인합니다
Linux 파일 시스템의 스크립트는 ls -l build.sh로 권한을 확인합니다. 직접 확인한 실행 대상 파일에만 실행 비트를 부여합니다. 다음은 파일명이 실제로 build.sh인 경우의 예시이며, 저장소 전체에 재귀적으로 적용하는 명령이 아닙니다.
ls -l build.sh
chmod u+x build.shWSL의 /mnt/c처럼 DrvFS로 연결된 Windows 파일에서는 Linux 권한 표시와 chmod 동작이 메타데이터 설정의 영향을 받습니다. 기본적으로 메타데이터가 꺼져 있으면 권한은 Windows 쪽 권한을 바탕으로 계산됩니다. Linux 모드 표시가 바뀌었다고 Windows 접근 권한까지 새로 얻는 것은 아닙니다. Linux 파일 시스템의 실행 비트와 같은 방식으로 단정하지 않습니다. Microsoft: WSL 파일 권한과 chmod 동작
저장소가 실행 비트를 추적하는 프로젝트라면 작업 트리뿐 아니라 Git에 기록된 파일 모드도 확인합니다. 그 방법은 Git의 실행 비트 처리를 참고합니다. 권한을 바꾸기 전에 스크립트 내용과 실행할 환경을 확인해야 합니다.
5. 배포판과 프로젝트가 요구하는 버전을 맞춥니다
프로젝트의 기존 빌드 지침에서 컴파일러·런타임·라이브러리 버전을 확인합니다. 배포판이 달라지면 패키지 이름과 관리 도구도 달라질 수 있습니다. Debian 계열에서 apt update는 패키지 목록을 갱신하는 명령이며, 설치된 프로그램을 업그레이드하는 명령은 아닙니다. apt install git은 Git 패키지 설치를 요청하는 별도 명령입니다. 여기서는 명령의 차이만 설명하며 설치를 요구하지 않습니다.
Debian은 대화형 사용에 apt, 스크립트에서의 호출에 apt-get을 구분해 안내합니다. 다른 배포판의 설치 절차에 이 명령을 그대로 대입하지 않습니다. Debian: 패키지 관리 도구와 기본 작업
목표가 Linux용 실행 파일이라면 빌드 뒤에도 ISA·ABI·동적 로더가 대상 환경과 맞는지 확인해야 합니다. WSL에서 일부 Windows 실행 파일을 호출할 수 있다는 사실과 Linux 바이너리가 정상 동작한다는 사실은 다릅니다. 상세한 점검 순서는 빌드는 됐는데 실행되지 않을 때에서 다룹니다.
6. 목표 환경에서 빌드·테스트·실행을 마칩니다
- 빌드와 테스트를 실행한 운영체제·배포판·도구 버전을 기록했습니까?
- 코드와 설정의 파일 이름·경로가 실제 파일과 일치합니까?
- 스크립트의 줄끝·인코딩·실행 비트를 각각 확인했습니까?
- 의존성 버전이 프로젝트 요구와 일치합니까?
- 생성한 프로그램이 목표 환경에서 시작되고 필요한 테스트를 통과합니까?
실패하면 첫 오류 메시지와 실행한 명령, 작업 디렉터리를 함께 남깁니다. 파일을 복사했다는 이유만으로 이전이 끝났다고 판단하지 않습니다. 이 글은 문서에 근거한 점검 안내이며, 특정 프로젝트의 빌드나 WSL 설정 변경을 실행해 검증한 보고서가 아닙니다.