> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# build

> Build ML models into Docker container images.

# cirron build

Build ML models and Docker containers for your projects with intelligent project detection, validation, and registry configuration. Supports both ML model compilation and traditional application builds.

## Usage

```bash theme={null}
cirron build [options]
```

## Options

| Option              | Description                                    | Default        |
| ------------------- | ---------------------------------------------- | -------------- |
| `--env, -e`         | Environment (development, staging, production) | `development`  |
| `--arch, -a`        | Target architecture (`cpu`, `cuda`, `gpu`)     | Auto-detected  |
| `--index`           | Path to index/manifest file                    | `null`         |
| `--validate`        | Run validation checks before build             | `false`        |
| `--strict`          | Enable strict error handling                   | `false`        |
| `--clean`           | Clean output directory before build            | `false`        |
| `--watch, -w`       | Run build in watch mode                        | `false`        |
| `--analyze`         | Analyze build output after completion          | `false`        |
| `--push`            | Push Docker image to registry after build      | `false`        |
| `--tag, -t`         | Tag for the Docker image                       | Auto-generated |
| `-f, --force`       | Force build despite warnings                   | `false`        |
| `-i, --interactive` | Step-by-step build confirmations               | `false`        |

## Build Types

### ML model builds

For projects with ML frameworks (PyTorch, TensorFlow, Scikit-learn). The command detects the target architecture, validates files and dependencies, compiles the model for the target architecture, generates artifacts and metadata, then builds a Docker image (if a `Dockerfile` exists) and pushes it when `--push` is set.

```bash theme={null}
cirron build                              # basic ML model build
cirron build --arch cuda --validate       # PyTorch CUDA build with validation
cirron build --arch gpu --index config/index.json   # TensorFlow GPU build
cirron build --arch cpu                   # Scikit-learn
cirron build --push --tag v1.0.0          # build and push
```

| Architecture | Use case       | Notes                       |
| ------------ | -------------- | --------------------------- |
| `cpu`        | All frameworks | Lightweight, CPU inference  |
| `cuda`       | PyTorch        | Validates CUDA availability |
| `gpu`        | TensorFlow     | Validates GPU availability  |

### Traditional application builds

For non-ML projects with build configuration. Reads settings from `cirron.yaml`, sets environment variables, runs `beforeBuild` commands, the main build command, then `afterBuild` commands. Use `--analyze` to inspect output.

```bash theme={null}
cirron build --env development
cirron build --env production --clean --analyze
cirron build --watch                      # rebuild on change
```

## Configuration

ML project:

```json theme={null}
{
  "name": "my-ml-model",
  "version": "1.0.0",
  "framework": "pytorch",
  "pythonVersion": "3.9",
  "gpuRequired": true
}
```

Traditional project:

```json theme={null}
{
  "name": "my-app",
  "version": "1.0.0",
  "build": {
    "command": "npm run build",
    "outputDir": "dist",
    "beforeBuild": ["npm install", "npm run lint"],
    "afterBuild": ["npm run test"]
  },
  "environments": {
    "development": { "variables": { "NODE_ENV": "development" } },
    "production":  { "variables": { "NODE_ENV": "production"  } }
  }
}
```

## Validation

With `--validate`:

* **ML projects**: required files (`src/model.py`, `requirements.txt`), Python version compatibility, CUDA/GPU availability for GPU architectures, model instantiation, index file format.
* **Traditional projects**: build configuration in `cirron.yaml`, command availability, dependencies, output directory writable.

## Docker and Registry

Images are named `registry/organization/project:tag`. Configure with `CIRRON_REGISTRY` and `CIRRON_ORG`:

```bash theme={null}
CIRRON_REGISTRY=localhost:5000
CIRRON_ORG=myorg

cirron build --env development          # localhost:5000/myorg/my-project:latest
cirron build --env production --tag v1.0.0   # localhost:5000/myorg/my-project:production-1.0.0
```

`.cirronignore` patterns are automatically merged into `.dockerignore` during build.

## Environment Variables

| Variable     | Description        | Example      |
| ------------ | ------------------ | ------------ |
| `NODE_ENV`   | Node environment   | `production` |
| `CIRRON_ENV` | Cirron environment | `production` |

Per-environment overrides live in `cirron.yaml`:

```json theme={null}
{
  "environments": {
    "production": {
      "variables": { "API_URL": "https://api.production.com", "DEBUG": "false" }
    }
  }
}
```

## Build Output

```
Build Results:
  • Architecture: cuda
  • Artifacts: 3 files generated
    - models/model_cuda.pth
    - artifacts/build_info.json
    - build/model_metadata.json

ML model build completed successfully!
```

```
Build completed successfully!

Output directory: dist
Build size: 2.1 MB
Files: 15
Environment: development

Run cirron deploy to deploy this build
```

With `--analyze`:

```
Build Analysis
Total size: 2.1 MB
File count: 15

Largest files:
  main.js: 1.2 MB
  vendor.js: 800 KB
  styles.css: 100 KB

Recommendations:
  • Consider code splitting to reduce bundle size
  • Enable source maps for better debugging
```

## Watch Mode

```bash theme={null}
cirron build --watch     # Ctrl+C to stop
```

## Troubleshooting

| Error                                   | Resolution                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| `No cirron.yaml found`                  | `cirron init my-project`                                                        |
| `Build command failed with exit code 1` | `cat cirron.yaml` to verify command; try `cirron build --clean`; reinstall deps |
| `CUDA not available for PyTorch`        | Use `--arch cpu`, install CUDA, or verify with `nvidia-smi`                     |
| Docker build issues                     | `docker --version`, check disk space (`df -h`)                                  |
| Registry push failures                  | `docker login`, verify image exists with `docker images`                        |
| Large/slow builds                       | Use `.dockerignore`, verify memory/disk capacity                                |
| Debugging                               | `CIRRON_VERBOSE=1`, run with `--validate` first                                 |

## Best Practices and CI/CD

* Run `--validate` for production builds.
* Choose architecture to match the target deployment hardware.
* Use index files for complex model configurations.
* Use `--clean` and meaningful `--tag` values for production.
* Use `.cirronignore` to keep build context lean.

```yaml theme={null}
# GitHub Actions
- name: Build ML Model
  run: |
    cirron build --arch cuda --validate --push
    cirron build --env production --clean --analyze
```

```bash theme={null}
# Local dev cycle
cirron build --watch
cirron build --env staging --validate
cirron build --env production --clean --push
```