> ## 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.
# 소스에서 빌드
> MySQL용 VillageSQL Server를 소스 코드에서 컴파일하고 확장을 시작하세요.
## 개요
소스에서 VillageSQL을 빌드하면 최신 기능을 얻을 수 있으며, 특정 환경에 맞게 빌드를 사용자 정의할 수 있습니다.
## 사전 요구 사항
시작하기 전에 다음이 설치되어 있는지 확인하세요:
* **Git** - 저장소 복제용
* **CMake** 3.16 이상 - 빌드 시스템 생성기
* **C++ 컴파일러** - GCC 8+, Clang 8+, 또는 MSVC 2019+
* **빌드 도구** - make, ninja, 또는 이와 동등한 도구
* **개발 라이브러리** - OpenSSL, ncurses, pkg-config, bison, 및 기타 MySQL 종속성
### 의존성 설치
**Ubuntu/Debian:**
```bash theme={null}
sudo apt install cmake libssl-dev libncurses5-dev pkg-config bison \
libtirpc-dev rpcsvc-proto build-essential zlib1g-dev
```
**macOS (Homebrew 사용):**
Homebrew를 설치하지 않았다면 먼저 설치하세요:
```bash theme={null}
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
그런 다음 의존성을 설치하세요:
```bash theme={null}
brew install cmake openssl pkgconf bison libtirpc rpcsvc-proto
```
## 단계 1: 저장소 복제
GitHub에서 VillageSQL Server 저장소를 복제합니다. CMake 단계가 수정 없이 작동하도록 홈 디렉터리에 복제하세요:
```bash theme={null}
cd $HOME
git clone --depth 1 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```
저장소는 MySQL 코드베이스로 인해 몇 GB에 달합니다.
## 단계 2: CMake로 구성
저장소 외부에 빌드 디렉터리를 만들고 프로젝트를 구성합니다:
**Linux:**
```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 -DCMAKE_INSTALL_PREFIX=$HOME/mysql
```
**macOS:**
```bash theme={null}
# Create build directory (outside the repo)
mkdir -p ~/build/villagesql
cd ~/build/villagesql
# Configure with CMake
cmake ~/villagesql-server -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX=~/mysql -DWITH_SSL=system
```
**Linux 사용자:** 절대 경로에 `$HOME` 사용. **macOS 사용자:** `~` (틸드) 사용. 저장소 경로가 다른 경우 실제 복제 위치로 대체하세요.
### CMake 옵션 설명
* `` - 복제된 VillageSQL 저장소 경로 (Linux에서는 `$HOME`, macOS에서는 `~` 사용)
* `-DWITH_DEBUG=1` - 디버그 심볼 활성화 (개발에 권장됨)
* `-DCMAKE_INSTALL_PREFIX=~/mysql` - 설치 디렉터리 설정
* `-DWITH_SSL=system` - 시스템 OpenSSL 라이브러리 사용 (macOS에서 필수)
### 추가 CMake 옵션
**디버그 심볼 없이 프로덕션 빌드:**
Linux:
```bash theme={null}
cmake $HOME/villagesql-server -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
```
macOS:
```bash theme={null}
cmake ~/villagesql-server -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
```
**사용자 정의 컴파일 주석 포함:**
Linux:
```bash theme={null}
cmake $HOME/villagesql-server -DWITH_DEBUG=1 \
-DCMAKE_INSTALL_PREFIX=$HOME/mysql \
-DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```
macOS:
```bash theme={null}
cmake ~/villagesql-server -DWITH_DEBUG=1 \
-DCMAKE_INSTALL_PREFIX=~/mysql \
-DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```
**더 엄격한 경고로 개발자 모드:**
Linux:
```bash theme={null}
cmake $HOME/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```
macOS:
```bash theme={null}
cmake ~/villagesql-server -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```
재구성해야 할 경우 먼저 CMake 캐시를 지우세요 (빌드 디렉터리에서 실행):
```bash theme={null}
rm CMakeCache.txt
```
## 단계 3: 코드 컴파일
병렬 컴파일로 make를 사용하여 VillageSQL을 빌드합니다. 빌드 디렉터리에서 실행하세요:
**서버만 빌드 (개발에 권장):**
```bash theme={null}
make -j10 mysqld
```
**모든 항목 빌드:**
```bash theme={null}
make -j10
```
병렬 처리 (`-j10`)를 CPU 코어 수에 따라 조정하세요. 전체 코어 수에서 2-4를 빼서 시스템 반응성을 유지하세요. 예를 들어 12코어 머신에서는 `-j10`을 사용하세요.
완료되면 서버 이진 파일이 빌드되었는지 확인합니다:
**Linux:**
```bash theme={null}
ls $HOME/build/villagesql/bin/mysqld
```
**macOS:**
```bash theme={null}
ls ~/build/villagesql/bin/mysqld
```
## 단계 4: 데이터베이스 초기화
서버를 처음 시작하기 전에 데이터 디렉터리를 초기화합니다:
**Linux:**
프로덕션 (생성된 비밀번호 포함 - 권장):
```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
```
**root로 실행 (Docker 또는 sudo):**
root로 실행하는 경우 (예: Docker), MySQL은 `--user=root` 플래그가 필요합니다:
```bash theme={null}
# Initialize as root
$HOME/build/villagesql/bin/mysqld --user=root --initialize-insecure --datadir=$HOME/mysql-data/data --basedir=$HOME/build/villagesql
```
**macOS:**
프로덕션 (생성된 비밀번호 포함 - 권장):
```bash theme={null}
mkdir -p ~/mysql-data/data
~/build/villagesql/bin/mysqld --initialize --datadir=~/mysql-data/data --basedir=~/build/villagesql
```
개발 (비밀번호 없음 - 선택):
```bash theme={null}
mkdir -p ~/mysql-data/data
~/build/villagesql/bin/mysqld --initialize-insecure --datadir=~/mysql-data/data --basedir=~/build/villagesql
```
프로덕션과 유사한 환경에서는 `--initialize` (비밀번호 포함)를 사용하세요. `--initialize-insecure` (비밀번호 없음)은 로컬 개발 및 테스트에만 사용하세요. `--initialize` 사용 시 임시 비밀번호가 콘솔에 생성되어 표시됩니다: `A temporary password is generated for root@localhost: `
초기화 성공 여부를 확인하려면 시스템 데이터베이스가 생성되었는지 확인합니다:
**Linux:**
```bash theme={null}
ls $HOME/mysql-data/data/mysql
```
**macOS:**
```bash theme={null}
ls ~/mysql-data/data/mysql
```
## 단계 5: 서버 시작
VillageSQL 서버를 시작합니다:
**Linux:**
```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
```
**macOS:**
```bash theme={null}
~/build/villagesql/bin/mysqld --gdb --datadir=~/mysql-data/data --basedir=~/build/villagesql
```
`--gdb` 플래그는 Ctrl-C로 서버를 정상적으로 종료할 수 있도록 `SIGINT` 핸들러를 설치합니다 — 터미널에서 대화식으로 실행할 때 유용합니다. 백그라운드에서 실행하려면 `mysqld` 명령에 `--daemonize`를 추가하세요.
## 단계 6: MySQL 클라이언트로 연결
새 터미널을 열고 MySQL 클라이언트로 서버에 연결합니다:
**Linux:**
`--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
```
**macOS:**
`--initialize-insecure` 사용 (비밀번호 없음):
```bash theme={null}
~/build/villagesql/bin/mysql -u root
```
`--initialize` 사용 (생성된 비밀번호 포함):
```bash theme={null}
~/build/villagesql/bin/mysql -u root -p
# Enter the temporary password printed during initialization
```
MySQL 프롬프트가 표시되어야 합니다:
```
Welcome to the VillageSQL Server for MySQL monitor.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
```
### 설치 확인
VillageSQL을 실행 중인지 확인합니다:
```sql theme={null}
SELECT VERSION();
```
개발 빌드는 버전 문자열에 git 커밋 해시를 포함합니다:
```
8.4.10-villagesql-0.0.5
```
## 단계 7: 사용자 및 데이터베이스 설정
### Root 비밀번호 변경
`--initialize`를 사용한 경우 임시 비밀번호를 변경합니다:
```sql theme={null}
SET PASSWORD = 'your-secure-password';
```
### 개발 사용자 생성
일상 개발을 위해 root가 아닌 사용자를 생성합니다:
```sql theme={null}
-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';
-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;
```
세션을 종료하고 새 사용자로 다시 연결합니다:
**Linux:**
```bash theme={null}
# Ctrl-D to exit
$HOME/build/villagesql/bin/mysql -u developer -p
```
**macOS:**
```bash theme={null}
# Ctrl-D to exit
~/build/villagesql/bin/mysql -u developer -p
```
### 데이터베이스 생성
```sql theme={null}
CREATE DATABASE my_database;
USE my_database;
```
특정 데이터베이스에 연결: `mysql -u developer -p -D my_database`
GDB 디버깅, 테스트 실행, 서버 코드베이스 기여를 위해 [서버 개발 가이드](/docs/ko/mysql-8.4/0.0.5/server-development)를 참조하세요.
## 문제 해결
### 빌드가 누락된 종속성으로 인해 실패
플랫폼에 맞는 개발 패키지를 설치하세요. 오류 메시지에서 누락된 라이브러리를 확인하세요.
### 서버가 시작되지 않습니다
* 데이터 디렉터리가 초기화되었는지 확인: `ls ~/mysql-data/data/`
* 다른 MySQL/VillageSQL 인스턴스가 포트 3306을 사용 중인지 확인
* `~/mysql-data/data/*.err`에서 오류 로그 검토
### 확장 설치 실패
* 확장 라이브러리 (`.so` 또는 `.dll`)가 빌드 출력에 존재하는지 확인
* VillageSQL이 확장을 로드할 수 있는 권한이 있는지 확인
* 확장 이름 및 `.veb` 파일 이름이 올바른지 확인
## 다음 단계
VillageSQL 확장 설치, 업데이트, 관리 방법을 배웁니다.
VillageSQL용 사용자 정의 확장을 구축합니다.
VillageSQL 빠른 시작 가이드.