Provided by: liblocal-lib-perl_2.000029-1_all bug

NAME

       local::lib~[de] - Erschaffen und benutzen von Perl Modulen in einem lokalen lib/
       Verzeichnis mit PERL5LIB

SYNOPSIS

       Im Code -

         use local::lib; # Benutzt das Verzeichnis ~/perl5 zum anlegen des lokalen lib/ Verzeichnisses

         use local::lib '~/foo'; # das selbe, aber mit ~/foo

         # Oder...
         use FindBin;
         use local::lib "$FindBin::Bin/../support";  # Applikationsspezifische Sammlung von Modulen

       Von der Shell -

         # Installiert LWP und alle notwendigen Abhängigkeiten in das '~/perl5' Verzeichnis
         perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'

         # Gibt die Shell Kommandos aus um die Umgebung vorzubereiten
         $ perl -Mlocal::lib
         export PERL_MB_OPT='--install_base /home/username/perl5'
         export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
         export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
         export PATH="/home/username/perl5/bin:$PATH"

   Die Bootstrapping Methode
       Ein typischer Weg um local::lib zu benutzen ist die sogenannte "Bootstrapping" Methode.
       Diese Methode wird benutzt wenn noch kein local::lib auf dem System installiert ist. In
       diesem Fall kannst du einfach local::lib direkt in deinem Home-Verzeichnis installieren.

       Selbst wenn du administrative Rechte hast, ist es wichtig das die Umgebungsvariablen von
       Schritt 4 in deinem Shell Startup Skript gesetzt werden. Ohne diesen Schritt werden die
       Module von CPAN weiterhin im System installiert und auch Perl Skripte die du startest
       würden das von local::lib erstellte lib/ Verzeichnis nicht nutzen.

       Standardmäßig installiert sich local::lib in ~/perl5.

       Windows Benutzern müssen ausserdem dies hier lesen: "Unterschiede bei Benutzung dieses
       Module mit Win32".

       1. Lade das Tar-Archiv von CPAN runter (Suche nach "Download" auf der CPAN Seite von
       local::lib) und entpacke es in einem beliebigem Verzeichnis. Um das obige Problem zu
       vermeiden, sollte man dies als normaler User tun und nicht als root oder Administrator.

       2. Starte in dem entstandenen Verzeichnis folgenden Befehl:

         perl Makefile.PL --bootstrap

       Wenn das System dir vorschlägt gewisse Dinge eigenständig zu konfigurieren ist es in fast
       allen Fällen vollkommen in Ordnung einfach "yes" zu antworten.

       Falls du local::lib nicht in das Standard Verzeichnis installieren willst, musst du dieses
       Verzeichnis als Parameter angeben:

         perl Makefile.PL --bootstrap=~/foo

       3. Danach folgenden Befehl starten: (local::lib erwartet make auf dem System)

         make test && make install

       4. Nun müssen wir die benötigten Umgebungsvariablen, damit Perl unser neu generiertes lib/
       Verzeichnis benutzt. Wenn du bash oder eine andere Bourne Shell benutzt, kannst du es über
       diesen Weg zu deinem Shell Startup Skript hinzufügen:

         echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc

       Wenn du C Shell benutzt, du kannst das gleiche hiermit erreichen:

         /bin/csh
         echo $SHELL
         /bin/csh
         perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc

       Wenn du beim bootstrappen ein anderes Verzeichnis benutzt als das Standardverzeichnis,
       dann musst du dieses Verzeichnis als Parameter beim Laden des Modules local::lib angeben:

         echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc

       Nachdem diese Änderungen in deinem Shell Startup Skript gemacht wurden, ist es nun wichtig
       das diese Umgebungsvariablen auch gesetzt sind in deiner aktuellen Umgebung. In Bourne
       Shells macht man dies z.B. mit ". ~/.bashrc", und in C Shell würde man es mit: "source
       ~/.cshrc" mit.

       Wenn du eine sehr langsames System hast, oder du unter drakonischen Regulierungen des
       Plattenplatz leben musst, kann man die automatische Generierung der manpages vom POD bei
       der Installation des Moduls deaktivieren beim bootstrapping mit dem "--no-manpages"
       Parameter:

         perl Makefile.PL --bootstrap --no-manpages

       Um zu vermeiden das man mehrere bootstraps macht um z.B. für verschiedene Applikationen
       eigene local::lib Installationen zu nutzen, kann man eine dieser Umgebungen benutzen um
       einfach in beliebigen anderen Verzeichnis Module zu installieren und somit weitere
       eigenständige lib/ Umgebungen zu bekommen:

         cd ~/mydir1
         perl -Mlocal::lib=./
         eval $(perl -Mlocal::lib=./)  ### Um die Umgebungsvariablen für die
                                       ### aktuelle Shell zusetzen

         printenv                      ### Hier kannst du sehen das ~/mydir1
                                       ### in der PERL5LIB Umgebungsvariable
                                       ### steht

         perl -MCPAN -e install ... ### welche Module auch immer ...
         cd ../mydir2

         ... WIEDERHOLEN ...

       Für mehrere Umgebungen in dieser Form brauch man eine Modifikation in der Benutzung von
       "use FindBin" in dem "Im Code" Beispiel oben. Wenn du sowas machst, und du hast damit z.B.
       Perl Module nach "~/mydir1/lib" installiert und du hast ein Script in
       "~/mydir1/scripts/myscript.pl", du musst dort angeben das die Module die es braucht im
       Verzeichnis "~/mydir1/lib" liegen.

       In "~/mydir1/scripts/myscript.pl" steht dann:

         use strict;
         use warnings;
         use local::lib "$FindBin::Bin/..";  ### zeigt auf ~/mydir1 und local::lib
                                             ### findet dort lib
         use lib "$FindBin::Bin/../lib";     ### zeigt auf ~/mydir1/lib

       Setze das vor jeden BEGIN { ... } Block der die Module braucht die du installiert hast.

   Unterschiede bei Benutzung dieses Module mit Win32
       Um die nötigen Umgebungsvariablen für diese Variablen in der derzeitigen Sitzung mit
       "CMD.EXE" zu setzen, kann man folgendes kommando nutzen:

         C:\>perl -Mlocal::lib
         set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
         set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
         set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
         set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%

         ### Um die Umgebungsvariablen für diese Shell alleine zu setzen
         C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
         ### anstelle von $(perl -Mlocal::lib=./) in bash.

       Wenn du willst das die Umgebungsvariablen dauerhaft gesetzt sind, musst du diese in
       Systemsteuerung / System dauerhaft selber eintragen oder App::local::lib::Win32Helper
       benutzen.

       Die "~" wird übersetzt zu dem Benutzer Profil Verzeichnis (das Verzeichnis was beim User
       als "Dokumente und Einstellungen" bekannt ist unter Windows XP und vorher oder das
       "Benutzer" Verzeichnis bei Windows Vista und später), solange $ENV{HOME} nicht gesetzt
       ist. Das Verzeichnis wird hierbei zu dem korrekten Kurznamen umgewandelt, und muss daher
       definitiv existieren, und wird um die nötigen Unterverzeichnise erweitert.

GRUNDPRINZIP

       Die Version von den Perl Paketen die man benötigt für spezifische Aufgaben sind sehr
       häufig nicht die richtigen oder korrekten Versionen auf dem System vorinstalliert. Ein
       Updaten von diesen Modulen ist in vielen Fällen einfach nicht möglich weil die nötigen
       Rechte fehlen. Ausserdem ist es generell nicht gut eigenständig die Versionen der Module
       auf dem System auszutauschen, weil natürlich der Rest des Systems genau die Version
       erwartet die von der Systemverwaltung auch installiert wurde.

       local::lib löst dieses Problem, es erlaubt dir dein komplett eigenes Verzeichnis für deine
       CPAN Module zu haben und bist so nicht genötigt die Module vom System zu nutzen oder
       andersrum andere User nicht mit individuellen Modulwünschen zu Überarbeitung ihres Codes
       zu zwingen, weil bestimmte Module zentral für alle auf neuere Version upgedatet werden.
       Die Installation findet hierbei dann z.B. im Home Verzeichnis statt. Es werden nur
       Umgebungsvariablen gesetzt die das installierte Perl dazu bewegen die im Homeverzeichnis
       installierten Module zu benutzen, zusätzlich und vorgezogen zu denen auf dem System.

       Daher muss man sich wenn man ein Paket System benutzt, wie z.b. Debian, garnicht mehr
       Sorgen machen, irgendwas auf dem System zu verletzten nur durch die Installation von Perl
       Modulen.

BESCHREIBUNG

       Dieses Modul bietet eine schnelle und legitime Art und Weise ein sogenanntes bootstrapping
       zu machen um in einem User Homeverzeichnis eine Sammlung von Modulen zu installieren. Es
       erstellt auch die nötigen Umgebungsvariablen die benötigt werden um diese Module zu
       nutzen, passend zu der Shell die der User in der Umgebungsvariable "SHELL" angegeben hat,
       um dann direkt passend in die entsprechenden Konfigurationsdateien der Shell einfügt zu
       werden.

       Weitergehend ist local::lib in der Lage Module zu nutzen die nicht im standardmäßigen @INC
       Pfad von Perl enthalten sind. Das macht es einfacher für bestimmte Applikationen ein
       bestimmtes Set von Modulen zu installieren ohne die anderen Module auf dem System in
       irgendeiner Art anzufassen. Damit es z.B. auch sicherer Module zu installieren die vom
       Maintainer noch nicht als Release verfügbar sind.

       Beim Import setzt local::lib die folgenden Umgebungsvariablen zu den nötigen Werten:

       PERL_MB_OPT
       PERL_MM_OPT
       PERL5LIB
       PATH
           Am PATH wird natürlich angehangen, und nicht ersetzt.

       Diese Werte sind dann verfügbar für jeden Code der danach importiert wurde.

ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN

       Mit lib::core::only besteht eine Möglichkeit dieses zutun, aber beachte das hier eine
       Menge von Fallstricken und Problemen existieren, und man sollte immer darauf achten das
       man auf einem Perl aufbaut was sowenig wie möglich verändert wurde (d.h. site und vendor
       Verzeichnis so leer wie möglich).

METHODEN

   ensure_dir_structure_for
       Parameter: $path
       Rückgabewert: Keiner

       Versucht den angegebenen Pfad anzulegen, mit allen nötigen drüberliegenden Verzeichnissen.
       Im Fehlerfall wird eine Exception geworfen.

   print_environment_vars_for
       Parameter: $pfad
       Rückgabewert: Keiner

       Gibt die Umgebungsvariablen aus, die benötigt werden um den angegebenen Pfad als Basis
       Verzeichnis zu nutzen.

   build_environment_vars_for
       Parameter: $pfad, $interpolate
       Rückgabewert: \%umgebungs_variablen

       Gibt ein Hash zurück mit den Variablen die nötig sind in den Umgebungsvariablen um eine
       Installation in dem gegebenen Pfad zu benutzen.

   setup_env_hash_for
       Parameter: $pfad
       Rückgabewert: Keiner

       Setzt die %ENV Einträge basierend auf dem Aufruf von "build_environment_vars_for".

   install_base_perl_path
       Parameter: $pfad
       Rückgabewert: $module_installations_pfad

       Gibt den Pfad zurück der benutzt wird um Perl Module zu installieren bei dem gegebenen
       Pfad als Basis. Prinzipiell wird nur "lib" und "perl5" als Pfadelemente angehangen.

   install_base_arch_path
       Parameter: $pfad
       Rückgabewert: $architektur_module_installations_pfad

       Gibt den Pfad zurück der benutzt wird um die Architektur-abhängigen Perl Module zu
       installieren basirend auf dem angegebenen Pfad als Basis. Basierend auf dem was
       "install_base_perl_path" zurückgibt, and appends the value of $Config{archname}.asis.

   install_base_bin_path
       Parameter: $pfad
       Rückgabewert: $ausfuehrbare_programme_installations_pfad

       Gibt den Pfad zurück, wo ausführbare Programme installiert werden, basierend auf der Basis
       des angegebenen Pfad. Basierend auf "install_base_perl_path" Rückgabewert, hängt diese
       Methode noch "bin" an.

   resolve_empty_path
       Parameter: $pfad
       Rückgabewert: $basis_pfad

       Erstellt und gibt zurück den Pfad der benutzt wird als Basis zur Installation der Module.
       Standardmäßig dies ist "~/perl5".

   resolve_home_path( $path )
       Parameter: $pfad
       Rückgabewert: $home

       Versucht das Home Verzeichnis vom aktullen User zu finden. Es wird eine Exception
       geworfen, wenn kein Home Verzeichnis ermittelt werden konnte.

   resolve_relative_path
       Parameter: $pfad
       Rückgabewert: $absoluter_pfad

       Macht aus dem angegebenen Pfad einen absoluten Pfad.

   resolve_path
       Parameter: $pfad
       Rückgabewert: $absoluter_pfad

       Hierbei wird der Pfad durch die folgende Methoden gegeben, wobei der Rückgabewert der
       ersten an die nächste weitergeben wird, um die Umgebung zu konfigurieren für die lokale
       Bibliotheks Installation: "resolve_empty_path", "resolve_home_path",
       "resolve_relative_path". Der daraus resultierende Pfad wird zu "resolve_empty_path"
       übergeben, dessen Resultat dann weitergegeben wird an "resolve_home_path", wessen Resultat
       dann weitergegeben wird an "resolve_relative_path". Dieses Resultat wird dann final an
       "resolve_path" übergeben, welches dann den Rückgabewert stellt.

EINE WARNUNG VOR UNINST=1

       Wenn man local::lib in Kombination mit "make install UNINST=1" benutzt, muss man
       vorsichtig sein über die Tatsache das der Prozess über die Neuinstallation eine nicht
       ausreichende Sicherheit hat bezüglich wo er nun installieren muss. Hierdurch mann es
       passieren das beim deinstallieren eines Modul u.U. das globale Modul deinstalliert wird
       (wenn die Rechte vorhanden sind) aber die neue Version nur in der lokalen Version
       installiert ist. Es ist hier also sehr wichtig das man "make install UNINST=1" und
       local::lib nur gleichzeitig benutzt wenn man sehr sicher darüber ist welche Konsequenzen
       einem entgegenkommen.

EINSCHRÄNKUNGEN

       Die Werkzeuge von perl, die benutzt werden um die Pakete zu installieren (die sogenannte
       toolchain), sind leider nicht in der Lage sauber mit Verzeichnissen umzugehen die
       Leerzeichen enthalten und können daher local::lib nicht direkt in ein solches Verzeichnis
       installieren. Was du machen kannst ist nach der Installation von local::lib und der Module
       die du in deiner local::lib haben willst, das gesamte Verzeichnis dahin zu bewegen.
       local::lib kann mit dem Verzeichnis mit Leerzeichen umgehen. Bitte aufpassen das natürlich
       eine weitere Installation oder ein Erneuern von Paketen mit dem CPAN Programm nicht mehr
       möglich ist.

       Die Shell Erkennung ist sehr primitiv. Derzeit ist es so das alles was "csh" im Namen hat
       auch als C Shell eingeordnet wird, und alles andere wird als Bourne Shell betrachet,
       ausser auf Win32 Systemen. Wenn die "SHELL" Variable nicht gesetzt ist, eine Bourne Shell
       wird angenommen.

       Bootstrap ist leider ein Hack, und wird auf jedenfall CPAN.pm benutzen für
       ExtUtils::MakeMaker, auch wenn CPANPLUS installiert ist.

       Es setzt definitiv PERL5LIB, PERL_MM_OPT und PERL_MB_OPT neu und vernichtet jeden Wert der
       vorher gesetzt war.

       Es sollte vielleicht eine automatische Korrektur der CPAN Config machen, wenn das nicht
       schon gemacht wurde.

       "Patches Welcome" - Patches sind immer willkommen beim Autor oder den anderen
       Mitwirkenden.

       Auf Win32 Systemen werden die Umgebungsvariablen nicht direkt in die Registrierung
       geschrieben damit sie auch nach dem Neustarten erhalten bleiben.

FEHLERANALYSE

       Wenn du local::lib konfiguriert hast CPAN Module in deinem Home Verzeichnis zu
       installieren, und du danach versuchst mit "cpan -i Foo::Bar" ein Modul zu installieren,
       und dabei einen Fehler bekommst, wie: "Warning: You do not have permissions to install
       into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at /usr/lib64/perl5/5.8.8/Foo/Bar.pm"
       und in der installationsausgabe steht irgendwo ein Fehler der sagt "'INSTALL_BASE' is not
       a known MakeMaker parameter name", dann hast du aus irgendeinem Grund dein neue Version
       von ExtUtils::MakeMaker verloren.

       Um dies zu korrigieren, einfach nochmal die bootstrapping Methode laufen lassen, wie oben
       beschrieben.

       Dann starte "rm -r ~/.cpan/build/Foo-Bar*"

       Abschliessend dann nochmal mit "cpan -i Foo::Bar" installieren und die Probleme sollten
       verschwunden sein.

UMGEBUNGSVARIABLEN

       SHELL
       COMSPEC
           local::lib schaut in die "SHELL" Umgebungsvariable um die korrekten Kommandos zu der
           Shell Konfiguration hinzuzufügen.

           Auf Win32 Systemen, "COMSPEC" wird auch analysiert.

SUPPORT

       IRC:

           Wir sind im Channel #local-lib auf dem Server irc.perl.org.

AUTOR DER ÜBERSETZUNG

       Torsten Raudssus <torsten@raudssus.de> http://www.raudssus.de/

URHEBERRECHT

       Copyright (c) 2007 - 2010 von den local::lib "AUTHOR" in local::lib und "CONTRIBUTORS" in
       local::lib aufgelistet in local::lib.

LIZENZ

       Diese Sammlung ist freie Software und kann unter der selben Lizenz verbreitet werden wie
       Perl selber.