From 494241071bd94d5e4b87ba113753642e57090af8 Mon Sep 17 00:00:00 2001 From: Oliver Tappe Date: Sat, 23 Feb 2008 18:44:04 +0000 Subject: * adjusted plugin-API according to recent discussion with Volker: + dropped pre- and post-methods as they are not really needed, since ... + we now bind-mount /opt/openslx into /mnt/openslx of the vendor-OS chroot, so plugins can copy any required files from there * cleaned up existing plugin implementations * improved documentation for plugin developers (available via 'perldoc os-plugins/OpenSLX/OSPlugins/Base.pm'). git-svn-id: http://svn.openslx.org/svn/openslx/trunk@1570 95ad53e4-c205-0410-b2fa-d234c58c8868 --- os-plugins/OpenSLX/OSPlugin/Base.pm | 296 +++++++++++++++++++++++++----------- 1 file changed, 210 insertions(+), 86 deletions(-) (limited to 'os-plugins/OpenSLX/OSPlugin/Base.pm') diff --git a/os-plugins/OpenSLX/OSPlugin/Base.pm b/os-plugins/OpenSLX/OSPlugin/Base.pm index c1945c95..2eef4b82 100644 --- a/os-plugins/OpenSLX/OSPlugin/Base.pm +++ b/os-plugins/OpenSLX/OSPlugin/Base.pm @@ -18,48 +18,137 @@ use warnings; our $VERSION = 1.01; # API-version . implementation-version +=head1 NAME + +OpenSLX::OSPlugin::Base - the base class for all OpenSLX OS-plugins. + +=head1 DESCRIPTION + +This class defines the OpenSLX API for OS-plugins. + +The general idea behind OS-plugins is to extend any installed vendor-OS with +a specific features. Each feature is implemented as a separate, small software +component in order to make them easy to understand and maintain. + +Since all of these software components are plugged into the OpenSLX system by +means of a common API, we call them Bs. + +This API can be separated into different parts: + +=over + +=item - L (provide info about a plugin) + +=item - L (installing or removing a plugin into/from a +vendor-OS) + +=item - L (integrating a plugin into an initramfs) + +=item - L (offers each plugin access to OpenSLX services) + +=back + +=head1 MORE INFO + +Please read the user-level introduction on plugins in the OpenSLX-wiki: +L (in German). + +If you'd like to know how a plugin is implemented, please have a look at the +'example' plugin, which contains some explainations and useful hints. + +If you have any questions regarding the concept of OS-plugins and their +implementation, please drop a mail to: ot@openslx.com, or join the IRC-channel +'#openslx' (on freenode). + +=cut + use OpenSLX::Basics; -################################################################################ -# if you have any questions regarding the concept of OS-plugins and their -# implementation, please drop a mail to: ot@openslx.com, or join the IRC-channel -# '#openslx' (on freenode). -################################################################################ +=head1 PLUGIN API + +=head2 Declarative Interface + +=over + +=item new() + +Every plugin should provide a new-method and provide it's own name in the +'name' entry of $self. + +Please note that by convention, plugin names are all lowercase! + +=cut sub new { confess "Creating OpenSLX::OSPlugin::Base-objects directly makes no sense!"; } +=item initialize() + +Initializes basic context for this plugin (esp. a reference to the OSPlugin +engine that drives this plugin. + +=cut + sub initialize { my $self = shift; - # The os-plugin-engine drives us, it provides some useful services relevant - # to installing stuff into the vendor-OS, like downloading functionality, - # access to meta-packager, ... $self->{'os-plugin-engine'} = shift; return; } +=item getInfo() + +Returns a hash-ref with administrative information about this plugin (what does +it do and how does it relate to other plugins). Every plugin needs to provide +this method and return the information about itself. + +=cut + sub getInfo -{ # returns a hash-ref with administrative information about this plugin - # (what does it do and how does it relate to other plugins) +{ my $self = shift; return { # a short (one-liner) description of this plugin description => '', - # a list of plugins that must have completed before this plugin can - # be executed - mustRunAfter => [], }; } +=item getAttrInfo() + +Returns a hash-ref with information about all attributes supported by this +specific plugin. + +This default configuration will be added as attributes to the default system, +such that it can be overruled for any specific system by means of B. + +The returned hash-ref must include at least the following entries: + +=over + +=item B::active> + +Indicates whether or not this plugin is active (1 for active, 0 for inactive). + +=item B::precedence> + +Specifies the execution precedence of this plugin with respect to all other +plugins (plugins with lower precedences will be started before the ones with +a higher precedence). + +Valid values range from 0-99. If your plugin does not have any requirements +in this context, just specify the default value '50'. + +=back + +=cut + sub getAttrInfo -{ # returns a hash-ref with information about all attributes supported - # by this specific plugin +{ my $self = shift; # This default configuration will be added as attributes to the default @@ -71,107 +160,125 @@ sub getAttrInfo }; } -sub preInstallationPhase -{ # called before chrooting into vendor-OS root, should be used if any files - # have to be downloaded outside of the chroot (which might be necessary - # if the required files can't be installed via the meta-packager) - my $self = shift; - my $pluginRepositoryPath = shift; - # the folder where the stage1-plugin should store all files - # required by the corresponding stage3 runlevel script - my $pluginTempPath = shift; - # a temporary playground that will be cleaned up automatically - - return; -} +=back + +=head2 Vendor-OS Interface + +=over + +=item installationPhase() + +In this method, the plugin should install itself into the given vendor-OS. + +What "installation" means is up to the plugin. Some plugins may just copy +a file from the OpenSLX host installation into the vendor-OS, while others may +need to download files from the internet and/or install packages through the +vendor-OS' meta packager. + +N.B.: This method is invoked while chrooted into the vendor-OS root. In order to +make the OpenSLX files from the host available, the OpenSLX base folder +(normally /opt/openslx) will be mounted to /mnt/openslx. So if you have to copy +any files from the host, fetch them from there. + +=cut sub installationPhase -{ # called while chrooted to the vendor-OS root, most plugins will do all - # their installation work here +{ my $self = shift; my $pluginRepositoryPath = shift; - # the repository folder, this time from inside the chroot + # the repository folder, relative to the vendor-OS root my $pluginTempPath = shift; - # the temporary folder, this time from inside the chroot + # the temporary folder, relative to the vendor-OS root + my $openslxPath = shift; + # the openslx base path bind-mounted into the chroot (/mnt/openslx) return; } -sub postInstallationPhase -{ # called after having returned from chrooted environment, should be used - # to cleanup any leftovers, if any such thing is necessary - my $self = shift; - my $pluginRepositoryPath = shift; - my $pluginTempPath = shift; - - return; -} +=item removalPhase() -sub preRemovalPhase -{ # called before chrooting into vendor-OS root, should be used if any - # preparations outside of the chroot have to be made before the plugin - # can be removed - my $self = shift; - my $pluginRepositoryPath = shift; - # the folder where the stage1-plugin has stored all files - # required by the corresponding stage3 runlevel script - my $pluginTempPath = shift; - # a temporary playground that will be cleaned up automatically - - return; -} +In this method, the plugin should remove itself from the given vendor-OS. + +What "removal" means is up to the plugin. Some plugins may just delete +a file from the vendor-OS, while others may need to uninstall packages through +the vendor-OS' meta packager. + +N.B.: This method is invoked while chrooted into the vendor-OS root. + +=cut sub removalPhase -{ # called while chrooted to the vendor-OS root, most plugins will do all - # their uninstallation work here +{ my $self = shift; my $pluginRepositoryPath = shift; - # the repository folder, this time from inside the chroot + # the repository folder, relative to the vendor-OS root my $pluginTempPath = shift; - # the temporary folder, this time from inside the chroot + # the temporary folder, relative to the vendor-OS root + my $openslxPath = shift; + # the openslx base path bind-mounted into the chroot (/mnt/openslx) return; } -sub postRemovalPhase -{ # called after having returned from chrooted environment, should be used - # to cleanup any leftovers, if any such thing is necessary - my $self = shift; - my $pluginRepositoryPath = shift; - my $pluginTempPath = shift; - - return; -} +=back + +=head2 Initramfs Interface + +All of the following methods are invoked by the config demuxer when it makes an +initramfs for a system that has this plugin activated. Through these methods, +each plugin can integrate itself into that initramfs. + +=over + +=item suggestAdditionalKernelParams() + +Called in order to give the plugin a chance to add any kernel params it +requires. + +In order to do so, the plugin should return a list of additional kernel params +that it would like to see added. + +=cut sub suggestAdditionalKernelParams -{ # called by config-demuxer in order to give the plugin a chance to add - # any kernel params it requires. - # In order to do so, the plugin should return a list of additional kernel - # params that it would like to see added. +{ my $self = shift; my $makeInitRamFSEngine = shift; return; } +=item suggestAdditionalKernelModules() + +Called in order to give the plugin a chance to add any kernel modules it +requires. + +In order to do so, the plugin should return the names of additional kernel +modules that it would like to see added. + +=cut + sub suggestAdditionalKernelModules -{ # called by config-demuxer in order to give the plugin a chance to add - # any kernel modules it requires. - # In order to do so, the plugin should return the names of additional kernel - # modules that it would like to see added. +{ my $self = shift; my $makeInitRamFSEngine = shift; return; } +=item copyRequiredFilesIntoInitramfs() + +Called in order to give the plugin a chance to copy all required files from the +vendor-OS into the initramfs. + +N.B.: Only files that are indeed required by the initramfs should be copied +here, i.e. files that are needed *before* the root-fs has been mounted. +All other files should be taken from the root-fs instead! + +=cut + sub copyRequiredFilesIntoInitramfs -{ # called by config-demuxer in order to give the plugin a chance to copy - # all required files from the vendor-OS into the initramfs. - # N.B.: Only files that are indeed required by the initramfs should be - # copied here, i.e. files that are needed *before* the root-fs - # has been mounted. - # All other files should be taken from the root-fs instead! +{ my $self = shift; my $targetPath = shift; my $attrs = shift; @@ -180,12 +287,19 @@ sub copyRequiredFilesIntoInitramfs return; } +=item setupPluginInInitramfs() + +Called in order to let the plugin setup all the files it requires in the +initramfs. + +Normally, you don't need to override this method in your own plugin, +as it is usually enough to override suggestAdditionalKernelParams(), +suggestAdditionalKernelModules() and maybe copyRequiredFilesIntoInitramfs(). + +=cut + sub setupPluginInInitramfs -{ # called by config-demuxer in order to let the plugin setup all the files - # it requires in the initramfs. - # Normally, you don't need to override this method in your own plugin, - # as it is usually enough to override suggestAdditionalKernelParams(), - # suggestAdditionalKernelModules() and maybe copyRequiredFilesIntoInitramfs(). +{ my $self = shift; my $attrs = shift; my $makeInitRamFSEngine = shift; @@ -240,3 +354,13 @@ sub setupPluginInInitramfs return 1; } + +=back + +=head2 Support Interface + +=over + +=cut + +1; -- cgit v1.2.3-55-g7522