# Build Process for OpenMed: Complete Packaging and Distribution Guide

> Master the OpenMed build process with our comprehensive guide. Learn to create source distributions and wheels using Hatchling and Makefiles, plus optional PyPI publishing for seamless distribution.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: how-to-guide
- Published: 2026-06-13

---

**The OpenMed build process uses Hatchling as the build backend and a Makefile to automate the creation of source distributions and wheels via `python3 -m build`, with optional publishing to PyPI through `hatch publish`.**

OpenMed is a Python package managed in the `maziyarpanahi/openmed` repository that adheres to modern Python packaging standards. The **build process for OpenMed** relies on Hatchling as the build backend, orchestrated through a convenient Makefile that handles everything from environment setup to PyPI publication.

## Prerequisites and Environment Setup

Before building OpenMed, ensure you have **Python 3.10 or higher** installed. The project recommends using the `uv` package manager for fast, reproducible environment management.

1. Install `uv` if you haven't already:

   ```bash
   pip install uv
   ```

2. Create a clean virtual environment:

   ```bash
   uv venv
   source .venv/bin/activate
   ```

3. Install build-time dependencies:

   ```bash
   uv pip install hatchling build
   ```

## Build System Configuration

The build configuration resides in [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml) at the repository root. According to the OpenMed source code, the file declares `hatchling` as the build backend:

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

```

Version tracking is handled dynamically. Hatch reads the version from [`openmed/__about__.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/__about__.py) as specified in the [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml):

```toml
[tool.hatch.version]
path = "openmed/__about__.py"

```

## Building the Package

The `Makefile` provides the primary interface for building. To create both a source distribution (`.tar.gz`) and a wheel (`.whl`), run:

```bash
make build

```

This command invokes `python3 -m build`, which generates the distribution artifacts in the `dist/` directory. You can verify the output:

```bash
ls dist/

# ├── openmed-0.1.0-py3-none-any.whl

# └── openmed-0.1.0.tar.gz

```

Alternatively, you can run the build command directly without Make:

```bash
python3 -m build

```

## Makefile Targets and Build Automation

The `Makefile` in the repository root defines several targets that streamline the **build process for OpenMed**:

- **`make build`** – Executes `python3 -m build` to generate distribution files
- **`make clean`** – Removes `dist/`, `build/`, and `*.egg-info/` directories
- **`make publish`** – Calls `hatch publish` to upload artifacts to PyPI
- **`make release`** – Chains `clean`, `build`, and `publish` for a full release cycle

The relevant Makefile definitions are:

```makefile
build: ## Build the package

	@echo "🔨 Building package..."
	python3 -m build

publish: ## Publish to PyPI using Hatch

	@echo "📤 Publishing to PyPI..."
	hatch publish

release: clean build publish ## Full release cycle: clean, build, publish

clean: ## Clean build artifacts

	@echo "🧹 Cleaning build artifacts..."
	rm -rf dist/ build/ *.egg-info/

```

## Publishing to PyPI

To publish a release, ensure you have built the package first and have PyPI credentials configured in `~/.pypirc`. The `make publish` target wraps the Hatch publishing command:

```bash
make publish

```

For a complete release workflow that includes cleaning old artifacts, building fresh ones, and publishing, use:

```bash
make release

```

This executes the full pipeline: `clean` → `build` → `publish`.

## Documentation Build

OpenMed uses MkDocs for documentation. The Makefile includes helpers for building and serving documentation locally:

- **`make docs-serve`** – Runs `uv run mkdocs serve -a 127.0.0.1:8008` for live preview
- **`make docs-build`** – Runs `uv run mkdocs build --strict` to generate static files

These commands rely on the `docs` extra defined in [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml), which includes `mkdocs` and `mkdocs-material`.

## Key Files in the Build Process

Understanding these files helps when modifying the **build process for OpenMed**:

- **[`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml)** – Declares the `hatchling.build` backend, dependencies, and version path
- **[`openmed/__about__.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/__about__.py)** – Stores the current version string read by Hatch during builds
- **`Makefile`** – Provides the `build`, `publish`, `release`, and `clean` automation targets
- **[`scripts/release/release.py`](https://github.com/maziyarpanahi/openmed/blob/main/scripts/release/release.py)** – Helper script for version bumping invoked by Makefile targets

## Summary

- **Build backend**: OpenMed uses `hatchling` as specified in [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml) with the `hatchling.build` backend
- **Build command**: Run `make build` or `python3 -m build` to generate wheels and source distributions in `dist/`
- **Version location**: The version is defined in [`openmed/__about__.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/__about__.py) and read dynamically by Hatch
- **Publishing**: Use `make publish` (which calls `hatch publish`) or `make release` for the full cycle
- **Documentation**: Build docs with `make docs-build` or preview with `make docs-serve`

## Frequently Asked Questions

### What build backend does OpenMed use?

OpenMed uses **Hatchling** as its build backend. The configuration in [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml) specifies `build-backend = "hatchling.build"` and uses Hatch's versioning system to read from [`openmed/__about__.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/__about__.py).

### How do I build OpenMed from source without Make?

If you prefer not to use the Makefile, activate your virtual environment and run `python3 -m build` directly. This requires the `build` package to be installed (`pip install build`). The command creates both the wheel and source distribution in the `dist/` directory.

### Where does OpenMed store its version number?

The package version is stored in [`openmed/__about__.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/__about__.py). Hatch reads this file dynamically during the build process according to the `[tool.hatch.version]` configuration in [`pyproject.toml`](https://github.com/maziyarpanahi/openmed/blob/main/pyproject.toml), eliminating the need to hardcode versions in multiple locations.

### How do I publish a new release to PyPI?

Run `make release` from the repository root. This executes the full pipeline: cleaning old artifacts, building fresh distributions with `python3 -m build`, and publishing to PyPI via `hatch publish`. Ensure you have PyPI credentials configured in `~/.pypirc` or set as environment variables.