Project:Portage/Sync

Starting with Portage version 2.2.16, Portage now has a modular, plug-in sync system. This new sync system will ease code maintenance as well as make it possible for third party modules to be installed. Many of the users will be learning about the style changes that have been in Portage for several years now for the first time.

Portage has been migrating away from 's PORTDIR and PORTDIR_OVERLAY variable settings for quite some time. Those settings are very limited in their capabilities as compared to the style of repository configuration. The new sync system is the next step in that migration.

Using PORTDIR and PORTDIR_OVERLAY in limited Portage by only defining where the repository was located. Portage had no controls to specify other important attributes about that repository. The configuration style allows for settings to be defined on a per repository, per sync-type basis. Along with this new expandability and the plug-in sync system, it will be much easier to change to new repository syncing methods.

Changes

 * New auto-sync setting for all repository types (needed):
 * New auto-sync setting for all repository types (needed):

where n = {0,1,2,3,...} Sync a subversion repository Perform an emerge-webrsync operation on the repo. By using this sync-type, a user can do a normal or  instead of running the  command. (if installed) runs layman's code to sync the repository (overlay) Runs all hook scripts found once, after all repos have been synced. Compatible with all existing postsync.d scripts. Replaces the portage-utils installed post_sync hook script. Runs each hook script found with three arguments: repo name, sync-uri, location Each script is run at the completion of each repository that was synced. Using these arguments, the hook script can decide if it needs to run or just exit. This is useful for when only a certain repo has been updated and needs to trigger some other process or update system.
 * New for git sync-type:
 * 0 is equivalent to full git history
 * 1 shallow clone, only current state (default if option is absent)
 * 2, 3, ... history depth to download.
 * New sync-type modules:
 * for <=sys-apps/portage-2.2.18
 * for >=sys-apps/portage-2.2.19
 * New native portage postsync hooks

Migration
The primary reason for upgrading from style PORTDIR (deprecated, only there for backward compatibility with old tools, the  setting is used for its value) and PORTDIR_OVERLAY (still functional, but deprecated) listings and the new  style definitions is functionality. The method is a lot more flexible and powerful for controlling the repositories. The PORTDIR_OVERLAY listings are simple listing which are not capable of listing the options to control the new sync features and abilities, let alone other portage capabilities such as priority.

Portage configuration
If the directory does not exist:

Then edit the file to the desired settings, continue as needed with the remaining migration instructions. Edit all files, add the auto-sync option to each defined repository.

For sync-type, set it to one of the installed supported types.

Current supported sync types include:


 * 1)   or   (equivalent to running  separately).
 * 2)   (if installed by Layman)
 * 1)   or   (equivalent to running  separately).
 * 2)   (if installed by Layman)
 * 1)   (if installed by Layman)
 * 1)   (if installed by Layman)

Example local overlay sync-able from a git remote:

The above overlay can be synced with

Manually editing /etc/portage/repos.conf/layman.conf
For an existing file:

1) Change/add the sync-type:

2) Ensure Layman 2.3.0 or higher has been installed with the laymansync module.

layman-updater method
Perform the next series of steps when migrating from the old layman conf_type to  type.

1) Ensure the new plug-in sync Portage version is installed, upgrading portage if necessary:

2) Install the new laymansync enabled layman version. To install layman with the portage plugin, the sync-plugin-portage USE flag must be enabled:

3) Edit change it to the  config type:

Save and exit the file.

4) Generate the new file:

5) Delete layman's file:

6) Edit : remove the  line.

Done

Operation
Primary control of all sync operations has been moved from to. now runs the emaint sync module with the  option. This  option performs a sync on only those repositories with the auto-sync setting set to   or. If the auto-sync option is not set to  or is absent, then  may not sync any repositories.

The module operates similar to. It can sync single or multiple repos. It can also sync repos with  set in the respective  file. This gives users and administrators more flexibility in how and when repositories are synced:

Examples
Equivalent to. Sync all repositories where  is set.

Sync the foo repo (ignores auto-sync setting):

Sync all repositories with a valid sync-type and sync-url defined. (ignores auto-sync setting)

--

Directory structure

 * /usr/lib/portage/
 * sync/
 * modules/
 * rsync/
 * __init__.py
 * rsync.py
 * git/
 * __init__.py
 * git.py
 * __init__.py
 * config_checks.py
 * controller.py
 * getaddrinfo_validate.py
 * old_tre_timestamp.py
 * syncbase.py

Module's __init__.py
Example module definition:

Validating repos.conf variables
Depending on the needs of the sync module, the "validate_config" variable can be assigned in the module's spec the portage.sync.config_checks.CheckSyncConfig class or subclass it, adding any checks for additional variables needed to be defined in the definition for that sync type.

Example module adding an additional validation test

Common classes used by sync modules

 * class SyncBase(object):........ Base Sync class meant to be subclassed. It defines some common functions which can be used or overriden as needed by the target module. It provides stubs for all functions needed by the main sync controller.
 * def name:
 * def can_progressbar(self, func):
 * def __init__(self, bin_command, bin_pkg):
 * def _kwargs(self, kwargs):.... Sets internal variables from kwargs
 * def exists(self, **kwargs):.... Tests whether the repo actually exists
 * def sync(self, **kwargs):...... Stub only: Sync the repository
 * def post_sync(self, portdb, location, emerge_config):.... Stub only: repo.sync_type == "Blank" NOTE: Do this after reloading the config, in case it did not exist prior to sync, so that the config and portdb properly account for its existence.


 * class NewBase(object):........ Base Sync class which subclasses SyncBase and also meant to be subclassed. It adds a predefined sync, and stubs for new and update. It forms the base for a module which requires separate new and update operations.
 * def sync(self, **kwargs):...... Conditionally syncs the repository using either the new or update functions
 * def new(self, **kwargs):....... Stub only: Do the initial download and install of the repository
 * def update(self):............... Stub only: Update existing repository


 * class CheckSyncConfig(object):..... Base repos.conf settings checks class
 * def __init__(self, repo=None, logger=None):.... Class init function
 * self.checks = ['check_uri', 'check_auto_sync']...... List of predefined checks to perform. When subclassing append to it or redfine as needed
 * def repo_checks(self):......................... Perform all checks available
 * def check_uri(self):.............................. Check the sync_uri setting
 * def check_auto_sync(self):................. Check the auto_sync setting