소스에서 빌드

개요

소스에서 VillageSQL을 빌드하면 최신 기능을 얻을 수 있으며, 특정 환경에 맞게 빌드를 사용자 정의할 수 있습니다. 이 단계는 업스트림 MySQL 8.4 기반으로 VillageSQL을 빌드합니다. VillageSQL은 대체 코드베이스로 Percona Server 기반으로도 빌드됩니다 — Percona 빌드 페이지를 참조하세요.

사전 요구 사항

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

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

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

단계 1: 저장소 복제

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

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

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

릴리스가 배포한 코드를 정확히 그대로 빌드하려면, 브랜치 대신 그 릴리스를 표시하는 태그를 복제하세요: -b publish/mysql-8.4_0.0.7.

단계 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에서는 OpenSSL 3 디렉터리도 지정하세요. Homebrew의 버전 없는 openssl은 이제 OpenSSL 4이며, 서버는 OpenSSL 4로 빌드되지 않습니다.

cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
  -DWITH_SSL="$(brew --prefix openssl@3)"

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

CMake 옵션 설명

"$HOME/villagesql-server" - 복제된 VillageSQL 저장소 경로
-DWITH_DEBUG=1 - DBUG 기능과 어서션을 활성화한, 최적화되지 않은 빌드를 만듭니다 (개발에 권장됨)
-DCMAKE_INSTALL_PREFIX="$HOME/mysql" - 설치 디렉터리 설정
-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=으로 중단됩니다.

추가 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 캐시를 지우세요 (빌드 디렉터리에서 실행):

rm CMakeCache.txt

단계 4: 코드 컴파일

병렬 컴파일로 make를 사용하여 VillageSQL을 빌드합니다. 빌드 디렉터리에서 실행하세요: 모든 항목 빌드 (권장):

make -j10

이 명령은 서버, 단계 7에서 연결에 사용하는 mysql 클라이언트, 확장 SDK, 예제 확장의 VEB 파일을 빌드합니다. 서버와 클라이언트만 빌드:

make -j10 mysqld mysql

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

병렬 처리 (-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 플래그는 SIGINT의 차단을 해제하므로, 터미널에서 실행할 때 Ctrl-C로 서버를 종료할 수 있습니다. 또한 크래시 백트레이스를 억제하고 --core-file을 무효화하므로, 크래시 리포트가 필요하다면 이 플래그를 사용하지 마세요. 백그라운드에서 실행하려면 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 MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version> Source distribution

mysql>

Root 비밀번호 변경

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

SET PASSWORD = 'your-secure-password';

설치 확인

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

SELECT VERSION();

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

8.4.11-villagesql-0.0.7-dev-689c74a9-debug

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

개발 사용자 생성

일상 개발을 위해 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

단계 9: 테스트 실행

빌드 디렉터리에서 VillageSQL 테스트 스위트로 빌드를 검증합니다:

cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto

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

make -j10 villagesql-unit-tests && ctest -L villagesql

테스트가 실패하면 두 명령 중 어느 쪽이든 0이 아닌 값으로 종료됩니다. GDB 디버깅, 개별 테스트 실행, 예상 결과 다시 기록, 서버 코드베이스 기여를 위해 서버 개발 가이드를 참조하세요.

네이티브 패키지 빌드 (RPM/DEB)

villagesql/bld_tools/build_deb.sh와 build_rpm.sh는 소스 트리에서 바로 Debian 또는 RPM 패키지를 빌드하므로, 위의 수동 단계를 따르는 대신 패키지 관리자로 설치할 수 있습니다. 둘 다 사전 CMake 구성이 필요하지 않습니다 — 둘 다 저장소 루트의 VSQL_VERSION 및 MYSQL_VERSION 파일에서 패키지 버전을 가져옵니다. 단계 1-2를 이미 마쳤다면, 패키징 도구와 단계 2가 설치하지 않는 빌드 종속성을 설치하세요 — Debian/Ubuntu에서는 dpkg-dev, debhelper, libcurl4-openssl-dev, libsystemd-dev, systemd-dev, Enterprise Linux에서는 rpm-build — 그런 다음 저장소 루트에서 둘 중 하나를 실행합니다:

cd "$HOME/villagesql-server"
villagesql/bld_tools/build_deb.sh   # writes to ./debs
# or
villagesql/bld_tools/build_rpm.sh   # writes to ./rpms

이 도구를 추가한 villagesql-server#931에 따르면, 생성된 패키지는 대상 호스트의 기존 MySQL 설치와 나란히 설치되는 것이 아니라 그것을 대체합니다.

문제 해결

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

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

"$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 파일 이름이 올바른지 확인

다음 단계

확장 사용

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

확장 만들기

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

빠른 시작

VillageSQL 빠른 시작 가이드.

Getting Started

Server Development

Using Extensions

Creating Extensions

개요

사전 요구 사항

단계 1: 저장소 복제

단계 2: 빌드 종속성 설치

단계 3: CMake로 구성

CMake 옵션 설명

추가 CMake 옵션

단계 4: 코드 컴파일

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

단계 6: 서버 시작

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

Root 비밀번호 변경

설치 확인

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

개발 사용자 생성

데이터베이스 생성

단계 9: 테스트 실행

네이티브 패키지 빌드 (RPM/DEB)

문제 해결

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

서버가 시작되지 않습니다

확장 설치 실패

다음 단계

확장 사용

확장 만들기

빠른 시작

​개요

​사전 요구 사항

​단계 1: 저장소 복제

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

​단계 3: CMake로 구성

​CMake 옵션 설명

​추가 CMake 옵션

​단계 4: 코드 컴파일

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

​단계 6: 서버 시작

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

​Root 비밀번호 변경

​설치 확인

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

​개발 사용자 생성

​데이터베이스 생성

​단계 9: 테스트 실행

​네이티브 패키지 빌드 (RPM/DEB)

​문제 해결

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

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

​확장 설치 실패

​다음 단계

확장 사용

확장 만들기

빠른 시작

개요

사전 요구 사항

단계 1: 저장소 복제

단계 2: 빌드 종속성 설치

단계 3: CMake로 구성

CMake 옵션 설명

추가 CMake 옵션

단계 4: 코드 컴파일

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

단계 6: 서버 시작

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

Root 비밀번호 변경

설치 확인

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

개발 사용자 생성

데이터베이스 생성

단계 9: 테스트 실행

네이티브 패키지 빌드 (RPM/DEB)

문제 해결

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

서버가 시작되지 않습니다

확장 설치 실패

다음 단계