Publishing AUR Package

arch / linux / development

This article details the process of publishing a package to the Arch User Repository (AUR), using xmind2md version 1.0.0 as a practical example. We’ll cover everything from package preparation to publication and maintenance.

Introduction

xmind2md is a command-line tool that converts XMind mind maps to Markdown format. This tool serves as an excellent example for demonstrating the AUR package creation process, especially since it involves Python dependencies and virtual environment management.

Prerequisites

  • An Arch Linux system or compatible distribution
  • Basic understanding of Git
  • A GitHub account
  • An AUR account

Project Structure

The xmind2md project consists of these core files:

xmind2md/
├── PKGBUILD
├── xmind_converter.py
├── LICENSE
└── README.md

The Core Script (xmind_converter.py)

#!/usr/bin/env python3

import xmindparser
import os
import sys
from pathlib import Path

def process_line(line):
    """Process a single line and convert to appropriate format"""
    stripped = line.strip()
    if not stripped:
        return ""

    # Extract the level and content
    level = 0
    while stripped.startswith('#'):
        level += 1
        stripped = stripped[1:]
    content = stripped.strip()

    # Format based on level
    if level == 1:  # h1
        return f"# {content}\n"
    elif level == 2:  # h2
        return f"## {content}\n"
    elif level == 3:  # h3 as bold text
        return f"**{content}**\n"
    elif level == 4:  # h4
        return f"- {content}\n"
    elif level == 5:  # h5
        return f"    - {content}\n"
    elif level == 6:  # h6
        return f"        - {content}\n"
    elif level == 7:  # h7
        return f"            - {content}\n"
    elif level == 8:  # h8
        return f"                - {content}\n"
    else:
        return line

def convert_xmind(input_file, output_file):
    try:
        # Parse XMind
        content = xmindparser.xmind_to_dict(input_file)
        if not content:
            return False

        # Open output file
        with open(output_file, 'w', encoding='utf-8') as f:
            def write_topic(topic, level=1):
                # Write title
                title = topic.get('title', '').strip()
                if title:
                    line = f"{'#' * level} {title}\n"
                    f.write(process_line(line))

                # Write note if exists
                if 'note' in topic and topic['note']:
                    f.write(topic['note'].strip() + '\n\n')

                # Process subtopics
                if 'topics' in topic:
                    for subtopic in topic['topics']:
                        write_topic(subtopic, level + 1)

            # Start processing from root
            write_topic(content[0]['topic'])

        return True

    except Exception as e:
        print(f"Error: {str(e)}")
        return False

def main():
    if len(sys.argv) != 3:
        print("Usage: python script.py <source_directory> <output_directory>")
        return

    source_dir = Path(sys.argv[1])
    output_dir = Path(sys.argv[2])

    if not source_dir.exists():
        print("Source directory does not exist")
        return

    output_dir.mkdir(parents=True, exist_ok=True)

    success = 0
    failed = 0

    for xmind_file in source_dir.glob('*.xmind'):
        output_file = output_dir / (xmind_file.stem + '.md')
        print(f"Converting: {xmind_file.name}")

        if convert_xmind(str(xmind_file), str(output_file)):
            print(f"Success: {xmind_file.name}")
            success += 1
        else:
            print(f"Failed: {xmind_file.name}")
            failed += 1

    print(f"\nDone! Successful: {success}, Failed: {failed}")

if __name__ == "__main__":
    main()

The PKGBUILD File

# Maintainer: Chirag Bharambe <chirag@bharambe.dev>

pkgname=xmind2md
pkgver=1.0.0
pkgrel=1
pkgdesc="A tool to convert XMind files to Markdown format"
arch=('any')
url="https://github.com/chiragbharambe/xmind2md"
license=('MIT')
depends=('python')
makedepends=('python-pip' 'python-virtualenv')

source=("$pkgname-$pkgver.tar.gz::https://github.com/chiragbharambe/$pkgname/archive/v$pkgver.tar.gz")
sha256sums=('SKIP')

package() {
    cd "$srcdir/$pkgname-$pkgver"

    # Create necessary directories
    install -dm755 "$pkgdir/usr/bin"
    install -dm755 "$pkgdir/usr/lib/$pkgname"
    install -dm755 "$pkgdir/usr/share/$pkgname"

    # Install Python script
    install -Dm755 xmind_converter.py "$pkgdir/usr/lib/$pkgname/xmind_converter.py"

    # Create setup script
    cat > "$pkgdir/usr/lib/$pkgname/setup.sh" << 'EOF'
#!/bin/bash

VENV_PATH="$HOME/.local/share/xmind2md/venv"

# Create virtual environment if it doesn't exist
if [ ! -d "$VENV_PATH" ]; then
    mkdir -p "$HOME/.local/share/xmind2md"
    python -m venv "$VENV_PATH"
    source "$VENV_PATH/bin/activate"
    pip install xmindparser
    deactivate
fi

echo "Setup complete! xmind2md is ready to use."
EOF
    chmod 755 "$pkgdir/usr/lib/$pkgname/setup.sh"

    # Create main executable
    cat > "$pkgdir/usr/bin/$pkgname" << 'EOF'
#!/bin/bash

VENV_PATH="$HOME/.local/share/xmind2md/venv"

# Check if venv exists, if not run setup
if [ ! -d "$VENV_PATH" ]; then
    /usr/lib/xmind2md/setup.sh
fi

# Activate venv and run converter
source "$VENV_PATH/bin/activate"
python /usr/lib/xmind2md/xmind_converter.py "$@"
deactivate
EOF
    chmod 755 "$pkgdir/usr/bin/$pkgname"

    # Install license and readme
    install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
    install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"
}

Step-by-Step Publishing Process

1. Setting Up GitHub Repository

# Initialize local repository
mkdir xmind2md
cd xmind2md
git init

# Add project files
touch PKGBUILD
touch xmind_converter.py
touch LICENSE
touch README.md

# Add content to files
# ... (add content to each file)

# Initial commit
git add .
git commit -m "Initial commit"

# Create GitHub repository and push
git remote add origin https://github.com/yourusername/xmind2md.git
git push -u origin main

2. Creating a GitHub Release

  1. Navigate to your repository on GitHub
  2. Click “Releases” on the right sidebar
  3. Click “Create a new release”
  4. Set tag version to “v1.0.0”
  5. Set release title to “xmind2md 1.0.0”
  6. Add release notes
  7. Publish release

3. Setting Up AUR Account

  1. Create an account at aur.archlinux.org
  2. Generate SSH key:
ssh-keygen -f ~/.ssh/aur
cat ~/.ssh/aur.pub
  1. Add the public key to your AUR account settings

4. Publishing to AUR

# Create working directory
mkdir ~/aur-work
cd ~/aur-work

# Clone AUR repository
git clone ssh://aur@aur.archlinux.org/xmind2md.git
cd xmind2md

# Copy PKGBUILD
cp /path/to/your/PKGBUILD .

# Generate .SRCINFO
makepkg --printsrcinfo > .SRCINFO

# Commit and push
git add PKGBUILD .SRCINFO
git commit -m "Initial release: xmind2md 1.0.0"
git push

Package Installation and Testing

After publishing, users can install the package using an AUR helper:

yay -S xmind2md

Note: It may take 15-30 minutes for the package to be indexed and become searchable.

Package Usage

Once installed, users can convert XMind files to Markdown:

xmind2md <source_directory> <output_directory>

Maintenance Responsibilities

1. Version Updates

When updating the package:

cd ~/aur-work/xmind2md
# Edit PKGBUILD with new version
# Update sha256sums if needed
makepkg --printsrcinfo > .SRCINFO
git add PKGBUILD .SRCINFO
git commit -m "Update to version X.X.X"
git push

2. Common Maintenance Tasks

  • Monitor AUR comments for bug reports
  • Keep dependencies updated
  • Respond to user issues
  • Update package when upstream changes

3. Best Practices

  • Always test locally before pushing updates
  • Use semantic versioning
  • Keep documentation updated
  • Maintain clean git history

Troubleshooting

Common Issues and Solutions

  1. SSH Key Problems:
ssh -T aur@aur.archlinux.org
  1. Git Configuration:
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
  1. Package Not Found:
yay -Sy  # Update package database
yay -Ss xmind2md  # Search explicitly

Conclusion

Publishing to AUR requires attention to detail and commitment to maintenance, but it’s a valuable way to contribute to the Arch Linux community. The xmind2md package serves as an example of handling Python dependencies, virtual environments, and proper package structure.

Resources