Skip to content

How to add support for a new distro type

Jump to bottom
RedBearAK edited this page Jan 31, 2025 · 6 revisions

Adding Support for New Package Managers and Distros

Overview

The Toshy installer script is designed to work across many Linux distributions, each with its own package manager and package naming conventions. If you want to add support for a new distribution, this guide will walk you through the process. Don't worry - while it might look complex at first, the modular design makes it quite straightforward once you understand the components.

Key Components

1. Distribution Group Mapping

  • Located in distro_groups_map
  • Maps distribution types to one or more specific distro IDs
  • Example: 
    'fedora-based': ["fedora", "fedoralinux", "nobara", "ultramarine"]

2. Package Group Mapping

  • Located in pkg_groups_map
  • Maps distribution types to required native packages
  • Each distribution type has its own list of package names

3. Package Manager Groups Class

  • PackageManagerGroups class
  • Maintains lists of distributions for each package manager
  • Creates dispatch map linking distro lists to installer methods
  • Example attributes: 
    self.apt_distros    # Debian/Ubuntu distros
self.dnf_distros    # Fedora/RHEL/OpenMandriva distros

4. Package Install Dispatcher

  • PackageInstallDispatcher class
  • Contains static methods for each package manager type
  • Each method implements the specific installation logic

Adding Support for a New Distribution Type

Let's walk through adding support for a new distribution, using a hypothetical example. Say we're adding support for a new distribution called "NewLinux" that uses a package manager called "newpkg".

Step 1: Add Distribution Group

First, we need to tell Toshy about our new distribution. In distro_groups_map, we'll add an entry that lists all the variants of our distribution:

'newlinux-based': ["newlinux", "newlinux-community", "newlinux-enterprise"]

The IDs here should match what's in the distribution's /etc/os-release file - we're not using the "pretty" names, but rather the short identifiers.

Step 2: Define Package List

Now comes the trickier part - defining what packages our new distribution needs. In pkg_groups_map, we'll add our list, following the pattern of similar distributions:

'newlinux-based': [
    "gcc",                    # For building Python modules
    "python3-devel",          # Python development files
    "libxkbcommon-devel",     # For keyboard layout handling
    "cairo-devel",            # For GUI elements
    # ... and so on
]

This step often requires some trial and error in a test environment. Look at the package lists for similar distributions as a starting point - for instance, if your new distribution is RPM-based, the Fedora package list might be a good reference.

Step 3: Update PackageManagerGroups

In the PackageManagerGroups class, we need to add our new package manager type:

# In __init__:
self.newpkg_distros = []  # 'newpkg': NewLinux package manager

# In populate_lists():
# 'newpkg': NewLinux types
self.newpkg_distros += distro_groups_map['newlinux-based']

Some package managers are used across different distro types that use different package lists. Add the distro types

Step 4: Add Install Method

Now we create the method that knows how to install packages on our new distribution. In PackageInstallDispatcher:

@staticmethod
def install_on_newpkg_distro():
    """Handler for NewLinux distributions using newpkg"""
    cmd_lst = ['sudo', 'newpkg', 'install', '--yes', '--quiet']
    native_pkg_installer.install_pkg_list(cmd_lst, cnfg.pkgs_for_distro)

The key here is finding the right command-line options to make the package manager install packages non-interactively. Always include the appropriate non-interactive flags for the new package manager, to avoid interrupting the overall Toshy setup process by asking for input.

Step 5: Update Dispatch Map

Finally, connect everything together in PackageManagerGroups.create_dispatch_map():

self.dispatch_map = {
    # ... existing entries ...
    tuple(self.newpkg_distros): PackageInstallDispatcher.install_on_newpkg_distro,
}

Special Cases

Sometimes distributions need special handling. Here's how to handle common scenarios:

Package Modifications

Need to add or remove specific packages for certain distribution versions? Use these maps:

# Add extra packages
extra_pkgs_map = {
    ('newlinux', '2.0'): ["extra-package-1", "extra-package-2"]
}

# Remove problematic packages
remove_pkgs_map = {
    ('newlinux', None): ["incompatible-package"]
}

Distro Quirks

If your distribution needs special setup (like enabling extra repositories), add a method to DistroQuirksHandler:

@staticmethod
def handle_quirks_NewLinux():
    print('Preparing NewLinux environment...')
    # Add your special handling here

Testing

The best way to test your additions is in a clean virtual machine:

  1. Start with a fresh install of your distribution
  2. Take a snapshot (so you can easily retry)
  3. Run the Toshy installer
  4. Watch for any package installation errors
  5. Verify Toshy works after installation
  6. Document any special requirements

Common Issues and Solutions

  • Package Names: Different distributions often use different names for the same package. For example, python3-devel on RPM-based systems might be python3-dev on Debian-based systems.
  • Build Dependencies: Some distributions might need additional packages for building Python modules.
  • Package Manager Options: Each package manager has its own way of handling non-interactive installation. Check the distribution's documentation for the right options.

Tips for Success

  1. Start with a distribution similar to yours as a template
  2. Keep a log of what packages you needed to add or remove during testing
  3. Test thoroughly in a clean environment
  4. Document any special steps in the code comments
  5. Submit a pull request with your changes!
Clone this wiki locally