| 1 |
NAME |
| 2 |
|
| 3 |
Carton - Perl module dependency manager (aka Bundler for Perl) |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
# On your development environment |
| 8 |
> cat cpanfile |
| 9 |
requires 'Plack', '0.9980'; |
| 10 |
requires 'Starman', '0.2000'; |
| 11 |
|
| 12 |
> carton install |
| 13 |
> git add cpanfile cpanfile.snapshot |
| 14 |
> git commit -m "add Plack and Starman" |
| 15 |
|
| 16 |
# Other developer's machine, or on a deployment box |
| 17 |
> carton install |
| 18 |
> carton exec starman -p 8080 myapp.psgi |
| 19 |
|
| 20 |
# carton exec is optional |
| 21 |
> perl -Ilocal/lib/perl5 local/bin/starman -p 8080 myapp.psgi |
| 22 |
> PERL5LIB=/path/to/local/lib/perl5 /path/to/local/bin/starman -p 8080 myapp.psgi |
| 23 |
|
| 24 |
AVAILABILITY |
| 25 |
|
| 26 |
Carton only works with perl installation with the complete set of core |
| 27 |
modules. If you use perl installed by a vendor package with modules |
| 28 |
stripped from core, Carton is not expected to work correctly. |
| 29 |
|
| 30 |
Also, Carton requires you to run your command/application with carton |
| 31 |
exec command or to include the local/lib/perl5 directory in your Perl |
| 32 |
library search path (using PERL5LIB, -I, or lib). |
| 33 |
|
| 34 |
DESCRIPTION |
| 35 |
|
| 36 |
carton is a command line tool to track the Perl module dependencies for |
| 37 |
your Perl application. Dependencies are declared using cpanfile format, |
| 38 |
and the managed dependencies are tracked in a cpanfile.snapshot file, |
| 39 |
which is meant to be version controlled, and the snapshot file allows |
| 40 |
other developers of your application will have the exact same versions |
| 41 |
of the modules. |
| 42 |
|
| 43 |
For cpanfile syntax, see cpanfile documentation. |
| 44 |
|
| 45 |
TUTORIAL |
| 46 |
|
| 47 |
Initializing the environment |
| 48 |
|
| 49 |
carton will use the local directory to install modules into. You're |
| 50 |
recommended to exclude these directories from the version control |
| 51 |
system. |
| 52 |
|
| 53 |
> echo local/ >> .gitignore |
| 54 |
> git add cpanfile cpanfile.snapshot |
| 55 |
> git commit -m "Start using carton" |
| 56 |
|
| 57 |
Tracking the dependencies |
| 58 |
|
| 59 |
You can manage the dependencies of your application via cpanfile. |
| 60 |
|
| 61 |
# cpanfile |
| 62 |
requires 'Plack', '0.9980'; |
| 63 |
requires 'Starman', '0.2000'; |
| 64 |
|
| 65 |
And then you can install these dependencies via: |
| 66 |
|
| 67 |
> carton install |
| 68 |
|
| 69 |
The modules are installed into your local directory, and the |
| 70 |
dependencies tree and version information are analyzed and saved into |
| 71 |
cpanfile.snapshot in your directory. |
| 72 |
|
| 73 |
Make sure you add cpanfile and cpanfile.snapshot to your version |
| 74 |
controlled repository and commit changes as you update dependencies. |
| 75 |
This will ensure that other developers on your app, as well as your |
| 76 |
deployment environment, use exactly the same versions of the modules |
| 77 |
you just installed. |
| 78 |
|
| 79 |
> git add cpanfile cpanfile.snapshot |
| 80 |
> git commit -m "Added Plack and Starman" |
| 81 |
|
| 82 |
Specifying a CPAN distribution |
| 83 |
|
| 84 |
You can pin a module resolution to a specific distribution using a |
| 85 |
combination of dist, mirror and url options in cpanfile. |
| 86 |
|
| 87 |
# specific distribution on PAUSE |
| 88 |
requires 'Plack', '== 0.9980', |
| 89 |
dist => 'MIYAGAWA/Plack-0.9980.tar.gz'; |
| 90 |
|
| 91 |
# local mirror (darkpan) |
| 92 |
requires 'Plack', '== 0.9981', |
| 93 |
dist => 'MYCOMPANY/Plack-0.9981-p1.tar.gz', |
| 94 |
mirror => 'https://pause.local/'; |
| 95 |
|
| 96 |
# URL |
| 97 |
requires 'Plack', '== 1.1000', |
| 98 |
url => 'https://pause.local/authors/id/M/MY/MYCOMPANY/Plack-1.1000.tar.gz'; |
| 99 |
|
| 100 |
Deploying your application |
| 101 |
|
| 102 |
Once you've done installing all the dependencies, you can push your |
| 103 |
application directory to a remote machine (excluding local and .carton) |
| 104 |
and run the following command: |
| 105 |
|
| 106 |
> carton install --deployment |
| 107 |
|
| 108 |
This will look at the cpanfile.snapshot and install the exact same |
| 109 |
versions of the dependencies into local, and now your application is |
| 110 |
ready to run. |
| 111 |
|
| 112 |
The --deployment flag makes sure that carton will only install modules |
| 113 |
and versions available in your snapshot, and won't fallback to query |
| 114 |
for CPAN Meta DB for missing modules. |
| 115 |
|
| 116 |
Bundling modules |
| 117 |
|
| 118 |
carton can bundle all the tarballs for your dependencies into a |
| 119 |
directory so that you can even install dependencies that are not |
| 120 |
available on CPAN, such as internal distribution aka DarkPAN. |
| 121 |
|
| 122 |
> carton bundle |
| 123 |
|
| 124 |
will bundle these tarballs into vendor/cache directory, and |
| 125 |
|
| 126 |
> carton install --cached |
| 127 |
|
| 128 |
will install modules using this local cache. Combined with --deployment |
| 129 |
option, you can avoid querying for a database like CPAN Meta DB or |
| 130 |
downloading files from CPAN mirrors upon deployment time. |
| 131 |
|
| 132 |
As of Carton v1.0.32, the bundle also includes a package index allowing |
| 133 |
you to simply use cpanm (which has a standalone version) instead of |
| 134 |
installing Carton on a remote machine. |
| 135 |
|
| 136 |
> cpanm -L local --from "$PWD/vendor/cache" --installdeps --notest --quiet . |
| 137 |
|
| 138 |
PERL VERSIONS |
| 139 |
|
| 140 |
When you take a snapshot in one perl version and deploy on another |
| 141 |
(different) version, you might have troubles with core modules. |
| 142 |
|
| 143 |
The simplest solution, which might not work for everybody, is to use |
| 144 |
the same version of perl in the development and deployment. |
| 145 |
|
| 146 |
To enforce that, you're recommended to use plenv and .perl-version to |
| 147 |
lock perl versions in development. |
| 148 |
|
| 149 |
You can also specify the minimum perl required in cpanfile: |
| 150 |
|
| 151 |
requires 'perl', '5.16.3'; |
| 152 |
|
| 153 |
and carton (and cpanm) will give you errors when deployed on hosts with |
| 154 |
perl lower than the specified version. |
| 155 |
|
| 156 |
COMMUNITY |
| 157 |
|
| 158 |
https://github.com/perl-carton/carton |
| 159 |
|
| 160 |
Code repository, Wiki and Issue Tracker |
| 161 |
|
| 162 |
AUTHOR |
| 163 |
|
| 164 |
Tatsuhiko Miyagawa |
| 165 |
|
| 166 |
COPYRIGHT |
| 167 |
|
| 168 |
Tatsuhiko Miyagawa 2011- |
| 169 |
|
| 170 |
LICENSE |
| 171 |
|
| 172 |
This software is licensed under the same terms as Perl itself. |
| 173 |
|
| 174 |
SEE ALSO |
| 175 |
|
| 176 |
Carmel |
| 177 |
|
| 178 |
cpanm |
| 179 |
|
| 180 |
cpanfile |
| 181 |
|
| 182 |
Bundler <http://gembundler.com/> |
| 183 |
|
| 184 |
pip <http://pypi.python.org/pypi/pip> |
| 185 |
|
| 186 |
npm <http://npmjs.org/> |
| 187 |
|
| 188 |
perlrocks <https://github.com/gugod/perlrocks> |
| 189 |
|
| 190 |
only |
| 191 |
|