> ## 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. # Build from Source > Compile VillageSQL Server for MySQL from source code and get started with extensions. ## Overview Building VillageSQL from source gives you the latest features and allows you to customize the build for your specific environment. ## Prerequisites Before you begin, ensure you have the following installed: * **Git** - For cloning the repository * **CMake** 3.16 or higher - Build system generator * **C++ Compiler** - GCC 8+, Clang 8+, or MSVC 2019+ * **Build tools** - make, ninja, or equivalent * **Development libraries** - OpenSSL, ncurses, pkg-config, bison, and other MySQL dependencies ### Install Dependencies **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 (using Homebrew):** First, install Homebrew if you haven't already: ```bash theme={null} /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Then install dependencies: ```bash theme={null} brew install cmake openssl pkgconf bison libtirpc rpcsvc-proto ``` ## Step 1: Clone the Repository Clone the VillageSQL Server repository from GitHub. Clone into your home directory so the CMake steps below work without modification: ```bash theme={null} cd $HOME git clone --depth 1 https://github.com/villagesql/villagesql-server.git cd villagesql-server ``` The repository is several GB due to the MySQL codebase. ## Step 2: Configure with CMake Create a build directory outside the repository and configure the project: **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 users:** Use `$HOME` for absolute paths. **macOS users:** Use `~` (tilde). Replace the repository path with your actual clone location if different. ### CMake Options Explained * `` - Path to the cloned VillageSQL repository (use `$HOME` on Linux, `~` on macOS) * `-DWITH_DEBUG=1` - Enables debug symbols (recommended for development) * `-DCMAKE_INSTALL_PREFIX=~/mysql` - Sets installation directory * `-DWITH_SSL=system` - Uses system OpenSSL library (required on macOS) ### Additional CMake Options **Production build without debug symbols:** 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 ``` **With custom compilation comment:** 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" ``` **Developer mode with stricter warnings:** 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 ``` If you need to reconfigure, clear the CMake cache first (run from within the build directory): ```bash theme={null} rm CMakeCache.txt ``` ## Step 3: Compile the Code Build VillageSQL using make with parallel compilation. From within the build directory: **Build only the server (recommended for development):** ```bash theme={null} make -j10 mysqld ``` **Build everything:** ```bash theme={null} make -j10 ``` Adjust the parallelism (`-j10`) based on your CPU cores. Subtract 2-4 from your total core count to keep your system responsive. For example, on a 12-core machine, use `-j10`. When complete, verify the server binary was built: **Linux:** ```bash theme={null} ls $HOME/build/villagesql/bin/mysqld ``` **macOS:** ```bash theme={null} ls ~/build/villagesql/bin/mysqld ``` ## Step 4: Initialize the Database Before starting the server for the first time, initialize the data directory: **Linux:** Production (with generated password - recommended): ```bash theme={null} mkdir -p $HOME/mysql-data/data $HOME/build/villagesql/bin/mysqld --initialize --datadir=$HOME/mysql-data/data --basedir=$HOME/build/villagesql ``` Development (no password - optional): ```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 ``` **Running as root (Docker or sudo):** If running as root (e.g., in Docker), MySQL requires the `--user=root` flag: ```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:** Production (with generated password - recommended): ```bash theme={null} mkdir -p ~/mysql-data/data ~/build/villagesql/bin/mysqld --initialize --datadir=~/mysql-data/data --basedir=~/build/villagesql ``` Development (no password - optional): ```bash theme={null} mkdir -p ~/mysql-data/data ~/build/villagesql/bin/mysqld --initialize-insecure --datadir=~/mysql-data/data --basedir=~/build/villagesql ``` Use `--initialize` (with password) for production-like setups. Use `--initialize-insecure` (no password) only for local development and testing. When using `--initialize`, a temporary password will be generated and printed to the console: `A temporary password is generated for root@localhost: ` Verify initialization succeeded by checking that the system databases were created: **Linux:** ```bash theme={null} ls $HOME/mysql-data/data/mysql ``` **macOS:** ```bash theme={null} ls ~/mysql-data/data/mysql ``` ## Step 5: Start the Server Start the VillageSQL server: **Linux:** ```bash theme={null} $HOME/build/villagesql/bin/mysqld --gdb --datadir=$HOME/mysql-data/data --basedir=$HOME/build/villagesql ``` **Running as root (Docker or 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 ``` The `--gdb` flag installs a `SIGINT` handler so Ctrl-C stops the server cleanly — useful when running interactively from a terminal. To run in the background, add `--daemonize` to the `mysqld` command. ## Step 6: Connect with MySQL Client Open a new terminal and connect to the server using the MySQL client: **Linux:** If using --initialize-insecure (no password): ```bash theme={null} $HOME/build/villagesql/bin/mysql -u root ``` If using --initialize (with generated password): ```bash theme={null} $HOME/build/villagesql/bin/mysql -u root -p # Enter the temporary password printed during initialization ``` **macOS:** If using --initialize-insecure (no password): ```bash theme={null} ~/build/villagesql/bin/mysql -u root ``` If using --initialize (with generated password): ```bash theme={null} ~/build/villagesql/bin/mysql -u root -p # Enter the temporary password printed during initialization ``` You should see the MySQL prompt: ``` Welcome to the VillageSQL Server for MySQL monitor. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql> ``` ### Verify Installation Check that you're running VillageSQL: ```sql theme={null} SELECT VERSION(); ``` Development builds include the git commit hash in the version string: ``` 8.4.10-villagesql-0.0.5 ``` ## Step 7: Set Up Users and Database ### Change Root Password If you used `--initialize`, change the temporary password: ```sql theme={null} SET PASSWORD = 'your-secure-password'; ``` ### Create a Development User For daily development, create a non-root user: ```sql theme={null} -- Create user CREATE USER developer IDENTIFIED BY 'dev-password'; -- Grant all privileges GRANT ALL PRIVILEGES ON *.* TO developer; ``` Exit and reconnect as your new user: **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 ``` ### Create a Database ```sql theme={null} CREATE DATABASE my_database; USE my_database; ``` Connect to a specific database: `mysql -u developer -p -D my_database` For GDB debugging, running tests, and contributing to the server codebase, see the [Server Development Guide](/mysql-8.4/0.0.5/server-development). ## Troubleshooting ### Build Fails with Missing Dependencies Install the required development packages for your platform. Check the error message for specific missing libraries. ### Server Won't Start * Verify the data directory was initialized: `ls ~/mysql-data/data/` * Check if another MySQL/VillageSQL instance is using port 3306 * Review error logs in `~/mysql-data/data/*.err` ### Extension Installation Fails * Ensure the extension library (`.so` or `.dll`) exists in the build output * Check that VillageSQL has the necessary permissions to load extensions * Verify the extension name and .veb filename are correct ## Next Steps Learn how to install, update, and manage VillageSQL extensions. Build your own custom extensions for VillageSQL. Quick start guide for VillageSQL.