> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 서버 개발 가이드

> 디버깅, 테스트 및 VillageSQL 서버 코드베이스 기여.

이 가이드는 디버깅, 서버 테스트 스위트 실행, VillageSQL에 기여하는 방법을 다룹니다. 작동하는 소스 빌드를 전제로 합니다 — 아직 하지 않았다면 [소스에서 빌드](/docs/ko/mysql-8.4/0.0.5/source)를 참조하세요.

## 디버깅

VillageSQL 서버 디버깅은 Linux에서는 GDB를, macOS에서는 lldb를 사용합니다. macOS의 GDB는 코드 서명이 필요하여 설정하기 번거롭습니다 — lldb는 macOS의 표준 디버거이며 별도 설정 없이 바로 작동합니다.

### Linux (GDB)

VillageSQL을 GDB에서 실행:

```bash theme={null}
gdb --args $HOME/build/villagesql/bin/mysqld --gdb --datadir=$HOME/mysql-data/data --basedir=$HOME/build/villagesql
```

**GDB 내부:**

```
(gdb) run                    # Start the server
(gdb) break function_name    # Set breakpoints
(gdb) continue               # Resume execution
(gdb) bt                     # Show backtrace on crash
```

**일반적인 GDB 명령어:**

```
# Break on specific SQL command execution
(gdb) break mysql_execute_command

# Break on extension loading
(gdb) break Sql_cmd_install_extension::execute

# Print variable values
(gdb) print variable_name

# Step through code
(gdb) step      # Step into functions
(gdb) next      # Step over functions
```

### macOS (lldb)

VillageSQL을 lldb에서 실행:

```bash theme={null}
lldb -- $HOME/build/villagesql/bin/mysqld --datadir=$HOME/mysql-data/data --basedir=$HOME/build/villagesql
```

**lldb 내부:**

```
(lldb) run                         # Start the server
(lldb) breakpoint set -n function_name  # Set breakpoints
(lldb) continue                    # Resume execution
(lldb) bt                          # Show backtrace on crash
```

**일반적인 lldb 명령어:**

```
# Break on specific SQL command execution
(lldb) breakpoint set -n mysql_execute_command

# Break on extension loading
(lldb) breakpoint set -n Sql_cmd_install_extension::execute

# Print variable values
(lldb) print variable_name

# Step through code
(lldb) step      # Step into functions
(lldb) next      # Step over functions
```

## 테스트 실행

VillageSQL은 기능을 검증하기 위해 단위 테스트와 회귀 테스트를 포함합니다.

### 단위 테스트

VillageSQL 전용 단위 테스트 실행 (빌드 디렉터리 내에서):

```bash theme={null}
make -j10 villagesql-unit-tests && ctest -L villagesql
```

또는 모든 단위 테스트 실행:

```bash theme={null}
ctest --output-on-failure
```

### 회귀 테스트

mysql-test 디렉터리로 이동:

```bash theme={null}
cd mysql-test
```

**전체 MySQL 테스트 스위트 실행 (느림):**

```bash theme={null}
./mysql-test-run.pl --parallel=auto
```

**VillageSQL 전용 테스트만 실행:**

```bash theme={null}
./mysql-test-run.pl --suite=villagesql
```

**모든 하위 스위트를 포함한 VillageSQL 테스트 실행:**

```bash theme={null}
./mysql-test-run.pl --do-suite=villagesql --parallel=auto
```

<Note>
  **--suite vs --do-suite:**

  * `--suite=villagesql`은 상위 레벨 villagesql 테스트만 실행합니다
  * `--do-suite=villagesql`은 하위 스위트(insert, select, stored\_procedure 등)를 포함한 모든 테스트를 실행합니다
</Note>

### 개별 테스트 실행

테스트 이름으로 특정 테스트 실행:

```bash theme={null}
./mysql-test-run.pl villagesql.complex_index
```

하위 스위트에서 테스트 실행:

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

### 테스트 결과 업데이트

기능 변경 후 예상 테스트 출력을 업데이트해야 하는 경우:

```bash theme={null}
./mysql-test-run.pl --record villagesql.complex_index
```

<Warning>
  **테스트 기록:** 항상 `.result` 파일 변경 사항을 검토하여 버그가 아닌 의도된 동작을 반영했는지 확인하세요. `--record` 플래그는 예상 출력을 맹목적으로 덮어씁니다.
</Warning>

### 테스트 이식성

테스트 출력에 테스트 실행기의 임시 디렉터리 경로가 포함된 경우, 기록된 결과에 다른 머신에서 작동하지 않는 절대 경로가 포함되지 않도록 `.test` 파일 내부에 다음 지시문을 추가하세요:

```sql theme={null}
--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR
```

### 테스트 실패 디버깅

VillageSQL 전용 로그 메시지(`LogVSQL()`을 통해 출력)는 기본적으로 억제됩니다. 테스트 실행 중 오류 로그에 표시되도록 하려면:

```bash theme={null}
./mysql-test-run.pl --mysqld=--log-error-verbosity=3 villagesql.complex_index
```

전체 오류 로그는 `mysql-test/var/log/mysqld.1.err`에 있습니다.

확장 회귀 테스트 작성에 대한 자세한 내용은 [개발 가이드](/docs/ko/mysql-8.4/0.0.5/development)를 참조하세요.

## 바이너리 설치

VillageSQL을 시스템 전체에 설치하려면 (적절한 권한이 필요):

```bash theme={null}
cmake --build build --target install
```

기본적으로 바이너리가 `/usr/local/mysql/`에 설치됩니다. 설치 접두사를 사용자 정의할 수 있습니다:

```bash theme={null}
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build build --target install
```

## 기여하기

VillageSQL에 기여하는 경우, 코딩 표준 및 개발 워크플로우에 대한 [기여 가이드라인](https://github.com/villagesql/villagesql-server/blob/main/CONTRIBUTING.md)을 참조하세요.