KOKO\Mimi
153 lines
5.7 KiB
Markdown
153 lines
5.7 KiB
Markdown
# Harness 운영 가이드
|
|
|
|
## Requirements
|
|
|
|
Windows, Python 3.10 이상, Codex CLI가 필요하다. CMake 프로젝트에는 Visual Studio의
|
|
Desktop development with C++ 워크로드와 MSBuild, CMake/CTest를 설치한다.
|
|
|
|
## 프로젝트 자동 감지
|
|
|
|
프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의
|
|
CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는
|
|
건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는
|
|
오류로 처리한다.
|
|
|
|
설정을 시작하려면 다음을 실행한다.
|
|
|
|
```powershell
|
|
Copy-Item .harness/config.example.json .harness/config.json
|
|
python scripts/execute.py <phase-name>
|
|
python scripts/execute.py <phase-name> --push
|
|
```
|
|
|
|
Codex의 `workspace-write` sandbox 밖에 설치된 실행 도구나 runtime이 필요한 경우에만
|
|
`--codex-add-dir`를 반복 지정한다. 경로는 존재하는 절대 디렉터리여야 하며, Codex
|
|
CLI의 추가 writable directory와 child PATH 끝에 함께 전달된다.
|
|
|
|
```powershell
|
|
python scripts/execute.py <phase-name> `
|
|
--codex-add-dir "C:\path\to\tool-bin" `
|
|
--codex-add-dir "C:\path\to\runtime"
|
|
```
|
|
|
|
이 옵션은 지정한 디렉터리에 child agent의 쓰기 권한도 부여하므로, 사용자 프로필이나
|
|
드라이브 루트처럼 넓은 경로를 지정하지 말고 실행에 필요한 최소 설치 디렉터리만
|
|
허용한다.
|
|
|
|
## Harness Python 검증
|
|
|
|
이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
|
|
다음 명령으로 실행한다.
|
|
|
|
```powershell
|
|
uv run --with pytest python -m pytest -v -rs
|
|
```
|
|
|
|
## CMake preset 설정
|
|
|
|
`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
|
|
`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
|
|
지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
|
|
|
|
FESA의 외부 패키지 위치는 개발 머신마다 다르므로 tracked preset이나 production
|
|
CMake 기본값에 절대경로를 넣지 않는다. 새 PowerShell 세션에서는 configure 전에
|
|
다음 package directory 환경 변수를 설정한다. 아래 값은 현재 검증된 개발 환경이며,
|
|
설치 버전이나 위치가 다르면 해당 `*Config.cmake`가 있는 디렉터리로 바꾼다.
|
|
|
|
```powershell
|
|
$env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl"
|
|
$env:TBB_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\tbb"
|
|
$env:HDF5_DIR = "C:\Program Files\HDF_Group\HDF5\2.1.1\cmake"
|
|
$env:GTest_DIR = "C:\Users\baram\AppData\Local\FESA\dependencies\googletest-1.17.0-v145-x64-crt\lib\cmake\GTest"
|
|
|
|
Test-Path "$env:MKL_DIR\MKLConfig.cmake"
|
|
Test-Path "$env:TBB_DIR\TBBConfig.cmake"
|
|
Test-Path "$env:HDF5_DIR\hdf5-config.cmake"
|
|
Test-Path "$env:GTest_DIR\GTestConfig.cmake"
|
|
```
|
|
|
|
네 확인 명령이 모두 `True`인 같은 세션에서 preset을 실행한다. oneAPI는 component별
|
|
별칭 디렉터리가 아니라 위 통합 `2026.1` package를 사용해야 HDF5의 Intel runtime
|
|
의존성까지 CTest PATH에 포함된다.
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"projectType": "cmake",
|
|
"cmake": {
|
|
"sourceDir": ".",
|
|
"binaryDir": "out/build/windows-debug",
|
|
"configurePreset": "windows-debug",
|
|
"buildPreset": "windows-debug",
|
|
"testPreset": "windows-debug"
|
|
}
|
|
}
|
|
```
|
|
|
|
```powershell
|
|
cmake --fresh --preset windows-debug
|
|
cmake --build --preset windows-debug
|
|
ctest --preset windows-debug --output-on-failure
|
|
```
|
|
|
|
Preset을 쓰지 않는 경우에는 같은 격리된 build directory를 명시한다.
|
|
|
|
```powershell
|
|
cmake -S . -B .harness/build -A x64
|
|
cmake --build .harness/build --config Debug
|
|
ctest --test-dir .harness/build -C Debug --output-on-failure
|
|
```
|
|
|
|
## 직접 MSBuild 설정
|
|
|
|
`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
|
|
지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
|
|
파일과 인수를 JSON 배열로 적는다.
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"projectType": "msbuild",
|
|
"msbuild": {
|
|
"solution": "MyProject.sln",
|
|
"configuration": "Debug",
|
|
"platform": "x64",
|
|
"testCommand": ["build/tests/Debug/MyProjectTests.exe"]
|
|
}
|
|
}
|
|
```
|
|
|
|
```powershell
|
|
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
|
|
.\build\tests\Debug\MyProjectTests.exe
|
|
```
|
|
|
|
## TDD 확장
|
|
|
|
`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다
|
|
`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은
|
|
기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를
|
|
대체하지 않고 추가한다.
|
|
|
|
```json
|
|
{
|
|
"version": 1,
|
|
"tdd": {
|
|
"testRoots": ["tests", "integration-tests"],
|
|
"testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
|
|
"exclude": ["legacy/generated/**"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## 실패 복구
|
|
|
|
- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
|
|
- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다.
|
|
- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
|
|
- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다.
|
|
- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다.
|
|
- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리,
|
|
종료 코드와 출력 tail을 확인하고 해당 명령을 단독으로 다시 실행한다. Harness는
|
|
별도의 로그 파일을 만들지 않는다.
|