| 1 | package Devel::IPerl::Plugin::Perlbrew; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use warnings; | ||
| 5 | use feature 'say'; | ||
| 6 | use Symbol 'delete_package'; | ||
| 7 | use constant DEBUG => $ENV{IPERL_PLUGIN_PERLBREW_DEBUG} ? 1 : 0; | ||
| 8 | |||
| 9 | use constant PERLBREW_CLASS => $ENV{IPERL_PLUGIN_PERLBREW_CLASS} | ||
| 10 | ? $ENV{IPERL_PLUGIN_PERLBREW_CLASS} | ||
| 11 | : 'App::perlbrew'; | ||
| 12 | |||
| 13 | use constant PERLBREW_INSTALLED => eval 'use '. PERLBREW_CLASS.'; 1' ? 1 : 0; | ||
| 14 | |||
| 15 | our $VERSION = '0.03'; | ||
| 16 | |||
| 17 | sub brew { | ||
| 18 | my $self = shift; | ||
| 19 | my %env = %{$self->env || {}}; | ||
| 20 | my %save = (); | ||
| 21 | for my $var(_filtered_env_keys(\%env)) { | ||
| 22 | say STDERR "@$self{name} ", join " = ", $var, $env{$var} if DEBUG; | ||
| 23 | $save{$var} = $ENV{$var} if exists $ENV{$var}; | ||
| 24 | $ENV{$var} = $env{$var}; | ||
| 25 | } | ||
| 26 | if ($env{PERL5LIB}) { | ||
| 27 | say STDERR join " = ", 'PERL5LIB', $env{'PERL5LIB'} if DEBUG; | ||
| 28 | eval "use lib split ':', q[$env{PERL5LIB}];"; | ||
| 29 | warn $@ if $@; ## uncoverable branch true | ||
| 30 | } | ||
| 31 | return $self->saved(\%save); | ||
| 32 | } | ||
| 33 | |||
| 34 | sub env { return $_[0]{env} if @_ == 1; $_[0]{env} = $_[1]; $_[0]; } | ||
| 35 | |||
| 36 | sub new { | ||
| 37 | my $class = shift; | ||
| 38 | bless @_ ? @_ > 1 ? {@_} : {%{$_[0]}} : {}, ref $class || $class; | ||
| 39 | } | ||
| 40 | |||
| 41 | sub name { return $_[0]{name} if @_ == 1; $_[0]{name} = $_[1]; $_[0]; } | ||
| 42 | |||
| 43 | sub register { | ||
| 44 | my ($class, $iperl) = @_; | ||
| 45 | |||
| 46 | my $domain = sub { | ||
| 47 | my $instance = $_[0]->instance; | ||
| 48 | return $instance->{'perlbrew_domain'} if @_ == 1; | ||
| 49 | $instance->{'perlbrew_domain'} = $_[1]; | ||
| 50 | $instance; | ||
| 51 | }; | ||
| 52 | |||
| 53 | $domain->($iperl, $ENV{'PERLBREW_HOME'}); | ||
| 54 | |||
| 55 | for my $name (qw{perlbrew}) { | ||
| 56 | my $current = $class->new->name('@@@'); ## impossible name | ||
| 57 | |||
| 58 | $iperl->helper($name => sub { | ||
| 59 | my ($ip, $lib, $unload, $ret) = (shift, shift, shift || 0, -1); | ||
| 60 | return $ret if not defined $lib; | ||
| 61 | return $ret if 0 == PERLBREW_INSTALLED; | ||
| 62 | |||
| 63 | my $new = $class->new->name($class->_make_name($lib)); | ||
| 64 | if ($current->unload($unload)->name ne $new->name) { | ||
| 65 | my $pb = PERLBREW_CLASS->new(); | ||
| 66 | $pb->home($domain->($ip)); | ||
| 67 | $new->env({ $pb->perlbrew_env($new->name) }); | ||
| 68 | ## ensure the timing of the DESTROY, spoil | ||
| 69 | undef($current = $current->spoil); | ||
| 70 | $current = $new->brew; | ||
| 71 | } | ||
| 72 | return $new->success; | ||
| 73 | }); | ||
| 74 | } | ||
| 75 | |||
| 76 | for my $name (qw{list list_modules}) { | ||
| 77 | $iperl->helper("perlbrew_$name" => sub { | ||
| 78 | my ($ip, $ret) = (shift, -1); | ||
| 79 | return $ret if 0 == PERLBREW_INSTALLED; | ||
| 80 | my $pb = PERLBREW_CLASS->new(); | ||
| 81 | $pb->home($domain->($ip)); | ||
| 82 | local $App::perlbrew::PERLBREW_HOME = $pb->home | ||
| 83 | if ($name eq 'list_modules'); | ||
| 84 | return $pb->run_command($name, @_); | ||
| 85 | }); | ||
| 86 | } | ||
| 87 | |||
| 88 | for my $name (qw{lib_create}) { | ||
| 89 | $iperl->helper("perlbrew_$name" => sub { | ||
| 90 | my ($ip, $lib, $ret) = (shift, shift, -1); | ||
| 91 | return $ret if not defined $lib; | ||
| 92 | return $ret if 0 == PERLBREW_INSTALLED; | ||
| 93 | my $pb = PERLBREW_CLASS->new(); | ||
| 94 | $pb->home($domain->($ip)); | ||
| 95 | eval { $pb->run_command_lib_create($class->_make_name($lib)); }; | ||
| 96 | return $@ ? 0 : 1; | ||
| 97 | }); | ||
| 98 | } | ||
| 99 | |||
| 100 | $iperl->helper('perlbrew_domain' => sub { | ||
| 101 | my ($ip, $dir) = (shift, shift); | ||
| 102 | return $domain->($ip) unless $dir && -d $dir; | ||
| 103 | return $domain->($ip, $dir)->{'perlbrew_domain'}; | ||
| 104 | }); | ||
| 105 | |||
| 106 | return 1; | ||
| 107 | } | ||
| 108 | |||
| 109 | sub saved { return $_[0]{saved} if @_ == 1; $_[0]{saved} = $_[1]; $_[0]; } | ||
| 110 | |||
| 111 | sub spoil { | ||
| 112 | my $self = shift; | ||
| 113 | my %env = %{$self->env || {}}; | ||
| 114 | my %save = %{$self->saved || {}}; | ||
| 115 | for my $var(_filtered_env_keys(\%env)) { | ||
| 116 | if (exists $save{$var}) { | ||
| 117 | say STDERR "revert ", join " = ", $var, $save{$var} if DEBUG; | ||
| 118 | $ENV{$var} = $save{$var}; | ||
| 119 | } else { | ||
| 120 | say STDERR "unset ", $var if DEBUG; | ||
| 121 | delete $ENV{$var}; | ||
| 122 | } | ||
| 123 | } | ||
| 124 | if ($env{PERL5LIB}) { | ||
| 125 | say STDERR join " = ", 'PERL5LIB', $env{'PERL5LIB'} if DEBUG; | ||
| 126 | eval "no lib split ':', q[$env{PERL5LIB}];"; | ||
| 127 | warn $@ if $@; ## uncoverable branch true | ||
| 128 | if ($self->unload) { | ||
| 129 | my $path_re = qr{\Q$env{PERL5LIB}\E}; | ||
| 130 | for my $module_path(keys %INC) { | ||
| 131 | ## autosplit modules | ||
| 132 | next if $module_path =~ m{\.(al|ix)$} && delete $INC{$module_path}; | ||
| 133 | ## global destruction ? | ||
| 134 | next if not defined $INC{$module_path}; | ||
| 135 | ## FatPacked ? | ||
| 136 | next if ref($INC{$module_path}); | ||
| 137 | ## Not part of this PERL5LIB | ||
| 138 | next if $INC{$module_path} !~ m{^$path_re}; | ||
| 139 | ## translate to class_path | ||
| 140 | (my $class = $module_path) =~ s{/}{::}g; | ||
| 141 | $class =~ s/\.pm//; | ||
| 142 | ## notify and unload | ||
| 143 | say "unloading $class ($module_path) from $INC{$module_path}"; | ||
| 144 | _teardown( $class ); | ||
| 145 | delete $INC{$module_path}; | ||
| 146 | } | ||
| 147 | } | ||
| 148 | } | ||
| 149 | # no need to revert again. | ||
| 150 | return $self->env({})->saved({}); | ||
| 151 | } | ||
| 152 | |||
| 153 | sub success { scalar(keys %{$_[0]->{env}}) ? 1 : 0; } | ||
| 154 | |||
| 155 | sub unload { return $_[0]{unload} if @_ == 1; $_[0]{unload} = $_[1]; $_[0]; } | ||
| 156 | |||
| 157 | sub _filtered_env_keys { | ||
| 158 | return (sort grep { m/^PERL/i && $_ ne "PERL5LIB" } keys %{+pop}); | ||
| 159 | } | ||
| 160 | |||
| 161 | sub _from_binary_path { | ||
| 162 | say STDERR $^X if DEBUG; | ||
| 163 | if ($^X =~ m{/perls/([^/]+)/bin/perl}) { return $1; } | ||
| 164 | (my $v = $^V->normal) =~ s/v/perl-/; | ||
| 165 | return $v; | ||
| 166 | } | ||
| 167 | |||
| 168 | sub _make_name { | ||
| 169 | my ($class, $name, $current) = | ||
| 170 | (shift, shift, $ENV{PERLBREW_PERL} || _from_binary_path()); | ||
| 171 | my ($perl, $lib) = | ||
| 172 | split /\@/, ($name =~ m/\@/ || $name eq $current ? $name : "\@$name"); | ||
| 173 | $perl = $current; | ||
| 174 | return $perl unless $lib; | ||
| 175 | return join '@', $perl, $lib; | ||
| 176 | } | ||
| 177 | |||
| 178 | ## from Mojo::Util | ||
| 179 | sub _teardown { | ||
| 180 | return unless my $class = shift; | ||
| 181 | # @ISA has to be cleared first because of circular references | ||
| 182 | no strict 'refs'; | ||
| 183 | @{"${class}::ISA"} = (); | ||
| 184 | delete_package $class; | ||
| 185 | } | ||
| 186 | |||
| 187 | sub DESTROY { | ||
| 188 | my $self = shift; | ||
| 189 | say STDERR "DESTROY $self @$self{name}" if DEBUG; | ||
| 190 | $self->spoil; | ||
| 191 | return ; | ||
| 192 | } | ||
| 193 | |||
| 194 | 1; | ||
| 195 | |||
| 196 | =pod | ||
| 197 | |||
| 198 | =head1 NAME | ||
| 199 | |||
| 200 | Devel::IPerl::Plugin::Perlbrew - interact with L<perlbrew> in L<Jupyter|https://jupyter.org> IPerl kernel | ||
| 201 | |||
| 202 | =begin html | ||
| 203 | |||
| 204 | <!--- Travis ---> | ||
| 205 | <a href="https://travis-ci.org/kiwiroy/Devel-IPerl-Plugin-Perlbrew"> | ||
| 206 | <img src="https://travis-ci.org/kiwiroy/Devel-IPerl-Plugin-Perlbrew.svg?branch=master" | ||
| 207 | alt="Build Status" /> | ||
| 208 | </a> | ||
| 209 | |||
| 210 | <!-- Coveralls --> | ||
| 211 | <a href='https://coveralls.io/github/kiwiroy/Devel-IPerl-Plugin-Perlbrew?branch=master'> | ||
| 212 | <img src='https://coveralls.io/repos/github/kiwiroy/Devel-IPerl-Plugin-Perlbrew/badge.svg?branch=master' | ||
| 213 | alt='Coverage Status' /> | ||
| 214 | </a> | ||
| 215 | |||
| 216 | <!-- Kritika --> | ||
| 217 | <a href="https://kritika.io/users/kiwiroy/repos/6870682787977901/heads/master/"> | ||
| 218 | <img src="https://kritika.io/users/kiwiroy/repos/6870682787977901/heads/master/status.svg" | ||
| 219 | alt="Kritika Analysis Status"/> | ||
| 220 | </a> | ||
| 221 | |||
| 222 | =end html | ||
| 223 | |||
| 224 | =head1 DESCRIPTION | ||
| 225 | |||
| 226 | In a shared server environment the Perl module needs of multiple users can be | ||
| 227 | met most easily with access to L<perlbrew> and the ability to install perl | ||
| 228 | modules under their own libraries. A user can generate a L<cpanfile> to | ||
| 229 | facilitate the creation of these libraries in a reproducible manner. At the | ||
| 230 | command line a typical workflow in such an environment might appear thus: | ||
| 231 | |||
| 232 | perlbrew lib create perl-5.26.0@reproducible | ||
| 233 | perlbrew use perl-5.26.0@reproducible | ||
| 234 | ## assuming a cpanfile | ||
| 235 | cpanm --installdeps . | ||
| 236 | |||
| 237 | During the analysis that utilises such codebases using a JupyterHub on the same | ||
| 238 | environment a user will wish to access these installed modules in a way that is | ||
| 239 | as simple as the command line and within the framework of a Jupyter notebook. | ||
| 240 | |||
| 241 | This plugin is designed to easily transition between command line and Jupyter | ||
| 242 | with similar syntax and little overhead. | ||
| 243 | |||
| 244 | =begin html | ||
| 245 | |||
| 246 | <p>There are some Jupyter notebooks in the <a href="./examples/">examples directory</a></p> | ||
| 247 | |||
| 248 | =end html | ||
| 249 | |||
| 250 | =head1 SYNOPSIS | ||
| 251 | |||
| 252 | IPerl->load_plugin('Perlbrew') unless IPerl->can('perlbrew'); | ||
| 253 | IPerl->perlbrew_list(); | ||
| 254 | IPerl->perlbrew_list_modules(); | ||
| 255 | |||
| 256 | IPerl->perlbrew('perl-5.26.0@reproducible'); | ||
| 257 | |||
| 258 | =head1 INSTALLATION AND REQUISITES | ||
| 259 | |||
| 260 | ## install dependencies | ||
| 261 | cpanm --installdeps --quiet . | ||
| 262 | ## install | ||
| 263 | cpanm . | ||
| 264 | |||
| 265 | If there are some issues with L<Devel::IPerl> installing refer to their | ||
| 266 | L<README.md|https://github.com/EntropyOrg/p5-Devel-IPerl>. The C<.travis.yml> in | ||
| 267 | this repository might provide sources of help. | ||
| 268 | |||
| 269 | L<App::perlbrew> is a requirement and it is B<suggested> that L<Devel::IPerl> is | ||
| 270 | deployed into a L<perlbrew> installed L<perl|perlbrew#COMMAND:-INSTALL> and call | ||
| 271 | the L</"perlbrew"> function to use each L<library|perlbrew#COMMAND:-LIB>. | ||
| 272 | |||
| 273 | =over 4 | ||
| 274 | |||
| 275 | =item installing perlbrew | ||
| 276 | |||
| 277 | For a single user use case the recommended install proceedure at | ||
| 278 | L<https://perlbrew.pl> should be used. If installing for a shared environment | ||
| 279 | and JupyterHub, the following may act as a template. | ||
| 280 | |||
| 281 | version=0.82 | ||
| 282 | mkdir -p /sw/perlbrew-$version | ||
| 283 | export PERLBREW_ROOT=!$ | ||
| 284 | curl -L https://install.perlbrew.pl | bash | ||
| 285 | |||
| 286 | =item installing iperl | ||
| 287 | |||
| 288 | The kernel specification needs to be installed so that Jupyter can find it. This | ||
| 289 | is achieved thus: | ||
| 290 | |||
| 291 | iperl --version | ||
| 292 | |||
| 293 | =item perlbrew-ise the kernel | ||
| 294 | |||
| 295 | The kernel specification should be updated to make the environment variables, | ||
| 296 | that L<App::perlbrew> relies on, available. Included in this dist is the command | ||
| 297 | C<perlbrewise-spec>. | ||
| 298 | |||
| 299 | perlbrewise-spec | ||
| 300 | |||
| 301 | =back | ||
| 302 | |||
| 303 | =head1 IPerl Interface Method | ||
| 304 | |||
| 305 | =head2 register | ||
| 306 | |||
| 307 | Called by C<<< IPerl->load_plugin('Perlbrew') >>>. | ||
| 308 | |||
| 309 | =head1 REGISTERED METHODS | ||
| 310 | |||
| 311 | =head2 perlbrew | ||
| 312 | |||
| 313 | # 1 - success | ||
| 314 | IPerl->perlbrew('perl-5.26.0@reproducible'); | ||
| 315 | # 0 - it is already loaded | ||
| 316 | IPerl->perlbrew('perl-5.26.0@reproducible'); | ||
| 317 | # -1 - no library specified | ||
| 318 | IPerl->perlbrew(); | ||
| 319 | # 1 - success switching off reproducible and reverting to perl-5.26.0 | ||
| 320 | IPerl->perlbrew($ENV{'PERLBREW_PERL'}); | ||
| 321 | |||
| 322 | This is identical to C<<< perlbrew use perl-5.26.0@reproducible >>> and will | ||
| 323 | switch any from any previous call. Returns C<1>, C<0> or C<-1> for I<success>, | ||
| 324 | I<no change> and I<error> respectively. A name for the library is required. To | ||
| 325 | revert to the I<"system"> or non-library version pass the value of | ||
| 326 | C<$ENV{PERLBREW_PERL}>. | ||
| 327 | |||
| 328 | IPerl->perlbrew('perl-5.26.0@tutorial', 1); | ||
| 329 | |||
| 330 | The function takes a Boolean as an optional second argument. A I<true> value will | ||
| 331 | result in all the modules that were loaded during the activity of the previous | ||
| 332 | library to be unloaded using L<delete_package|Symbol>. The default value is | ||
| 333 | I<false> as setting is to true might expose the L<unexpected|Symbol#BUGS> | ||
| 334 | behaviour. | ||
| 335 | |||
| 336 | When using multiple L<perlbrew> libraries it may be possible to use modules from | ||
| 337 | both, although this is not a recommended use. | ||
| 338 | |||
| 339 | IPerl->perlbrew('perl-5.26.0@tutorial'); | ||
| 340 | use Jupyter::Tutorial::Simple; | ||
| 341 | ## run some code | ||
| 342 | |||
| 343 | ## load @reproducible, but do not unload Jupyter::Tutorial::Simple | ||
| 344 | IPerl->perlbrew('perl-5.26.0@reproducible', 0); | ||
| 345 | use Bio::Taxonomy; | ||
| 346 | ## ... more code, possibly using Jupyter::Tutorial::Simple | ||
| 347 | |||
| 348 | =head2 perlbrew_domain | ||
| 349 | |||
| 350 | B<This is experimental>. | ||
| 351 | |||
| 352 | # /home/username/.perlbrew | ||
| 353 | IPerl->perlbrew_domain; | ||
| 354 | # /work/username/perlbrew-libs | ||
| 355 | IPerl->perlbrew_domain('/work/username/perlbrew-libs'); | ||
| 356 | |||
| 357 | Users often generate a large number of libraries which can quickly result in a | ||
| 358 | long list generated in the output of L</"perlbrew_list">. This experimental | ||
| 359 | feature allows for switching between I<domains> to reduce the size of these | ||
| 360 | lists. Thus, a collection of libraries are organised under domains. These are | ||
| 361 | only directories, must exist before use and are synonymous with | ||
| 362 | C<$ENV{PERLBREW_HOME}>. Indeed, this is a convenient alternative to | ||
| 363 | C<$App::perlbrew::PERLBREW_HOME>. | ||
| 364 | |||
| 365 | =head2 perlbrew_lib_create | ||
| 366 | |||
| 367 | # 1 - success | ||
| 368 | IPerl->perlbrew_lib_create('reproducible'); | ||
| 369 | # 0 - already exists | ||
| 370 | IPerl->perlbrew_lib_create('reproducible'); | ||
| 371 | # -1 - no library name given | ||
| 372 | IPerl->perlbrew_lib_create(); | ||
| 373 | |||
| 374 | This is identical to C<<< perlbrew lib create >>>. Returns C<1>, C<0> or C<-1> | ||
| 375 | for I<success>, I<already exists> and I<error> respectively. | ||
| 376 | |||
| 377 | =head2 perlbrew_list | ||
| 378 | |||
| 379 | IPerl->perlbrew_list; | ||
| 380 | |||
| 381 | This is identical to C<<< perlbrew list >>> and will output the same information. | ||
| 382 | |||
| 383 | =head2 perlbrew_list_modules | ||
| 384 | |||
| 385 | IPerl->perlbrew_list_modules; | ||
| 386 | |||
| 387 | This is identical to C<<< perlbrew list_modules >>> and will output the same | ||
| 388 | information. | ||
| 389 | |||
| 390 | =head1 ENVIRONMENT VARIABLES | ||
| 391 | |||
| 392 | The following environment variables alter the behaviour of the plugin. | ||
| 393 | |||
| 394 | =over 4 | ||
| 395 | |||
| 396 | =item IPERL_PLUGIN_PERLBREW_DEBUG | ||
| 397 | |||
| 398 | A logical to control how verbose the plugin is during its activities. | ||
| 399 | |||
| 400 | =item IPERL_PLUGIN_PERLBREW_CLASS | ||
| 401 | |||
| 402 | This defaults to L<App::prelbrew> | ||
| 403 | |||
| 404 | =back | ||
| 405 | |||
| 406 | =head1 INTERNAL INTERFACES | ||
| 407 | |||
| 408 | These are part of the internal interface and not designed for end user | ||
| 409 | consumption. | ||
| 410 | |||
| 411 | =head2 brew | ||
| 412 | |||
| 413 | $plugin->brew; | ||
| 414 | |||
| 415 | Use the perlbrew library specified in L</"name">. | ||
| 416 | |||
| 417 | =head2 env | ||
| 418 | |||
| 419 | $plugin->env({PERLBREW_ROOT => '/sw/perlbrew', ...}); | ||
| 420 | # {PERLBREW_ROOT => '/sw/perlbrew', ...} | ||
| 421 | $plugin->env; | ||
| 422 | |||
| 423 | An accessor that stores the environment from L<App::perlbrew> for a subsequent | ||
| 424 | call to L</"brew">. | ||
| 425 | |||
| 426 | =head2 new | ||
| 427 | |||
| 428 | my $plugin = Devel::IPerl::Plugin::Perlbrew->new(); | ||
| 429 | |||
| 430 | Instantiate an object. | ||
| 431 | |||
| 432 | =head2 name | ||
| 433 | |||
| 434 | $plugin->name('perl-5.26.0@reproducible'); | ||
| 435 | # perl-5.26.0@reproducible | ||
| 436 | $plugin->name; | ||
| 437 | |||
| 438 | An accessor for the name of the perlbrew library. | ||
| 439 | |||
| 440 | =head2 saved | ||
| 441 | |||
| 442 | $plugin->saved; | ||
| 443 | |||
| 444 | An accessor for the previous environment variables so they may be restored as | ||
| 445 | the L</"brew"> L</"spoil">s. | ||
| 446 | |||
| 447 | =head2 spoil | ||
| 448 | |||
| 449 | $plugin->spoil; | ||
| 450 | |||
| 451 | When a L</"brew"> is finished with. This is called automatically during object | ||
| 452 | destruction. | ||
| 453 | |||
| 454 | =head2 success | ||
| 455 | |||
| 456 | # boolean where 1 == success, 0 == not success | ||
| 457 | $plugin->success; | ||
| 458 | |||
| 459 | Was everything a success? | ||
| 460 | |||
| 461 | =head2 unload | ||
| 462 | |||
| 463 | $plugin->unload(1); | ||
| 464 | # 1 | ||
| 465 | $plugin->unload; | ||
| 466 | |||
| 467 | A flag to determine whether to unload all the modules that were used as part of | ||
| 468 | this library during cleanup. | ||
| 469 | |||
| 470 | =cut |