# VEOX Client Bible

Welcome to the canonical reference for the VEOX Client. 

## Build and Deploy Tutorial

The canonical client build and publish matrix relies on the `build_and_publish_client.sh` bash script which intelligently handles environment isolation, dynamic module loading, PEP-517 compilation, and PyPI publication via Twine.

### Prerequisites

Always execute the client pipeline from within an activated Python virtual environment to avoid polluting global host directories. The build script will intentionally warn you if it detects a raw `system` Python environment scope.

```bash
# Example environment activation
python3 -m venv .venv
source .venv/bin/activate
```

### Usage Options

You can invoke the automated pipeline script from anywhere inside the repository, but most developers run it natively from the repository root:

```bash
bash Public/veox_client/build_and_publish_client.sh [OPTIONS]
```

**Available Flags:**
- `--build`       Builds the Python package (sdist / bdist_wheel) inside the `dist/` directory.
- `--publish`     Publishes the built packages in `dist/` to PyPI.
- `--tag TAG`     Specifies the module version constraint (e.g., `0.1.7`). The script will update your `pyproject.toml` statically to match this semantic tag array prior to generation.
- `-y, --yes`     Skips all interactive prompts (excellent for CI/CD integrations).

### Step-by-step Example

**1. Building a Release**

Execute the build flag and assign the semantic version tag. The script automatically handles any missing backend tooling (like `build` natively) through automated `pip` installations. 

```bash
bash Public/veox_client/build_and_publish_client.sh --build --tag "1.0.0"
```

**2. Publishing to PyPI**

Once the distribution `tar.gz` and `.whl` files are populated inside `Public/veox_client/dist`, you can execute the publish flag alone to securely push that artifact matrix upstream.

> [!NOTE]
> The publish phase requires valid PyPI credentials stored in your `~/.pypirc` file (or exported natively in your environment). The script leverages `twine` to orchestrate the final secure transfer over TLS.

```bash
bash Public/veox_client/build_and_publish_client.sh --publish
```

**3. Combined CI Execution**

For non-interactive integrations or complete immediate deployment loops, simply concatenate the command parameters:

```bash
bash Public/veox_client/build_and_publish_client.sh --build --publish --tag "1.0.1" -y
```
