pyPhotoAlbum/INSTALLATION.md

pyPhotoAlbum Installation Guide

This guide provides multiple installation methods for pyPhotoAlbum on Linux systems, with specific instructions for Fedora and Arch/CachyOS.

Table of Contents

• Quick Install (Recommended)
• Manual Installation
• Distribution-Specific Packages
  • Fedora (RPM)
  • Arch/CachyOS (PKGBUILD)
• Development Installation
• Troubleshooting

---

Quick Install (Recommended)

The easiest way to install pyPhotoAlbum is using the provided installation script:

# Clone the repository
git clone https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum.git
cd pyPhotoAlbum

# Run the installation script
./install.sh

The script will:

1. Detect your distribution (Fedora, Arch, Ubuntu, etc.)
2. Offer to install system dependencies
3. Install pyPhotoAlbum
4. Set up desktop integration (icon and menu entry)

Installation Modes

User installation (default):

./install.sh

• Installs to ~/.local/
• No root privileges required
• Only affects current user

System-wide installation:

sudo ./install.sh --system

• Installs to /usr/
• Requires root privileges
• Available to all users

---

Manual Installation

Step 1: Install Dependencies

Fedora:

sudo dnf install python3 python3-pip python3-qt6 python3-pyopengl \
    python3-numpy python3-pillow python3-reportlab python3-lxml

Arch/CachyOS:

sudo pacman -S python python-pip python-pyqt6 python-pyopengl \
    python-numpy python-pillow python-reportlab python-lxml

Ubuntu/Debian:

sudo apt install python3 python3-pip python3-pyqt6 python3-opengl \
    python3-numpy python3-pil python3-reportlab python3-lxml

Other distributions:

If your distribution isn't listed, install these Python packages via pip:

pip install --user PyQt6 PyOpenGL numpy Pillow reportlab lxml

Step 2: Install pyPhotoAlbum

For current user only:

cd pyPhotoAlbum
pip install --user .

System-wide:

cd pyPhotoAlbum
sudo pip install .

Step 3: Desktop Integration (Optional)

User installation:

# Create directories
mkdir -p ~/.local/share/applications
mkdir -p ~/.local/share/icons/hicolor/256x256/apps

# Install files
cp pyphotoalbum.desktop ~/.local/share/applications/
cp pyPhotoAlbum/icons/icon.png ~/.local/share/icons/hicolor/256x256/apps/pyphotoalbum.png

# Update caches
update-desktop-database ~/.local/share/applications
gtk-update-icon-cache ~/.local/share/icons/hicolor/

System-wide:

sudo install -Dm644 pyphotoalbum.desktop /usr/share/applications/pyphotoalbum.desktop
sudo install -Dm644 pyPhotoAlbum/icons/icon.png /usr/share/icons/hicolor/256x256/apps/pyphotoalbum.png
sudo update-desktop-database /usr/share/applications
sudo gtk-update-icon-cache /usr/share/icons/hicolor/

---

Distribution-Specific Packages

Fedora (RPM)

Build and install an RPM package for Fedora:

Prerequisites

sudo dnf install rpm-build rpmdevtools

Build Source Tarball

# From the project root
cd ..
tar czf pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
mv pyphotoalbum-0.1.0.tar.gz ~/rpmbuild/SOURCES/

Build RPM

cd pyPhotoAlbum
rpmbuild -ba pyphotoalbum.spec

The RPM will be created in ~/rpmbuild/RPMS/noarch/

Install RPM

sudo dnf install ~/rpmbuild/RPMS/noarch/pyphotoalbum-0.1.0-1.*.noarch.rpm

Create Local Repository (Optional)

To create a local yum repository:

# Create repository directory
sudo mkdir -p /var/local-repo

# Copy RPM
sudo cp ~/rpmbuild/RPMS/noarch/pyphotoalbum-*.rpm /var/local-repo/

# Create repository metadata
sudo createrepo /var/local-repo

# Add repository configuration
sudo tee /etc/yum.repos.d/local.repo << EOF
[local]
name=Local Repository
baseurl=file:///var/local-repo
enabled=1
gpgcheck=0
EOF

# Install from local repository
sudo dnf install pyphotoalbum

---

Arch/CachyOS (PKGBUILD)

Build and install using the provided PKGBUILD:

Build Source Tarball

# From the project root
cd ..
tar czf pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
mv pyphotoalbum-0.1.0.tar.gz pyPhotoAlbum/
cd pyPhotoAlbum

Build Package

makepkg -si

This will:

• Build the package
• Install it automatically (-i flag)
• Sync dependencies (-s flag)

Build Without Installing

makepkg

The package will be created as pyphotoalbum-0.1.0-1-any.pkg.tar.zst

Install Package

sudo pacman -U pyphotoalbum-0.1.0-1-any.pkg.tar.zst

Create Local Repository (Optional)

To create a local pacman repository:

# Create repository directory
mkdir -p ~/local-repo

# Copy package
cp pyphotoalbum-*.pkg.tar.zst ~/local-repo/

# Create repository database
cd ~/local-repo
repo-add local.db.tar.gz pyphotoalbum-*.pkg.tar.zst

# Add repository to pacman.conf
sudo tee -a /etc/pacman.conf << EOF

[local]
SigLevel = Optional TrustAll
Server = file:///home/$USER/local-repo
EOF

# Update and install
sudo pacman -Sy pyphotoalbum

---

Development Installation

For development work, install in editable mode:

# Clone repository
git clone https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum.git
cd pyPhotoAlbum

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run application
pyphotoalbum
# or
python pyPhotoAlbum/main.py

Development Tools

The development installation includes:

• pytest - Testing framework
• pytest-qt - Qt testing support
• pytest-cov - Coverage reporting
• pytest-mock - Mocking utilities
• flake8 - Linting
• black - Code formatting
• mypy - Type checking

Running Development Tools

# Format code
black pyPhotoAlbum tests

# Run linter
flake8 pyPhotoAlbum tests

# Type checking
mypy pyPhotoAlbum

# Run tests with coverage
pytest --cov=pyPhotoAlbum --cov-report=html

---

Troubleshooting

Command not found: pyphotoalbum

Issue: After user installation, the pyphotoalbum command is not found.

Solution: Add ~/.local/bin to your PATH:

# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Application doesn't appear in menu

Issue: Desktop entry not showing in application menu.

Solution: Update desktop database:

# For user installation
update-desktop-database ~/.local/share/applications

# For system installation
sudo update-desktop-database /usr/share/applications

You may need to log out and back in or restart your desktop environment.

Icon not displaying

Issue: Application icon not showing in menu or taskbar.

Solution: Update icon cache:

# For user installation
gtk-update-icon-cache ~/.local/share/icons/hicolor/

# For system installation
sudo gtk-update-icon-cache /usr/share/icons/hicolor/

PyQt6 import errors

Issue: ImportError: cannot import name 'xxx' from 'PyQt6'

Solution: Ensure PyQt6 is properly installed:

# Uninstall and reinstall
pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6

OpenGL errors

Issue: OpenGL-related errors when starting the application.

Solution: Install OpenGL libraries:

Fedora:

sudo dnf install mesa-libGL mesa-libGL-devel

Arch/CachyOS:

sudo pacman -S mesa libglvnd

Permission denied errors

Issue: Permission errors during system-wide installation.

Solution: Use sudo or switch to user installation:

# User installation (no sudo needed)
pip install --user .
./install.sh  # Without --system flag

Building RPM fails

Issue: Missing build dependencies for RPM.

Solution: Install all build requirements:

sudo dnf install rpm-build rpmdevtools python3-devel python3-setuptools \
    python3-pip desktop-file-utils

Building on Arch fails

Issue: Missing dependencies when running makepkg.

Solution: Install build dependencies:

sudo pacman -S base-devel python-build python-installer python-wheel

---

Verifying Installation

After installation, verify it works:

# Check if command is available
which pyphotoalbum

# Check Python package
python -c "import pyPhotoAlbum; print(pyPhotoAlbum.__file__)"

# Run application
pyphotoalbum --version  # If version flag is implemented
pyphotoalbum

---

Uninstallation

User Installation

pip uninstall pyphotoalbum
rm ~/.local/share/applications/pyphotoalbum.desktop
rm ~/.local/share/icons/hicolor/256x256/apps/pyphotoalbum.png
update-desktop-database ~/.local/share/applications

System Installation

sudo pip uninstall pyphotoalbum
sudo rm /usr/share/applications/pyphotoalbum.desktop
sudo rm /usr/share/icons/hicolor/256x256/apps/pyphotoalbum.png
sudo update-desktop-database /usr/share/applications

RPM (Fedora)

sudo dnf remove pyphotoalbum

Pacman (Arch/CachyOS)

sudo pacman -R pyphotoalbum

---

Getting Help

If you encounter issues not covered here:

1. Check the README.md for general information
2. Search existing issues: https://gitea.tourolle.paris/dtourolle/pyPhotoAlbum/issues
3. Create a new issue with:
   • Your distribution and version
   • Installation method used
   • Complete error messages
   • Output of python --version and pip list | grep -i pyqt

---

Next Steps

After installation, see:

• README.md - General usage and features
• EMBEDDED_TEMPLATES.md - Template system
• Examples in the examples/ directory

Enjoy using pyPhotoAlbum!