1=head1 NAME 2 3Carton::Doc::FAQ - Frequently Asked Questions 4 5=head1 QUESTIONS 6 7=head2 It looks useful, but what is the use case of this tool? 8 9The particular problem that carton is trying to address is this: 10 11You develop a Perl-based application, possibly but not limited to 12webapps, with dozens of CPAN module dependencies. You install these 13modules on your development machine, and describe these dependencies 14in your I<cpanfile>. 15 16Now you get a production environment, either on PaaS provider or some 17VPS, you install the dependencies using C<cpanm --installdeps .> and 18it will pull all the latest releases from CPAN as of today and 19everything just works. 20 21A few weeks later, your application becomes more popular, and you 22think you need another machine to serve more requests. You set up 23another machine with vanilla perl installation and install the 24dependencies the same way. That will pull the I<latest> releases from 25CPAN I<on that date>, rather than the same as what you have today. 26 27And that is the problem. It's not likely that everything just breaks 28one day, but there's always a chance that one of the dependencies 29breaks an API compatibility, or just uploaded a buggy version to CPAN 30on that particular day. 31 32Carton allows you to I<lock> these dependencies into a version 33controlled system, so that every time you deploy from a checkout, it 34is guaranteed that all the same versions are installed into the local 35environment. 36 37=head2 How is this different from Pinto or CPAN::Mini::Inject? 38 39carton definitely shares the goal with these private CPAN repository 40management tool. But the main difference is that rather than creating 41an actual CPAN-like repository that works with any CPAN clients, 42Carton provides a way to install specific versions of distributions 43from CPAN, or any CPAN-like mirrors (as well as git repositories in 44the future version of Carton). 45 46Existing tools are designed to work I<with> CPAN clients such as 47L<CPAN> or L<CPANPLUS>, and have accomplished that by working around 48the CPAN mirror structure. 49 50carton I<internally> does the same thing, but its user interface is 51centered around the installer, by implementing a wrapper for 52L<cpanm|App::cpanminus>, so you can use the same commands in the 53development mode and deployment mode. 54 55Carton automatically maintains the L<cpanfile.snapshot> file, which is meant 56to be version controlled, inside your application directory. You don't 57need a separate database, a directory or a web server to maintain 58tarballs outside your application. The I<cpanfile.snapshot> file can always 59be generated with C<carton install> command, and C<carton install> on 60another machine can use the version in the snapshot. 61 62=head2 I already use Pinto to create DarkPAN mirror. Can I use Carton with this? 63 64Yes, by specifying Pinto mirror as your Carton mirror, you can take a 65snapshot of your dependencies including your private modules on Pinto, 66or whatever DarkPAN mirror. 67 68=head2 I'm already using perlbrew and local::lib. Can I use carton with this? 69 70If you're using L<local::lib> already with L<perlbrew> perl, possibly 71with the new C<perlbrew lib> command, that's great! There are multiple 72benefits over using L<perlbrew> and L<local::lib> for development and 73use L<Carton> for deployment. 74 75The best practice and workflow to get your perl environment as clean 76as possible with lots of modules installed for quick development would 77be this: 78 79=over 80 81=item * 82 83Install fresh perl using perlbrew. The version must be the same 84against the version you'll run on the production environment. 85 86=item * 87 88Once the installation is done, use C<perlbrew lib> command to create a 89new local lib environment (let's call it I<devel>) and always use the 90library as a default environment. Install as many modules as you would 91like into the I<devel> library path. 92 93This ensures to have a vanilla C<perl> library path as clean as 94possible. 95 96=item * 97 98When you build a new project that you want to manage dependencies via 99Carton, turn off the I<devel> local::lib and create a new one, like 100I<myapp>. Install L<Carton> and all of its dependencies to the 101I<myapp> local::lib path. Then run C<carton install> like you 102normally do. 103 104Because I<devel> and I<myapp> are isolated, the modules you installed 105into I<devel> doesn't affect the process when carton builds the 106dependency tree for your new project at all. This could often be 107critical when you have a conditional dependency in your tree, like 108L<Any::Moose>. 109 110=back 111 112=head2 I'm using perlbrew, but C<< carton install >> uses system perl, how to fix? 113 114The issue is most likelly caused by a inital bad install of C<cpanm> 115or C<carton> or both, that ended up with a shebang line pointed to the 116(wrong) system perl. 117 118=over 4 119 120=item Re-install Carton on you perlbrew environment 121 122Run C<< cpanm -f Carton >>. This will force-install Carton, 123and because your C<cpanm> is now using the correct C<perl>, 124the same will happen with C<carton>. 125 126=back 127 128Make sure the shebang (the first line) of your C<carton> script points to the right perl path, rather than C</usr/bin/perl>. 129