# Build Types

Polytropos supports three build types for different use cases. For more details on
Python packaging formats, see the
[Python Packaging User Guide](https://packaging.python.org/en/latest/).

## Editable Install

Use editable installs for local development. The module code stays in place, and a
`.pth` file points Python to your source directory.

### Installation

```bash
uv add --editable ./addon --config-setting odoo_release=19.0
```

### How It Works

Polytropos generates `__manifest__.py` at install time based on the specified Odoo
release. The manifest is written directly to your source directory.

### Limitations

You cannot test two Odoo releases in parallel with editable installs, since each would
generate a different `__manifest__.py` in the same location. If you need to test
multiple releases simultaneously, either:

-   Clone the module into separate folders and install each in editable mode
-   Use [wheels](#binary-distribution-bdistwheel) instead

### Gitignore

Add `__manifest__.py` and `PKG-INFO` to your module's `.gitignore` to prevent
accidentally committing generated files:

```gitignore title=".gitignore"
__manifest__.py
PKG-INFO
```

-   `__manifest__.py`: The generated manifest, regenerated at build time for the target
    release
-   `PKG-INFO`: Metadata file required for editable installs (created by whool)

This ensures the manifest regenerates at build time for the target release, not whatever
was used during development.

## Source Distribution (sdist)

Use sdist for distribution via PyPI or when you need a portable source package. See
[Creating source distributions](https://packaging.python.org/en/latest/tutorials/creating-and-discovering-packages/#creating-source-distributions).

### Build

```bash
uv build --sdist
```

This produces a `.tar.gz` file in the `dist/` directory.

!!! info

    You always need to pass `--sdist` explicitly!

### Version

The sdist version is just the module version (e.g., `1.2.3`), not
`release.module_version` (e.g., `18.0.1.2.3`). This is intentional: an sdist serves as a
[build artifact](https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist)
that can be used to build a wheel for any release.

### How It Works

Polytropos produces a tarball containing the module source code, without any
`__manifest__.py` file.

## Binary Distribution (bdist/wheel)

Use wheel (bdist) for installing the module as a proper Python package. See
[Building Python wheels](https://packaging.python.org/en/latest/tutorials/packaging-python-packages/#creating-wheel-packages).

### Build

```bash
uv build --wheel --config-setting odoo_release=17.0
```

This produces a `.whl` file in the `dist/` directory.

!!! info

    You always need to pass `--wheel` explicitly!

### Version

The wheel version is the combination of the Odoo release + module version (e.g.,
`19.0.1.2.3`). The wheel is only compatible with that release.

### How It Works

The wheel contains:

-   The module code
-   The generated `__manifest__.py` for the specified release
-   Metadata from `pyproject.toml`

## Src Layout

By default, Polytropos expects module files at the project root. Use the `src` option to
place them in a subdirectory:

```toml title="pyproject.toml"
[tool.polytropos]
default_odoo_release = "18.0"
src = "src"

[[tool.polytropos.manifest]]
data = [
    "security/ir.model.access.csv",
]
```

```
project/
  pyproject.toml
  src/
    __init__.py
    models/
      __init__.py
      my_model.py
    security/
      ir.model.access.csv
```

The `src` option applies to wheel and editable builds. The sdist always includes the
full project tree.
