소스에서 빌드

개요

소스에서 VillageSQL을 빌드하면 최신 기능을 얻을 수 있으며, 특정 환경에 맞게 빌드를 사용자 정의할 수 있습니다.

사전 요구 사항

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

Git - 저장소 복제용
지원되는 플랫폼 - Debian 또는 Ubuntu Linux, 또는 Homebrew가 설치된 macOS

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

단계 1: 저장소 복제

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

cd "$HOME"
git clone --depth 1 https://github.com/villagesql/villagesql-server.git
cd villagesql-server

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

단계 2: 빌드 종속성 설치

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

cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh

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

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

단계 3: CMake로 구성

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

# 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에서는 CMake가 Homebrew의 OpenSSL을 찾을 수 있도록 -DWITH_SSL=system을 추가하세요:

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" -DWITH_SSL=system

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

CMake 옵션 설명

<path-to-repo> - 복제된 VillageSQL 저장소 경로
-DWITH_DEBUG=1 - 디버그 심볼 활성화 (개발에 권장됨)
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - 설치 디렉터리 설정
-DWITH_SSL=system - 시스템 OpenSSL 라이브러리 사용 (macOS에서 필수)

추가 CMake 옵션

디버그 심볼 없이 프로덕션 빌드:

cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql

사용자 정의 컴파일 주석 포함:

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"

더 엄격한 경고로 개발자 모드:

cmake "$HOME/villagesql-server" -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1

재구성해야 할 경우 먼저 CMake 캐시를 지우세요 (빌드 디렉터리에서 실행):

rm CMakeCache.txt

단계 4: 코드 컴파일

병렬 컴파일로 make를 사용하여 VillageSQL을 빌드합니다. 빌드 디렉터리에서 실행하세요: 서버와 클라이언트 빌드 (개발에 권장):

make -j10 mysqld mysql

mysql 대상은 단계 7에서 연결에 사용하는 클라이언트를 빌드합니다. make -j10 mysqld만 실행하면 서버만 빌드되며, 단계 7에서 실행할 클라이언트가 없게 됩니다. 모든 항목 빌드:

make -j10

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

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

ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"

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

서버를 처음 시작하기 전에 데이터 디렉터리를 초기화합니다: 프로덕션 (생성된 비밀번호 포함 - 권장):

mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

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

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 플래그가 필요합니다:

# Initialize as root
"$HOME/build/villagesql/bin/mysqld" --user=root --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

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

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

ls "$HOME/mysql-data/data/mysql"

단계 6: 서버 시작

VillageSQL 서버를 시작합니다:

"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

root로 실행 (Docker 또는 sudo):

"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"

--gdb 플래그는 Ctrl-C로 서버를 정상적으로 종료할 수 있도록 SIGINT 핸들러를 설치합니다 — 터미널에서 대화식으로 실행할 때 유용합니다. 백그라운드에서 실행하려면 mysqld 명령에 --daemonize를 추가하세요.

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

새 터미널을 열고 MySQL 클라이언트로 서버에 연결합니다: --initialize-insecure 사용 (비밀번호 없음):

"$HOME/build/villagesql/bin/mysql" -u root

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

"$HOME/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을 실행 중인지 확인합니다:

SELECT VERSION();

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

9.7.2-villagesql-0.0.6-dev-5a64e122090

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

Root 비밀번호 변경

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

SET PASSWORD = 'your-secure-password';

개발 사용자 생성

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

-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

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

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

# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p

데이터베이스 생성

CREATE DATABASE my_database;
USE my_database;

특정 데이터베이스에 연결: mysql -u developer -p -D my_database

GDB 디버깅, 테스트 실행, 서버 코드베이스 기여를 위해 서버 개발 가이드를 참조하세요.

문제 해결

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

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

"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"

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

서버가 시작되지 않습니다

데이터 디렉터리가 초기화되었는지 확인: ls "$HOME/mysql-data/data/"
다른 MySQL/VillageSQL 인스턴스가 포트 3306을 사용 중인지 확인
$HOME/mysql-data/data/*.err에서 오류 로그 검토

확장 설치 실패

확장 라이브러리 (Linux에서는 .so, macOS에서는 .dylib)가 빌드 출력에 존재하는지 확인
VillageSQL이 확장을 로드할 수 있는 권한이 있는지 확인
확장 이름 및 .veb 파일 이름이 올바른지 확인

다음 단계

확장 사용

VillageSQL 확장 설치, 업데이트, 관리 방법을 배웁니다.

확장 만들기

VillageSQL용 사용자 정의 확장을 구축합니다.

빠른 시작

VillageSQL 빠른 시작 가이드.

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

개요

사전 요구 사항

단계 1: 저장소 복제

단계 2: 빌드 종속성 설치

단계 3: CMake로 구성

CMake 옵션 설명

추가 CMake 옵션

단계 4: 코드 컴파일

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

단계 6: 서버 시작

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

설치 확인

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

Root 비밀번호 변경

개발 사용자 생성

데이터베이스 생성

문제 해결

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

서버가 시작되지 않습니다

확장 설치 실패

다음 단계

확장 사용

확장 만들기

빠른 시작

​개요

​사전 요구 사항

​단계 1: 저장소 복제

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

​단계 3: CMake로 구성

​CMake 옵션 설명

​추가 CMake 옵션

​단계 4: 코드 컴파일

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

​단계 6: 서버 시작

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

​설치 확인

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

​Root 비밀번호 변경

​개발 사용자 생성

​데이터베이스 생성

​문제 해결

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

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

​확장 설치 실패

​다음 단계

확장 사용

확장 만들기

빠른 시작

개요

사전 요구 사항

단계 1: 저장소 복제

단계 2: 빌드 종속성 설치

단계 3: CMake로 구성

CMake 옵션 설명

추가 CMake 옵션

단계 4: 코드 컴파일

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

단계 6: 서버 시작

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

설치 확인

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

Root 비밀번호 변경

개발 사용자 생성

데이터베이스 생성

문제 해결

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

서버가 시작되지 않습니다

확장 설치 실패

다음 단계