FEAT: Linux Support - Build and C++ (#113)

### ADO Work Item Reference  
<!-- Insert your ADO Work Item ID below (e.g. AB#37452) -->
>
[AB#34987](https://sqlclientdrivers.visualstudio.com/c6d89619-62de-46a0-8b46-70b92a84d85e/_workitems/edit/34987)
-------------------------------------------------------------------
### Summary   
<!-- Insert your Copilot Generated Summary below -->  
This pull request introduces cross-platform compatibility improvements
for macOS and Linux in the MSSQL Python bindings, updates build scripts
to support multiple operating systems, and refines driver handling
logic. The most significant changes include adding Linux-specific
handling alongside macOS, enhancing build scripts for OS detection, and
integrating Python for dynamic driver path resolution.

### Cross-Platform Compatibility Enhancements:
*
[`mssql_python/pybind/ddbc_bindings.cpp`](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L261-R262):
Updated numerous code sections to include Linux-specific handling,
ensuring proper encoding and buffer management for SQLWCHAR data. This
includes changes in functions like `BindParameters`,
`SQLExecDirect_wrap`, and `FetchBatchData`.
[[1]](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L261-R262)
[[2]](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L828-R831)
[[3]](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L1609-R1613)
*
[`mssql_python/pybind/ddbc_bindings.h`](diffhunk://#diff-85167a2d59779df18704284ab7ce46220c3619408fbf22c631ffdf29f794d635L35-R35):
Replaced macOS-specific headers with Unix-specific headers to
accommodate both macOS and Linux environments.
[[1]](diffhunk://#diff-85167a2d59779df18704284ab7ce46220c3619408fbf22c631ffdf29f794d635L35-R35)
[[2]](diffhunk://#diff-85167a2d59779df18704284ab7ce46220c3619408fbf22c631ffdf29f794d635L65-R67)

### Build Script Updates:
*
[`mssql_python/pybind/build.sh`](diffhunk://#diff-7cfcd9b5499a176c28ca4d028e9b2b060238ec79c4bea5b062d4b39929f9fb04L2-R22):
Enhanced the script to detect the operating system dynamically and
configure builds accordingly for macOS and Linux. Added OS-specific
diagnostic messages and build configurations.
[[1]](diffhunk://#diff-7cfcd9b5499a176c28ca4d028e9b2b060238ec79c4bea5b062d4b39929f9fb04L2-R22)
[[2]](diffhunk://#diff-7cfcd9b5499a176c28ca4d028e9b2b060238ec79c4bea5b062d4b39929f9fb04L30-R50)
[[3]](diffhunk://#diff-7cfcd9b5499a176c28ca4d028e9b2b060238ec79c4bea5b062d4b39929f9fb04L48-R81)
*
[`mssql_python/pybind/build.bat`](diffhunk://#diff-a08055320153458138a68ccff086b540cb080819b76f921664caa782603a4c2eL166-R166):
Updated VCREDIST path to reflect platform-specific directory structures.

### Driver Handling Improvements:
*
[`mssql_python/pybind/ddbc_bindings.cpp`](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L621-R659):
Integrated Python to dynamically determine the driver path based on the
module directory and system architecture. Added a new function
`GetDriverPathFromPython` for this purpose.
[[1]](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L621-R659)
[[2]](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1L650-R673)
*
[`mssql_python/pybind/ddbc_bindings.cpp`](diffhunk://#diff-dde2297345718ec449a14e7dff91b7bb2342b008ecc071f562233646d71144a1R2069):
Exposed the `get_driver_path` function to Python for external usage.

### Documentation Updates:
*
[`mssql_python/pybind/README.md`](diffhunk://#diff-1429930017ef4a5b84d9331206c1ac47e546427b914986e531e3f04e45f4bb31L62-R62):
Corrected the file name for compilation instructions, replacing
`ddbc_bindings_mac.cpp` with `ddbc_bindings.cpp`.

### Miscellaneous Improvements:
*
[`mssql_python/pybind/CMakeLists.txt`](diffhunk://#diff-dbb5892fbbb28149d1639664797cf3adb48ced28ec11aba95f2e2b338ca46badR15-R16):
Added a TODO comment suggesting a unified module for platform detection
across Python and C++.

<!-- 
### PR Title Guide

> For feature requests
FEAT: (short-description)

> For non-feature requests like test case updates, config updates ,
dependency updates etc
CHORE: (short-description) 

> For Fix requests
FIX: (short-description)

> For doc update requests 
DOC: (short-description)

> For Formatting, indentation, or styling update
STYLE: (short-description)

> For Refactor, without any feature changes
REFACTOR: (short-description)

> For release related changes, without any feature changes
RELEASE: #<RELEASE_VERSION> (short-description) 
-->

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: bewithgaurav

mssql_python/ddbc_bindings.py

@@ -3,27 +3,77 @@
 import sys
 import platform
 
+def normalize_architecture(platform_name, architecture):
+    """
+    Normalize architecture names for the given platform.
+    
+    Args:
+        platform_name (str): Platform name ('windows', 'darwin', 'linux')
+        architecture (str): Architecture string to normalize
+        
+    Returns:
+        str: Normalized architecture name
+        
+    Raises:
+        ImportError: If architecture is not supported for the given platform
+        OSError: If platform is not supported
+    """
+    arch_lower = architecture.lower()
+    
+    if platform_name == "windows":
+        arch_map = {
+            "win64": "x64", "amd64": "x64", "x64": "x64",
+            "win32": "x86", "x86": "x86",
+            "arm64": "arm64"
+        }
+        if arch_lower in arch_map:
+            return arch_map[arch_lower]
+        else:
+            supported = list(set(arch_map.keys()))
+            raise ImportError(f"Unsupported architecture '{architecture}' for platform '{platform_name}'; expected one of {supported}")
+    
+    elif platform_name == "darwin":
+        # For macOS, return runtime architecture
+        return platform.machine().lower()
+    
+    elif platform_name == "linux":
+        arch_map = {
+            "x64": "x86_64", "amd64": "x86_64",
+            "arm64": "arm64", "aarch64": "arm64"
+        }
+        if arch_lower in arch_map:
+            return arch_map[arch_lower]
+        else:
+            supported = list(set(arch_map.keys()))
+            raise ImportError(f"Unsupported architecture '{architecture}' for platform '{platform_name}'; expected one of {supported}")
+    
+    else:
+        supported_platforms = ["windows", "darwin", "linux"]
+        raise OSError(f"Unsupported platform '{platform_name}'; expected one of {supported_platforms}")
+
 # Get current Python version and architecture
 python_version = f"cp{sys.version_info.major}{sys.version_info.minor}"
 
-platform_name = sys.platform.lower()
-architecture = platform.machine().lower()
+platform_name = platform.system().lower()
+raw_architecture = platform.machine().lower()
 
-# On macOS, prioritize universal2 binary regardless of the local architecture
+# Special handling for macOS universal2 binaries
 if platform_name == 'darwin':
     architecture = "universal2"
-elif platform_name == 'win32':
-    if architecture in ('amd64', 'x86_64', 'x64'):
-        architecture = "amd64" if platform_name == 'win32' else "x86_64"
-    elif architecture in ('arm64', 'aarch64'):
-        architecture = "arm64"
-    else:
-        raise ImportError(f"Unsupported architecture for mssql-python: {platform_name}-{architecture}")
 else:
-    raise ImportError(f"Unsupported architecture for mssql-python: {platform_name}-{architecture}")
+    architecture = normalize_architecture(platform_name, raw_architecture)
+    
+    # Handle Windows-specific naming for binary files
+    if platform_name == 'windows' and architecture == 'x64':
+        architecture = "amd64"
+
+# Validate supported platforms
+if platform_name not in ['windows', 'darwin', 'linux']:
+    supported_platforms = ['windows', 'darwin', 'linux']
+    raise ImportError(f"Unsupported platform '{platform_name}' for mssql-python; expected one of {supported_platforms}")
 
 # Determine extension based on platform
-if platform_name == 'win32':
+if platform_name == 'windows':
     extension = '.pyd'
 else:  # macOS or Linux
     extension = '.so'

mssql_python/helpers.py

@@ -7,6 +7,9 @@
 from mssql_python import ddbc_bindings
 from mssql_python.exceptions import raise_exception
 from mssql_python.logging_config import get_logger, ENABLE_LOGGING
+import platform
+from pathlib import Path
+from mssql_python.ddbc_bindings import normalize_architecture
 
 logger = get_logger()
 
@@ -109,3 +112,75 @@ def add_driver_name_to_app_parameter(connection_string):
 
     # Join the parameters back into a connection string
     return ";".join(modified_parameters) + ";"
+
+
+def detect_linux_distro():
+    """
+    Detect Linux distribution for driver path selection.
+
+    Returns:
+        str: Distribution name ('debian_ubuntu', 'rhel', 'alpine', etc.)
+    """
+    import os
+
+    distro_name = "debian_ubuntu"  # default
+
+    try:
+        if os.path.exists("/etc/os-release"):
+            with open("/etc/os-release", "r") as f:
+                content = f.read()
+            for line in content.split("\n"):
+                if line.startswith("ID="):
+                    distro_id = line.split("=", 1)[1].strip('"\'')
+                    if distro_id in ["ubuntu", "debian"]:
+                        distro_name = "debian_ubuntu"
+                    elif distro_id in ["rhel", "centos", "fedora"]:
+                        distro_name = "rhel"
+                    elif distro_id == "alpine":
+                        distro_name = "alpine"
+                    else:
+                        distro_name = distro_id  # use as-is
+                    break
+    except Exception:
+        pass  # use default
+
+    return distro_name
+
+def get_driver_path(module_dir, architecture):
+    """
+    Get the platform-specific ODBC driver path.
+
+    Args:
+        module_dir (str): Base module directory
+        architecture (str): Target architecture (x64, arm64, x86, etc.)
+
+    Returns:
+        str: Full path to the ODBC driver file
+
+    Raises:
+        RuntimeError: If driver not found or unsupported platform
+    """
+
+    platform_name = platform.system().lower()
+    normalized_arch = normalize_architecture(platform_name, architecture)
+
+    if platform_name == "windows":
+        driver_path = Path(module_dir) / "libs" / "windows" / normalized_arch / "msodbcsql18.dll"
+
+    elif platform_name == "darwin":
+        driver_path = Path(module_dir) / "libs" / "macos" / normalized_arch / "lib" / "libmsodbcsql.18.dylib"
+
+    elif platform_name == "linux":
+        distro_name = detect_linux_distro()
+        driver_path = Path(module_dir) / "libs" / "linux" / distro_name / normalized_arch / "lib" / "libmsodbcsql-18.5.so.1.1"
+
+    else:
+        raise RuntimeError(f"Unsupported platform: {platform_name}")
+
+    driver_path_str = str(driver_path)
+
+    # Check if file exists
+    if not driver_path.exists():
+        raise RuntimeError(f"ODBC driver not found at: {driver_path_str}")
+
+    return driver_path_str