GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  WX::LOADER (3)

.ds Aq ’

NAME

Wx::Loader - using custom dll loaders with Wx

CONTENTS

SYNOPSIS



  #---------------------------------------
  # For Packagers
  #---------------------------------------
 
  # the order of these use()s is important
  use MyCustomWxLoader;
  use Wx;
 
  or .....
 
  use threads;
  use threads::shared;
  use MyCustomLoader;
  use Wx;
 
  or - Wx::Perl::Splashfast special case
   
  use MyCustomWxLoader;
  use Wx::Perl::SplashFast ("./logo.jpg",5000);
  use Wx;
 
  ............. meanwhile in MyCustomWxLoader.pm
 
  package MyCustomWxLoader;
  require Wx::Mini;
  our @ISA = qw( Wx::Loader::Standard );
   
  $Wx::wx_binary_loader = __PACKAGE__;
  ...... or
  $Wx::wx_binary_loader = __PACKAGE__->new;
 
  #-----------------------------------------
  # For binary distributions
  #-----------------------------------------
 
  # Provide a custom Wx::Loader::Custom
  # to be loaded by Wx::Mini
 
  package Wx::Loader::Custom
  our @ISA = qw( Wx::Loader::Standard );
 
  # be polite if another loader is already in place
 
  $Wx::wx_binary_loader = __PACKAGE__ if !$Wx::wx_binary_loader;
  ...... or
  $Wx::wx_binary_loader = __PACKAGE__->new() if !$Wx::wx_binary_loader;



DESCRIPTION

If you are providing binary distributions of Wx or packaging Wx applications to run on machines without Perl (PAR, PerlApp),you may need to override dll loading methods. Providing a custom wx_binary_loader package allows you to do this.

Binary Distributions

A binary distribution my provide alternative sources and loading methods for the wxWidgets dlls. It achieves this by providing a Wx::Loader::Custom module in the distribution



  package Wx::Loader::Custom
  our @ISA = qw( Wx::Loader::Standard );
 
  # be polite if another loader is already in place
 
  $Wx::wx_binary_loader = __PACKAGE__ if !$Wx::wx_binary_loader;
  ...... or
  $Wx::wx_binary_loader = __PACKAGE__->new() if !$Wx::wx_binary_loader;
 
  # remember that Wx.pm has not necessarily been loaded so only
  # Wx::Mini is available



Perl Application Packagers



  Applications that package perl scripts to run on machines without
  Perl (PAR, PerlApp etc) can override dll loading methods if necessary
  by loading a custom package before wx
 
  package MyCustomWxLoader;
  require Wx::Mini;
  our @ISA = qw( Wx::Loader::Standard );
   
  $Wx::wx_binary_loader = __PACKAGE__;
  ...... or
  $Wx::wx_binary_loader = __PACKAGE__->new;
 
  # remember that Wx.pm has not necessarily been loaded so only
  # Wx::Mini is available



METHODS



  The following methods may be provided by custom loaders to override the
  default behaviour



    loader_info



  should return an information string about the loader and MUST be provided.
  The default loader has
 
  sub loader_info { Standard Distribution; }
 
  so any custom loader should return something different
 
  e.g.
 
  sub loader_info { "Marks Broken Distribution - its all my fault"; }



    set_binary_path



  allows setting a custom path for the wxWidgets libraries.
 
  sub set_binary_path {
    my $class_or_object = shift;
   
    ... work out binary path
   
    return $newbinarypath; # method MUST return a path
  }



    load_dll



  Is called to load wxWidgets plugin dlls using a key for the $Wx::dlls hash
  ( see Wx::Mini )
 
  sub load_dll {
    my ($class_or_object, $dllkey) = @_;
    ..... load dll - or maybe not
  }
 
  the default loader does nothing - dependencies are loaded automatically
  and determined by the standard methods of the os:
 
  an example of pre loading a known dependency
 
  sub load_dll {
    return if $^O !~ /^(mswin|linux)/i;
    local $ENV{PATH} = $Wx::wx_path . ; . $ENV{PATH} if $Wx::wx_path;
    return unless exists $Wx::dlls->{$_[1]} && $Wx::dlls->{$_[1]};
    my $dll = $Wx::dlls->{$_[1]};
    $dll = $Wx::wx_path . / . $dll if $Wx::wx_path;
    Wx::_load_plugin( $dll );
  }



    unload_dll



  Is called ONCE from within an END block
  A custom loader may choose, for example to unload any dlls it has loaded
 
  sub unload_dll {
    my $class_or_object = shift;
   
    ... carry out END actions
  }
 
  The default unload_dll is a noop ( sub unload_dll {} )



    external_set_load



  A deprecated method of replacing the load function for plugins
  A custom loader may override this to prevent a legacy loader replacing
  the loading methods.



    external_set_unload



  A deprecated method of replacing the unload function for plugins
  A custom loader may override this to prevent a legacy loader replacing
  the unloading methods.



    boot_overload



  For binary distributions and packaged applications, normal shared
  library loading semantics may not work. A custom loader may provide
  this method to use in place of, or to supplement the standard XS load
  of Wx.dll (Wx.so).
 
  The method MUST return true or false, depending on whether it has
  loaded Wx.dll (Wx.so).
 
  For example, to load the core wxWidgets dlls before Wx is loaded
 
  sub boot_overload {
    shift;
    require DynaLoader;
    for my $dll ( qw( base core adv ) ) {
      next unless exists $Wx::dlls->{$dll} && $Wx::dlls->{$dll};
      my $file = ( $Wx::wx_path ) ? $Wx::wx_path . / . $Wx::dlls->{$dll} : $Wx::dlls->{$dll};
      my $libref = DynaLoader::dl_load_file($file, 0);
      push(@DynaLoader::dl_librefs,$libref) if $libref;
     
      # Dynaloader should take care of unloading
   
    }
  
    #------------ IMPORTANT ----------
    return 0; # we have not loaded Wx
    #---------------------------------
  }
 
 
  Some packagers extract dlls at runtime, and then may attempt to remove them
  at application close. This may fail for Wx. For example, on MSWin the directory
  cleanup fails whilst on Linux the application will seg-fault on exit.
  Packagers may avoid this by loading Wx.dll( Wx.so) from a non standard location
  ( perhaps a separate binary distribution of wx dlls ) that is not removed at
  application exit.
 
  For example
 
  sub boot_overload {
    my $class = shift
    require DynaLoader;
    for my $dll ( qw( base core adv ) ) {
      next unless exists $Wx::dlls->{$dll} && $Wx::dlls->{$dll};
      my $file = ( $Wx::wx_path ) ? $Wx::wx_path . / . $Wx::dlls->{$dll} : $Wx::dlls->{$dll};
      my $libref = DynaLoader::dl_load_file($file, 0);
      push(@DynaLoader::dl_librefs,$libref) if $libref;
     
      # Dynaloader should take care of unloading
   
    }
   
    package
       DynaLoader;
   
    my $file = $class->get_the_location_to_wx_xs_module;
   
    #------------------------------------------
    # From XSLoader
    #------------------------------------------
   
    my $module  = Wx;
   
    my $boots = "$module\::bootstrap";
    my $bootname = "boot_$module";
    $bootname =~ s/\W/_/g;
    @DynaLoader::dl_require_symbols = ($bootname);
    my $boot_symbol_ref;
   
    my $libref = dl_load_file($file, 0) or do {
        require Carp;
        Carp::croak("Cant load $file for module $module: " . dl_error());
    };
    push(@DynaLoader::dl_librefs,$libref);  # record loaded object

    my @unresolved = dl_undef_symbols();
    if (@unresolved) {
        require Carp;
        Carp::carp("Undefined symbols present after loading $file: @unresolved\n");
    }

    $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do {
        require Carp;
        Carp::croak("Cant find $bootname symbol in $file\n");
    };

    push(@DynaLoader::dl_modules, $module); # record loaded module

    my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file);

    push(@DynaLoader::dl_shared_objects, $file); # record files loaded
       
    #------------ IMPORTANT ----------
    return 1; # we have loaded Wx
    #---------------------------------
}



Full Custom Loader Example



  ################################################
  # Custom loader for Wx distribution from
  # http://www.wxperl.co.uk/repository
  #
  ################################################
 
  package Wx::Loader::Custom;
  use strict;
  use warnings;
 
  our @ISA = qw( Wx::Loader::Standard );
 
  $Wx::wx_binary_loader = __PACKAGE__ if !$Wx::wx_binary_loader;
 
  sub loader_info { Linux PPM Distribution from http://www.wxperl.co.uk/repository; }
 
  sub boot_overload {
      shift;
      require DynaLoader;
      for my $dll ( qw( base core adv ) ) {
        next unless exists $Wx::dlls->{$dll} && $Wx::dlls->{$dll};
        my $file = ( $Wx::wx_path ) ? $Wx::wx_path . / . $Wx::dlls->{$dll} : $Wx::dlls->{$dll};
        my $libref = DynaLoader::dl_load_file($file, 0);
        push(@DynaLoader::dl_librefs,$libref) if $libref;
       
        # Dynaloader should take care of unloading
      }
     return 0;
  }
 
  # Allow legacy packaging call to override our load method
 
  my( $load_fun ) = ( \&_load_dll );
 
  sub _load_dll {
      return unless exists $Wx::dlls->{$_[0]} && $Wx::dlls->{$_[0]};
      my $dll = $Wx::dlls->{$_[0]};
      $dll = $Wx::wx_path . / . $dll if $Wx::wx_path;
      return Wx::_load_plugin( $dll ); 
  }
 
  sub external_set_load { $load_fun = $_[1] }
 
  sub load_dll {
    shift;
    goto &$load_fun;
  }



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 WX::LOADER (3) 2014-03-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.