> ## 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 built on Percona Server for MySQL 8.4 from source.

## Overview

These steps build VillageSQL on Percona Server for MySQL 8.4. They match the
[MySQL 8.4 build](https://villagesql.com/docs/en/8.4/dev/source.md), except for the code you clone in
Step 1 and five CMake settings in Step 3. What the Percona build includes and
leaves out is on the [Get Started with Percona Server](https://villagesql.com/docs/en/8.4/dev/percona.md) page.

## Prerequisites

Before you begin, ensure you have the following installed:

* **Git** - For cloning the repository
* **A supported platform** - Debian or Ubuntu Linux, or macOS with [Homebrew](https://brew.sh)

The repository ships a script that installs CMake and the development libraries the build needs. On Linux it also installs the compiler; on macOS the Xcode Command Line Tools provide it. Step 2 runs that script, so you do not
have to install those packages yourself.

## 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 -b percona-8.4 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

> [!NOTE]
>
> The repository is several GB due to the MySQL codebase.

## Step 2: Install Build Dependencies

Run the setup script from the repository you just cloned. The script detects
your operating system and installs the packages the build needs:

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

On Linux the script uses `apt-get` and asks for `sudo`. On macOS it uses
Homebrew. VillageSQL CI installs its build dependencies with the same script,
so the package list stays current with the build.

> [!NOTE]
>
> The script supports Debian or Ubuntu Linux and macOS. On another Linux
> distribution, read `villagesql/bld_tools/setup_linux_build_env.sh` and
> install the equivalent packages with your own package manager.

## Step 3: Configure with CMake

Create a build directory outside the repository and configure the project:

```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
```

On macOS, add the OpenSSL 3 directory to that command. Homebrew's unversioned
`openssl` is now OpenSSL 4, which the server does not build against:

```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]
>
> Paths use `$HOME` rather than `~` throughout, on both platforms. The shell only
> expands `~` at the start of a word, so `--datadir=~/mysql-data/data` reaches
> `mysqld` as a directory literally named `~` and the server aborts. Quoting
> `"$HOME/..."` also keeps the path in one piece if your home directory name
> contains a space. Replace the repository path with your actual clone location
> if different.

### CMake Options Explained

* `"$HOME/villagesql-server"` - Path to the cloned VillageSQL repository
* `-DWITH_DEBUG=1` - Builds with the DBUG facility and assertions, unoptimized (recommended for development)
* `-DWITH_CURL=system` - Builds with the system curl library. Percona's `keyring_vault` component needs it; Step 2 installs it.
* `-DWITH_ROCKSDB=0`, `-DWITH_COREDUMPER=OFF`, `-DWITHOUT_COMPONENT_KEYRING_KMIP=ON`, `-DWITH_AUTH_OPENID_CONNECT=OFF` - Leave out MyRocks, the coredumper library, the KMIP keyring component, and OpenID Connect authentication. The VillageSQL release leaves them out too, and the source for the first three is not in the repository, so the configure step fails without these settings.
* `-DWITH_SSL="$(brew --prefix openssl@3)"` - Points cmake at OpenSSL 3. Step 2 installs `openssl@3`. If you skipped Step 2, run `brew install openssl@3` first, because `brew --prefix openssl@3` prints a path even when the package is absent, and cmake then stops with `Wrong option or path for WITH_SSL=`.

> [!NOTE]
>
> If you need to reconfigure, clear the CMake cache first (run from within the build directory):
>
> ```bash theme={null}
> rm CMakeCache.txt
> ```

## Step 4: Compile the Code

Build VillageSQL using make with parallel compilation. From within the build directory:

**Build everything (recommended):**

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

This builds the server, the `mysql` client that
[Step 7](#step-7-connect-with-mysql-client) uses, the extension SDK, and the
example extensions' `.veb` files.

**Build the server and client only:**

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

This pair is faster and builds neither the extension SDK nor the example
`.veb` files, so `INSTALL EXTENSION vsql_complex` finds no bundle to install
and an extension build that passes `-DVillageSQL_BUILD_DIR` finds no SDK.

> [!TIP]
>
> 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 and client binaries were built:

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

## Step 5: Initialize the Database

Before starting the server for the first time, initialize the data directory:

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"
```

> [!NOTE]
>
> 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: <password>`

Verify initialization succeeded by checking that the system databases were created:

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

## Step 6: Start the Server

Start the VillageSQL server:

```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"
```

> [!TIP]
>
> The `--gdb` flag unblocks `SIGINT`, so Ctrl-C stops the server when you run it from a terminal. It also suppresses the crash backtrace and cancels `--core-file`, so leave it out when you want a crash report. To run in the background, add `--daemonize` to the `mysqld` command.

## Step 7: Connect with MySQL Client

Open a new terminal and connect to the server using the MySQL client:

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
```

You should see the MySQL prompt:

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

mysql>
```

### Change Root Password

If you used `--initialize`, change the temporary password:

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

### 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.11-villagesql-0.0.7-dev-aaa9ffc2-debug
```

Check that the server was built on Percona:

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

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

## Step 8: Set Up Users and Database

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

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

### Create a Database

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

> [!TIP]
>
> Connect to a specific database: `"$HOME/build/villagesql/bin/mysql" -u developer -p -D my_database`

## Step 9: Run the Tests

Verify the build with the VillageSQL test suite, from the build directory. Run the tests as an ordinary user: as root, the test runner skips some tests, and one of them fails.

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

`--nounit-tests` skips the upstream MySQL unit tests, which include known failures. Run the VillageSQL unit tests separately:

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

A failing test makes either command exit non-zero.

For GDB debugging, running individual tests, re-recording expected results, and contributing to the server codebase, see the [Server Development Guide](https://villagesql.com/docs/en/8.4/dev/server-development.md).

## Troubleshooting

### Build Fails with Missing Dependencies

Run the setup script again. [Step 3](#step-3-configure-with-cmake) leaves you in
the build directory, so give the script its absolute path:

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

Check the error message for the specific missing library.

### Server Won't Start

* Verify the data directory was initialized: `ls "$HOME/mysql-data/data/"`
* Check if another MySQL/VillageSQL instance is using port 3306
* Read the messages that `mysqld` prints in its terminal, or start it with `--log-error="$HOME/mysql-data/error.log"` and read that file

### Extension Installation Fails

* Ensure the extension `.veb` file exists in the `veb_dir` directory (`$HOME/build/villagesql/lib/veb` for a source build) and that its library is named `<extension_name>.so` on Linux and macOS
* Check that VillageSQL has the necessary permissions to load extensions
* Verify the extension name and .veb filename are correct

## Next Steps

> [card] [Using Extensions](https://villagesql.com/docs/en/extensions/install.md)
>
> Learn how to install, update, and manage VillageSQL extensions.

> [card] [Creating Extensions](https://villagesql.com/docs/en/extensions/build/create.md)
>
> Build your own custom extensions for VillageSQL.

> [card] [Install](https://villagesql.com/docs/en/8.4/dev/install-server.md)
>
> Quick start guide for VillageSQL.


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