> ## 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
* **A supported platform** - Debian or Ubuntu Linux, or macOS with [Homebrew](https://brew.sh)

The repository ships a script that installs the compiler, CMake, and the
development libraries the build needs. 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 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

<Note>
  The repository is several GB due to the MySQL codebase.
</Note>

## 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.
</Note>

## 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 -DCMAKE_INSTALL_PREFIX="$HOME/mysql"
```

On macOS, add `-DWITH_SSL=system` so CMake finds the Homebrew OpenSSL:

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 -DCMAKE_INSTALL_PREFIX="$HOME/mysql" -DWITH_SSL=system
```

<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.
</Note>

### CMake Options Explained

* `<path-to-repo>` - Path to the cloned VillageSQL repository
* `-DWITH_DEBUG=1` - Enables debug symbols (recommended for development)
* `-DCMAKE_INSTALL_PREFIX="$HOME/mysql"` - Sets installation directory
* `-DWITH_SSL=system` - Uses system OpenSSL library (required on macOS)

### Additional CMake Options

**Production build without debug symbols:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DCMAKE_INSTALL_PREFIX=/usr/local/mysql
```

**With custom compilation comment:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCMAKE_INSTALL_PREFIX="$HOME/mysql" \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```

**Developer mode with stricter warnings:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DMYSQL_MAINTAINER_MODE=ON -DWITH_DEBUG=1
```

<Note>
  If you need to reconfigure, clear the CMake cache first (run from within the build directory):

  ```bash theme={null}
  rm CMakeCache.txt
  ```
</Note>

## Step 4: Compile the Code

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

**Build the server and client (recommended for development):**

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

The `mysql` target builds the client used to connect in
[Step 7](#step-7-connect-with-mysql-client); `make -j10 mysqld` alone builds
only the server, and Step 7 would then have no client to run.

**Build everything:**

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

<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`.
</Tip>

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

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

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

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 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.
</Tip>

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

```
9.7.2-villagesql-0.0.6-dev-5a64e122090
```

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

```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: `mysql -u developer -p -D my_database`
</Tip>

For GDB debugging, running tests, and contributing to the server codebase, see the [Server Development Guide](/docs/mysql-9.7/dev/server-development).

## 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
* Review error logs in `$HOME/mysql-data/data/*.err`

### Extension Installation Fails

* Ensure the extension library (`.so` on Linux, `.dylib` on macOS) 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

<CardGroup cols={3}>
  <Card title="Using Extensions" icon="puzzle-piece" href="/docs/mysql-9.7/dev/install">
    Learn how to install, update, and manage VillageSQL extensions.
  </Card>

  <Card title="Creating Extensions" icon="code" href="/docs/mysql-9.7/dev/create">
    Build your own custom extensions for VillageSQL.
  </Card>

  <Card title="Getting Started" icon="rocket" href="/docs/mysql-9.7/dev/index">
    Quick start guide for VillageSQL.
  </Card>
</CardGroup>