lib/POD2/DE/local/lib.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 local::lib~[de] - Erschaffen und benutzen von Perl Modulen in einem lokalen lib/ Verzeichnis mit PERL5LIB
   6
   7 =head1 SYNOPSIS
   8
   9 Im Code -
  10
  11   use local::lib; # Benutzt das Verzeichnis ~/perl5 zum anlegen des lokalen lib/ Verzeichnisses
  12
  13   use local::lib '~/foo'; # das selbe, aber mit ~/foo
  14
  15   # Oder...
  16   use FindBin;
  17   use local::lib "$FindBin::Bin/../support";  # Applikationsspezifische Sammlung von Modulen
  18
  19 Von der Shell -
  20
  21   # Installiert LWP und alle notwendigen Abhängigkeiten in das '~/perl5' Verzeichnis
  22   perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
  23
  24   # Gibt die Shell Kommandos aus um die Umgebung vorzubereiten
  25   $ perl -Mlocal::lib
  26   export MODULEBUILDRC=/home/username/perl/.modulebuildrc
  27   export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
  28   export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
  29   export PATH="/home/username/perl/bin:$PATH"
  30
  31 =head2 Die Bootstrapping Methode
  32
  33 Ein typischer Weg um local::lib zu benutzen ist die sogenannte "Bootstrapping" Methode.
  34 Diese Methode wird benutzt wenn noch kein local::lib auf dem System installiert ist.
  35 In diesem Fall kannst du einfach local::lib direkt in deinem Home-Verzeichnis installieren.
  36
  37 Selbst wenn du administrative Rechte hast, ist es wichtig das die Umgebungsvariablen von
  38 Schritt 4 in deinem Shell Startup Skript gesetzt werden. Ohne diesen Schritt werden die
  39 Module von CPAN weiterhin im System installiert und auch Perl Skripte die du startest
  40 würden das von local::lib erstellte lib/ Verzeichnis nicht nutzen.
  41
  42 Standardmäßig installiert sich local::lib in ~/perl5.
  43
  44 Windows Benutzern müssen ausserdem dies hier lesen:
  45 L</Unterschiede bei Benutzung dieses Module mit Win32>.
  46
  47 1. Lade das Tar-Archiv von CPAN runter (Suche nach "Download" auf der CPAN Seite von
  48 local::lib) und entpacke es in einem beliebigem Verzeichnis. Um das obige Problem zu
  49 vermeiden, sollte man dies als normaler User tun und nicht als root oder Administrator.
  50
  51 2. Starte in dem entstandenen Verzeichnis folgenden Befehl:
  52
  53   perl Makefile.PL --bootstrap
  54
  55 Wenn das System dir vorschlägt gewisse Dinge eigenständig zu konfigurieren ist es in
  56 fast allen Fällen vollkommen in Ordnung einfach "yes" zu antworten.
  57
  58 Falls du local::lib nicht in das Standard Verzeichnis installieren willst, musst du
  59 dieses Verzeichnis als Parameter angeben:
  60
  61   perl Makefile.PL --bootstrap=~/foo
  62
  63 3. Danach folgenden Befehl starten: (local::lib erwartet make auf dem System)
  64
  65   make test && make install
  66
  67 4. Nun müssen wir die benötigten Umgebungsvariablen, damit Perl unser neu generiertes
  68 lib/ Verzeichnis benutzt. Wenn du bash oder eine andere Bourne Shell benutzt, kannst
  69 du es über diesen Weg zu deinem Shell Startup Skript hinzufügen:
  70
  71   echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
  72
  73 Wenn du C Shell benutzt, du kannst das gleiche hiermit erreichen:
  74
  75   /bin/csh
  76   echo $SHELL
  77   /bin/csh
  78   perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
  79
  80 Wenn du beim bootstrappen ein anderes Verzeichnis benutzt als das Standardverzeichnis,
  81 dann musst du dieses Verzeichnis als Parameter beim Laden des Modules local::lib angeben:
  82
  83   echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
  84
  85 Nachdem diese Änderungen in deinem Shell Startup Skript gemacht wurden, ist es nun wichtig
  86 das diese Umgebungsvariablen auch gesetzt sind in deiner aktuellen Umgebung. In Bourne
  87 Shells macht man dies z.B. mit C<. ~/.bashrc>, und in C Shell würde man es mit:
  88 C<source ~/.cshrc> mit.
  89
  90 Wenn du eine sehr langsames System hast, oder du unter drakonischen Regulierungen des
  91 Plattenplatz leben musst, kann man die automatische Generierung der manpages vom POD
  92 bei der Installation des Moduls deaktivieren beim bootstrapping mit dem C<--no-manpages>
  93 Parameter:
  94
  95   perl Makefile.PL --bootstrap --no-manpages
  96
  97 Um zu vermeiden das man mehrere bootstraps macht um z.B. für verschiedene Applikationen
  98 eigene local::lib Installationen zu nutzen, kann man eine dieser Umgebungen benutzen
  99 um einfach in beliebigen anderen Verzeichnis Module zu installieren und somit weitere
 100 eigenständige lib/ Umgebungen zu bekommen:
 101
 102   cd ~/mydir1
 103   perl -Mlocal::lib=./
 104   eval $(perl -Mlocal::lib=./)  ### Um die Umgebungsvariablen für die
 105                                 ### aktuelle Shell zusetzen
 106
 107   printenv                      ### Hier kannst du sehen das ~/mydir1
 108                                 ### in der PERL5LIB Umgebungsvariable
 109                                 ### steht
 110
 111   perl -MCPAN -e install ...    ### welche Module auch immer ...
 112   cd ../mydir2
 113
 114   ... WIEDERHOLEN ...
 115
 116 Für mehrere Umgebungen in dieser Form brauch man eine Modifikation in der
 117 Benutzung von C<< use FindBin >> in dem "Im Code" Beispiel oben.
 118 Wenn du sowas machst, und du hast damit z.B. Perl Module nach C<<
 119 ~/mydir1/lib >> installiert und du hast ein Script in C<<
 120 ~/mydir1/scripts/myscript.pl >>, du musst dort angeben das die Module
 121 die es braucht im Verzeichnis C<< ~/mydir1/lib >> liegen.
 122
 123 In C<< ~/mydir1/scripts/myscript.pl >> steht dann:
 124
 125   use strict;
 126   use warnings;
 127   use local::lib "$FindBin::Bin/..";  ### zeigt auf ~/mydir1 und local::lib
 128                                       ### findet dort lib
 129   use lib "$FindBin::Bin/../lib";     ### zeigt auf ~/mydir1/lib
 130
 131 Setze das vor jeden BEGIN { ... } Block der die Module braucht die du
 132 installiert hast.
 133
 134 =head2 Unterschiede bei Benutzung dieses Module mit Win32
 135
 136 Um die nötigen Umgebungsvariablen für diese Variablen in der derzeitigen
 137 Sitzung mit C<CMD.EXE> zu setzen, kann man folgendes kommando nutzen:
 138
 139   C:\>perl -Mlocal::lib
 140   set MODULEBUILDRC=C:\DOCUME~1\ADMINI~1\perl5\.modulebuildrc
 141   set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
 142   set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
 143   set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
 144
 145   ### Um die Umgebungsvariablen für diese Shell alleine zu setzen
 146   C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
 147   ### anstelle von $(perl -Mlocal::lib=./) in bash.
 148
 149 Wenn du willst das die Umgebungsvariablen dauerhaft gesetzt sind, musst du diese
 150 in Systemsteuerung / System dauerhaft selber eintragen oder
 151 L<App::local::lib::Win32Helper> benutzen.
 152
 153 Die "~" wird übersetzt zu dem Benutzer Profil Verzeichnis (das Verzeichnis was
 154 beim User als "Dokumente und Einstellungen" bekannt ist unter Windows XP und
 155 vorher oder das "Benutzer" Verzeichnis bei Windows Vista und später), solange
 156 $ENV{HOME} nicht gesetzt ist. Das Verzeichnis wird hierbei zu dem korrekten
 157 Kurznamen umgewandelt, und muss daher definitiv existieren, und wird um die
 158 nötigen Unterverzeichnise erweitert.
 159
 160 =head1 GRUNDPRINZIP
 161
 162 Die Version von den Perl Paketen die man benötigt für spezifische Aufgaben sind
 163 sehr häufig nicht die richtigen oder korrekten Versionen auf dem System
 164 vorinstalliert. Ein Updaten von diesen Modulen ist in vielen Fällen einfach
 165 nicht möglich weil die nötigen Rechte fehlen. Ausserdem ist es generell nicht
 166 gut eigenständig die Versionen der Module auf dem System auszutauschen, weil
 167 natürlich der Rest des Systems genau die Version erwartet die von der
 168 Systemverwaltung auch installiert wurde.
 169
 170 local::lib löst dieses Problem, es erlaubt dir dein komplett eigenes Verzeichnis
 171 für deine CPAN Module zu haben und bist so nicht genötigt die Module vom
 172 System zu nutzen oder andersrum andere User nicht mit individuellen
 173 Modulwünschen zu Überarbeitung ihres Codes zu zwingen, weil bestimmte Module
 174 zentral für alle auf neuere Version upgedatet werden. Die Installation findet
 175 hierbei dann z.B. im Home Verzeichnis statt. Es werden nur Umgebungsvariablen
 176 gesetzt die das installierte Perl dazu bewegen die im Homeverzeichnis
 177 installierten Module zu benutzen, zusätzlich und vorgezogen zu denen auf dem
 178 System.
 179
 180 Daher muss man sich wenn man ein Paket System benutzt, wie z.b. Debian, garnicht
 181 mehr Sorgen machen, irgendwas auf dem System zu verletzten nur durch die
 182 Installation von Perl Modulen.
 183
 184 =head1 BESCHREIBUNG
 185
 186 Dieses Modul bietet eine schnelle und legitime Art und Weise ein sogenanntes
 187 bootstrapping zu machen um in einem User Homeverzeichnis eine Sammlung von
 188 Modulen zu installieren. Es erstellt auch die nötigen Umgebungsvariablen
 189 die benötigt werden um diese Module zu nutzen, passend zu der Shell die der
 190 User in der Umgebungsvariable C<SHELL> angegeben hat, um dann direkt passend
 191 in die entsprechenden Konfigurationsdateien der Shell einfügt zu werden.
 192
 193 Weitergehend ist local::lib in der Lage Module zu nutzen die nicht im
 194 standardmäßigen C<@INC> Pfad von Perl enthalten sind. Das macht es einfacher
 195 für bestimmte Applikationen ein bestimmtes Set von Modulen zu installieren
 196 ohne die anderen Module auf dem System in irgendeiner Art anzufassen.
 197 Damit es z.B. auch sicherer Module zu installieren die vom Maintainer noch
 198 nicht als Release verfügbar sind.
 199
 200 Beim Import setzt local::lib die folgenden Umgebungsvariablen zu den
 201 nötigen Werten:
 202
 203 =over 4
 204
 205 =item MODULEBUILDRC
 206
 207 =item PERL_MM_OPT
 208
 209 =item PERL5LIB
 210
 211 =item PATH
 212
 213 Am PATH wird natürlich angehangen, und nicht ersetzt.
 214
 215 =back
 216
 217 Diese Werte sind dann verfügbar für jeden Code der danach importiert wurde.
 218
 219 =head1 ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN
 220
 221 Mit L<lib::core::only> besteht eine Möglichkeit dieses zutun, aber beachte das
 222 hier eine Menge von Fallstricken und Problemen existieren, und man sollte
 223 immer darauf achten das man auf einem Perl aufbaut was sowenig wie möglich
 224 verändert wurde (d.h. site und vendor Verzeichnis so leer wie möglich).
 225
 226 =head1 METHODEN
 227
 228 =head2 ensure_dir_structure_for
 229
 230 =over 4
 231
 232 =item Parameter: $path
 233
 234 =item Rückgabewert: Keiner
 235
 236 =back
 237
 238 Versucht den angegebenen Pfad anzulegen, mit allen nötigen drüberliegenden
 239 Verzeichnissen. Im Fehlerfall wird eine Exception geworfen.
 240
 241 =head2 print_environment_vars_for
 242
 243 =over 4
 244
 245 =item Parameter: $pfad
 246
 247 =item Rückgabewert: Keiner
 248
 249 =back
 250
 251 Gibt die Umgebungsvariablen aus, die benötigt werden um den angegebenen Pfad
 252 als Basis Verzeichnis zu nutzen.
 253
 254 =head2 build_environment_vars_for
 255
 256 =over 4
 257
 258 =item Parameter: $pfad, $interpolate
 259
 260 =item Rückgabewert: \%umgebungs_variablen
 261
 262 =back
 263
 264 Gibt ein Hash zurück mit den Variablen die nötig sind in den Umgebungsvariablen
 265 um eine Installation in dem gegebenen Pfad zu benutzen.
 266
 267 =head2 setup_env_hash_for
 268
 269 =over 4
 270
 271 =item Parameter: $pfad
 272
 273 =item Rückgabewert: Keiner
 274
 275 =back
 276
 277 Setzt die C<%ENV> Einträge basierend auf dem Aufruf von
 278 L</build_environment_vars_for>.
 279
 280 =head2 install_base_perl_path
 281
 282 =over 4
 283
 284 =item Parameter: $pfad
 285
 286 =item Rückgabewert: $module_installations_pfad
 287
 288 =back
 289
 290 Gibt den Pfad zurück der benutzt wird um Perl Module zu installieren bei
 291 dem gegebenen Pfad als Basis. Prinzipiell wird nur C<lib> und C<perl5> als
 292 Pfadelemente angehangen.
 293
 294 =head2 install_base_arch_path
 295
 296 =over 4
 297
 298 =item Parameter: $pfad
 299
 300 =item Rückgabewert: $architektur_module_installations_pfad
 301
 302 =back
 303
 304 Gibt den Pfad zurück der benutzt wird um die Architektur-abhängigen Perl
 305 Module zu installieren basirend auf dem angegebenen Pfad als Basis. Basierend
 306 auf dem was L</install_base_perl_path> zurückgibt, and appends the value of
 307 C<$Config{archname}>.asis.
 308
 309 =head2 install_base_bin_path
 310
 311 =over 4
 312
 313 =item Parameter: $pfad
 314
 315 =item Rückgabewert: $ausfuehrbare_programme_installations_pfad
 316
 317 =back
 318
 319 Gibt den Pfad zurück, wo ausführbare Programme installiert werden, basierend
 320 auf der Basis des angegebenen Pfad. Basierend auf L</install_base_perl_path>
 321 Rückgabewert, hängt diese Methode noch C<bin> an.
 322
 323 =head2 modulebuildrc_path
 324
 325 =over 4
 326
 327 =item Parameter: $pfad
 328
 329 =item Rückgabewert: $modulebuildrc_pfad
 330
 331 =back
 332
 333 Gibt den Pfad zurück wo die C<.modulebuildrc> Datei angelegt wird, basierend
 334 auf der Basis des angegebenen Pfad.
 335
 336 =head2 resolve_empty_path
 337
 338 =over 4
 339
 340 =item Parameter: $pfad
 341
 342 =item Rückgabewert: $basis_pfad
 343
 344 =back
 345
 346 Erstellt und gibt zurück den Pfad der benutzt wird als Basis zur Installation
 347 der Module. Standardmäßig dies ist C<~/perl5>.
 348
 349 =head2 resolve_home_path( $path )
 350
 351 =over 4
 352
 353 =item Parameter: $pfad
 354
 355 =item Rückgabewert: $home
 356
 357 =back
 358
 359 Versucht das Home Verzeichnis vom aktullen User zu finden. Wenn C<File::HomeDir>
 360 installiert ist, für dieses benutzt dafür. Es wird eine Exception geworfen, wenn
 361 kein Home Verzeichnis ermittelt werden konnte.
 362
 363 =head2 resolve_relative_path
 364
 365 =over 4
 366
 367 =item Parameter: $pfad
 368
 369 =item Rückgabewert: $absoluter_pfad
 370
 371 =back
 372
 373 Macht aus dem angegebenen Pfad einen absoluten Pfad.
 374
 375 =head2 resolve_path
 376
 377 =over 4
 378
 379 =item Parameter: $pfad
 380
 381 =item Rückgabewert: $absoluter_pfad
 382
 383 =back
 384
 385 Hierbei wird der Pfad durch die folgende Methoden gegeben, wobei der Rückgabewert
 386 der ersten an die nächste weitergeben wird, um die Umgebung zu konfigurieren
 387 für die lokale Bibliotheks Installation: L</resolve_empty_path>,
 388 L</resolve_home_path>, L</resolve_relative_path>.
 389 Der daraus resultierende Pfad wird zu L</resolve_empty_path> übergeben, dessen
 390 Resultat dann weitergegeben wird an L</resolve_home_path>, wessen Resultat dann
 391 weitergegeben wird an L</resolve_relative_path>. Dieses Resultat wird dann final
 392 an L</resolve_path> übergeben, welches dann den Rückgabewert stellt.
 393
 394 =head1 EINE WARNUNG VOR UNINST=1
 395
 396 Wenn man local::lib in Kombination mit "make install UNINST=1" benutzt, muss
 397 man vorsichtig sein über die Tatsache das der Prozess über die Neuinstallation
 398 eine nicht ausreichende Sicherheit hat bezüglich wo er nun installieren muss.
 399 Hierdurch mann es passieren das beim deinstallieren eines Modul u.U. das
 400 globale Modul deinstalliert wird (wenn die Rechte vorhanden sind) aber die
 401 neue Version nur in der lokalen Version installiert ist. Es ist hier also sehr
 402 wichtig das man "make install UNINST=1" und local::lib nur gleichzeitig
 403 benutzt wenn man sehr sicher darüber ist welche Konsequenzen einem
 404 entgegenkommen.
 405
 406 =head1 EINSCHRÄNKUNGEN
 407
 408 Die Werkzeuge von perl, die benutzt werden um die Pakete zu installieren
 409 (die sogenannte toolchain), sind leider nicht in der Lage sauber mit
 410 Verzeichnissen umzugehen die Leerzeichen enthalten und können daher local::lib
 411 nicht direkt in ein solches Verzeichnis installieren. Was du machen kannst
 412 ist B<nach> der Installation von local::lib und der Module die du in deiner
 413 local::lib haben willst, das gesamte Verzeichnis dahin zu bewegen. local::lib
 414 kann mit dem Verzeichnis mit Leerzeichen umgehen. Bitte aufpassen das natürlich
 415 eine weitere Installation oder ein Erneuern von Paketen mit dem CPAN Programm
 416 nicht mehr möglich ist.
 417
 418 Die Shell Erkennung ist sehr primitiv. Derzeit ist es so das alles was "csh"
 419 im Namen hat auch als C Shell eingeordnet wird, und alles andere wird als
 420 Bourne Shell betrachet, ausser auf Win32 Systemen. Wenn die C<SHELL> Variable
 421 nicht gesetzt ist, eine Bourne Shell wird angenommen.
 422
 423 Bootstrap ist leider ein Hack, und wird auf jedenfall CPAN.pm benutzen für
 424 ExtUtils::MakeMaker, auch wenn CPANPLUS installiert ist.
 425
 426 Es setzt definitiv PERL5LIB, PERL_MM_OPT und MODULEBUILDRC neu und vernichtet
 427 jeden Wert der vorher gesetzt war.
 428
 429 Es sollte vielleicht eine automatische Korrektur der CPAN Config machen, wenn
 430 das nicht schon gemacht wurde.
 431
 432 "Patches Welcome" - Patches sind immer willkommen beim Autor oder den anderen
 433 Mitwirkenden.
 434
 435 Auf Win32 Systemen werden die Umgebungsvariablen nicht direkt in die Registrierung
 436 geschrieben damit sie auch nach dem Neustarten erhalten bleiben.
 437
 438 =head1 FEHLERANALYSE
 439
 440 Wenn du local::lib konfiguriert hast CPAN Module in deinem Home Verzeichnis
 441 zu installieren, und du danach versuchst mit C<cpan -i Foo::Bar> ein Modul
 442 zu installieren, und dabei einen Fehler bekommst, wie: C<Warning: You do not
 443 have permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
 444 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> und in der installationsausgabe steht
 445 irgendwo ein Fehler der sagt C<'INSTALL_BASE' is not a known MakeMaker parameter
 446 name>, dann hast du aus irgendeinem Grund dein neue Version von ExtUtils::MakeMaker
 447 verloren.
 448
 449 Um dies zu korrigieren, einfach nochmal die bootstrapping Methode laufen lassen,
 450 wie oben beschrieben.
 451
 452 Dann starte C<rm -r ~/.cpan/build/Foo-Bar*>
 453
 454 Abschliessend dann nochmal mit C<cpan -i Foo::Bar> installieren und die Probleme
 455 sollten verschwunden sein.
 456
 457 =head1 UMGEBUNGSVARIABLEN
 458
 459 =over 4
 460
 461 =item SHELL
 462
 463 =item COMSPEC
 464
 465 local::lib schaut in die C<SHELL> Umgebungsvariable um die korrekten Kommandos
 466 zu der Shell Konfiguration hinzuzufügen.
 467
 468 Auf Win32 Systemen, C<COMSPEC> wird auch analysiert.
 469
 470 =back
 471
 472 =head1 SUPPORT
 473
 474 IRC:
 475
 476     Wir sind im Channel #local-lib auf dem Server irc.perl.org.
 477
 478 =head1 AUTOR DER ÜBERSETZUNG
 479
 480 Torsten Raudssus <torsten@raudssus.de> http://www.raudssus.de/
 481
 482 =head1 URHEBERRECHT
 483
 484 Copyright (c) 2007 - 2010 von den local::lib L<local::lib/"AUTHOR">
 485 und L<local::lib/"CONTRIBUTORS"> aufgelistet in L<local::lib|local::lib>.
 486
 487 =head1 LIZENZ
 488
 489 Diese Sammlung ist freie Software und kann unter der selben Lizenz verbreitet
 490 werden wie Perl selber.
 491
 492 =cut
 493
 494 1;