Debian Codegraph @

README

raw
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