> ## 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.

# 소스에서 빌드

> Percona Server for MySQL 8.4 기반으로 빌드된 VillageSQL Server를 소스에서 컴파일하세요.

## 개요

이 단계는 Percona Server for MySQL 8.4 기반으로 VillageSQL을 빌드합니다. 단계 1에서
복제하는 코드와 단계 3의 CMake 설정 다섯 개를 제외하면 MySQL 8.4용
[소스에서 빌드](https://villagesql.com/docs/ko/8.4/stable/source.md) 페이지와 동일합니다. Percona 빌드에 포함되는 것과
포함되지 않는 것은 [Percona Server 시작하기](https://villagesql.com/docs/ko/8.4/stable/percona.md) 페이지에 있습니다.

## 사전 요구 사항

시작하기 전에 다음이 설치되어 있는지 확인하세요:

* **Git** - 저장소 복제용
* **지원되는 플랫폼** - Debian 또는 Ubuntu Linux, 또는 [Homebrew](https://brew.sh)가 설치된 macOS

저장소에는 CMake와 빌드에 필요한 개발 라이브러리를 설치하는 스크립트가 포함되어 있습니다. Linux에서는 이 스크립트가 컴파일러도 설치하며, macOS에서는 Xcode Command Line Tools가 컴파일러를 제공합니다. 단계 2에서 그 스크립트를 실행하므로 해당 패키지를 직접 설치할 필요가 없습니다.

## 단계 1: 저장소 복제

GitHub에서 VillageSQL Server 저장소를 복제합니다. CMake 단계가 수정 없이 작동하도록 홈 디렉터리에 복제하세요:

```bash theme={null}
cd "$HOME"
git clone --depth 1 -b publish/percona-8.4_0.0.7 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

> [!NOTE]
>
> 저장소는 MySQL 코드베이스로 인해 몇 GB에 달합니다.

## 단계 2: 빌드 종속성 설치

방금 복제한 저장소에서 설정 스크립트를 실행하세요. 이 스크립트는 운영 체제를 감지하여 빌드에 필요한 패키지를 설치합니다:

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh
```

Linux에서 이 스크립트는 `apt-get`을 사용하며 `sudo`를 요청합니다. macOS에서는 Homebrew를 사용합니다. VillageSQL CI도 동일한 스크립트로 빌드 종속성을 설치하므로 패키지 목록은 빌드와 함께 최신 상태로 유지됩니다.

> [!NOTE]
>
> 이 스크립트는 Debian 또는 Ubuntu Linux와 macOS를 지원합니다. 다른 Linux
> 배포판에서는 `villagesql/bld_tools/setup_linux_build_env.sh`를 읽고 사용 중인
> 패키지 관리자로 동등한 패키지를 설치하세요.

## 단계 3: CMake로 구성

저장소 외부에 빌드 디렉터리를 만들고 프로젝트를 구성합니다:

```bash theme={null}
# Create build directory (outside the repo)
mkdir -p "$HOME/build/villagesql"
cd "$HOME/build/villagesql"

# Configure with CMake
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
  -DWITH_CURL=system -DWITH_ROCKSDB=0 -DWITH_COREDUMPER=OFF \
  -DWITHOUT_COMPONENT_KEYRING_KMIP=ON -DWITH_AUTH_OPENID_CONNECT=OFF
```

macOS에서는 OpenSSL 3 디렉터리도 지정하세요. Homebrew의 버전 없는 `openssl`은 이제 OpenSSL 4이며, 서버는 OpenSSL 4로 빌드되지 않습니다.

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
  -DWITH_SSL="$(brew --prefix openssl@3)" \
  -DWITH_CURL=system -DWITH_ROCKSDB=0 -DWITH_COREDUMPER=OFF \
  -DWITHOUT_COMPONENT_KEYRING_KMIP=ON -DWITH_AUTH_OPENID_CONNECT=OFF
```

> [!NOTE]
>
> 경로는 두 플랫폼 모두에서 `~` 대신 `$HOME`을 사용합니다. 셸은 단어의 시작
> 부분에서만 `~`를 확장하므로, `--datadir=~/mysql-data/data`는 `mysqld`에
> 문자 그대로 `~`라는 이름의 디렉터리로 전달되고 서버는 중단됩니다.
> `"$HOME/..."`와 같이 큰따옴표로 감싸면 홈 디렉터리 이름에 공백이 있어도 경로가 하나로
> 유지됩니다. 저장소 경로가 다른 경우 실제 복제 위치로 대체하세요.

### CMake 옵션 설명

* `"$HOME/villagesql-server"` - 복제된 VillageSQL 저장소 경로
* `-DWITH_DEBUG=1` - DBUG 기능과 어서션을 활성화한, 최적화되지 않은 빌드를 만듭니다 (개발에 권장됨)
* `-DWITH_CURL=system` - 시스템 curl 라이브러리로 빌드합니다. Percona의 `keyring_vault` 컴포넌트에 필요하며, 단계 2에서 설치합니다.
* `-DWITH_ROCKSDB=0`, `-DWITH_COREDUMPER=OFF`, `-DWITHOUT_COMPONENT_KEYRING_KMIP=ON`, `-DWITH_AUTH_OPENID_CONNECT=OFF` - MyRocks, coredumper 라이브러리, KMIP 키링 컴포넌트, OpenID Connect 인증을 제외합니다. VillageSQL 릴리스도 이들을 제외하며, 앞의 세 가지는 소스가 저장소에 없으므로 이 설정이 없으면 구성 단계가 실패합니다.
* `-DWITH_SSL="$(brew --prefix openssl@3)"` - cmake가 OpenSSL 3을 사용하도록 지정합니다. 단계 2에서 `openssl@3`을 설치합니다. 단계 2를 건너뛰었다면 먼저 `brew install openssl@3`을 실행하세요. `brew --prefix openssl@3`은 패키지가 없어도 경로를 출력하므로, cmake는 `Wrong option or path for WITH_SSL=`으로 중단됩니다.

> [!NOTE]
>
> 재구성해야 할 경우 먼저 CMake 캐시를 지우세요 (빌드 디렉터리에서 실행):
>
> ```bash theme={null}
> rm CMakeCache.txt
> ```

## 단계 4: 코드 컴파일

병렬 컴파일로 make를 사용하여 VillageSQL을 빌드합니다. 빌드 디렉터리에서 실행하세요:

**모든 항목 빌드 (권장):**

```bash theme={null}
make -j10
```

이 명령은 서버, [단계 7](#step-7-connect-with-mysql-client)에서 연결에 사용하는 `mysql` 클라이언트, 확장 SDK, 예제 확장의 `.veb` 파일을 빌드합니다.

**서버와 클라이언트만 빌드:**

```bash theme={null}
make -j10 mysqld mysql
```

이 조합은 더 빠르지만 확장 SDK와 예제 `.veb` 파일은 빌드하지 않습니다. 따라서 `INSTALL EXTENSION vsql_complex`는 설치할 번들을 찾지 못하고, `-DVillageSQL_BUILD_DIR`를 전달하는 확장 빌드는 SDK를 찾지 못합니다.

> [!TIP]
>
> 병렬 처리 (`-j10`)를 CPU 코어 수에 따라 조정하세요. 전체 코어 수에서 2-4를 빼서 시스템 반응성을 유지하세요. 예를 들어 12코어 머신에서는 `-j10`을 사용하세요.

완료되면 서버 및 클라이언트 이진 파일이 빌드되었는지 확인합니다:

```bash theme={null}
ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"
```

## 단계 5: 데이터베이스 초기화

서버를 처음 시작하기 전에 데이터 디렉터리를 초기화합니다:

프로덕션 (생성된 비밀번호 포함 - 권장):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

개발 (비밀번호 없음 - 선택):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

> [!NOTE]
>
> 프로덕션과 유사한 환경에서는 `--initialize` (비밀번호 포함)를 사용하세요. `--initialize-insecure` (비밀번호 없음)은 로컬 개발 및 테스트에만 사용하세요. `--initialize` 사용 시 임시 비밀번호가 콘솔에 생성되어 표시됩니다: `A temporary password is generated for root@localhost: <password>`

초기화 성공 여부를 확인하려면 시스템 데이터베이스가 생성되었는지 확인합니다:

```bash theme={null}
ls "$HOME/mysql-data/data/mysql"
```

## 단계 6: 서버 시작

VillageSQL 서버를 시작합니다:

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

**root로 실행 (Docker 또는 sudo):**

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

> [!TIP]
>
> `--gdb` 플래그는 `SIGINT`의 차단을 해제하므로, 터미널에서 실행할 때 Ctrl-C로 서버를 종료할 수 있습니다. 또한 크래시 백트레이스를 억제하고 `--core-file`을 무효화하므로, 크래시 리포트가 필요하다면 이 플래그를 사용하지 마세요. 백그라운드에서 실행하려면 `mysqld` 명령에 `--daemonize`를 추가하세요.

## 단계 7: MySQL 클라이언트로 연결

새 터미널을 열고 MySQL 클라이언트로 서버에 연결합니다:

`--initialize-insecure` 사용 (비밀번호 없음):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root
```

`--initialize` 사용 (생성된 비밀번호 포함):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root -p
# Enter the temporary password printed during initialization
```

MySQL 프롬프트가 표시되어야 합니다:

```
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version>

mysql>
```

### Root 비밀번호 변경

`--initialize`를 사용한 경우 임시 비밀번호를 변경합니다:

```sql theme={null}
SET PASSWORD = 'your-secure-password';
```

### 설치 확인

VillageSQL을 실행 중인지 확인합니다:

```sql theme={null}
SELECT VERSION();
```

개발 빌드는 버전 문자열에 git 커밋 해시를 포함합니다:

```
8.4.11-villagesql-0.0.7-dev-aaa9ffc2-debug
```

서버가 Percona 기반으로 빌드되었는지 확인합니다:

```sql theme={null}
SELECT @@villagesql_server_version;
```

```
percona-8.4_0.0.7-dev
```

## 단계 8: 사용자 및 데이터베이스 설정

### 개발 사용자 생성

일상 개발을 위해 root가 아닌 사용자를 생성합니다:

```sql theme={null}
-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;
```

세션을 종료하고 새 사용자로 다시 연결합니다:

```bash theme={null}
# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p
```

### 데이터베이스 생성

```sql theme={null}
CREATE DATABASE my_database;
USE my_database;
```

> [!TIP]
>
> 특정 데이터베이스에 연결: `"$HOME/build/villagesql/bin/mysql" -u developer -p -D my_database`

## 단계 9: 테스트 실행

빌드 디렉터리에서 VillageSQL 테스트 스위트로 빌드를 검증합니다. 테스트는 일반 사용자로 실행하세요. root로 실행하면 테스트 러너가 일부 테스트를 건너뛰고, 그중 하나는 실패합니다.

```bash theme={null}
cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto
```

`--nounit-tests`는 알려진 실패를 포함하는 업스트림 MySQL 단위 테스트를 건너뜁니다. VillageSQL 단위 테스트는 따로 실행하세요:

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

테스트가 실패하면 두 명령 중 어느 쪽이든 0이 아닌 값으로 종료됩니다.

GDB 디버깅, 개별 테스트 실행, 예상 결과 다시 기록, 서버 코드베이스 기여를 위해 [서버 개발 가이드](https://villagesql.com/docs/ko/8.4/stable/server-development.md)를 참조하세요.

## 문제 해결

### 빌드가 누락된 종속성으로 인해 실패

설정 스크립트를 다시 실행하세요. [단계 3](#step-3-configure-with-cmake)을 마치면 빌드 디렉터리에 있게 되므로 스크립트의 절대 경로를 지정하세요:

```bash theme={null}
"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"
```

오류 메시지에서 누락된 특정 라이브러리를 확인하세요.

### 서버가 시작되지 않습니다

* 데이터 디렉터리가 초기화되었는지 확인: `ls "$HOME/mysql-data/data/"`
* 다른 MySQL/VillageSQL 인스턴스가 포트 3306을 사용 중인지 확인
* `mysqld`가 터미널에 출력하는 메시지를 읽거나, `--log-error="$HOME/mysql-data/error.log"`로 서버를 시작하고 그 파일을 읽으세요

### 확장 설치 실패

* 확장 `.veb` 파일이 `veb_dir` 디렉터리(소스 빌드의 경우 `$HOME/build/villagesql/lib/veb`)에 존재하고, 그 라이브러리 이름이 Linux와 macOS 모두에서 `<extension_name>.so`인지 확인
* VillageSQL이 확장을 로드할 수 있는 권한이 있는지 확인
* 확장 이름 및 `.veb` 파일 이름이 올바른지 확인

## 다음 단계

> [card] [확장 사용](https://villagesql.com/docs/ko/extensions/install.md)
>
> VillageSQL 확장 설치, 업데이트, 관리 방법을 배웁니다.

> [card] [확장 만들기](https://villagesql.com/docs/ko/extensions/build/create.md)
>
> VillageSQL용 사용자 정의 확장을 구축합니다.

> [card] [설치](https://villagesql.com/docs/ko/8.4/stable/install-server.md)
>
> VillageSQL 빠른 시작 가이드.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.