DOC: Add comprehensive BUILDGUIDE.md with cross-platform build instructions and VS Code setup

BUILDGUIDE.md

@@ -0,0 +1,295 @@
+# Build Guide for Contributors
+
+Welcome to the development build guide for the **mssql-python** project!  
+This guide will help you set up your environment, build the native bindings, and package the project as a Python wheel.
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Prerequisites](#prerequisites)
+- [Platform-Specific Setup](#platform-specific-setup)
+  - [Windows](#windows)
+  - [macOS](#macos)
+  - [Linux](#linux)
+- [Building Native Bindings](#building-native-bindings)
+- [Building the Python Wheel (.whl)](#building-the-python-wheel-whl)
+- [Running Tests](#running-tests)
+- [Setting Up a Test Database (Optional)](#setting-up-a-test-database-optional)
+- [Directory Structure](#directory-structure)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Getting Started
+
+To contribute to this project, you'll need to fork and clone the repository. You can do this using either the command line or Visual Studio Code.
+
+### Option 1: Command Line
+
+1. **Fork the repository** on GitHub by clicking the "Fork" button on the [mssql-python repository page](https://github.com/microsoft/mssql-python).
+2. **Clone your fork** to your local machine:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/mssql-python.git
+   cd mssql-python
+   ```
+3. **Set up the upstream remote** to keep your fork in sync:
+   ```bash
+   git remote add upstream https://github.com/microsoft/mssql-python.git
+   ```
+
+### Option 2: Visual Studio Code
+
+1. **Install the GitHub extension** in VS Code:
+   - Open VS Code
+   - Go to the Extensions view (Ctrl+Shift+X)
+   - Search for "GitHub Pull Requests and Issues" and install it
+2. **Fork and clone the repository**:
+   - Navigate to the [mssql-python repository page](https://github.com/microsoft/mssql-python)
+   - Click "Create new fork" to create a fork in your GitHub account
+   - Open VS Code
+   - Open the Command Palette (Ctrl+Shift+P)
+   - Type "Git: Clone" and select it
+   - Select "Clone from GitHub"
+   - Search for and select your forked repository
+   - Choose a local directory to clone to
+3. **The upstream remote will be set up automatically** when you fork through GitHub.
+
+---
+
+## Prerequisites
+
+- **Python:** Minimum supported version is 3.10.  
+  Ensure `python` and `pip` commands refer to your Python 3.10+ installation.
+- **pybind11:** Used for C++/Python bindings.
+- **CMake:** For Unix and macOS builds.
+- **Microsoft ODBC Driver:** For packaging driver dependencies and header files such as `sql.h`, `sqlext.h` etc.
+- **setuptools, wheel, pytest:** For building and testing (`pip install setuptools wheel pytest`).
+
+---
+
+## Platform-Specific Setup
+
+### Windows
+
+1. **Install Python** (3.10+ from [python.org](https://www.python.org/downloads/)).
+2. **Install Visual Studio Build Tools**
+   - Include the “Desktop development with C++” workload.
+   - CMake is included by default.
+   - **Alternative for VS Code users:** If you already have VS Code installed, you can configure it for C++ development by following [this guide](https://code.visualstudio.com/docs/cpp/config-msvc).
+3. **Install Microsoft ODBC Driver for SQL Server:**  
+   [Download here](https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server).
+4. **Install required Python packages:**
+   ```bash
+   # Will install pybind11, setuptools etc.
+   pip install -r requirements.txt
+   ```
+
+### macOS
+
+1. **Install Python** (3.10+ from [python.org](https://www.python.org/downloads/)).
+2. **Install CMake:**
+   ```bash
+   brew install cmake
+   ```
+3. **Install Microsoft ODBC Driver for SQL Server:**
+   - Follow [official instructions](https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/install-microsoft-odbc-driver-sql-server-macos).
+4. **Install Python requirements:**
+   ```bash
+   # Will install pybind11, setuptools etc.
+   pip install -r requirements.txt
+   ```
+
+### Linux
+
+1. **Install Python and development tools:**
+   ```bash
+   sudo apt-get update
+   sudo apt-get install python3 python3-dev python3-pip build-essential cmake
+   ```
+   Ensure `python` and `pip` refer to Python 3.10+.
+2. **Install Microsoft ODBC Driver for SQL Server:**  
+   - Follow [official instructions](https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server).
+3. **Install Python packages:**
+   ```bash
+   # Will install pybind11, setuptools etc.
+   pip install -r requirements.txt
+   ```
+
+---
+
+## Building Native Bindings
+
+The native bindings are in the `mssql_python/pybind` directory.
+
+### Windows
+
+Open a **Developer Command Prompt for VS** and run:
+
+```bash
+cd mssql_python/pybind
+build.bat
+```
+
+This will:
+- Clean previous builds
+- Configure with CMake
+- Build the extension
+- Copy the generated `.pyd` file to the correct location
+
+### macOS & Linux
+
+```bash
+cd mssql_python/pybind
+./build.sh
+```
+
+This will:
+- Clean previous builds
+- Configure with CMake
+- Build the extension
+- Copy the generated `.so` file to the correct location
+
+---
+
+## Running Tests
+
+Tests require a database connection string and must be run from the project root directory.
+Set the `DB_CONNECTION_STRING` environment variable before running tests:
+
+> [!TIP]
+> If you are using VS Code you may have to close all open instances of the IDE for the new environment variable to be visible. If you are still getting errors about invalid connection strings, you may need to reboot your system.
+
+### Windows (Command Prompt)
+```cmd
+# If you're in mssql_python/pybind/, navigate back to the project root:
+cd ../..
+
+set DB_CONNECTION_STRING=your-connection-string-here
+python -m pytest -v
+```
+
+### macOS & Linux (bash/zsh)
+```bash
+# If you're in mssql_python/pybind/, navigate back to the project root:
+cd ../..
+
+export DB_CONNECTION_STRING=your-connection-string-here
+python -m pytest -v
+```
+
+---
+
+## Building the Python Wheel (.whl)
+
+The wheel includes the native bindings.  
+**You must build the native bindings first** (see above).
+
+### Windows
+
+From the project root:
+
+```bash
+python setup.py bdist_wheel
+```
+
+The wheel file will be created in the `dist/` directory.
+
+### macOS & Linux
+
+From the project root:
+
+```bash
+# Build the bindings first!
+cd mssql_python/pybind
+./build.sh
+cd ../..
+
+# Then build the wheel:
+python setup.py bdist_wheel
+```
+
+The wheel file will be created in the `dist/` directory.
+
+---
+
+## Directory Structure
+
+- `mssql_python/pybind/` — Native C++/pybind11 bindings and platform build scripts
+- `mssql_python/` — Python package source
+- `tests/` — Test suite
+- `dist/` — Built wheel packages
+
+---
+
+## Setting Up a Test Database (Optional)
+
+If you don't have access to a SQL Server instance, you can quickly set up a containerized SQL Server using go-sqlcmd:
+
+### Windows
+```bash
+# Install Docker Desktop and sqlcmd
+winget install Docker.DockerDesktop
+```
+Configure Docker, accept EULA, etc., then open a new terminal window:
+```bash
+winget install sqlcmd
+```
+Open a new window to get new path variables:
+```bash
+sqlcmd create mssql --name mssql-python --accept-eula tag 2025-latest --using https://github.com/Microsoft/sql-server-samples/releases/download/wide-world-importers-v1.0/WideWorldImporters-Full.bak
+sqlcmd config connection-strings
+```
+Copy the ODBC connection string and remove the driver clause before storing it in your `DB_CONNECTION_STRING` environment variable.
+
+### macOS
+```bash
+# Install Docker Desktop and sqlcmd
+brew install --cask docker
+brew install sqlcmd
+```
+Start Docker Desktop, then:
+```bash
+sqlcmd create mssql --name mssql-python --accept-eula tag 2025-latest --using https://github.com/Microsoft/sql-server-samples/releases/download/wide-world-importers-v1.0/WideWorldImporters-Full.bak
+sqlcmd config connection-strings
+```
+Copy the ODBC connection string and remove the driver clause before storing it in your `DB_CONNECTION_STRING` environment variable.
+
+### Linux
+```bash
+# Install Docker and sqlcmd (Ubuntu/Debian)
+sudo apt-get update
+sudo apt-get install docker.io
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# Install sqlcmd
+curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
+echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/repos/microsoft-ubuntu-$(lsb_release -rs)-prod $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mssql-release.list
+sudo apt-get update
+sudo apt-get install sqlcmd
+```
+Then create the SQL Server container:
+```bash
+sudo sqlcmd create mssql --name mssql-python --accept-eula tag 2025-latest --using https://github.com/Microsoft/sql-server-samples/releases/download/wide-world-importers-v1.0/WideWorldImporters-Full.bak
+sqlcmd config connection-strings
+```
+Copy the ODBC connection string and remove the driver clause before storing it in your `DB_CONNECTION_STRING` environment variable.
+
+---
+
+## Troubleshooting
+
+- Ensure all prerequisites are installed and on your PATH.
+- If a build fails, clean up old artifacts and try again (`mssql_python/pybind/build.bat clean` or `./build.sh clean`).
+- For wheel issues, ensure the native binding (`.pyd` or `.so`) is present in the expected location before building the wheel.
+- For test failures, double-check your `DB_CONNECTION_STRING`.
+
+---
+
+For more details on the native bindings, see [`mssql_python/pybind/README.md`](mssql_python/pybind/README.md).
+
+---
+
+Happy coding!