# Generated by Pod::WikiDoc version 0.18

=pod

=head1 NAME

ylib - Add paths to @INC from a config file

=head1 VERSION

This documentation describes version 0.002.

=head1 SYNOPSIS

   # in .mylib file
   /home/david/some/library/path
 
   # from the command line
   $ perl -Mylib -E 'say for @INC'
   /home/david/some/library/path
   ...

=head1 DESCRIPTION

The ylib module adds paths to C<<< @INC >>> from a configuration file named C<<< .mylib >>>
in which each line represents a library path.  The C<<< .mylib >>> file can be either
in the current directory andE<sol>or in the user's home directory.  It is equivalent
to calling C<<< 'use lib' >>> on each path.

Note: C<<< ylib >>> will issue a warning if a path in C<<< .mylib >>> can't be found.

=head1 USAGE

Occasionally, it's useful to customize C<<< @INC >>> on a per-directory basis without
changing the global C<<< PERL5LIB >>> environment variable.  For example, when
developing or testing code that requires uninstalled code in an adjancent
directory, one could create a C<<< .mylib >>> file that adds the necessary path.

For example, consider this directory tree with two Perl distributions, Foo-Bar
and Baz-Bam:

   ~/projects/
       Foo-Bar/
       Baz-Bam/

The code in Foo-Bar depends on code in Baz-Bam.  So in Foo-Bar, create a
C<<< .mylib >>> file with the appropriate path:

   $ cd Foo-Bar
   $ echo '../Baz-Bam/lib' > .mylib
   $ perl -Mylib Build.PL
   $ Build && Build test

That's easier and shorter than using C<<< PERL5LIB >>> on the command line, and it
scales better as the number of libraries increases.

In the example above, the C<<< Build >>> script preserve C<<< @INC >>> including the effect
of C<<< -Mylib >>> when it was created.  This is not the case with C<<< Makefile.PL >>> or
C<<< prove >>>, in which case, C<<< PERL5OPT >>> might be an alternative approach for using
C<<< -Mylib >>>:

   $ export PERL5OPT=-Mylib
   $ prove

=head1 BUGS

Please report any bugs or feature requests using the CPAN Request Tracker web
interface at L<http://rt.cpan.org/Dist/Display.html?Queue=ylib>

When submitting a bug or request, please include a test-file or a patch to an
existing test-file that illustrates the bug or desired feature.

=head1 SEE ALSO

=over

=item *

L<lib>

=item *

L<rlib>

=item *

L<local::lib>

=back

=head1 AUTHOR

David A. Golden (DAGOLDEN)

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2009 by David A. Golden. All rights reserved.

Licensed under Apache License, Version 2.0 (the "License").
You may not use this file except in compliance with the License.
A copy of the License was distributed with this file or you may obtain a 
copy of the License from http:E<sol>E<sol>www.apache.orgE<sol>licensesE<sol>LICENSE-2.0

Files produced as output though the use of this software, shall not be
considered Derivative Works, but shall be considered the original work of the
Licensor.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.