local-lib-2.000018/000755 000765 000024 00000000000 12614451500 014061 5ustar00gknopstaff000000 000000 local-lib-2.000018/Changes000644 000765 000024 00000033445 12614451416 015373 0ustar00gknopstaff000000 000000 Revision history for local::lib 2.000018 - 2015-10-29 - repair CPAN.pm bootstrapping broken by extraneous prerequisite. - ensure directories are created in correct order to avoid errors 2.000017 - 2015-10-06 - fix shell quoting for fish shell - work around issue where some cpanm versions wouldn't upgrade ExtUtils::MakeMaker in some cases it should have - added --quiet option to surpress directory creation message - build_environment_vars_for, build_activate_environment_vars_for, and environment_vars_string_for options will always include directories being added, even if they were already in current ENV vars - fixes for author tests - create directory structure under created local::libs, ensuring arch dirs will always be added to @INC by perl - only cause CPAN.pm to prefer ExtUtils::MakeMaker over Module::Build during bootstrap process, not after - bootstrap process refactored 2.000015 - 2014-12-12 - Avoid using += in Makefile when bootstrapping for portability (RT#100797) - adjust quoting of paths with spaces to work with ExtUtils::MakeMaker 7.0, and bump our EUMM prereq to 7.0. - fix shell test for shells where we can't prevent some rc files from being loaded, like zsh (RT#99819). 2.000014 - 2014-09-04 - fix taint-mode test in some cases on case insensitive filesystems 2.000013 - 2014-08-16 - fix test failure in ActiveState perl - better test diagnostics - fix quoting of spaces for fish shell (rt#95268) - improve quoting for use with cmd.exe - fix quoting any arbitrary character when contructing strings for bash - skip testing use with shells if the shell doesn't work at all 2.000012 - 2014-05-12 - restore build_activate_environment_vars_for, build_deactivate_environment_vars_for, build_deact_all_environment_vars_for methods for perlbrew compatibility - fix transforming relative paths to absolute paths in older perls - fix quoting for fish shell 2.000011 - 2014-04-02 - more fixes for issue where PERL5LIB Carp is not the same version as in the local-lib 2.000010 - 2014-03-28 - fix shell test on cygwin 2.000_009 - 2014-03-15 - no longer loads File::Spec, so an upgraded version installed inside a local lib dir can be used by scripts 2.000008 - 2014-03-13 - fix --bootstrap option without a path specified 2.000007 - 2014-03-11 - even more relaxed shell output testing - only test shells in /etc/shells - fix Makefile.PL on solaris 2.000006 - 2014-03-07 - fix bootstrapping not auto-configuring in some cases - more relaxed shell output testing - use normal arguments to be used on the command line in addition to import arguments - support fish shell - stop trying to test csh/sh on Win32 - work around CPAN.pm issues with checking prerequisites 2.000004 - 2014-01-03 - fix errors in PowerShell output when clearing nonexistant variables - fix shell test to avoid extremely long lines - fix shell test to avoid testing standard Win32 shells on Cygwin - improved diagnostics in shell test 2.000003 - 2013-12-30 - releasing 2.000_002 as stable 2.000_002 - 2013-12-25 - fix CPAN setup error check in Makefile.PL - fix install test warnings - fix shell test to skip cmd/powershell startup scripts 2.000_001 - 2013-12-23 - fix shell output for old bourne shells - fix various shell test issues - note issues/workarounds when combining with PREFIX/--prefix options 2.000_000 - 2013-12-22 - significant refactor of internals, adding an object oriented interface - add --no-create option to prevent directory creation on activation - add support for powershell output - add --shelltype option to specify shell instead of auto detecting - document recommended use of $SHLVL - document limitations regarding File::Spec - avoid including empty path segments in output - fix output for csh to allow direct use in eval - improve taint handling test - fix docs for build_environment_vars, install_base_bin_path - use Distar instead of Module::Install for packaging 1.008026 - 2013-11-05 - drop perl prerequisite to 5.6, since everything works there. 1.008025 - 2013-11-01 (development release, unindexed) - fix install test on cygwin - fix stackable test on win32 and when external local::lib is set - clarify errors in Makefile.PL about CPAN configuration - adjust csh output to allow use directly by eval - silence a possible warning in Makefile.PL - add additional docs about combining local::lib with lib::core::only - reverse order of PERL_LOCAL_LIB_ROOT. new local::libs are now added to the beginning instead of the end, to match the order of other similar environment variables. 1.008024 - 2013-10-28 (development release, unindexed) - fix installation into directories with spaces or backslashes, as well as Win32 test failures when Capture::Tiny is installed - fix test breaking in some cases when an external local::lib is set - fix test compatibility with old versions of Exporter 1.008023 - 2013-10-19 - stable release of 1.008022 (no code changes since 1.008012) 1.008022 - 2013-10-07 (development release, unindexed) - see 1.008019 through 1.008021 1.008021 - 2013-10-04 (development release, unindexed) - yet another attempt to overcome win32 testing issues (paths with spaces, backslashes) 1.008020 - 2013-10-03 (development release, unindexed) - yet another attempt to overcome win32 testing issues (paths with spaces, backslashes) 1.008019 - 2013-09-29 (development release, unindexed) - another attempt to overcome win32 testing issues (paths with spaces, backslashes) 1.008018 - 2013-09-15 - print out actual paths in more test cases, for helping to diagnose mysterious failures 1.008017 - 2013-09-14 - avoid "Unrecognized escape \s passed through" errors on win32 (again) 1.008016 - 2013-09-13 - avoid "Unrecognized escape \s passed through" errors on win32 1.008015 - 2013-09-12 - re-release 1.008014 to fix broken MANIFEST 1.008014 - 2013-09-12 - fix new test to use alternate path representations on windows, to handle potential space issues (regression since 1.008012) 1.008013 - 2013-09-11 - fix undef value errors when not installing into a local::lib 1.008012 - 2013-09-11 - now handling using -Mlocal::lib in a taintperl environment, by ensuring that all libs in PERL_LOCAL_LIB_ROOT are properly added to @INC (RT#76661, Karen Etheridge) 1.008011 - 2013-07-26 - skip CPAN workaround if running via cpanminus (miyagawa, RT#85731) 1.008010 - 2013-05-26 - Fix a split on undefined value warning (David Golden -- see https://github.com/gugod/App-perlbrew/issues/305) 1.008009 - 2013-02-24 - Remove Carp::Always dep 1.008008 - 2013-02-24 - Fix putting arch path in PERL5LIB - Refactor Win32 path handling out of ensure_dir_structure_for() - Fix active_paths when PERL_LOCAL_LIB_ROOT starts with : - Fix ~/perl5/bin missing in $PATH - The environment variables definition for the shell is now output in a way that allows to put the generated content directly in the .profile without requiring to launch perl (the only difference is how PERL_LOCAL_LIB_ROOT is generated) (Olivier Mengué). 1.008007 - 2013-02-17 - Back to 1.008004 with Carp fix since subsequent releases were botched - Avoid issue where PERL5LIB Carp is older than local::lib one 1.008004 - 2011-02-24 - Fix stackable tests on win32 by canonicalizing the path ahead of time 1.008003 - 2011-02-23 - Fix tests with stacking l::ls. 1.008002 - 2011-02-23 - Add local::lib stacking support. - Add activation/deactivation support. 1.008001 - 2011-01-09 - Bootstrap Module::Build just like ExtUtils::MakeMaker 1.008000 - 2011-01-05 - Remove redundant prereqs now that Module::Build 0.36 is required - Makefile.PL avoids CPAN client configuration when not required - print_environment_vars_for() refactored with separate function environment_vars_string_for() - PERL_LOCAL_LIB_ROOT environment is added to disambiguate when PERL_MM_OPT, etc. was set by local::lib or other means 1.007000 - 2010-12-09 - Chase the Module::Build version which supports PERL_MB_OPT. Thanks to miyagawa for pointing this out. 1.006009 - 2010-12-09 - Split up method guess_shelltype from parts of print_environment_vars_for - Updated documentation about change of use with .modulebuildrc 1.006008 - 2010-11-17 - Finally move to PERL_MB_OPT rather than using .modulebuildrc. 1.006007 - 2010-08-12 - Fixing stuff so that search.cpan.org displays right - Documented one method in all languages 1.006006 - 2010-08-12 - Added portuguese translation - Several minor fixes in the documentation - Changed methods look in documentation 1.006005 - 2010-07-13 - Added support informations (also for german) - Fixed newline in german translation from DOS2UNIX 1.006004 - 2010-06-10 - I am stupid. 1.006003 - 2010-06-10 - Added german translation right 1.006002 - 2010-06-10 - Hotfix for a search.cpan.org "Bug" 1.006001 - 2010-06-10 - Added german translation - Enhanced some parts of english documentation - doc patch for win32 from run4flat - reverse the perl/arch paths in PERL5LIB 1.006000 - 2010-03-31 - Create lib::core::only that provides the "set @INC to core dirs only" functionality that was the only part of --self-contained that ever worked usefully. - Delete broken --self-contained flag from core 1.005001 - 2010-03-10 - I am an idiot. 1.005000 - 2010-03-10 - More robust handling of running new toolchains on older perls. This should sort out issues users have with bootstrapping on e.g. Solaris and other traditional Unices. In addition, try to find a GNU tar capable of dealing with @LongLink so bootstrapping doesn't fail. - Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced by a patch from Marco Emilio Poleggi. - Start of better docs for C<--self-contained> thanks to markstos@cpan.org. 1.004009 - 2009-11-07 - Fix warning if your $ENV{PERL5LIB} is undef - Doc improvement from kgish/#perl-help@irc.perl.org - t0m and chrisa on #local-lib@irc.perl.org pointed out a PERL5LIB ordering issue with C<--self-contained>. 1.004008 - 2009-10-13 - Clarify re-reading the shell config file after writing to it. - Clarify copyright and licensing for packaging by vendors. 1.004007 - 2009-09-02 - Ensure that $ENV{PERL5LIB} and @INC are always de-duped, stopping them from growing if local::lib is invoked multiple times for the same path. (t0m) - Doc improvements by kurisuto@irc.perl.org/#catalyst. - Cleaned up indentation of code lines in the POD. Everything should be nice and flush, now. 1.004006 - 2009-08-25 - Fix parsing of --self-contained and local lib directory. It's now possible to specify flags and the directory in any order. Also made adding future flags easier in the future. Thanks to frew@irc.perl.org/#catalyst for pointing out that --self-contained wouldn't work without a directory. 1.004005 - 2009-08-23 - Add the --no-manpages option to bootstraping to tell EUMM / MB to not generate manpages from POD. Thanks to RKITOVER for providing the necessary values for CPAN.pm's configuration. 1.004004 - 2009-08-05 - Add dependency on Extutils::Install 1.43 and install in --bootstrap otherwise we fail to build with latest MakeMaker on OpenSolaris (t0m) - Fix Win32 / Cygwin detection (emazep). 1.004003 - 2009-16-16 - Stop Makefile.PL exploding if your CPAN is too old to have CPAN::HandleConfig. Needed when installing local::lib via CPAN using an old CPAN version (t0m) - Fix warning from Makefile.PL about ExtUtils::MakeMaker::prompt (t0m) - Set PERL5LIB back to calculated @INC with --self-contained, to stop invoking other perl scripts from losing the local::lib if they mangle @INC from $ENV{PERL5LIB}, and fix install of 'difficult' modules with such as Test::Deep (t0m) 1.004002 - 2009-06-15 - Fixed up INC untaint procedure to skip/ignore CODE, ARRAY, blessed entries. (grink) - Include test in xt/ for the above - Put PERL5LIB first, so it'll be favored over privlibexp and archlibexp when self contained. - Automatically untaint @INC (t0m) - Prevent @INC from growing when you have multiple scripts using --self-contained called from inside one another. (grink by way of t0m) - eg/scripted_install.pl now no longer requires TARGET, but still respects it. (confound) 1.004001 - 2009-05-21 - Clean up CPAN.pm's environment variable the same way we do for CPANPLUS. Add an example program showing local::lib employed programmatically (confound). - Add the beginnings of a troubleshooting section (pattern). 1.004000 - 2009-05-14 - Don't allow dangerous settings for CPAN.pm that affect where CPAN installs stuff, as this conflicts with what we're trying to do. - Make sure that our Makefile is written to the correct directory when bootstrapping (confound). 1.003004 - 2009-05-12 - Additional documentation and examples concerning having multiple local::lib enviornments (amiri) - Some install tests courtesy of Hans Dieter Pearcey . Thanks! 1.003003 - 2009-04-09 - Expose the internals per RT #36846. - Fix the MANIFEST up a bit. 1.003002 - 2009-02-25 - Add a doc patch from Torsten Raudssus that clarifies how to specify a directory other than ~/perl5. 1.003001 - 2009-01-14 - Properly bail if given fancy dashes obtained by copy-pasting from a UTF8-happy POD formatter. This will bail in both the Makefile.PL and in local::lib::import(). 1.003000 - 2009-01-13 - Add the --self-contained flag from Mark Stosberg, which also contains a doc patch warning about the dangers of UNINST=1. Thanks, Mark! 1.002000 - 2008-08-06 - make CPAN config reinit non-prompting but still robust - make bootstrap auto-init CPAN config and set USE_DEFAULT for deps 1.001000 - 2007-09-19 - refactored shell command generation - implemented C shell command generation based on this (checks $SHELL} - improved docs - modified Makefile.PL to install an up-to-date CPAN.pm if needed 1.000000 - 2007-09-13 - initial release local-lib-2.000018/eg/000755 000765 000024 00000000000 12614451477 014471 5ustar00gknopstaff000000 000000 local-lib-2.000018/inc/000755 000765 000024 00000000000 12614451477 014647 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/000755 000765 000024 00000000000 12614451477 014644 5ustar00gknopstaff000000 000000 local-lib-2.000018/LICENSE000644 000765 000024 00000043653 12531456676 015122 0ustar00gknopstaff000000 000000 This software is copyright (c) 2007 by Matt S Trout. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- The GNU General Public License, Version 1, February 1989 --- This software is Copyright (c) 2007 by Matt S Trout. This is free software, licensed under: The GNU General Public License, Version 1, February 1989 GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Suite 500, Boston, MA 02110-1335 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! --- The Artistic License 1.0 --- This software is Copyright (c) 2007 by Matt S Trout. This is free software, licensed under: The Artistic License 1.0 The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End local-lib-2.000018/maint/000755 000765 000024 00000000000 12614451477 015206 5ustar00gknopstaff000000 000000 local-lib-2.000018/Makefile.PL000644 000765 000024 00000015723 12614373757 016064 0ustar00gknopstaff000000 000000 use strict; use warnings FATAL => 'all'; my %META = ( name => 'local-lib', license => 'perl_5', prereqs => { configure => { requires => { } }, build => { requires => { } }, test => { requires => { 'Test::More' => 0, } }, runtime => { requires => { 'perl' => 5.006, 'ExtUtils::MakeMaker' => '7.00', # version INSTALL_BASE taken as string, not shell 'ExtUtils::Install' => '1.43', # version INSTALL_BASE was added 'Module::Build' => '0.36', # PERL_MB_OPT 'CPAN' => '1.82', # sudo support + CPAN::HandleConfig } }, develop => { requires => { 'Test::EOL' => 0, 'Test::NoTabs' => 0, 'Test::Pod' => 0, 'Capture::Tiny' => 0, 'Test::More' => 0.81_01, 'Test::MinimumVersion' => 0, 'Perl::MinimumVersion' => 1.35, }, recommends => { 'Test::CPAN::Changes' => 0, }, }, }, resources => { repository => { url => 'git://github.com/Perl-Toolchain-Gang/local-lib', web => 'https://github.com/Perl-Toolchain-Gang/local-lib', type => 'git', }, x_IRC => 'irc://irc.perl.org/#local-lib', bugtracker => { web => 'https://rt.cpan.org/Public/Dist/Display.html?Name=local-lib', mailto => 'bug-local-lib@rt.cpan.org', }, license => [ 'http://dev.perl.org/licenses/' ], }, ); my %MM_ARGS = (); ############################################################################## # Solaris (and possibly other Unices) have a tar in /usr/bin that, among # other things, does not understand @LongLink. This can cause # extraction to look like it succeeded, but it actually failed (because # the error message for the @LongLink failure scrolled offscreen). # Therefore, given the fact that GNU tar is the most widespread tar available, # and it actually supports the feature we want (I'd bet it originated in GNU # tar, but I digress), we'll look for GNU tar. If we don't find it, and the # user hasn't pointed us to a suitable tar, we'll bomb and tell them what to # do. # require File::Spec; unless (exists $ENV{PERL_LL_TAR} ? -x $ENV{PERL_LL_TAR} : $^O eq 'solaris' ? (grep -x, map File::Spec->catfile($_, 'gtar'), File::Spec->path) : 1) { die <<'DEATH'; You are using Solaris (or another traditional Unix) that does not provide a sane tar, capable of dealing with the output of GNU tar. Please either set the PERL_LL_TAR environment variable to the location of a version of tar that understands the @LongLink convention or put a binary named gtar somewhere on your PATH. DEATH } # watch out for fancy dashes. these can wind up in our @ARGV if the user is # copypasting the bootstrap command from the POD displayed e.g. by perldoc # on a Mac OS X terminal. since no software recognizes and handles these # dashes, it's better to die loudly telling the user exactly what happened # so they don't make the same mistake again rather than being the only # program in the universe that works with them. # the fancy dash is U+2212 or \xE2\x88\x92 if(grep { /\xE2\x88\x92/ || /\x{2212}/ } @ARGV) { die <<'DEATH'; WHOA THERE! It looks like you've got some fancy dashes in your commandline! These are *not* the traditional -- dashes that software recognizes. You probably got these by copy-pasting from the perldoc for this module as rendered by a UTF8-capable formatter. This most typically happens on an OS X terminal, but can happen elsewhere too. Please try again after replacing the dashes with normal minus signs. DEATH } my $bootstrapping; my $disable_manpages; if (my ($x) = grep { /^--bootstrap(?:=.*)?$/ } @ARGV) { @ARGV = grep { !/^--bootstrap(?:=.*)?$/ } @ARGV; my ($path) = $x =~ /^--bootstrap(?:=(.*))?$/; if(my ($x) = grep { /^--no-manpages$/ } @ARGV) { $disable_manpages = 1; @ARGV = grep { !/^--no-manpages/ } @ARGV; } { local @INC = @INC; unshift(@INC, 'lib'); require local::lib; } local::lib->import($path || ()); $bootstrapping = 1; } my $requires = $MM_ARGS{PREREQ_PM} = { %{$META{prereqs}{runtime}{requires}} }; if ($ENV{PERL5_CPANM_IS_RUNNING}) { $requires->{CPAN} = undef; } for my $module (grep { $_ ne 'perl' } keys %$requires) { my $need_v = $requires->{$module} or next; my $res = system($^X, '-Minc::CheckVersion', '-', $module, $need_v); $res >>= 8; if ($res == 0 || $res == 1) { $requires->{$module} = undef; } } if ($bootstrapping) { my @modules = grep $requires->{$_}, qw(ExtUtils::MakeMaker ExtUtils::Install Module::Build CPAN); { no warnings 'once'; package MY; *init_PERL = sub { my $self = shift; $self->SUPER::init_PERL(@_); $self->{PERL} .= ' -I$(INSTALLPRIVLIB)'; $self->{FULLPERL} .= ' -I$(INSTALLPRIVLIB)'; }; } local $ENV{PERL_AUTOINSTALL_PREFER_CPAN} = 1; local $ENV{PERL_MM_USE_DEFAULT} = 1; if (@modules || $disable_manpages) { system($^X, '-Minc::CPAN=init_config'); } if (@modules) { system($^X, '-Minc::CPAN=install', '-', $_) for @modules; } if (grep { $_ eq 'CPAN' } @modules ) { system($^X, '-MCPAN', '-e', 'CPAN::Config->load;CPAN::Config->commit;'); } if ($disable_manpages) { system($^X, '-Minc::CPAN=disable_manpages'); } } if (!$ENV{PERL5_CPANM_IS_RUNNING}) { my $status = system $^X, '-Minc::CPAN=check', '-', $META{prereqs}{runtime}{requires}{CPAN}; exit $status if $status; } ## BOILERPLATE ############################################################### require ExtUtils::MakeMaker; (do 'maint/Makefile.PL.include' or die $@) unless -f 'META.yml'; # have to do this since old EUMM dev releases miss the eval $VERSION line my $eumm_version = eval $ExtUtils::MakeMaker::VERSION; my $mymeta = $eumm_version >= 6.57_02; my $mymeta_broken = $mymeta && $eumm_version < 6.57_07; ($MM_ARGS{NAME} = $META{name}) =~ s/-/::/g; ($MM_ARGS{VERSION_FROM} = "lib/$MM_ARGS{NAME}.pm") =~ s{::}{/}g; $META{license} = [ $META{license} ] if $META{license} && !ref $META{license}; $MM_ARGS{LICENSE} = $META{license}[0] if $META{license} && $eumm_version >= 6.30; $MM_ARGS{NO_MYMETA} = 1 if $mymeta_broken; $MM_ARGS{META_ADD} = { 'meta-spec' => { version => 2 }, %META } unless -f 'META.yml'; for (qw(configure build test runtime)) { my $key = $_ eq 'runtime' ? 'PREREQ_PM' : uc $_.'_REQUIRES'; my $r = $MM_ARGS{$key} = { %{$META{prereqs}{$_}{requires} || {}}, %{delete $MM_ARGS{$key} || {}}, }; defined $r->{$_} or delete $r->{$_} for keys %$r; } $MM_ARGS{MIN_PERL_VERSION} = delete $MM_ARGS{PREREQ_PM}{perl} || 0; delete $MM_ARGS{MIN_PERL_VERSION} if $eumm_version < 6.47_01; $MM_ARGS{BUILD_REQUIRES} = {%{$MM_ARGS{BUILD_REQUIRES}}, %{delete $MM_ARGS{TEST_REQUIRES}}} if $eumm_version < 6.63_03; $MM_ARGS{PREREQ_PM} = {%{$MM_ARGS{PREREQ_PM}}, %{delete $MM_ARGS{BUILD_REQUIRES}}} if $eumm_version < 6.55_01; delete $MM_ARGS{CONFIGURE_REQUIRES} if $eumm_version < 6.51_03; ExtUtils::MakeMaker::WriteMakefile(%MM_ARGS); ## END BOILERPLATE ########################################################### local-lib-2.000018/MANIFEST000644 000765 000024 00000001466 12614451500 015221 0ustar00gknopstaff000000 000000 Changes eg/scripted_install.pl inc/CheckVersion.pm inc/CPAN.pm lib/lib/core/only.pm lib/local/lib.pm lib/POD2/DE/local/lib.pod lib/POD2/PT_BR/local/lib.pod LICENSE maint/Makefile.PL.include Makefile.PL MANIFEST This list of files t/bad_variables.t t/carp-mismatch.t t/classmethod.t t/coderefs_in_inc.t t/de-dup.t t/lib-core-only.t t/lib/ENVDumper.pm t/lib/TempDir.pm t/pipeline.t t/shell.t t/stackable.t t/subroutine-in-inc.t t/taint-mode.t xt/author/cpan-changes.t xt/author/eol.t xt/author/minimum-version.t xt/author/no-tabs.t xt/author/pod-syntax.t xt/bootstrap.t xt/install.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) README README file (added by Distar) local-lib-2.000018/META.json000644 000765 000024 00000003654 12614451500 015512 0ustar00gknopstaff000000 000000 { "abstract" : "create and use a local lib/ for perl modules with PERL5LIB", "author" : [ "mst - Matt S. Trout (cpan:MSTROUT) " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.1, CPAN::Meta::Converter version 2.150001", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "local-lib", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : {} }, "configure" : { "requires" : {} }, "develop" : { "recommends" : { "Test::CPAN::Changes" : "0" }, "requires" : { "Capture::Tiny" : "0", "Perl::MinimumVersion" : "1.35", "Test::EOL" : "0", "Test::MinimumVersion" : "0", "Test::More" : "0.8101", "Test::NoTabs" : "0", "Test::Pod" : "0" } }, "runtime" : { "requires" : { "CPAN" : "1.82", "ExtUtils::Install" : "1.43", "ExtUtils::MakeMaker" : "7.00", "Module::Build" : "0.36", "perl" : "5.006" } }, "test" : { "requires" : { "Test::More" : "0" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "mailto" : "bug-local-lib@rt.cpan.org", "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=local-lib" }, "license" : [ "http://dev.perl.org/licenses/" ], "repository" : { "type" : "git", "url" : "git://github.com/Perl-Toolchain-Gang/local-lib", "web" : "https://github.com/Perl-Toolchain-Gang/local-lib" }, "x_IRC" : "irc://irc.perl.org/#local-lib" }, "version" : "2.000018" } local-lib-2.000018/META.yml000644 000765 000024 00000001506 12614451500 015334 0ustar00gknopstaff000000 000000 --- abstract: 'create and use a local lib/ for perl modules with PERL5LIB' author: - 'mst - Matt S. Trout (cpan:MSTROUT) ' build_requires: Test::More: '0' configure_requires: {} dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.1, CPAN::Meta::Converter version 2.150001' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: local-lib no_index: directory: - t - inc requires: CPAN: '1.82' ExtUtils::Install: '1.43' ExtUtils::MakeMaker: '7.00' Module::Build: '0.36' perl: '5.006' resources: IRC: irc://irc.perl.org/#local-lib bugtracker: https://rt.cpan.org/Public/Dist/Display.html?Name=local-lib license: http://dev.perl.org/licenses/ repository: git://github.com/Perl-Toolchain-Gang/local-lib version: '2.000018' local-lib-2.000018/README000644 000765 000024 00000054440 12614451500 014750 0ustar00gknopstaff000000 000000 NAME local::lib - create and use a local lib/ for perl modules with PERL5LIB SYNOPSIS In code - use local::lib; # sets up a local lib at ~/perl5 use local::lib '~/foo'; # same, but ~/foo # Or... use FindBin; use local::lib "$FindBin::Bin/../support"; # app-local support library From the shell - # Install LWP and its missing dependencies to the '~/perl5' directory perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)' # Just print out useful shell commands $ perl -Mlocal::lib PERL_MB_OPT='--install_base /home/username/perl5'; export PERL_MB_OPT; PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'; export PERL_MM_OPT; PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB; PATH="/home/username/perl5/bin:$PATH"; export PATH; PERL_LOCAL_LIB_ROOT="/home/usename/perl5:$PERL_LOCAL_LIB_ROOT"; export PERL_LOCAL_LIB_ROOT; From a .bash_profile or .bashrc file - eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" The bootstrapping technique A typical way to install local::lib is using what is known as the "bootstrapping" technique. You would do this if your system administrator hasn't already installed local::lib. In this case, you'll need to install local::lib in your home directory. Even if you do have administrative privileges, you will still want to set up your environment variables, as discussed in step 4. Without this, you would still install the modules into the system CPAN installation and also your Perl scripts will not use the lib/ path you bootstrapped with local::lib. By default local::lib installs itself and the CPAN modules into ~/perl5. Windows users must also see "Differences when using this module under Win32". 1. Download and unpack the local::lib tarball from CPAN (search for "Download" on the CPAN page about local::lib). Do this as an ordinary user, not as root or administrator. Unpack the file in your home directory or in any other convenient location. 2. Run this: perl Makefile.PL --bootstrap If the system asks you whether it should automatically configure as much as possible, you would typically answer yes. In order to install local::lib into a directory other than the default, you need to specify the name of the directory when you call bootstrap, as follows: perl Makefile.PL --bootstrap=~/foo 3. Run this: (local::lib assumes you have make installed on your system) make test && make install 4. Now we need to setup the appropriate environment variables, so that Perl starts using our newly generated lib/ directory. If you are using bash or any other Bourne shells, you can add this to your shell startup script this way: echo 'eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc If you are using C shell, you can do this as follows: /bin/csh echo $SHELL /bin/csh echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc If you passed to bootstrap a directory other than default, you also need to give that as import parameter to the call of the local::lib module like this way: echo 'eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc After writing your shell configuration file, be sure to re-read it to get the changed settings into your current shell's environment. Bourne shells use ". ~/.bashrc" for this, whereas C shells use "source ~/.cshrc". If you're on a slower machine, or are operating under draconian disk space limitations, you can disable the automatic generation of manpages from POD when installing modules by using the "--no-manpages" argument when bootstrapping: perl Makefile.PL --bootstrap --no-manpages To avoid doing several bootstrap for several Perl module environments on the same account, for example if you use it for several different deployed applications independently, you can use one bootstrapped local::lib installation to install modules in different directories directly this way: cd ~/mydir1 perl -Mlocal::lib=./ eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone printenv ### You will see that ~/mydir1 is in the PERL5LIB perl -MCPAN -e install ... ### whatever modules you want cd ../mydir2 ... REPEAT ... If you use .bashrc to activate a local::lib automatically, the local::lib will be re-enabled in any sub-shells used, overriding adjustments you may have made in the parent shell. To avoid this, you can initialize the local::lib in .bash_profile rather than .bashrc, or protect the local::lib invocation with a $SHLVL check: [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" If you are working with several "local::lib" environments, you may want to remove some of them from the current environment without disturbing the others. You can deactivate one environment like this (using bourne sh): eval $(perl -Mlocal::lib=--deactivate,~/path) which will generate and run the commands needed to remove "~/path" from your various search paths. Whichever environment was activated most recently will remain the target for module installations. That is, if you activate "~/path_A" and then you activate "~/path_B", new modules you install will go in "~/path_B". If you deactivate "~/path_B" then modules will be installed into "~/pathA" -- but if you deactivate "~/path_A" then they will still be installed in "~/pathB" because pathB was activated later. You can also ask "local::lib" to clean itself completely out of the current shell's environment with the "--deactivate-all" option. For multiple environments for multiple apps you may need to include a modified version of the "use FindBin" instructions in the "In code" sample above. If you did something like the above, you have a set of Perl modules at "~/mydir1/lib". If you have a script at "~/mydir1/scripts/myscript.pl", you need to tell it where to find the modules you installed for it at "~/mydir1/lib". In "~/mydir1/scripts/myscript.pl": use strict; use warnings; use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib Put this before any BEGIN { ... } blocks that require the modules you installed. Differences when using this module under Win32 To set up the proper environment variables for your current session of "CMD.exe", you can use this: 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 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH% ### To set the environment for this shell alone C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat ### instead of $(perl -Mlocal::lib=./) If you want the environment entries to persist, you'll need to add them to the Control Panel's System applet yourself or use App::local::lib::Win32Helper. The "~" is translated to the user's profile directory (the directory named for the user under "Documents and Settings" (Windows XP or earlier) or "Users" (Windows Vista or later)) unless $ENV{HOME} exists. After that, the home directory is translated to a short name (which means the directory must exist) and the subdirectories are created. PowerShell local::lib also supports PowerShell, and can be used with the "Invoke-Expression" cmdlet. Invoke-Expression "$(perl -Mlocal::lib)" RATIONALE The version of a Perl package on your machine is not always the version you need. Obviously, the best thing to do would be to update to the version you need. However, you might be in a situation where you're prevented from doing this. Perhaps you don't have system administrator privileges; or perhaps you are using a package management system such as Debian, and nobody has yet gotten around to packaging up the version you need. local::lib solves this problem by allowing you to create your own directory of Perl packages downloaded from CPAN (in a multi-user system, this would typically be within your own home directory). The existing system Perl installation is not affected; you simply invoke Perl with special options so that Perl uses the packages in your own local package directory rather than the system packages. local::lib arranges things so that your locally installed version of the Perl packages takes precedence over the system installation. If you are using a package management system (such as Debian), you don't need to worry about Debian and CPAN stepping on each other's toes. Your local version of the packages will be written to an entirely separate directory from those installed by Debian. DESCRIPTION This module provides a quick, convenient way of bootstrapping a user-local Perl module library located within the user's home directory. It also constructs and prints out for the user the list of environment variables using the syntax appropriate for the user's current shell (as specified by the "SHELL" environment variable), suitable for directly adding to one's shell configuration file. More generally, local::lib allows for the bootstrapping and usage of a directory containing Perl modules outside of Perl's @INC. This makes it easier to ship an application with an app-specific copy of a Perl module, or collection of modules. Useful in cases like when an upstream maintainer hasn't applied a patch to a module of theirs that you need for your application. On import, local::lib sets the following environment variables to appropriate values: PERL_MB_OPT PERL_MM_OPT PERL5LIB PATH PERL_LOCAL_LIB_ROOT When possible, these will be appended to instead of overwritten entirely. These values are then available for reference by any code after import. CREATING A SELF-CONTAINED SET OF MODULES See lib::core::only for one way to do this - but note that there are a number of caveats, and the best approach is always to perform a build against a clean perl (i.e. site and vendor as close to empty as possible). IMPORT OPTIONS Options are values that can be passed to the "local::lib" import besides the directory to use. They are specified as "use local::lib '--option'[, path];" or "perl -Mlocal::lib=--option[,path]". --deactivate Remove the chosen path (or the default path) from the module search paths if it was added by "local::lib", instead of adding it. --deactivate-all Remove all directories that were added to search paths by "local::lib" from the search paths. --shelltype Specify the shell type to use for output. By default, the shell will be detected based on the environment. Should be one of: "bourne", "csh", "cmd", or "powershell". --no-create Prevents "local::lib" from creating directories when activating dirs. This is likely to cause issues on Win32 systems. CLASS METHODS ensure_dir_structure_for Arguments: $path Return value: None Attempts to create a local::lib directory, including subdirectories and all required parent directories. Throws an exception on failure. print_environment_vars_for Arguments: $path Return value: None Prints to standard output the variables listed above, properly set to use the given path as the base directory. build_environment_vars_for Arguments: $path Return value: %environment_vars Returns a hash with the variables listed above, properly set to use the given path as the base directory. setup_env_hash_for Arguments: $path Return value: None Constructs the %ENV keys for the given path, by calling "build_environment_vars_for". active_paths Arguments: None Return value: @paths Returns a list of active "local::lib" paths, according to the "PERL_LOCAL_LIB_ROOT" environment variable and verified against what is really in @INC. install_base_perl_path Arguments: $path Return value: $install_base_perl_path Returns a path describing where to install the Perl modules for this local library installation. Appends the directories "lib" and "perl5" to the given path. lib_paths_for Arguments: $path Return value: @lib_paths Returns the list of paths perl will search for libraries, given a base path. This includes the base path itself, the architecture specific subdirectory, and perl version specific subdirectories. These paths may not all exist. install_base_bin_path Arguments: $path Return value: $install_base_bin_path Returns a path describing where to install the executable programs for this local library installation. Appends the directory "bin" to the given path. installer_options_for Arguments: $path Return value: %installer_env_vars Returns a hash of environment variables that should be set to cause installation into the given path. resolve_empty_path Arguments: $path Return value: $base_path Builds and returns the base path into which to set up the local module installation. Defaults to "~/perl5". resolve_home_path Arguments: $path Return value: $home_path Attempts to find the user's home directory. If installed, uses "File::HomeDir" for this purpose. If no definite answer is available, throws an exception. resolve_relative_path Arguments: $path Return value: $absolute_path Translates the given path into an absolute path. resolve_path Arguments: $path Return value: $absolute_path Calls the following in a pipeline, passing the result from the previous to the next, in an attempt to find where to configure the environment for a local library installation: "resolve_empty_path", "resolve_home_path", "resolve_relative_path". Passes the given path argument to "resolve_empty_path" which then returns a result that is passed to "resolve_home_path", which then has its result passed to "resolve_relative_path". The result of this final call is returned from "resolve_path". OBJECT INTERFACE new Arguments: %attributes Return value: $local_lib Constructs a new "local::lib" object, representing the current state of @INC and the relevant environment variables. ATTRIBUTES roots An arrayref representing active "local::lib" directories. inc An arrayref representing @INC. libs An arrayref representing the PERL5LIB environment variable. bins An arrayref representing the PATH environment variable. extra A hashref of extra environment variables (e.g. "PERL_MM_OPT" and "PERL_MB_OPT") no_create If set, "local::lib" will not try to create directories when activating them. OBJECT METHODS clone Arguments: %attributes Return value: $local_lib Constructs a new "local::lib" object based on the existing one, overriding the specified attributes. activate Arguments: $path Return value: $new_local_lib Constructs a new instance with the specified path active. deactivate Arguments: $path Return value: $new_local_lib Constructs a new instance with the specified path deactivated. deactivate_all Arguments: None Return value: $new_local_lib Constructs a new instance with all "local::lib" directories deactivated. environment_vars_string Arguments: [ $shelltype ] Return value: $shell_env_string Returns a string to set up the "local::lib", meant to be run by a shell. build_environment_vars Arguments: None Return value: %environment_vars Returns a hash with the variables listed above, properly set to use the given path as the base directory. setup_env_hash Arguments: None Return value: None Constructs the %ENV keys for the given path, by calling "build_environment_vars". setup_local_lib Constructs the %ENV hash using "setup_env_hash", and set up @INC. A WARNING ABOUT UNINST=1 Be careful about using local::lib in combination with "make install UNINST=1". The idea of this feature is that will uninstall an old version of a module before installing a new one. However it lacks a safety check that the old version and the new version will go in the same directory. Used in combination with local::lib, you can potentially delete a globally accessible version of a module while installing the new version in a local place. Only combine "make install UNINST=1" and local::lib if you understand these possible consequences. LIMITATIONS * Directory names with spaces in them are not well supported by the perl toolchain and the programs it uses. Pure-perl distributions should support spaces, but problems are more likely with dists that require compilation. A workaround you can do is moving your local::lib to a directory with spaces after you installed all modules inside your local::lib bootstrap. But be aware that you can't update or install CPAN modules after the move. * Rather basic shell detection. Right now anything with csh in its name is assumed to be a C shell or something compatible, and everything else is assumed to be Bourne, except on Win32 systems. If the "SHELL" environment variable is not set, a Bourne-compatible shell is assumed. * Kills any existing PERL_MM_OPT or PERL_MB_OPT. * Should probably auto-fixup CPAN config if not already done. * On VMS and MacOS Classic (pre-OS X), local::lib loads File::Spec. This means any File::Spec version installed in the local::lib will be ignored by scripts using local::lib. A workaround for this is using "use lib "$local_lib/lib/perl5";" instead of using "local::lib" directly. * Conflicts with ExtUtils::MakeMaker's "PREFIX" option. "local::lib" uses the "INSTALL_BASE" option, as it has more predictable and sane behavior. If something attempts to use the "PREFIX" option when running a Makefile.PL, ExtUtils::MakeMaker will refuse to run, as the two options conflict. This can be worked around by temporarily unsetting the "PERL_MM_OPT" environment variable. * Conflicts with Module::Build's "--prefix" option. Similar to the previous limitation, but any "--prefix" option specified will be ignored. This can be worked around by temporarily unsetting the "PERL_MB_OPT" environment variable. Patches very much welcome for any of the above. * On Win32 systems, does not have a way to write the created environment variables to the registry, so that they can persist through a reboot. TROUBLESHOOTING If you've configured local::lib to install CPAN modules somewhere in to your home directory, and at some point later you try to install a module with "cpan -i Foo::Bar", but it fails with an error like: "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" and buried within the install log is an error saying "'INSTALL_BASE' is not a known MakeMaker parameter name", then you've somehow lost your updated ExtUtils::MakeMaker module. To remedy this situation, rerun the bootstrapping procedure documented above. Then, run "rm -r ~/.cpan/build/Foo-Bar*" Finally, re-run "cpan -i Foo::Bar" and it should install without problems. ENVIRONMENT SHELL COMSPEC local::lib looks at the user's "SHELL" environment variable when printing out commands to add to the shell configuration file. On Win32 systems, "COMSPEC" is also examined. SEE ALSO * Perl Advent article, 2011 SUPPORT IRC: Join #local-lib on irc.perl.org. AUTHOR Matt S Trout http://www.shadowcat.co.uk/ auto_install fixes kindly sponsored by http://www.takkle.com/ CONTRIBUTORS Patches to correctly output commands for csh style shells, as well as some documentation additions, contributed by Christopher Nehren . Doc patches for a custom local::lib directory, more cleanups in the english documentation and a german documentation contributed by Torsten Raudssus . Hans Dieter Pearcey sent in some additional tests for ensuring things will install properly, submitted a fix for the bug causing problems with writing Makefiles during bootstrapping, contributed an example program, and submitted yet another fix to ensure that local::lib can install and bootstrap properly. Many, many thanks! pattern of Freenode IRC contributed the beginnings of the Troubleshooting section. Many thanks! Patch to add Win32 support contributed by Curtis Jewell . Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced by a patch from Marco Emilio Poleggi. Mark Stosberg provided the code for the now deleted '--self-contained' option. Documentation patches to make win32 usage clearer by David Mertens (run4flat). Brazilian portuguese translation and minor doc patches contributed by Breno G. de Oliveira . Improvements to stacking multiple local::lib dirs and removing them from the environment later on contributed by Andrew Rodland . Patch for Carp version mismatch contributed by Hakim Cassimally . Rewrite of internals and numerous bug fixes and added features contributed by Graham Knop . COPYRIGHT Copyright (c) 2007 - 2013 the local::lib "AUTHOR" and "CONTRIBUTORS" as listed above. LICENSE This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. local-lib-2.000018/t/000755 000765 000024 00000000000 12614451477 014341 5ustar00gknopstaff000000 000000 local-lib-2.000018/xt/000755 000765 000024 00000000000 12614451477 014531 5ustar00gknopstaff000000 000000 local-lib-2.000018/xt/author/000755 000765 000024 00000000000 12614451477 016033 5ustar00gknopstaff000000 000000 local-lib-2.000018/xt/bootstrap.t000644 000765 000024 00000007704 12571546532 016742 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More 0.81_01; use IPC::Open3; use File::Temp; use File::Spec; use File::Path qw(mkpath); use File::Basename qw(dirname); use local::lib (); use ExtUtils::MakeMaker; use Cwd qw(cwd); sub check_version { my ($perl, $module) = @_; my @inc = `$perl -le "print for \@INC"`; chomp @inc; (my $file = "$module.pm") =~ s{::}{/}g; ($file) = grep -e, map { "$_/$file" } @inc; return undef unless $file; my $version = MM->parse_version($file); eval $version; } my @perl; my $verbose; while (@ARGV) { my $arg = shift @ARGV; if ($arg eq '-v') { $verbose = 1; } elsif ($arg eq '--') { push @perl, @ARGV; @ARGV = (); } elsif ($arg =~ /^-/) { warn "unrecognized option: $arg\n"; } else { push @perl, $arg; } } my $cwd = cwd; my $tempdir = File::Temp::tempdir('local-lib-source-XXXXX', CLEANUP => 1, TMPDIR => 1); END { chdir $cwd } my @files = qw( Makefile.PL lib/local/lib.pm inc/CPAN.pm inc/CheckVersion.pm ); for my $file (@files) { my $dest = File::Spec->catfile($tempdir, $file); mkpath(dirname($dest)); my $content = do { local $/; open my $fh, '<:raw', $file or die "can't read $file $!"; <$fh>; }; $content =~ s{.*do 'maint/Makefile.PL\.include'.*}{}; open my $fh, '>:raw', $dest or die "can't write $dest $!"; print { $fh } $content; close $fh; } chdir $tempdir; @perl = $^X unless @perl; my %modules = ( 'ExtUtils::MakeMaker' => '7.00', # version INSTALL_BASE taken as string, not shell 'ExtUtils::Install' => '1.43', # version INSTALL_BASE was added 'Module::Build' => '0.36', # PERL_MB_OPT 'CPAN' => '1.82', # sudo support + CPAN::HandleConfig ); plan tests => @perl * (2+2*keys %modules); for my $perl (@perl) { local @INC = @INC; local $ENV{AUTOMATED_TESTING} = 1; local $ENV{PERL5LIB}; local $ENV{PERL_LOCAL_LIB_ROOT}; local $ENV{PERL_MM_OPT}; local $ENV{PERL_MB_OPT}; delete $ENV{PERL5LIB}; delete $ENV{PERL_LOCAL_LIB_ROOT}; delete $ENV{PERL_MM_OPT}; delete $ENV{PERL_MB_OPT}; local $ENV{HOME} = my $home = File::Temp::tempdir('local-lib-home-XXXXX', CLEANUP => 1, TMPDIR => 1); diag "testing bootstrap with $perl"; my %old_versions; for my $module (sort keys %modules) { my $version = check_version($perl, $module); $old_versions{$module} = $version; if ($version && $version >= $modules{$module}) { diag "Can't test bootstrap of $module, version $version already meets requirement of $modules{$module}"; } } my $ll = File::Spec->catdir($home, 'local-lib'); unlink 'MYMETA.yml'; unlink 'META.yml'; unlink 'Makefile'; open my $null_in, '<', File::Spec->devnull; my $pid = open3 $null_in, my $out, undef, $perl, 'Makefile.PL', '--bootstrap='.$ll; while (my $line = <$out>) { note $line if $verbose || $line =~ /^Running |^\s.* -- (?:NOT OK|OK|NA|TIMED OUT)$/; } waitpid $pid, 0; is $?, 0, 'Makefile.PL ran successfully'; ok -e 'Makefile', 'Makefile created'; my $prereqs = {}; open my $fh, '<', 'Makefile' or die "Unable to open Makefile: $!"; while (<$fh>) { last if /MakeMaker post_initialize section/; my ($p) = m{^[\#]\s+PREREQ_PM\s+=>\s+(.+)} or next; while ( $p =~ m/(?:\s)([\w\:]+)=>(?:q\[(.*?)\]|undef),?/g ) { $prereqs->{$1} = $2; } } close $fh; local::lib->setup_env_hash_for($ll); for my $module (sort keys %modules) { my $version = check_version($perl, $module); my $old_v = $old_versions{$module}; my $want_v = $modules{$module}; if (defined $old_v) { is $prereqs->{$module}, ($old_v >= $want_v ? undef : $want_v), "prereqs correct for $module"; cmp_ok $version, '>=', $want_v, "bootstrap upgraded to new enough $module" or diag "PERL5LIB: $ENV{PERL5LIB}"; } else { ok !exists $prereqs->{$module}, "$module not listed as prereq"; is $version, undef, "bootstrap didn't install new module $module"; } } } unlink 'Makefile'; local-lib-2.000018/xt/install.t000644 000765 000024 00000004634 12571546532 016372 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use Capture::Tiny qw(capture_merged); use File::Spec; use File::Path qw(mkpath); use Cwd; use Config; use lib 't/lib'; use TempDir; use local::lib (); delete @ENV{ 'PERL_MM_OPT', 'PERL_MB_OPT', 'PERL_LOCAL_LIB_ROOT', grep /^MAKE/, keys %ENV }; my @dirs = ( 'plain', 'with space', 'with\backslash', 'with space\and-bs', ); my %dist_types = ( EUMM => sub { open my $fh, '>', 'Makefile.PL' or die "can't create Makefile.PL: $!"; print $fh 'use ExtUtils::MakeMaker; WriteMakefile( NAME => "EUMM" );'; close $fh; system($^X, 'Makefile.PL') && die "Makefile.PL failed"; system($Config{make}, 'install') && die "$Config{make} install failed"; }, MB => sub { open my $fh, '>', 'Build.PL' or die "can't create Build.PL: $!"; print $fh <new( module_name => "MB", dist_version => 1, license => "perl", )->create_build_script; END_BUILD close $fh; system($^X, 'Build.PL') && die "Build.PL failed"; system($^X, 'Build', 'install') && die "Build install failed"; }, ); plan tests => @dirs * keys(%dist_types) * 2; my $orig_dir = cwd; for my $dir_base (@dirs) { for my $dist_type (sort keys %dist_types) { chdir $orig_dir; local @ENV{ 'PERL_MM_OPT', 'PERL_MB_OPT', 'PERL_LOCAL_LIB_ROOT', grep /^MAKE/, keys %ENV }; local $ENV{PERL5LIB} = $ENV{PERL5LIB}; my $temp = mk_temp_dir("install-$dist_type-XXXXX"); my $ll_dir = "$dist_type-$dir_base"; my $ll = "$temp/$ll_dir"; mkpath(File::Spec->canonpath($ll)); local::lib->import($ll, '--quiet'); my $dist_dir = mk_temp_dir("source-$dist_type-XXXXX"); chdir $dist_dir; mkdir 'lib'; open my $fh, '>', "lib/$dist_type.pm"; print $fh '1;'; close $fh; my $output = capture_merged { eval { $dist_types{$dist_type}->(); } }; is $@, '', "installed $dist_type into '$ll_dir'" or diag $output; my $dest_dir = local::lib->install_base_perl_path($ll); my $file = File::Spec->catfile($dest_dir, "$dist_type.pm"); (my $short_file = $file) =~ s/^\Q$ll/$ll_dir/; ok( -e $file, "$dist_type - $dir_base - $dist_type.pm installed as '$short_file'", ) or diag 'Files in ' . $dest_dir . ":\n", join("\n", do { my $dh; (opendir $dh, $dest_dir) ? readdir $dh : "doesn't exist"; }); } } chdir $orig_dir; local-lib-2.000018/xt/author/cpan-changes.t000644 000765 000024 00000000161 12604603251 020531 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; plan tests => 4; use Test::CPAN::Changes; changes_file_ok('Changes'); local-lib-2.000018/xt/author/eol.t000644 000765 000024 00000000153 12571546532 016775 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use Test::EOL; all_perl_files_ok({ trailing_whitespace => 1 }); local-lib-2.000018/xt/author/minimum-version.t000644 000765 000024 00000000171 12571546532 021354 0ustar00gknopstaff000000 000000 use strict; use warnings; use Perl::MinimumVersion 1.35; use Test::MinimumVersion; all_minimum_version_ok( qq{5.006} ); local-lib-2.000018/xt/author/no-tabs.t000644 000765 000024 00000000122 12571546532 017555 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use Test::NoTabs; all_perl_files_ok(); local-lib-2.000018/xt/author/pod-syntax.t000644 000765 000024 00000000123 12571546532 020321 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use Test::Pod 1.41; all_pod_files_ok(); local-lib-2.000018/t/bad_variables.t000644 000765 000024 00000002227 12543732755 017311 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More tests => 6; use File::Temp 'tempdir'; use Config; use local::lib (); use lib 't/lib'; use TempDir; delete $ENV{PERL_LOCAL_LIB_ROOT}; my $dir1 = mk_temp_dir('test_local_lib-XXXXX'); my $dir2 = mk_temp_dir('test_local_lib-XXXXX'); my $dir3 = mk_temp_dir('test_local_lib-XXXXX'); ok(!(grep { $dir1 eq $_ } @INC), 'new dir is not already in @INC'); ok(!(grep { $dir1 eq $_ } split /\Q$Config{path_sep}\E/, ($ENV{PERL5LIB}||'')), 'new dir is not already in PERL5LIB'); local::lib->import($dir1); local::lib->import($dir2); # we have junk in here now $ENV{PERL_LOCAL_LIB_ROOT} = $dir3 . $Config{path_sep} . $ENV{PERL_LOCAL_LIB_ROOT}; local::lib->import($dir1); is( $ENV{PERL_LOCAL_LIB_ROOT}, join($Config{path_sep}, (grep { defined $_ and $_ ne '' } $dir1, $dir3, $dir2)), 'dir1 should have been removed and added back in at the top' ); ok((!grep { $_ eq $dir3 } local::lib->active_paths), 'junk dir added not included in active_paths'); ok((grep { /\Q$dir1\E/ } @INC), 'new dir has been added to @INC'); ok((grep { /\Q$dir1\E/ } split /\Q$Config{path_sep}\E/, $ENV{PERL5LIB}), 'new dir has been added to PERL5LIB'); local-lib-2.000018/t/carp-mismatch.t000644 000765 000024 00000003230 12571546532 017253 0ustar00gknopstaff000000 000000 use strict; use warnings; # something else (presumably a core module that local::lib uses) loads Carp, # and then later on something loads Carp::Heavy from the local-lib, which is # at a newer version use Carp; use Test::More tests => 4 + ( $Carp::VERSION < '1.22' ? 0 : 1 ); use File::Spec; use File::Path qw(mkpath rmtree); # use legacy versions for backcompat use local::lib (); is $Carp::Heavy::VERSION, undef, 'Carp::Heavy is not yet loaded'; # we do not use File::Temp because it loads Carp::Heavy. my $libdir = File::Spec->catdir(File::Spec->tmpdir, 'tmp-carp-newer-' . $$); my $carpdir = File::Spec->catdir($libdir, 'lib', 'perl5', 'Carp'); mkpath($carpdir); { my $heavy = File::Spec->catfile($carpdir, 'Heavy.pm'); open my $fh, '>', $heavy or die "failed to open $heavy for writing: $!"; print $fh "package Carp::Heavy;\nour \$VERSION = '500.0';\n"; close $fh; } { # another module, simply to ensure that we got the libdir path correct my $foo = File::Spec->catfile($carpdir, 'Foo.pm'); open my $fh, '>', $foo or die "failed to open foo heavy for writing: $!"; print $fh "package Carp::Foo;\nour \$VERSION = '200.0';\n"; close $fh; } local::lib->import('--no-create', $libdir); require Carp::Foo; is $Carp::Foo::VERSION, '200.0', 'some other module was loaded from our local::lib'; ok $INC{'Carp/Heavy.pm'}, 'Carp::Heavy has now been loaded'; is $Carp::Heavy::VERSION, $Carp::VERSION, 'Carp::Heavy matching Carp was loaded' unless $Carp::VERSION < '1.22'; # Carp::Heavy namespace did not exist isnt $Carp::Heavy::VERSION, '500.0', 'Carp::Heavy was not loaded from our local::lib'; END { rmtree($libdir) if $libdir; } local-lib-2.000018/t/classmethod.t000644 000765 000024 00000001513 12571546532 017033 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More tests => 7; use File::Temp; use File::Spec::Functions qw(catdir); use local::lib (); my $c = 'local::lib'; { is $c->resolve_empty_path, '~/perl5', 'empty path resolves to ~/perl5'; is $c->resolve_empty_path('foo'), 'foo', 'defined path resolves to same path'; } { my $warn = ''; local $SIG{__WARN__} = sub { $warn .= $_[0] }; my $dir = File::Temp::tempdir(); my $ll_dir = catdir($dir, 'splat'); $c->ensure_dir_structure_for($ll_dir); ok -d $ll_dir, 'base dir created'; ok -d $c->install_base_bin_path($ll_dir), 'bin dir created'; ok -d $c->install_base_perl_path($ll_dir), 'lib dir created'; ok -d $c->install_base_arch_path($ll_dir), 'arch dir created'; like $warn, qr/^Attempting to create directory/, 'warning about creation'; } local-lib-2.000018/t/coderefs_in_inc.t000644 000765 000024 00000000613 12571546532 017636 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More tests => 2; use lib 't/lib'; use TempDir; use Cwd; # Test that refs in @INC don't get mangled. my $dir = mk_temp_dir('test_local_lib-XXXXX'); use local::lib (); my $code = sub {}; push(@INC, $code); local::lib->import($dir); ok grep({ $_ eq $code } @INC), 'Can find code ref in @INC'; ok grep({ ref $_ } @INC), 'It really is a ref, not stringified'; local-lib-2.000018/t/de-dup.t000644 000765 000024 00000001043 12571546532 015701 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More tests => 2; use lib 't/lib'; use TempDir; use Cwd; my $dir = mk_temp_dir('test_local_lib-XXXXX'); use local::lib (); my %inc; my %perl5lib; $inc{$_}-- for @INC; $perl5lib{$_}-- for split /:/, $ENV{PERL5LIB}; local::lib->import($dir); local::lib->import($dir); $inc{$_}++ for @INC; $perl5lib{$_}++ for split /:/, $ENV{PERL5LIB}; ok ! (grep { $inc{$_} > 1 } keys %inc), '@INC entries not duplicated'; ok ! (grep { $perl5lib{$_} > 1 } keys %perl5lib), 'ENV{PERL5LIB} entries not duplicated'; local-lib-2.000018/t/lib/000755 000765 000024 00000000000 12614451477 015107 5ustar00gknopstaff000000 000000 local-lib-2.000018/t/lib-core-only.t000644 000765 000024 00000000421 12217002201 017146 0ustar00gknopstaff000000 000000 use strict; use warnings FATAL => 'all'; use Test::More tests => 1; use lib::core::only (); use Config; is_deeply( [ do { local @INC = @INC; lib::core::only->import; @INC } ], [ $Config{privlibexp}, $Config{archlibexp} ], 'lib::core::only mangles @INC correctly' ); local-lib-2.000018/t/pipeline.t000644 000765 000024 00000000431 12531456676 016335 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More tests => 1; use local::lib (); { package local::lib; { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } } my $foo = bless({}, 'Foo'); Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15); } local-lib-2.000018/t/shell.t000644 000765 000024 00000013712 12602776324 015637 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use File::Spec; use File::Basename qw(dirname); use File::Temp (); use File::Path; use Config; use local::lib (); use IPC::Open3 qw(open3); my @ext = $^O eq 'MSWin32' ? (split /\Q$Config{path_sep}/, $ENV{PATHEXT}) : (); sub which { my $shell = shift; my ($full) = grep { -x } map { my $x = $_; $x, map { $x . $_ } @ext } map { File::Spec->catfile( $_, $shell) } File::Spec->path; return $full; } BEGIN { *quote_literal = $^O ne 'MSWin32' ? sub { $_[0] } : sub { my ($text) = @_; $text =~ s{(\\*)(?="|\z)}{$1$1}g; $text =~ s{"}{\\"}g; $text = qq{"$text"}; return $text; }; } my %shell_path; { my @shell_paths; if (open my $fh, '<', '/etc/shells') { my @lines = <$fh>; s/^\s+//, s/\s+$// for @lines; @shell_paths = grep { length && !/^#/ } @lines; } %shell_path = map { m{[\\/]([^\\/]+)$} ? ($1 => $_) : () } grep { defined && -x } ( '/bin/sh', '/bin/csh', $ENV{'ComSpec'}, @shell_paths ); } my @extra_lib = ('-I' . dirname(dirname($INC{'local/lib.pm'}))); my $nul = File::Spec->devnull; my @shells; for my $shell ( { name => 'sh', test => '-c "exit 0"', }, { name => 'dash', test => '-c "exit 0"', }, { name => 'bash', test => '-c "exit 0"', }, { name => 'zsh', test => '-f -c "exit 0"', }, { name => 'ksh', test => '-c "exit 0"', }, { name => 'csh', test => '-c "exit 0"', opt => '-f', }, { name => 'tcsh', test => '-c "exit 0"', opt => '-f', }, { name => 'fish', test => '-c "exit 0"', }, { name => 'cmd.exe', opt => '/Q /D /C', test => '/Q /D /C "exit 0"', ext => 'bat', perl => qq{@"$^X"}, skip => $^O ne 'MSWin32', }, { name => 'powershell.exe', shell => which('powershell.exe'), opt => '-NoProfile -ExecutionPolicy Unrestricted -File', test => '-NoProfile -Command "exit 0"', ext => 'ps1', perl => qq{& '$^X'}, skip => $^O ne 'MSWin32', }, ) { my $name = $shell->{name}; $shell->{shell} ||= $shell_path{$name}; $shell->{ext} ||= $name; $shell->{perl} ||= qq{"$^X"}; if (@ARGV) { next if !grep {$_ eq $name} @ARGV; my $exec = $shell->{shell} ||= which($name); if (!$exec) { warn "unable to find executable for $name"; next; } } elsif ($shell->{skip} || !$shell->{shell}) { next; } elsif ($shell->{test}) { no warnings 'exec'; if (system "$shell->{shell} $shell->{test} > $nul 2> $nul") { diag "$name seems broken, skipping"; next; } } push @shells, $shell; } if (!@shells) { plan skip_all => 'no supported shells found'; } my @vars = qw(PATH PERL5LIB PERL_LOCAL_LIB_ROOT PERL_MM_OPT PERL_MB_OPT); my @strings = ( 'string', 'with space', 'with"quote', "with'squote", 'with\\bslash', 'with%per%cent', 'with$dollar', ); plan tests => @shells * (@vars * 2 + @strings * 2); my $sep = $Config{path_sep}; my $root = File::Spec->rootdir; for my $shell (@shells) { my $ll = local::lib->normalize_path(File::Temp::tempdir(CLEANUP => 1)); local $ENV{$_} for @vars; delete $ENV{$_} for @vars; $ENV{PATH} = $root; my $orig = call_shell($shell, ''); my $bin_path = local::lib->install_base_bin_path($ll); mkdir $bin_path; my $env = call_ll($shell, $ll); my %install_opts = local::lib->installer_options_for($ll); delete $orig->{$_} for qw(PERL_MM_OPT PERL_MB_OPT); my $want = { PERL_LOCAL_LIB_ROOT => $ll, PATH => $bin_path, PERL5LIB => local::lib->install_base_perl_path($ll), (map {; $_ => $install_opts{$_}} qw(PERL_MM_OPT PERL_MB_OPT)), }; for my $var (keys %$want) { $want->{$var} = join($sep, $want->{$var}, $orig->{$var} || ()), } for my $var (@vars) { is $env->{$var}, $want->{$var}, "$shell->{name}: activate $var"; } $ENV{$_} = $env->{$_} for @vars; $env = call_ll($shell, '--deactivate', "$ll"); for my $var (@vars) { is $env->{$var}, $orig->{$var}, "$shell->{name}: deactivate $var"; } my $shelltype = do { local $ENV{SHELL} = $shell->{shell}; local::lib->guess_shelltype; }; for my $string (@strings) { local $TODO = "$shell->{name}: can't quote strings with percents" if $shell->{name} eq 'cmd.exe' && $string =~ /%/; local $ENV{LL_TEST}; delete $ENV{LL_TEST}; my $script = local::lib->_build_env_string($shelltype, [ LL_TEST => $string, ]); my $env = call_shell($shell, $script); is $env->{LL_TEST}, $string, "$shell->{name}: can quote [$string]"; local $TODO = "$shell->{name}: can't test strings with double quotes" if $shell->{name} eq 'cmd.exe' && $string =~ /"/; $ENV{LL_TEST} = 'pre'; $script = local::lib->_build_env_string($shelltype, [ LL_TEST => [\"LL_TEST", $string], ]); $env = call_shell($shell, $script); is $env->{LL_TEST}, "pre$sep$string", "$shell->{name}: can append [$string]"; } } sub call_ll { my ($info, @options) = @_; local $ENV{SHELL} = $info->{shell}; open my $in, '<', File::Spec->devnull; open my $err, '>', File::Spec->devnull; open3 $in, my $out, $err, $^X, @extra_lib, '-Mlocal::lib', '-', '--no-create', map { quote_literal($_) } @options or die "blah"; my $script = do { local $/; <$out> }; close $out; call_shell($info, $script); } sub call_shell { my ($info, $script) = @_; $script .= "\n" . qq{$info->{perl} -Mt::lib::ENVDumper -e1\n}; my ($fh, $file) = File::Temp::tempfile( 'll-test-script-XXXXX', DIR => File::Spec->tmpdir, SUFFIX => '.'.$info->{ext}, UNLINK => 1, ); print { $fh } $script; close $fh; my $opt = $info->{opt} ? "$info->{opt} " : ''; my $cmd = qq{"$info->{shell}" $opt"$file"}; my $output = `$cmd`; if ($?) { diag "script:\n$script"; diag "running:\n$cmd"; diag "failed with code: $?"; return {}; } my $env = eval $output or die "bad output: $@"; $env; } local-lib-2.000018/t/stackable.t000644 000765 000024 00000004656 12571546532 016471 0ustar00gknopstaff000000 000000 use strict; use warnings; use Test::More; use File::Spec; use Config; plan tests => 24; use local::lib (); use lib 't/lib'; use TempDir; delete $ENV{PERL_LOCAL_LIB_ROOT}; my $dir1 = mk_temp_dir('test_local_lib-XXXXX'); my $dir2 = mk_temp_dir('test_local_lib-XXXXX'); my ($dir1_arch, $dir2_arch) = map { File::Spec->catfile($_, qw'lib perl5', $Config{archname}) } $dir1, $dir2; my $prev_active = () = local::lib->active_paths; local::lib->import($dir1); is +() = local::lib->active_paths, $prev_active + 1, 'one active path'; like $ENV{PERL_LOCAL_LIB_ROOT}, qr/\Q$dir1/, 'added one dir in root'; like $ENV{PERL5LIB}, qr/\Q$dir1/, 'added one dir in lib'; unlike $ENV{PERL5LIB}, qr/\Q$dir1_arch/, 'no arch in PERL5LIB'; my $dir1_escape = local::lib::_mm_escape_path($dir1); like $ENV{PERL_MM_OPT}, qr/\Q$dir1_escape/, 'first path is installation target'; local::lib->import($dir1); is +() = local::lib->active_paths, $prev_active + 1, 'still one active path after adding it twice'; local::lib->import($dir2); is +() = local::lib->active_paths, $prev_active + 2, 'two active paths'; like $ENV{PERL_LOCAL_LIB_ROOT}, qr/\Q$dir2/, 'added another dir in root'; like $ENV{PERL5LIB}, qr/\Q$dir2/, 'added another dir in lib'; unlike $ENV{PERL5LIB}, qr/\Q$dir2_arch/, 'no arch in PERL5LIB'; like $ENV{PERL_LOCAL_LIB_ROOT}, qr/\Q$dir1/, 'first dir is still in root'; like $ENV{PERL5LIB}, qr/\Q$dir1/, 'first dir is still in lib'; unlike $ENV{PERL5LIB}, qr/\Q$dir1_arch/, 'no arch in PERL5LIB'; my $dir2_escape = local::lib::_mm_escape_path($dir2); like $ENV{PERL_MM_OPT}, qr/\Q$dir2_escape/, 'second path is installation target'; local::lib->import($dir1); my @active = local::lib->active_paths; is @active, $prev_active + 2, 'still two active dirs after re-adding first'; is $active[0], $dir1, 'first dir was re-added on top'; like $ENV{PERL_MM_OPT}, qr/\Q$dir1_escape/, 'first path is installation target again'; local::lib->import('--deactivate', $dir2); unlike $ENV{PERL_LOCAL_LIB_ROOT}, qr/\Q$dir2/, 'second dir was removed from root'; unlike $ENV{PERL5LIB}, qr/\Q$dir2/, 'second dir was removed from lib'; unlike $ENV{PERL5LIB}, qr/\Q$dir2_arch/, 'no arch in PERL5LIB'; like $ENV{PERL_LOCAL_LIB_ROOT}, qr/\Q$dir1/, q{first dir didn't go away from root}; like $ENV{PERL5LIB}, qr/\Q$dir1/, q{first dir didn't go away from lib}; unlike $ENV{PERL5LIB}, qr/\Q$dir1_arch/, 'no arch in PERL5LIB'; like $ENV{PERL_MM_OPT}, qr/\Q$dir1_escape/, 'first dir stays installation target'; local-lib-2.000018/t/subroutine-in-inc.t000644 000765 000024 00000000645 12543732755 020107 0ustar00gknopstaff000000 000000 use strict; use warnings FATAL => 'all'; use Test::More tests => 1; use File::Spec; use Cwd; use lib 't/lib'; use TempDir; use local::lib (); sub CODE_in_INC() { return scalar grep { ref eq 'CODE' } @INC; } my $dir = mk_temp_dir('sub-in-INC-XXXXX'); my $base = CODE_in_INC; unshift @INC, sub { () }; splice @INC, 3, 1, sub { () }; push @INC, sub { () }; local::lib->import($dir); is( CODE_in_INC, $base + 3 ); local-lib-2.000018/t/taint-mode.t000644 000765 000024 00000005014 12571546532 016566 0ustar00gknopstaff000000 000000 # # t/taint-mode.t: checks that local::lib sets up @INC correctly when # included in a script that has taint mode on, and is executing in an # environment in which local::lib has already been loaded. # use strict; use warnings; use Cwd; # load before anything else to work around ActiveState bug use Test::More tests => 4; use File::Temp 'tempfile'; use File::Basename qw(basename dirname); use File::Spec; use IPC::Open3; use Config; use lib 't/lib'; use TempDir; my @INC_CLEAN = @INC; my $dir1 = mk_temp_dir('used_in_taint-XXXXX'); my $dir2 = mk_temp_dir('not_used_in_taint-XXXXX'); # Set up local::lib environment using our temp dir require local::lib; local::lib->import($dir1); local::lib->import($dir2); # Create a script that has taint mode turned on, and tries to use a # local lib to the same temp dir. mkdir 't/temp'; my ($fh, $filename) = tempfile( 'test_local_lib-XXXXX', DIR => Cwd::abs_path('t/temp'), UNLINK => 1, ); print $fh <<"EOM"; #!/usr/bin/perl -T use strict; use warnings; use local::lib "\Q$dir1\E"; print "\$_\\n" for \@INC; EOM close $fh; open my $in, '<', File::Spec->devnull; my $pid = open3($in, my $out, undef, $^X, map("-I$_", @INC_CLEAN), '-T', $filename); my @libs = <$out>; s/[\r\n]*\z// for @libs; close $out; waitpid $pid, 0; is $?, 0, 'test script ran without error'; my $dir1_lib = local::lib->install_base_perl_path($dir1); ok grep($_ eq $dir1_lib, @libs), 'local::lib used in taint script added to @INC' or diag "searched for '$dir1_lib' in: ", join(', ', map "'$_'", @libs); my $dir2_lib = local::lib->install_base_perl_path($dir2); ok !grep($_ eq $dir2_lib, @libs), 'local::lib not used used in taint script not added to @INC' or diag "searched for '$dir2_lib' in: ", join(', ', map "'$_'", @libs); { my $perl_file = basename($^X); if (!File::Spec->file_name_is_absolute($^X)) { my $perl_dir = dirname($^X); $ENV{PATH} = join($Config{path_sep}, $ENV{PATH}, $perl_dir); } my ($fh, $filename) = tempfile( 'test_local_lib-XXXXX', DIR => Cwd::abs_path('t/temp'), UNLINK => 1, ); print $fh <<'EOM'; #!/usr/bin/perl -T use strict; use warnings; use local::lib (); print local::lib::_cwd(); EOM close $fh; open my $err, '>', File::Spec->devnull or die "can't open null output: $!"; my $out; my $pid = open3($in, $out, $err, $^X, map("-I$_", @INC_CLEAN), '-T', $filename); my $cwd = do { local $/; <$out> }; $cwd =~ s/[\r\n]*\z//; $cwd = File::Spec->canonpath($cwd); is $cwd, File::Spec->canonpath(Cwd::getcwd()), 'reimplemented cwd matches standard cwd'; } local-lib-2.000018/t/lib/ENVDumper.pm000644 000765 000024 00000000172 12571546532 017251 0ustar00gknopstaff000000 000000 package t::lib::ENVDumper; use Data::Dumper; sub import { local $Data::Dumper::Terse = 1; print Dumper(\%ENV); } 1; local-lib-2.000018/t/lib/TempDir.pm000644 000765 000024 00000001443 12571546532 017012 0ustar00gknopstaff000000 000000 package TempDir; use strict; use warnings; use base 'Exporter'; our @EXPORT = qw(mk_temp_dir); use local::lib (); use Cwd; use File::Temp qw(tempdir); $File::Temp::KEEP_ALL = 1 if $ENV{LOCAL_LIB_TEST_DEBUG}; sub mk_temp_dir { my $name_template = shift; mkdir 't/temp'; my $path = tempdir($name_template, DIR => Cwd::abs_path('t/temp'), CLEANUP => 1); local::lib->ensure_dir_structure_for($path, { quiet => 1 }); # On Win32 the path where the distribution is built usually contains # spaces. This is a problem for some parts of the CPAN toolchain, so # local::lib uses the GetShortPathName trick do get an alternate # representation of the path that doesn't constain spaces. return ($^O eq 'MSWin32') ? Win32::GetShortPathName($path) : $path } 1; local-lib-2.000018/maint/Makefile.PL.include000644 000765 000024 00000000613 12571546532 020601 0ustar00gknopstaff000000 000000 BEGIN { -e 'Distar' or system("git clone git://git.shadowcat.co.uk/p5sagit/Distar.git") } use lib 'Distar/lib'; use Distar 0.001; use ExtUtils::MakeMaker 6.57_10 (); author 'mst - Matt S. Trout (cpan:MSTROUT) '; manifest_include eg => 'scripted_install.pl'; manifest_include lib => '.pod'; manifest_include inc => '.pm'; manifest_include '' => 'cpan-configure.pl'; 1; local-lib-2.000018/lib/lib/000755 000765 000024 00000000000 12614451477 015412 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/local/000755 000765 000024 00000000000 12614451477 015736 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/000755 000765 000024 00000000000 12614451477 015350 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/DE/000755 000765 000024 00000000000 12614451477 015640 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/PT_BR/000755 000765 000024 00000000000 12614451477 016256 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/PT_BR/local/000755 000765 000024 00000000000 12614451477 017350 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/PT_BR/local/lib.pod000644 000765 000024 00000037336 12267332110 020620 0ustar00gknopstaff000000 000000 =encoding utf8 =head1 NAME local::lib~[pt_br] - crie e use um diretório lib/ local para módulos perl com PERL5LIB =head1 SINOPSE No código - use local::lib; # configura um lib local em ~/perl5 use local::lib '~/foo'; # idem, mas ~/foo # Ou... use FindBin; use local::lib "$FindBin::Bin/../suporte"; # bibliotecas de suporte locais à aplicação Pela linha de comando (shell) - # Instala o LWP e suas dependências não encontradas no diretório '~/perl5' perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)' # Apenas exibe alguns comandos úteis para a shell $ 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" =head2 A técnica de 'bootstrapping' Uma forma comum de instalar o local::lib é usando o que é conhecido como técnica de "bootstrapping". É uma boa abordagem caso seu administrador de sistemas não tenha instalado o local::lib. Nesse caso, você precisará instalar o local::lib em seu diretório de usuário. Caso você tenha privilégios de administrador, ainda assim deverá configurar suas variáveis de ambiente, como discutido no passo 4, abaixo. Sem elas, você ainda instalará módulos no CPAN do sistema e seus scripts Perl não utilizarão o caminho para o lib/ que você definiu com o local::lib. Por padrão, o local::lib instala os módulos do CPAN e a si próprio em ~/perl5. Usuários do Windows devem ler L. 1. Baixe e descompacte o local::lib do CPAN (procure por "Download" na página do CPAN sobre o local::lib). Faça isso como um usuário comum, não como root ou administrador. Descompacte o arquivo em seu diretório de usuário ou em qualquer outro local conveniente. 2. Execute isso: perl Makefile.PL --bootstrap Caso o sistema pergunte se deve configurar tudo que puder automaticamente, você provavelmente deve responder que sim (yes). Para instalar o local::lib em um diretório que não o padrão, você precisará especificá-lo ao chamar o bootstrap, da seguinte forma: perl Makefile.PL --bootstrap=~/foo 3. Execute isso: (local::lib assume que você possui o comando 'make' instalado em seu sistema) make test && make install 4. Agora precisamos configurar as variáveis de ambiente apropriadas para que o Perl use nosso recém-criado diretório lib/. Caso esteja usando bash ou outra shell Bourne, você pode fazer isso adicionando a seguinte linha em seu script de inicialização da shell: echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc Caso esteja usando a shell C, pode fazer da seguinte forma: /bin/csh echo $SHELL /bin/csh perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc Caso tenha passado para o bootstrap um diretório que não o padrão, você precisará indicá-lo na chamada ao local::lib, dessa forma: echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc Após atualizar seu arquivo de configuração da shell, certifique-se de processá-lo novamente para obter as modificações em sua shell atual. Shells Bourne usam C<. ~/.bashrc> para isso, enquanto shells C usam C. Se estiver em uma máquina lenta ou operando com grandes limitações de espaço em disco, você pode desativar a geração automática de manpages a partir do POD ao instalar módulos. Para isso, basta passar o argumento C<--no-manpages> durante o bootstrap: perl Makefile.PL --bootstrap --no-manpages Para evitar ter que fazer vários bootstraps para vários ambientes de módulos Perl na mesma conta de usuário - por exemplo se você usa o local::lib para desenvolver diferentes aplicativos independentes - você pode utilizar uma única instalação bootstrap do local::lib para instalar módulos em diretórios diferentes da seguinte forma: cd ~/meudir1 perl -Mlocal::lib=./ eval $(perl -Mlocal::lib=./) ### Para configurar o ambiente apenas nessa shell printenv ### Veja que o ~/meudir1 está na PERL5LIB perl -MCPAN -e install ... ### Os módulos que quiser cd ../meudir2 ... REPITA ... Para múltiplos ambientes destinados a múltiplos aplicativos, você pode precisar incluir uma versão modificada das instruções de C<< use FindBin >> no exemplo "No código" acima. Caso tenha feito algo como o que foi descrito acima, terá um conjunto de módulos Perl em C<< ~/meudir1/lib >>. Caso tenha um script em C<< ~/meudir1/scripts/meuscript.pl >>, você precisará indicar a ele onde encontrar os módulos que instalou para ele em C<< ~/meudir1/lib >>. Em C<< ~/meudir1/scripts/meuscript.pl >>: use strict; use warnings; use local::lib "$FindBin::Bin/.."; ### aponta para ~/meudir1 e o local::lib acha o lib/ use lib "$FindBin::Bin/../lib"; ### aponta para ~/meudir1/lib Coloque isso antes de qualquer bloco BEGIN { ... } que precise dos módulos instalados. =head2 Diferenças ao usar esse módulo em Win32 Para configurar as variáveis de ambiente apropriadas para sua sessão atual do C, você pode fazer assim: 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% ### Para configurar o ambiente apenas dessa shell C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat ### em vez de $(perl -Mlocal::lib=./) Caso queira que as configurações do ambiente persistam, você precisará adicioná-las em Painel de Controle -> Sistema, ou usar o L. O "~" é transformado no diretório do perfil do usuário (o diretório com o nome do usuário dentro de "Documents and Settings" (Windows XP ou anterior) ou "Usuários" (Windows Vista e mais recentes)) a menos que $ENV{HOME} exista. Após isso, o nome do diretório é encurtado e os subdiretórios são criados (o que significa que o diretório deve existir). =head1 MOTIVAÇÃO A versão de um pacote Perl na sua máquina nem sempre é a que você precisa. Obviamente, a melhor coisa a fazer seria atualizá-la para a versão desejada. No entanto, você pode estar em uma situação que o impede de fazer isso. Talvez você não tenha privilégios de administrador do sistema; ou talvez esteja usando um sistema de gerenciamento de pacotes como o do Debian, e ainda não exista um pacote disponível na versão desejada. local::lib resolve esse problema possibilitando a criação de seu próprio diretório de pacotes Perl obtidos do CPAN (em sistemas multi-usuário, isso normalmente fica dentro do diretório de seu usuário). A instalação do Perl no sistema permanece inalterada; você simplesmente chama o Perl com opções especiais para que ele use os pacotes em seu diretório local em vez dos pacotes do sistema. O local::lib organiza as coisas para que versões dos pacotes Perl instalados localmente tenham precedência sobre as do sistema. Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas Debian), não precisará se preocupar com conflitos entre o Debian e o CPAN. Sua versão local dos pacotes será instalada em um diretório completamente diferente das versões instaladas pelo gerenciador de pacotes do sistema. =head1 DESCRIÇÃO Este módulo oferece uma forma rápida e conveniente para criar um repositório de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta e exibe para o usuário uma lista de variáveis de ambiente utilizando a sintaxe da shell atual do usuário (conforme especificado pela variável de ambiente C), pronta para ser adicionada diretamente no arquivo de configuração da shell. Generalizando, o local::lib permite a criação e uso de um diretório contendo módulos Perl fora do C<@INC> do Perl. Isso facilita a produção de aplicações com uma versão específica de determinado módulo, ou coleção de módulos. Também é útil quando o mantenedor de um módulo não aplicou determinado patch que você precisa para seu aplicativo. Durante o C, o local::lib define valores apropriados para as seguintes variáveis de ambiente: =over 4 =item PERL_MB_OPT =item PERL_MM_OPT =item PERL5LIB =item PATH valores serão anexados ao PATH, em vez de substituí-lo. =back Esses valores são então disponibilizados para referência por qualquer outro código após o C. =head1 CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS Veja L para uma maneira de fazer isso - mas note que há uma série de ressalvas na abordagem, e a melhor forma é sempre fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor' o mais vazios possível). =head1 MÉTODOS =head2 ensure_dir_structure_for =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: Nenhum =back Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha. =head2 print_environment_vars_for =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: Nenhum =back Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas para utilizar o caminho fornecido como diretório base. =head2 build_environment_vars_for =over 4 =item Argumentos: $caminho_do_diretorio, $interpolar =item Valor de Retorno: %variaveis_de_ambiente =back Retorna hash contendo as variáveis de ambiente listadas acima, devidamente ajustadas para utilizar o caminho fornecido como diretório base. =head2 setup_env_hash_for =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: Nenhum =back Constrói as chaves no C<%ENV> para o caminho fornecido, chamando C. =head2 install_base_perl_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_base_de_instalacao =back Retorna um caminho de diretório indicando onde instalar os módulos Perl para essa instalação local de bibliotecas. Adiciona os diretórios C e C ao final do caminho fornecido. =head2 install_base_arch_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_base_de_instalacao_arch =back Retorna um caminho de diretório indicando onde instalar os módulos Perl de arquiteturas específicas para essa instalação local de bibliotecas. Baseia-se no valor de retorno do método L, adicionando o valor de C<$Config{archname}>. =head2 install_base_bin_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_base_de_instalacao_bin =back Retorna um caminho de diretório indicando onde instalar programas executáveis para essa instalação local de bibliotecas. Baseia-se no valor de retorno do método L, adicionando o diretório C. =head2 resolve_empty_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_base_de_instalacao =back Cria e retorna o caminho de diretório raiz em que a instalação local de módulos deve ser feita. O padrão é C<~/perl5>. =head2 resolve_home_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_para_home =back Procura pelo diretório padrão (home) do usuário. Caso esteja instalado, utiliza o C para isso. Gera uma exceção caso não encontre resultado definitivo. =head2 resolve_relative_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_absoluto =back Transforma o caminho fornecido em um caminho absoluto. =head2 resolve_path =over 4 =item Argumentos: $caminho_do_diretorio =item Valor de Retorno: $caminho_absoluto =back Invoca os seguintes métodos em sequência, passando o resultado do método anterior para o seguinte, na tentativa de descobrir onde configurar o ambiente para a instalação local de bibliotecas: L, L, L. Passa o caminho de diretório fornecido para L que retorna um resultado que é passado para L, que então tem seu resultado passado para L. O resultado dessa chamada final é então retornado pelo L. =head1 UM AVISO SOBRE UNINST=1 Tenha cuidado ao usar o local::lib em conjunto com "make install UNINST=1". A idéia dessa opção é desinstalar a versão anterior de um módulo antes de instalar a mais recente. No entanto ela não possui uma verificação de segurança de que a versão antiga e a nova referem-se ao mesmo diretório. Usada em combinação com o local::lib, você pode potencialmente apagar uma versão globalmente acessível de um módulo e instalar a versão mais nova no diretório local. Apenas utilize "make install UNINST=1" junto com o local::lib se você entende essas possíveis consequências. =head1 LIMITAÇÕES As ferramentas auxiliares do perl não conseguem lidar com nomes de diretórios contendo espaços, então não é possível fazer seu bootstrap do local::lib em um diretório com espaços. O que você pode fazer é mover seu local::lib para um diretório com espaços B ter instalado todos os módulos dentro dele. Mas esteja ciente que você não poderá atualizar ou instalar outros módulos do CPAN nesse diretório local após a mudança. A detecção da shell é relativamente básica. Neste momento, qualquer coisa com csh no nome será tratada como a C shell ou compatível, e todo o resto será tratado como Bourne, exceto em sistemas Win32. Caso a variável de ambiente C não esteja disponível, assumiremos tratar-se de uma shell compatível com a Bourne. A técnica de bootstrap é um hack e usará o CPAN.pm para o ExtUtils::MakeMaker mesmo que você tenha o CPANPLUS instalado. Destrói qualquer valor pré-existente nas variáveis de ambiente PERL5LIB, PERL_MM_OPT e PERL_MB_OPT. Provavelmente deveria auto-configurar o CPAN caso isso ainda não tenha sido feito. Correções (patches) são muito bem-vindos para quaisquer dos itens acima. Em sistemas Win32, não há uma forma de escrever no registro as variáveis de ambiente criadas, para que elas persistam a uma reinicialização. =head1 SOLUÇÃO DE PROBLEMAS Se você configurou o local::lib para instalar módulos do CPAN em algum lugar do seu 'home', e mais tarde tentou instalar um módulo fazendo C, mas ele falhou com um erro como: C e em algum lugar no seu log de instalação houver um erro dizendo C<'INSTALL_BASE' is not a known MakeMaker parameter name>, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado. Para remediar a situação, execute novamente o procedimento de bootstrap descrito acima. Então, execute C Finalmente, execute novamente o C e ele deve instalar sem problemas. =head1 AMBIENTE =over 4 =item SHELL =item COMSPEC O local::lib procura pela variável de ambiente C do usuário ao processar e exibir os comandos a serem adicionados no arquivo de configuração da shell. Em sistemas Win32, C também será examinado. =back =head1 SUPORTE IRC: Acesse #local-lib em irc.perl.org. =head1 AUTOR DA TRADUÇÃO Breno G. de Oliveira, C<< >>, após ter perdido uma aposta para o L durante a Copa de 2010. =head1 COPYRIGHT Copyright (c) 2007 - 2010 L e L do local::lib como listados em L. =head1 LICENÇA Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos do perl. local-lib-2.000018/lib/POD2/DE/local/000755 000765 000024 00000000000 12614451477 016732 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/POD2/DE/local/lib.pod000644 000765 000024 00000040462 12267332110 020174 0ustar00gknopstaff000000 000000 =encoding utf8 =head1 NAME local::lib~[de] - Erschaffen und benutzen von Perl Modulen in einem lokalen lib/ Verzeichnis mit PERL5LIB =head1 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" =head2 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: L. 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 C<. ~/.bashrc>, und in C Shell würde man es mit: C 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 C<--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 C<< use FindBin >> in dem "Im Code" Beispiel oben. Wenn du sowas machst, und du hast damit z.B. Perl Module nach C<< ~/mydir1/lib >> installiert und du hast ein Script in C<< ~/mydir1/scripts/myscript.pl >>, du musst dort angeben das die Module die es braucht im Verzeichnis C<< ~/mydir1/lib >> liegen. In C<< ~/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. =head2 Unterschiede bei Benutzung dieses Module mit Win32 Um die nötigen Umgebungsvariablen für diese Variablen in der derzeitigen Sitzung mit C 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 L 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. =head1 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. =head1 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 C 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 C<@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: =over 4 =item PERL_MB_OPT =item PERL_MM_OPT =item PERL5LIB =item PATH Am PATH wird natürlich angehangen, und nicht ersetzt. =back Diese Werte sind dann verfügbar für jeden Code der danach importiert wurde. =head1 ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN Mit L 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). =head1 METHODEN =head2 ensure_dir_structure_for =over 4 =item Parameter: $path =item Rückgabewert: Keiner =back Versucht den angegebenen Pfad anzulegen, mit allen nötigen drüberliegenden Verzeichnissen. Im Fehlerfall wird eine Exception geworfen. =head2 print_environment_vars_for =over 4 =item Parameter: $pfad =item Rückgabewert: Keiner =back Gibt die Umgebungsvariablen aus, die benötigt werden um den angegebenen Pfad als Basis Verzeichnis zu nutzen. =head2 build_environment_vars_for =over 4 =item Parameter: $pfad, $interpolate =item Rückgabewert: \%umgebungs_variablen =back Gibt ein Hash zurück mit den Variablen die nötig sind in den Umgebungsvariablen um eine Installation in dem gegebenen Pfad zu benutzen. =head2 setup_env_hash_for =over 4 =item Parameter: $pfad =item Rückgabewert: Keiner =back Setzt die C<%ENV> Einträge basierend auf dem Aufruf von L. =head2 install_base_perl_path =over 4 =item Parameter: $pfad =item Rückgabewert: $module_installations_pfad =back Gibt den Pfad zurück der benutzt wird um Perl Module zu installieren bei dem gegebenen Pfad als Basis. Prinzipiell wird nur C und C als Pfadelemente angehangen. =head2 install_base_arch_path =over 4 =item Parameter: $pfad =item Rückgabewert: $architektur_module_installations_pfad =back 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 L zurückgibt, and appends the value of C<$Config{archname}>.asis. =head2 install_base_bin_path =over 4 =item Parameter: $pfad =item Rückgabewert: $ausfuehrbare_programme_installations_pfad =back Gibt den Pfad zurück, wo ausführbare Programme installiert werden, basierend auf der Basis des angegebenen Pfad. Basierend auf L Rückgabewert, hängt diese Methode noch C an. =head2 resolve_empty_path =over 4 =item Parameter: $pfad =item Rückgabewert: $basis_pfad =back Erstellt und gibt zurück den Pfad der benutzt wird als Basis zur Installation der Module. Standardmäßig dies ist C<~/perl5>. =head2 resolve_home_path( $path ) =over 4 =item Parameter: $pfad =item Rückgabewert: $home =back Versucht das Home Verzeichnis vom aktullen User zu finden. Wenn C installiert ist, für dieses benutzt dafür. Es wird eine Exception geworfen, wenn kein Home Verzeichnis ermittelt werden konnte. =head2 resolve_relative_path =over 4 =item Parameter: $pfad =item Rückgabewert: $absoluter_pfad =back Macht aus dem angegebenen Pfad einen absoluten Pfad. =head2 resolve_path =over 4 =item Parameter: $pfad =item Rückgabewert: $absoluter_pfad =back 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: L, L, L. Der daraus resultierende Pfad wird zu L übergeben, dessen Resultat dann weitergegeben wird an L, wessen Resultat dann weitergegeben wird an L. Dieses Resultat wird dann final an L übergeben, welches dann den Rückgabewert stellt. =head1 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. =head1 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 B 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 C 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. =head1 FEHLERANALYSE Wenn du local::lib konfiguriert hast CPAN Module in deinem Home Verzeichnis zu installieren, und du danach versuchst mit C ein Modul zu installieren, und dabei einen Fehler bekommst, wie: C und in der installationsausgabe steht irgendwo ein Fehler der sagt C<'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 C Abschliessend dann nochmal mit C installieren und die Probleme sollten verschwunden sein. =head1 UMGEBUNGSVARIABLEN =over 4 =item SHELL =item COMSPEC local::lib schaut in die C Umgebungsvariable um die korrekten Kommandos zu der Shell Konfiguration hinzuzufügen. Auf Win32 Systemen, C wird auch analysiert. =back =head1 SUPPORT IRC: Wir sind im Channel #local-lib auf dem Server irc.perl.org. =head1 AUTOR DER ÜBERSETZUNG Torsten Raudssus http://www.raudssus.de/ =head1 URHEBERRECHT Copyright (c) 2007 - 2010 von den local::lib L und L aufgelistet in L. =head1 LIZENZ Diese Sammlung ist freie Software und kann unter der selben Lizenz verbreitet werden wie Perl selber. =cut 1; local-lib-2.000018/lib/local/lib.pm000644 000765 000024 00000117065 12614451410 017037 0ustar00gknopstaff000000 000000 package local::lib; use 5.006; use strict; use warnings; use Config; our $VERSION = '2.000018'; $VERSION = eval $VERSION; BEGIN { *_WIN32 = ($^O eq 'MSWin32' || $^O eq 'NetWare' || $^O eq 'symbian') ? sub(){1} : sub(){0}; # punt on these systems *_USE_FSPEC = ($^O eq 'MacOS' || $^O eq 'VMS' || $INC{'File/Spec.pm'}) ? sub(){1} : sub(){0}; } our $_DIR_JOIN = _WIN32 ? '\\' : '/'; our $_DIR_SPLIT = (_WIN32 || $^O eq 'cygwin') ? qr{[\\/]} : qr{/}; our $_ROOT = _WIN32 ? do { my $UNC = qr{[\\/]{2}[^\\/]+[\\/][^\\/]+}; qr{^(?:$UNC|[A-Za-z]:|)$_DIR_SPLIT}; } : qr{^/}; our $_PERL; sub _cwd { my $drive = shift; if (!$_PERL) { ($_PERL) = $^X =~ /(.+)/; # $^X is internal how could it be tainted?! if (_is_abs($_PERL)) { } elsif (-x $Config{perlpath}) { $_PERL = $Config{perlpath}; } else { ($_PERL) = map { /(.*)/ } grep { -x $_ } map { join($_DIR_JOIN, $_, $_PERL) } split /\Q$Config{path_sep}\E/, $ENV{PATH}; } } local @ENV{qw(PATH IFS CDPATH ENV BASH_ENV)}; my $cmd = $drive ? "eval { Cwd::getdcwd(q($drive)) }" : 'getcwd'; my $cwd = `"$_PERL" -MCwd -le "print $cmd"`; chomp $cwd; if (!length $cwd && $drive) { $cwd = $drive; } $cwd =~ s/$_DIR_SPLIT?$/$_DIR_JOIN/; $cwd; } sub _catdir { if (_USE_FSPEC) { require File::Spec; File::Spec->catdir(@_); } else { my $dir = join($_DIR_JOIN, @_); $dir =~ s{($_DIR_SPLIT)(?:\.?$_DIR_SPLIT)+}{$1}g; $dir; } } sub _is_abs { if (_USE_FSPEC) { require File::Spec; File::Spec->file_name_is_absolute($_[0]); } else { $_[0] =~ $_ROOT; } } sub _rel2abs { my ($dir, $base) = @_; return $dir if _is_abs($dir); $base = _WIN32 && $dir =~ s/^([A-Za-z]:)// ? _cwd("$1") : $base ? $base : _cwd; return _catdir($base, $dir); } our $_DEVNULL; sub _devnull { return $_DEVNULL ||= _USE_FSPEC ? (require File::Spec, File::Spec->devnull) : _WIN32 ? 'nul' : $^O eq 'os2' ? '/dev/nul' : '/dev/null'; } sub import { my ($class, @args) = @_; push @args, @ARGV if $0 eq '-'; my @steps; my %opts; my %attr; my $shelltype; while (@args) { my $arg = shift @args; # check for lethal dash first to stop processing before causing problems # the fancy dash is U+2212 or \xE2\x88\x92 if ($arg =~ /\xE2\x88\x92/) { die <<'DEATH'; WHOA THERE! It looks like you've got some fancy dashes in your commandline! These are *not* the traditional -- dashes that software recognizes. You probably got these by copy-pasting from the perldoc for this module as rendered by a UTF8-capable formatter. This most typically happens on an OS X terminal, but can happen elsewhere too. Please try again after replacing the dashes with normal minus signs. DEATH } elsif ($arg eq '--self-contained') { die <<'DEATH'; FATAL: The local::lib --self-contained flag has never worked reliably and the original author, Mark Stosberg, was unable or unwilling to maintain it. As such, this flag has been removed from the local::lib codebase in order to prevent misunderstandings and potentially broken builds. The local::lib authors recommend that you look at the lib::core::only module shipped with this distribution in order to create a more robust environment that is equivalent to what --self-contained provided (although quite possibly not what you originally thought it provided due to the poor quality of the documentation, for which we apologise). DEATH } elsif( $arg =~ /^--deactivate(?:=(.*))?$/ ) { my $path = defined $1 ? $1 : shift @args; push @steps, ['deactivate', $path]; } elsif ( $arg eq '--deactivate-all' ) { push @steps, ['deactivate_all']; } elsif ( $arg =~ /^--shelltype(?:=(.*))?$/ ) { $shelltype = defined $1 ? $1 : shift @args; } elsif ( $arg eq '--no-create' ) { $opts{no_create} = 1; } elsif ( $arg eq '--quiet' ) { $attr{quiet} = 1; } elsif ( $arg =~ /^--/ ) { die "Unknown import argument: $arg"; } else { push @steps, ['activate', $arg, \%opts]; } } if (!@steps) { push @steps, ['activate', undef, \%opts]; } my $self = $class->new(%attr); for (@steps) { my ($method, @args) = @$_; $self = $self->$method(@args); } if ($0 eq '-') { print $self->environment_vars_string($shelltype); exit 0; } else { $self->setup_local_lib; } } sub new { my $class = shift; bless {@_}, $class; } sub clone { my $self = shift; bless {%$self, @_}, ref $self; } sub inc { $_[0]->{inc} ||= \@INC } sub libs { $_[0]->{libs} ||= [ \'PERL5LIB' ] } sub bins { $_[0]->{bins} ||= [ \'PATH' ] } sub roots { $_[0]->{roots} ||= [ \'PERL_LOCAL_LIB_ROOT' ] } sub extra { $_[0]->{extra} ||= {} } sub quiet { $_[0]->{quiet} } my $_archname = $Config{archname}; my $_version = $Config{version}; my @_inc_version_list = reverse split / /, $Config{inc_version_list}; my $_path_sep = $Config{path_sep}; sub _as_list { my $list = shift; grep length, map { !(ref $_ && ref $_ eq 'SCALAR') ? $_ : ( defined $ENV{$$_} ? split(/\Q$_path_sep/, $ENV{$$_}) : () ) } ref $list ? @$list : $list; } sub _remove_from { my ($list, @remove) = @_; return @$list if !@remove; my %remove = map { $_ => 1 } @remove; grep !$remove{$_}, _as_list($list); } my @_lib_subdirs = ( [$_version, $_archname], [$_version], [$_archname], (@_inc_version_list ? \@_inc_version_list : ()), [], ); sub install_base_bin_path { my ($class, $path) = @_; return _catdir($path, 'bin'); } sub install_base_perl_path { my ($class, $path) = @_; return _catdir($path, 'lib', 'perl5'); } sub install_base_arch_path { my ($class, $path) = @_; _catdir($class->install_base_perl_path($path), $_archname); } sub lib_paths_for { my ($class, $path) = @_; my $base = $class->install_base_perl_path($path); return map { _catdir($base, @$_) } @_lib_subdirs; } sub _mm_escape_path { my $path = shift; $path =~ s/\\/\\\\/g; if ($path =~ s/ /\\ /g) { $path = qq{"$path"}; } return $path; } sub _mb_escape_path { my $path = shift; $path =~ s/\\/\\\\/g; return qq{"$path"}; } sub installer_options_for { my ($class, $path) = @_; return ( PERL_MM_OPT => defined $path ? "INSTALL_BASE="._mm_escape_path($path) : undef, PERL_MB_OPT => defined $path ? "--install_base "._mb_escape_path($path) : undef, ); } sub active_paths { my ($self) = @_; $self = ref $self ? $self : $self->new; return grep { # screen out entries that aren't actually reflected in @INC my $active_ll = $self->install_base_perl_path($_); grep { $_ eq $active_ll } @{$self->inc}; } _as_list($self->roots); } sub deactivate { my ($self, $path) = @_; $self = $self->new unless ref $self; $path = $self->resolve_path($path); $path = $self->normalize_path($path); my @active_lls = $self->active_paths; if (!grep { $_ eq $path } @active_lls) { warn "Tried to deactivate inactive local::lib '$path'\n"; return $self; } my %args = ( bins => [ _remove_from($self->bins, $self->install_base_bin_path($path)) ], libs => [ _remove_from($self->libs, $self->install_base_perl_path($path)) ], inc => [ _remove_from($self->inc, $self->lib_paths_for($path)) ], roots => [ _remove_from($self->roots, $path) ], ); $args{extra} = { $self->installer_options_for($args{roots}[0]) }; $self->clone(%args); } sub deactivate_all { my ($self) = @_; $self = $self->new unless ref $self; my @active_lls = $self->active_paths; my %args; if (@active_lls) { %args = ( bins => [ _remove_from($self->bins, map $self->install_base_bin_path($_), @active_lls) ], libs => [ _remove_from($self->libs, map $self->install_base_perl_path($_), @active_lls) ], inc => [ _remove_from($self->inc, map $self->lib_paths_for($_), @active_lls) ], roots => [ _remove_from($self->roots, @active_lls) ], ); } $args{extra} = { $self->installer_options_for(undef) }; $self->clone(%args); } sub activate { my ($self, $path, $opts) = @_; $opts ||= {}; $self = $self->new unless ref $self; $path = $self->resolve_path($path); $self->ensure_dir_structure_for($path, { quiet => $self->quiet }) unless $opts->{no_create}; $path = $self->normalize_path($path); my @active_lls = $self->active_paths; if (grep { $_ eq $path } @active_lls[1 .. $#active_lls]) { $self = $self->deactivate($path); } my %args; if ($opts->{always} || !@active_lls || $active_lls[0] ne $path) { %args = ( bins => [ $self->install_base_bin_path($path), @{$self->bins} ], libs => [ $self->install_base_perl_path($path), @{$self->libs} ], inc => [ $self->lib_paths_for($path), @{$self->inc} ], roots => [ $path, @{$self->roots} ], ); } $args{extra} = { $self->installer_options_for($path) }; $self->clone(%args); } sub normalize_path { my ($self, $path) = @_; $path = ( Win32::GetShortPathName($path) || $path ) if $^O eq 'MSWin32'; return $path; } sub build_environment_vars_for { my $self = $_[0]->new->activate($_[1], { always => 1 }); $self->build_environment_vars; } sub build_activate_environment_vars_for { my $self = $_[0]->new->activate($_[1], { always => 1 }); $self->build_environment_vars; } sub build_deactivate_environment_vars_for { my $self = $_[0]->new->deactivate($_[1]); $self->build_environment_vars; } sub build_deact_all_environment_vars_for { my $self = $_[0]->new->deactivate_all; $self->build_environment_vars; } sub build_environment_vars { my $self = shift; ( PATH => join($_path_sep, _as_list($self->bins)), PERL5LIB => join($_path_sep, _as_list($self->libs)), PERL_LOCAL_LIB_ROOT => join($_path_sep, _as_list($self->roots)), %{$self->extra}, ); } sub setup_local_lib_for { my $self = $_[0]->new->activate($_[1]); $self->setup_local_lib; } sub setup_local_lib { my $self = shift; # if Carp is already loaded, ensure Carp::Heavy is also loaded, to avoid # $VERSION mismatch errors (Carp::Heavy loads Carp, so we do not need to # check in the other direction) require Carp::Heavy if $INC{'Carp.pm'}; $self->setup_env_hash; @INC = @{$self->inc}; } sub setup_env_hash_for { my $self = $_[0]->new->activate($_[1]); $self->setup_env_hash; } sub setup_env_hash { my $self = shift; my %env = $self->build_environment_vars; for my $key (keys %env) { if (defined $env{$key}) { $ENV{$key} = $env{$key}; } else { delete $ENV{$key}; } } } sub print_environment_vars_for { print $_[0]->environment_vars_string_for(@_[1..$#_]); } sub environment_vars_string_for { my $self = $_[0]->new->activate($_[1], { always => 1}); $self->environment_vars_string; } sub environment_vars_string { my ($self, $shelltype) = @_; $shelltype ||= $self->guess_shelltype; my $extra = $self->extra; my @envs = ( PATH => $self->bins, PERL5LIB => $self->libs, PERL_LOCAL_LIB_ROOT => $self->roots, map { $_ => $extra->{$_} } sort keys %$extra, ); $self->_build_env_string($shelltype, \@envs); } sub _build_env_string { my ($self, $shelltype, $envs) = @_; my @envs = @$envs; my $build_method = "build_${shelltype}_env_declaration"; my $out = ''; while (@envs) { my ($name, $value) = (shift(@envs), shift(@envs)); if ( ref $value && @$value == 1 && ref $value->[0] && ref $value->[0] eq 'SCALAR' && ${$value->[0]} eq $name) { next; } $out .= $self->$build_method($name, $value); } my $wrap_method = "wrap_${shelltype}_output"; if ($self->can($wrap_method)) { return $self->$wrap_method($out); } return $out; } sub build_bourne_env_declaration { my ($class, $name, $args) = @_; my $value = $class->_interpolate($args, '${%s}', qr/["\\\$!`]/, '\\%s'); if (!defined $value) { return qq{unset $name;\n}; } $value =~ s/(^|\G|$_path_sep)\$\{$name\}$_path_sep/$1\${$name}\${$name+$_path_sep}/g; $value =~ s/$_path_sep\$\{$name\}$/\${$name+$_path_sep}\${$name}/; qq{${name}="$value"; export ${name};\n} } sub build_csh_env_declaration { my ($class, $name, $args) = @_; my ($value, @vars) = $class->_interpolate($args, '${%s}', qr/["\$]/, '"\\%s"'); if (!defined $value) { return qq{unsetenv $name;\n}; } my $out = ''; for my $var (@vars) { $out .= qq{if ! \$?$name setenv $name '';\n}; } my $value_without = $value; if ($value_without =~ s/(?:^|$_path_sep)\$\{$name\}(?:$_path_sep|$)//g) { $out .= qq{if "\${$name}" != '' setenv $name "$value";\n}; $out .= qq{if "\${$name}" == '' }; } $out .= qq{setenv $name "$value_without";\n}; return $out; } sub build_cmd_env_declaration { my ($class, $name, $args) = @_; my $value = $class->_interpolate($args, '%%%s%%', qr(%), '%s'); if (!$value) { return qq{\@set $name=\n}; } my $out = ''; my $value_without = $value; if ($value_without =~ s/(?:^|$_path_sep)%$name%(?:$_path_sep|$)//g) { $out .= qq{\@if not "%$name%"=="" set "$name=$value"\n}; $out .= qq{\@if "%$name%"=="" }; } $out .= qq{\@set "$name=$value_without"\n}; return $out; } sub build_powershell_env_declaration { my ($class, $name, $args) = @_; my $value = $class->_interpolate($args, '$env:%s', qr/["\$]/, '`%s'); if (!$value) { return qq{Remove-Item -ErrorAction 0 Env:\\$name;\n}; } my $maybe_path_sep = qq{\$(if("\$env:$name"-eq""){""}else{"$_path_sep"})}; $value =~ s/(^|\G|$_path_sep)\$env:$name$_path_sep/$1\$env:$name"+$maybe_path_sep+"/g; $value =~ s/$_path_sep\$env:$name$/"+$maybe_path_sep+\$env:$name+"/; qq{\$env:$name = \$("$value");\n}; } sub wrap_powershell_output { my ($class, $out) = @_; return $out || " \n"; } sub build_fish_env_declaration { my ($class, $name, $args) = @_; my $value = $class->_interpolate($args, '$%s', qr/[\\"'$ ]/, '\\%s'); if (!defined $value) { return qq{set -e $name;\n}; } # fish has special handling for PATH, CDPATH, and MANPATH. They are always # treated as arrays, and joined with ; when storing the environment. Other # env vars can be arrays, but will be joined without a separator. We only # really care about PATH, but might as well make this routine more general. if ($name =~ /^(?:CD|MAN)?PATH$/) { $value =~ s/$_path_sep/ /g; my $silent = $name =~ /^(?:CD)?PATH$/ ? " ^"._devnull : ''; return qq{set -x $name $value$silent;\n}; } my $out = ''; my $value_without = $value; if ($value_without =~ s/(?:^|$_path_sep)\$$name(?:$_path_sep|$)//g) { $out .= qq{set -q $name; and set -x $name $value;\n}; $out .= qq{set -q $name; or }; } $out .= qq{set -x $name $value_without;\n}; $out; } sub _interpolate { my ($class, $args, $var_pat, $escape, $escape_pat) = @_; return unless defined $args; my @args = ref $args ? @$args : $args; return unless @args; my @vars = map { $$_ } grep { ref $_ eq 'SCALAR' } @args; my $string = join $_path_sep, map { ref $_ eq 'SCALAR' ? sprintf($var_pat, $$_) : do { s/($escape)/sprintf($escape_pat, $1)/ge; $_; }; } @args; return wantarray ? ($string, \@vars) : $string; } sub pipeline; sub pipeline { my @methods = @_; my $last = pop(@methods); if (@methods) { \sub { my ($obj, @args) = @_; $obj->${pipeline @methods}( $obj->$last(@args) ); }; } else { \sub { shift->$last(@_); }; } } sub resolve_path { my ($class, $path) = @_; $path = $class->${pipeline qw( resolve_relative_path resolve_home_path resolve_empty_path )}($path); $path; } sub resolve_empty_path { my ($class, $path) = @_; if (defined $path) { $path; } else { '~/perl5'; } } sub resolve_home_path { my ($class, $path) = @_; $path =~ /^~([^\/]*)/ or return $path; my $user = $1; my $homedir = do { if (! length($user) && defined $ENV{HOME}) { $ENV{HOME}; } else { require File::Glob; File::Glob::bsd_glob("~$user", File::Glob::GLOB_TILDE()); } }; unless (defined $homedir) { require Carp; require Carp::Heavy; Carp::croak( "Couldn't resolve homedir for " .(defined $user ? $user : 'current user') ); } $path =~ s/^~[^\/]*/$homedir/; $path; } sub resolve_relative_path { my ($class, $path) = @_; _rel2abs($path); } sub ensure_dir_structure_for { my ($class, $path, $opts) = @_; $opts ||= {}; my @dirs; foreach my $dir ( $class->lib_paths_for($path), $class->install_base_bin_path($path), ) { my $d = $dir; while (!-d $d) { push @dirs, $d; require File::Basename; $d = File::Basename::dirname($d); } } warn "Attempting to create directory ${path}\n" if !$opts->{quiet} && @dirs; my %seen; foreach my $dir (reverse @dirs) { next if $seen{$dir}++; mkdir $dir or -d $dir or die "Unable to create $dir: $!" } return; } sub guess_shelltype { my $shellbin = defined $ENV{SHELL} ? ($ENV{SHELL} =~ /([\w.]+)$/)[-1] : ( $^O eq 'MSWin32' && exists $ENV{'!EXITCODE'} ) ? 'bash' : ( $^O eq 'MSWin32' && $ENV{PROMPT} && $ENV{COMSPEC} ) ? ($ENV{COMSPEC} =~ /([\w.]+)$/)[-1] : ( $^O eq 'MSWin32' && !$ENV{PROMPT} ) ? 'powershell.exe' : 'sh'; for ($shellbin) { return /csh$/ ? 'csh' : /fish$/ ? 'fish' : /command(?:\.com)?$/i ? 'cmd' : /cmd(?:\.exe)?$/i ? 'cmd' : /4nt(?:\.exe)?$/i ? 'cmd' : /powershell(?:\.exe)?$/i ? 'powershell' : 'bourne'; } } 1; __END__ =encoding utf8 =head1 NAME local::lib - create and use a local lib/ for perl modules with PERL5LIB =head1 SYNOPSIS In code - use local::lib; # sets up a local lib at ~/perl5 use local::lib '~/foo'; # same, but ~/foo # Or... use FindBin; use local::lib "$FindBin::Bin/../support"; # app-local support library From the shell - # Install LWP and its missing dependencies to the '~/perl5' directory perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)' # Just print out useful shell commands $ perl -Mlocal::lib PERL_MB_OPT='--install_base /home/username/perl5'; export PERL_MB_OPT; PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'; export PERL_MM_OPT; PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB; PATH="/home/username/perl5/bin:$PATH"; export PATH; PERL_LOCAL_LIB_ROOT="/home/usename/perl5:$PERL_LOCAL_LIB_ROOT"; export PERL_LOCAL_LIB_ROOT; From a F<.bash_profile> or F<.bashrc> file - eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" =head2 The bootstrapping technique A typical way to install local::lib is using what is known as the "bootstrapping" technique. You would do this if your system administrator hasn't already installed local::lib. In this case, you'll need to install local::lib in your home directory. Even if you do have administrative privileges, you will still want to set up your environment variables, as discussed in step 4. Without this, you would still install the modules into the system CPAN installation and also your Perl scripts will not use the lib/ path you bootstrapped with local::lib. By default local::lib installs itself and the CPAN modules into ~/perl5. Windows users must also see L. =over 4 =item 1. Download and unpack the local::lib tarball from CPAN (search for "Download" on the CPAN page about local::lib). Do this as an ordinary user, not as root or administrator. Unpack the file in your home directory or in any other convenient location. =item 2. Run this: perl Makefile.PL --bootstrap If the system asks you whether it should automatically configure as much as possible, you would typically answer yes. In order to install local::lib into a directory other than the default, you need to specify the name of the directory when you call bootstrap, as follows: perl Makefile.PL --bootstrap=~/foo =item 3. Run this: (local::lib assumes you have make installed on your system) make test && make install =item 4. Now we need to setup the appropriate environment variables, so that Perl starts using our newly generated lib/ directory. If you are using bash or any other Bourne shells, you can add this to your shell startup script this way: echo 'eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc If you are using C shell, you can do this as follows: /bin/csh echo $SHELL /bin/csh echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc If you passed to bootstrap a directory other than default, you also need to give that as import parameter to the call of the local::lib module like this way: echo 'eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc After writing your shell configuration file, be sure to re-read it to get the changed settings into your current shell's environment. Bourne shells use C<. ~/.bashrc> for this, whereas C shells use C. =back If you're on a slower machine, or are operating under draconian disk space limitations, you can disable the automatic generation of manpages from POD when installing modules by using the C<--no-manpages> argument when bootstrapping: perl Makefile.PL --bootstrap --no-manpages To avoid doing several bootstrap for several Perl module environments on the same account, for example if you use it for several different deployed applications independently, you can use one bootstrapped local::lib installation to install modules in different directories directly this way: cd ~/mydir1 perl -Mlocal::lib=./ eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone printenv ### You will see that ~/mydir1 is in the PERL5LIB perl -MCPAN -e install ... ### whatever modules you want cd ../mydir2 ... REPEAT ... If you use F<.bashrc> to activate a local::lib automatically, the local::lib will be re-enabled in any sub-shells used, overriding adjustments you may have made in the parent shell. To avoid this, you can initialize the local::lib in F<.bash_profile> rather than F<.bashrc>, or protect the local::lib invocation with a C<$SHLVL> check: [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" If you are working with several C environments, you may want to remove some of them from the current environment without disturbing the others. You can deactivate one environment like this (using bourne sh): eval $(perl -Mlocal::lib=--deactivate,~/path) which will generate and run the commands needed to remove C<~/path> from your various search paths. Whichever environment was B will remain the target for module installations. That is, if you activate C<~/path_A> and then you activate C<~/path_B>, new modules you install will go in C<~/path_B>. If you deactivate C<~/path_B> then modules will be installed into C<~/pathA> -- but if you deactivate C<~/path_A> then they will still be installed in C<~/pathB> because pathB was activated later. You can also ask C to clean itself completely out of the current shell's environment with the C<--deactivate-all> option. For multiple environments for multiple apps you may need to include a modified version of the C<< use FindBin >> instructions in the "In code" sample above. If you did something like the above, you have a set of Perl modules at C<< ~/mydir1/lib >>. If you have a script at C<< ~/mydir1/scripts/myscript.pl >>, you need to tell it where to find the modules you installed for it at C<< ~/mydir1/lib >>. In C<< ~/mydir1/scripts/myscript.pl >>: use strict; use warnings; use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib Put this before any BEGIN { ... } blocks that require the modules you installed. =head2 Differences when using this module under Win32 To set up the proper environment variables for your current session of C, you can use this: 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 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH% ### To set the environment for this shell alone C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat ### instead of $(perl -Mlocal::lib=./) If you want the environment entries to persist, you'll need to add them to the Control Panel's System applet yourself or use L. The "~" is translated to the user's profile directory (the directory named for the user under "Documents and Settings" (Windows XP or earlier) or "Users" (Windows Vista or later)) unless $ENV{HOME} exists. After that, the home directory is translated to a short name (which means the directory must exist) and the subdirectories are created. =head3 PowerShell local::lib also supports PowerShell, and can be used with the C cmdlet. Invoke-Expression "$(perl -Mlocal::lib)" =head1 RATIONALE The version of a Perl package on your machine is not always the version you need. Obviously, the best thing to do would be to update to the version you need. However, you might be in a situation where you're prevented from doing this. Perhaps you don't have system administrator privileges; or perhaps you are using a package management system such as Debian, and nobody has yet gotten around to packaging up the version you need. local::lib solves this problem by allowing you to create your own directory of Perl packages downloaded from CPAN (in a multi-user system, this would typically be within your own home directory). The existing system Perl installation is not affected; you simply invoke Perl with special options so that Perl uses the packages in your own local package directory rather than the system packages. local::lib arranges things so that your locally installed version of the Perl packages takes precedence over the system installation. If you are using a package management system (such as Debian), you don't need to worry about Debian and CPAN stepping on each other's toes. Your local version of the packages will be written to an entirely separate directory from those installed by Debian. =head1 DESCRIPTION This module provides a quick, convenient way of bootstrapping a user-local Perl module library located within the user's home directory. It also constructs and prints out for the user the list of environment variables using the syntax appropriate for the user's current shell (as specified by the C environment variable), suitable for directly adding to one's shell configuration file. More generally, local::lib allows for the bootstrapping and usage of a directory containing Perl modules outside of Perl's C<@INC>. This makes it easier to ship an application with an app-specific copy of a Perl module, or collection of modules. Useful in cases like when an upstream maintainer hasn't applied a patch to a module of theirs that you need for your application. On import, local::lib sets the following environment variables to appropriate values: =over 4 =item PERL_MB_OPT =item PERL_MM_OPT =item PERL5LIB =item PATH =item PERL_LOCAL_LIB_ROOT =back When possible, these will be appended to instead of overwritten entirely. These values are then available for reference by any code after import. =head1 CREATING A SELF-CONTAINED SET OF MODULES See L for one way to do this - but note that there are a number of caveats, and the best approach is always to perform a build against a clean perl (i.e. site and vendor as close to empty as possible). =head1 IMPORT OPTIONS Options are values that can be passed to the C import besides the directory to use. They are specified as C or C. =head2 --deactivate Remove the chosen path (or the default path) from the module search paths if it was added by C, instead of adding it. =head2 --deactivate-all Remove all directories that were added to search paths by C from the search paths. =head2 --shelltype Specify the shell type to use for output. By default, the shell will be detected based on the environment. Should be one of: C, C, C, or C. =head2 --no-create Prevents C from creating directories when activating dirs. This is likely to cause issues on Win32 systems. =head1 CLASS METHODS =head2 ensure_dir_structure_for =over 4 =item Arguments: $path =item Return value: None =back Attempts to create a local::lib directory, including subdirectories and all required parent directories. Throws an exception on failure. =head2 print_environment_vars_for =over 4 =item Arguments: $path =item Return value: None =back Prints to standard output the variables listed above, properly set to use the given path as the base directory. =head2 build_environment_vars_for =over 4 =item Arguments: $path =item Return value: %environment_vars =back Returns a hash with the variables listed above, properly set to use the given path as the base directory. =head2 setup_env_hash_for =over 4 =item Arguments: $path =item Return value: None =back Constructs the C<%ENV> keys for the given path, by calling L. =head2 active_paths =over 4 =item Arguments: None =item Return value: @paths =back Returns a list of active C paths, according to the C environment variable and verified against what is really in C<@INC>. =head2 install_base_perl_path =over 4 =item Arguments: $path =item Return value: $install_base_perl_path =back Returns a path describing where to install the Perl modules for this local library installation. Appends the directories C and C to the given path. =head2 lib_paths_for =over 4 =item Arguments: $path =item Return value: @lib_paths =back Returns the list of paths perl will search for libraries, given a base path. This includes the base path itself, the architecture specific subdirectory, and perl version specific subdirectories. These paths may not all exist. =head2 install_base_bin_path =over 4 =item Arguments: $path =item Return value: $install_base_bin_path =back Returns a path describing where to install the executable programs for this local library installation. Appends the directory C to the given path. =head2 installer_options_for =over 4 =item Arguments: $path =item Return value: %installer_env_vars =back Returns a hash of environment variables that should be set to cause installation into the given path. =head2 resolve_empty_path =over 4 =item Arguments: $path =item Return value: $base_path =back Builds and returns the base path into which to set up the local module installation. Defaults to C<~/perl5>. =head2 resolve_home_path =over 4 =item Arguments: $path =item Return value: $home_path =back Attempts to find the user's home directory. If installed, uses C for this purpose. If no definite answer is available, throws an exception. =head2 resolve_relative_path =over 4 =item Arguments: $path =item Return value: $absolute_path =back Translates the given path into an absolute path. =head2 resolve_path =over 4 =item Arguments: $path =item Return value: $absolute_path =back Calls the following in a pipeline, passing the result from the previous to the next, in an attempt to find where to configure the environment for a local library installation: L, L, L. Passes the given path argument to L which then returns a result that is passed to L, which then has its result passed to L. The result of this final call is returned from L. =head1 OBJECT INTERFACE =head2 new =over 4 =item Arguments: %attributes =item Return value: $local_lib =back Constructs a new C object, representing the current state of C<@INC> and the relevant environment variables. =head1 ATTRIBUTES =head2 roots An arrayref representing active C directories. =head2 inc An arrayref representing C<@INC>. =head2 libs An arrayref representing the PERL5LIB environment variable. =head2 bins An arrayref representing the PATH environment variable. =head2 extra A hashref of extra environment variables (e.g. C and C) =head2 no_create If set, C will not try to create directories when activating them. =head1 OBJECT METHODS =head2 clone =over 4 =item Arguments: %attributes =item Return value: $local_lib =back Constructs a new C object based on the existing one, overriding the specified attributes. =head2 activate =over 4 =item Arguments: $path =item Return value: $new_local_lib =back Constructs a new instance with the specified path active. =head2 deactivate =over 4 =item Arguments: $path =item Return value: $new_local_lib =back Constructs a new instance with the specified path deactivated. =head2 deactivate_all =over 4 =item Arguments: None =item Return value: $new_local_lib =back Constructs a new instance with all C directories deactivated. =head2 environment_vars_string =over 4 =item Arguments: [ $shelltype ] =item Return value: $shell_env_string =back Returns a string to set up the C, meant to be run by a shell. =head2 build_environment_vars =over 4 =item Arguments: None =item Return value: %environment_vars =back Returns a hash with the variables listed above, properly set to use the given path as the base directory. =head2 setup_env_hash =over 4 =item Arguments: None =item Return value: None =back Constructs the C<%ENV> keys for the given path, by calling L. =head2 setup_local_lib Constructs the C<%ENV> hash using L, and set up C<@INC>. =head1 A WARNING ABOUT UNINST=1 Be careful about using local::lib in combination with "make install UNINST=1". The idea of this feature is that will uninstall an old version of a module before installing a new one. However it lacks a safety check that the old version and the new version will go in the same directory. Used in combination with local::lib, you can potentially delete a globally accessible version of a module while installing the new version in a local place. Only combine "make install UNINST=1" and local::lib if you understand these possible consequences. =head1 LIMITATIONS =over 4 =item * Directory names with spaces in them are not well supported by the perl toolchain and the programs it uses. Pure-perl distributions should support spaces, but problems are more likely with dists that require compilation. A workaround you can do is moving your local::lib to a directory with spaces B you installed all modules inside your local::lib bootstrap. But be aware that you can't update or install CPAN modules after the move. =item * Rather basic shell detection. Right now anything with csh in its name is assumed to be a C shell or something compatible, and everything else is assumed to be Bourne, except on Win32 systems. If the C environment variable is not set, a Bourne-compatible shell is assumed. =item * Kills any existing PERL_MM_OPT or PERL_MB_OPT. =item * Should probably auto-fixup CPAN config if not already done. =item * On VMS and MacOS Classic (pre-OS X), local::lib loads L. This means any L version installed in the local::lib will be ignored by scripts using local::lib. A workaround for this is using C instead of using C directly. =item * Conflicts with L's C option. C uses the C option, as it has more predictable and sane behavior. If something attempts to use the C option when running a F, L will refuse to run, as the two options conflict. This can be worked around by temporarily unsetting the C environment variable. =item * Conflicts with L's C<--prefix> option. Similar to the previous limitation, but any C<--prefix> option specified will be ignored. This can be worked around by temporarily unsetting the C environment variable. =back Patches very much welcome for any of the above. =over 4 =item * On Win32 systems, does not have a way to write the created environment variables to the registry, so that they can persist through a reboot. =back =head1 TROUBLESHOOTING If you've configured local::lib to install CPAN modules somewhere in to your home directory, and at some point later you try to install a module with C, but it fails with an error like: C and buried within the install log is an error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then you've somehow lost your updated ExtUtils::MakeMaker module. To remedy this situation, rerun the bootstrapping procedure documented above. Then, run C Finally, re-run C and it should install without problems. =head1 ENVIRONMENT =over 4 =item SHELL =item COMSPEC local::lib looks at the user's C environment variable when printing out commands to add to the shell configuration file. On Win32 systems, C is also examined. =back =head1 SEE ALSO =over 4 =item * L =back =head1 SUPPORT IRC: Join #local-lib on irc.perl.org. =head1 AUTHOR Matt S Trout http://www.shadowcat.co.uk/ auto_install fixes kindly sponsored by http://www.takkle.com/ =head1 CONTRIBUTORS Patches to correctly output commands for csh style shells, as well as some documentation additions, contributed by Christopher Nehren . Doc patches for a custom local::lib directory, more cleanups in the english documentation and a L contributed by Torsten Raudssus . Hans Dieter Pearcey sent in some additional tests for ensuring things will install properly, submitted a fix for the bug causing problems with writing Makefiles during bootstrapping, contributed an example program, and submitted yet another fix to ensure that local::lib can install and bootstrap properly. Many, many thanks! pattern of Freenode IRC contributed the beginnings of the Troubleshooting section. Many thanks! Patch to add Win32 support contributed by Curtis Jewell . Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced by a patch from Marco Emilio Poleggi. Mark Stosberg provided the code for the now deleted '--self-contained' option. Documentation patches to make win32 usage clearer by David Mertens (run4flat). Brazilian L and minor doc patches contributed by Breno G. de Oliveira . Improvements to stacking multiple local::lib dirs and removing them from the environment later on contributed by Andrew Rodland . Patch for Carp version mismatch contributed by Hakim Cassimally . Rewrite of internals and numerous bug fixes and added features contributed by Graham Knop . =head1 COPYRIGHT Copyright (c) 2007 - 2013 the local::lib L and L as listed above. =head1 LICENSE This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut local-lib-2.000018/lib/lib/core/000755 000765 000024 00000000000 12614451477 016342 5ustar00gknopstaff000000 000000 local-lib-2.000018/lib/lib/core/only.pm000644 000765 000024 00000006235 12531456676 017673 0ustar00gknopstaff000000 000000 package lib::core::only; use strict; use warnings FATAL => 'all'; use Config; sub import { @INC = @Config{qw(privlibexp archlibexp)}; return } =head1 NAME lib::core::only - Remove all non-core paths from @INC to avoid site/vendor dirs =head1 SYNOPSIS use lib::core::only; # now @INC contains only the two core directories To get only the core directories plus the ones for the local::lib in scope: $ perl -mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5 myscript.pl To attempt to do a self-contained build (but note this will not reliably propagate into subprocesses, see the CAVEATS below): $ PERL5OPT='-mlocal::lib -Mlib::core::only -Mlocal::lib=~/perl5' cpan Please note that it is necessary to use C twice for this to work. First so that C doesn't prevent C from loading (it's not currently in core) and then again after C so that the local paths are not removed. =head1 DESCRIPTION lib::core::only is simply a shortcut to say "please reduce my @INC to only the core lib and archlib (architecture-specific lib) directories of this perl". You might want to do this to ensure a local::lib contains only the code you need, or to test an L tree, or to avoid known bad vendor packages. You might want to use this to try and install a self-contained tree of perl modules. Be warned that that probably won't work (see L). This module was extracted from L's --self-contained feature, and contains the only part that ever worked. I apologise to anybody who thought anything else did. =head1 CAVEATS This does B propagate properly across perl invocations like local::lib's stuff does. It can't. It's only a module import, so it B. If you want to cascade it across invocations, you can set the PERL5OPT environment variable to '-Mlib::core::only' and it'll sort of work. But be aware that taint mode ignores this, so some modules' build and test code probably will as well. You also need to be aware that perl's command line options are not processed in order - -I options take effect before -M options, so perl -Mlib::core::only -Ilib is unlike to do what you want - it's exactly equivalent to: perl -Mlib::core::only If you want to combine a core-only @INC with additional paths, you need to add the additional paths using -M options and the L module: perl -Mlib::core::only -Mlib=lib # or if you're trying to test compiled code: perl -Mlib::core::only -Mblib For more information on the impossibility of sanely propagating this across module builds without help from the build program, see L - and for ways to achieve the old --self-contained feature's results, look at L's tree function, and at L's --local-lib-contained feature. =head1 AUTHOR Matt S. Trout =head1 LICENSE This library is free software under the same terms as perl itself. =head1 COPYRIGHT (c) 2010 the lib::core::only L as specified above. =cut 1; local-lib-2.000018/inc/CheckVersion.pm000644 000765 000024 00000000721 12571546532 017567 0ustar00gknopstaff000000 000000 package inc::CheckVersion; use strict; use warnings; sub import { my $target = caller; my $result = check_version(@ARGV); exit $result; } sub check_version { my ($module, $need_v) = @_; require ExtUtils::MakeMaker; (my $file = "$module.pm") =~ s{::}{/}g; my ($pm) = grep { -e } map { "$_/$file" } @INC; if (!$pm) { return 1; } my $v = MM->parse_version($pm) || 0; $v = eval $v; if ($v >= $need_v) { return 0; } return 2; } 1; local-lib-2.000018/inc/CPAN.pm000644 000765 000024 00000006331 12571546556 015736 0ustar00gknopstaff000000 000000 package inc::CPAN; use strict; use warnings; sub import { my ($class, $op) = @_; die "no operation specified!\n" unless $op; my $do = $class->can("cmd_$op") or die "invalid operation $op\n"; $do->(@ARGV); exit 0; } sub cmd_init_config { require ExtUtils::MakeMaker; my $done; my $orig = ExtUtils::MakeMaker->can("prompt"); no warnings 'once', 'redefine'; *ExtUtils::MakeMaker::prompt = sub ($;$) { if (!$done && $_[0] =~ /manual configuration/) { $done++; return "no"; } return $orig->(@_); }; require CPAN; CPAN->import; $CPAN::Config->{urllist} = ["http://www.cpan.org/"]; CPAN::Config->load; unless ($done || -w $CPAN::Config->{keep_source_where}) { my $save = $CPAN::Config->{urllist}; delete @{$CPAN::Config}{keys %$CPAN::Config}; $CPAN::Config->{urllist} = $save; CPAN::Config->init; } } sub cmd_install { my @modules = @_; package main; require CPAN; CPAN->import; CPAN::Config->load; # ExtUtils::ParseXS is a prerequisite of Module::Build. Previously, # it included a Build.PL file. If CPAN.pm is configured to prefer # Module::Build (the default), it would see the Build.PL file and assume # MB was a prerequisite. This introduces a circular dependency, which would # break installation. None of Module::Build's prerequisites include a # Build.PL anymore, but continue to prefer EUMM as a precaution. $CPAN::Config->{prefer_installer} = "EUMM"; force('install', @modules); } sub cmd_disable_manpages { require CPAN; CPAN->import; CPAN::HandleConfig->load; $CPAN::Config->{makepl_arg} = 'INSTALLMAN1DIR=none INSTALLMAN3DIR=none'; $CPAN::Config->{buildpl_arg} = '--install_path libdoc="" --install_path bindoc=""'; CPAN::Config->commit; } # make sure that the user doesn't have any existing CPAN config that'll # cause us problems for the next few steps. sub cmd_check { my $cpan_version = shift; # if CPAN loads this, it calls into CPAN::Shell which tries to run # autoconfiguration. if it doesn't exist, we don't care eval { require File::HomeDir; }; require CPAN; # Need newish CPAN.pm for this, ergo skip it if that version of CPAN isn't # installed yet. # It will already be installed by the time we reach here if bootstrapping, # otherwise, if we're running from CPAN then it will be installed soon # enough, and we'll come back here.. if (eval { require CPAN::HandleConfig; } ) { CPAN::HandleConfig->require_myconfig_or_config; if ( $CPAN::Config ) { for my $setting (qw( makepl_arg make_install_arg mbuild_arg mbuild_install_arg mbuildpl_arg )) { my $value = $CPAN::Config->{$setting} or next; if ($setting =~ /^make/ ? $value =~ /(?:PREFIX|INSTALL_BASE)/ : $value =~ /(?:--prefix|--install_base)/ ) { die <<"DEATH"; WHOA THERE! It looks like you've got $CPAN::Config->{$setting} set in your CPAN config. This is known to cause problems with local::lib. Please either remove this setting or clear out your .cpan directory. DEATH } } } } else { # Explode if it looks like requiring CPAN::HandleConfig should # have worked, but didn't. die $@ if $CPAN::VERSION >= $cpan_version; } } 1; local-lib-2.000018/eg/scripted_install.pl000644 000765 000024 00000001034 12217002201 020337 0ustar00gknopstaff000000 000000 #!/usr/bin/perl # contributed by hdp@cpan.org use strict; use warnings; use CPAN; use Cwd; use File::Spec; my $target = $ENV{TARGET} ? Cwd::abs_path($ENV{TARGET}) : undef; my $mod = CPAN::Shell->expand(Module => "local::lib"); $mod->get; my $dir = CPAN::Shell->expand(Distribution => $mod->cpan_file)->dir; chdir($dir); my $make = $CPAN::Config->{make}; my $bootstrap = $target ? "--bootstrap=$target" : "--bootstrap"; system($^X, 'Makefile.PL', $bootstrap) && exit 1; system($make, 'test') && exit 1; system($make, 'install') && exit 1;