Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
112 lines (84 loc) · 2.56 KB

DEVELOPMENT.md

File metadata and controls

112 lines (84 loc) · 2.56 KB

Development Guide

Quick Rebuild During Development

When actively developing Atomistica, use these scripts to quickly rebuild and reinstall:

Using standard pip/venv:

./rebuild.sh

Using uv:

./rebuild-uv.sh

Both scripts will:

  1. Build a new wheel with python -m build --no-isolation -w
  2. Force-reinstall it with pip install --force-reinstall
  3. Show a test command to verify the installation

Why Not Use Editable Installs?

Meson's editable install mode (pip install -e .) can have caching issues, especially with the factory code generation and Fortran module dependencies. The wheel rebuild workflow is more reliable for development.

Important Note for uv Users

Do not use uv run python after running rebuild-uv.sh!

uv run automatically syncs the project and will reinstall atomistica as an editable install (from source), which will fail due to stale build caches. Instead, always use .venv/bin/python directly:

# Wrong - will break
uv run python -c "import atomistica"

# Correct - uses the wheel install
.venv/bin/python -c "import atomistica"

If you accidentally run uv run, clean up and rebuild:

uv pip uninstall atomistica
rm -rf .venv/lib/python3.12/site-packages/__pycache__/_atomistica*
./rebuild-uv.sh

Full Development Setup

# Clone the repository
git clone https://github.com/Atomistica/atomistica.git
cd atomistica

# Create a virtual environment (using venv or uv)
python -m venv .venv
source .venv/bin/activate
# OR
uv venv
source .venv/bin/activate

# Install build dependencies
pip install meson-python meson ninja numpy ase build
# OR
uv pip install meson-python meson ninja numpy ase build

# Build and install
./rebuild.sh
# OR
./rebuild-uv.sh

# Run tests
cd tests
python run_tests.py

Making Changes

  1. Edit source files (Fortran, C, C++, or Python)
  2. Run ./rebuild.sh or ./rebuild-uv.sh
  3. Test your changes
  4. Repeat

Common Development Tasks

Running a single test:

cd tests
python bulk_properties.py

Verbose build output:

python -m build --no-isolation -w -v

Clean build artifacts:

rm -rf .mesonpy-* build dist *.egg-info

Using Meson directly:

meson setup builddir
meson compile -C builddir

Build System Files

  • pyproject.toml - Python package metadata and build backend configuration
  • meson.build - Meson build configuration (Fortran/C/C++ compilation)
  • build_helpers/generate_factories.py - Factory code generation script
  • src/gen_versioninfo.sh - Version info generation script