1Carmel(3) User Contributed Perl Documentation Carmel(3)
2
6 Carmel - CPAN Artifact Repository Manager
7
9 # Run with a directory with cpanfile
10 carmel install
11 # list all the modules to be loaded
13 carmel list
14 # list all the modules in a tree
16 carmel tree
17 # show a location where a module is installed
19 carmel show Plack
20 # update Plack to the latest
22 carmel update Plack
23 # update all the modules in the snapshot
25 carmel update
26 # pin modules tp specific versions
28 carmel update DBI@1.633 Plack@1.0000
29 # show diffs for cpanfile.snapshot in a nice way
31 carmel diff
32 # Runs your perl script with modules from artifacts
34 carmel exec perl ...
35 # Requires all your modules in cpanfile in one shot
37 carmel exec perl -e 'use Carmel::Preload;'
38 # Roll out the currently selected modules into ./local
40 carmel rollout
41 # package modules tarballs and index into ./vendor/cache
43 carmel package
44 # use Carmel packages inside a script (without carmel exec)
46 perl -e 'use Carmel::Setup; ...'
47 # prints export PATH=... etc for shell scripting
49 carmel export
50 # find a module in a repository
52 carmel find DBI
53 # find a module matching the version query
55 carmel find Plack ">= 1.0000, < 1.1000"
56
58 Carmel is yet another CPAN module manager.
59 Unlike traditional CPAN module installer, Carmel keeps the build of
61 your dependencies in a central repository, then select the library
62 paths to include upon runtime in development.
63 Carmel also allows you to rollout all the files in a traditional perl
65 INC directory structure, which is useful to use in a production
66 environment, such as containers.
67
69 Development
70 During the development, run "carmel install" when you setup a new
71 environment, and any time you make changes to "cpanfile". This will
72 update your build artifacts, and saves the changes to
73 "cpanfile.snapshot". Commit the snapshot file in version control system
74 so that you can reproduce the exact same versions across machines.
75 "carmel exec" makes it easy to run your application using the versions
77 in "cpanfile" and "cpanfile.snapshot" dynamically.
78 # On your development environment
80 > cat cpanfile
81 requires 'Plack', '0.9980';
82 requires 'Starman', '0.2000';
83 > carmel install
85 > echo /.carmel >> .gitignore
86 > git add cpanfile cpanfile.snapshot .gitignore
87 > git commit -m "add Plack and Starman"
88 # On a new setup, or another developer's machine
90 > git pull
91 > carmel install
92 > carmel exec starman -p 8080 myapp.psgi
93 # Add a new dependency
95 > echo "requires 'Try::Tiny';" >> cpanfile
96 > carmel install
97 > git commit -am 'Add Try::Tiny'
98 # Update Plack to the latest
100 > carmel update Plack
101 Production Deployments
103 Carmel allows you to manage all the dependencies the same way across
104 development environments and production environments. However, there
105 might be cases where you want to avoid running your application with
106 "carmel exec" in production, to avoid the overhead with large number of
107 include paths, or to avoid installing Carmel in the production hosts.
108 Carmel provides two easy ways to avoid depending on Carmel on the
110 deploy target environments. First, "carmel rollout" rolls out the build
111 artifacts into a regular perl5 library path in "local". Once the
112 rollout is complete, you can include the path just like a regular
113 local::lib directory.
114 # Production environment: Roll out to ./local
116 > carmel rollout
117 > perl -Ilocal/lib/perl5 local/bin/starman -p 8080 myapp.psgi
118 You can run "carmel rollout"> in a CI system to create the "local"
120 directory next to your application code for a linux package (e.g. deb
121 package), or Docker containers.
122 Second, "carmel package" (similar to "carton bundle") creates a
124 directory with tarballs and CPAN-style package index files, which you
125 can pass to cpanm on a target machine. This way, you only need "cpanm",
126 which is available as a self-contained single executable, to bootstrap
127 the installation on a host with a stock perl.
128 # Vendor all the packages to vendor/cache
130 > carmel package
131 > git add vendor/cache
132 > git commit -m 'Vendor all the tarballs'
133 # Remote environment (CI etc.)
135 > git clone https://.../myapp.git && cd myapp
136 > cpanm -L /path/to/lib --from $PWD/vendor/cache -nq --installdeps .
137
139 Carmel will keep the build directory (artifacts) after a cpanm
140 installation in a repository, which defaults to
141 "$HOME/.carmel/{version}-{archname}/builds", and your directory
142 structure would look like:
143 $HOME/.carmel/5.20.1-darwin-2level/builds
145 Plack-1.0033/
146 blib/
147 arch/
148 lib/
149 URI-1.64/
150 blib/
151 arch/
152 lib/
153 URI-1.63/
154 blib/
155 arch/
156 lib/
157 Carmel scans this directory and creates the mapping of which version of
159 any package belongs to which build directory.
160 Given the list of modules and requirements from "cpanfile", "carmel
162 install" computes which versions satisfy the requirements best, and if
163 there isn't, installs the modules from CPAN to put it to the artifact
164 repository. The computed mappings are preserved as a snapshot in
165 "cpanfile.snapshot".
166 Once the snapshot is created, each following "carmel" command runs uses
168 both "cpanfile" and "cpanfile.snapshot" to determine the best versions
169 to satisfy the requirements. When you update "cpanfile" to bump a
170 version or add a new module, "carmel" will install the new dependencies
171 and update the snapshot accordingly.
172 "carmel exec" command, like "install" command, lists the build
174 directories and ".pm" files you need from the repository, and then
175 prepend the mappings of these files in the @INC hook. This is a handy
176 way to run a perl program using the dependencies pinned by Carmel,
177 without changing any include path.
178 "carmel update" command allows you to selectively update a dependency
180 while preserving other dependencies in the snapshot. "carmel update
181 Plack" for example pulls the latest version of Plack from CPAN (and its
182 dependencies, if it needs a newer version than pinned in the snapshot),
183 and updates the snapshot properly. Running "carmel update" without any
184 arguments would update all the modules in "cpanfile", including its
185 dependencies.
186 On a production environment, you might want to use the "carmel rollout"
188 command, which saves all the files included in the "cpanfile", pinned
189 with "cpanfile.snapshot", to the "local" directory. This directory can
190 be included like a regular perl's library path, with
191 "PERL5LIB=/path/to/local/lib/perl5", or with "use lib", and you don't
192 need to use "carmel" command in production this way.
193 SNAPSHOT SUPPORT
195 As of v0.1.29, Carmel supports saving and loading snapshot file in
196 "cpanfile.snapshot", in a compatible format with Carton. Versions saved
197 in the snapshot file will be preserved across multiple runs of Carmel
198 across machines, so that versions frozen in one environment can be
199 committed to a source code repository, and can be reproduced in another
200 box, so long as the perl version and architecture is the same.
201
203 • If you run multiple instances of "carmel", or hit Ctrl-C to
204 interrupt the cpanm install session, Carmel might get into a state
205 where some modules have been installed properly, while some modules
206 in the dependency chain are missing. Make sure you don't run
207 multiple instances of "carmel" at the same time, and let it finish
208 the installation to get the full builds properly.
209 • There're certain dependencies that get missed during the initial
211 "carmel install", and you'll see the error message "Can't find an
212 artifact for Foo".
213 Please report it to the issue tracker if you can reliably reproduce
215 this type of errors.
216 Usually you run "carmel install" again and the error will be gone.
218 • In some situation, you might encounter conflicts in version
220 resolutions, between what's pinned in the snapshot and a new
221 version that's needed when you introduce a new module.
222 For example, suppose you have:
224 # cpanfile
226 requires 'Foo';
227 requires 'Bar'; # which requires Foo >= 1.001
228 Without the snapshot, Carmel has no trouble resolving the correct
230 versions for this combination. But if you have:
231 # cpanfile.snapshot
233 Foo-1.000
234 The first time you run "carmel install", Carmel will try to install
236 Foo-1.000, because that's the version pinned in the snapshot, while
237 trying to pull the module Bar, which would conflict with that
238 version of Foo.
239 This can happen 50% of the time, because if cpanm (called
241 internally by Carmel) installs Bar first, then the resolution is
242 done correctly and the version in the snapshot would be skipped,
243 and the snapshot will be updated accordingly. This is due to perl's
244 hash randomization after Perl 5.18.
245 To avoid this, you're recommended to run "carmel install" before
247 making any changes to cpanfile. That will put the build caches to
248 satisfy what's in cpanfile and the snapshot. After that, adding a
249 new dependency will likely reuse what's in the build cache, while
250 adding a new dependency can update the transient dependency (for
251 Foo) without having conflicts.
252 If you encounter conflicts like this, you can work around it by:
254 • Run "carmel update Foo" to pull the latest version of Foo
256 from CPAN, ignoring what's in the snapshot.
257 • Update "cpanfile" to explicitly update the version
259 requirement for "Foo".
260
262 Carton
263 Carmel shares the same goal with Carton, where you can manage your
264 dependencies by declaring them in "cpanfile", and pinning them in
265 "cpanfile.snapshot". Most of the commands work the same way, so Carmel
266 can most effectively be a drop-in replacement for Carton, if you're
267 currently using it.
268 Here's a few key differences between Carmel and Carton:
270 • Carton does not manage what's currently being installed in "local"
272 directory. It just runs "cpanm" command with "-L local", with a
273 hope that nothing has changed the directory except Carton, and
274 whatever is in the directory won't conflict with the snapshot file.
275 This can easily conflict when "cpanfile.snapshot" is updated by
276 multiple developers or when you continuously update the
277 dependencies across multiple machines.
278 Carmel manages all the dependencies for your project in the Carmel
280 repository under "$HOME/.carmel", and nothing is installed under
281 your project directory on development. The "local" directory is
282 only created when you request it via "carmel rollout" command, and
283 it's safe to run multiple times. Running "carmel install" after
284 pulling the changes to the snapshot file will always install the
285 correct dependencies from the snapshot file, as compared to Carton,
286 which doesn't honor the snapshot on a regular install command, if
287 whatever version in "local" already satisfies the version in
288 "cpanfile".
289 • Carton has no easy way to undo a change once you update a version
291 of a module in "local", because which version is actually selected
292 is only preserved as a file inside the directory, that's not
293 managed by Carton. To undo a change you have to remove the entire
294 "local" directory to start over.
295 Carmel preserves this information to the "cpanfile.snapshot" file,
297 and every invocation of Carmel resolves the dependencies declared
298 in "cpanfile" and pinned in "cpanfile.snapshot" dynamically, to
299 create a stable dependency tree, without relying on anything in a
300 directory under your project other than the snapshot file. Undoing
301 the change in "cpanfile.snapshot" file immediately reverts the
302 change.
303 cpm
305 App::cpm is an excellent standalone CPAN installer.
306 • Like Carton, cpm installs the dependencies declared in "cpanfile"
308 to "local". Carmel installs them into a build cache, and doesn't
309 use "local" directory for state management. You can run "carmel
310 rollout" to copy the dependencies to "local" directory.
311 • cpm installs the modules in parallel, which makes the installation
313 very fast. Like Carmel, cpm also manages its build artifacts cache,
314 so a module that has previously been installed would be very fast
315 to install, since there's no build process.
316 • Unlike Carton and Carmel, cpm doesn't have the ability to manage
318 "cpanfile.snapshot" file on its own. It can read the snapshot
319 however, so it's possible to use Carmel in a development
320 environment, and then use "cpm install" instead of "carmel install"
321 and "carmel rollout", if all you need is to build out a perl5
322 library path out of "cpanfile" and "cpanfile.snapshot" in the
323 source code repository.
324
326 <https://github.com/miyagawa/Carmel>
327 Code repository, Wiki and Issue Tracker
328
330 Tatsuhiko Miyagawa <miyagawa@bulknews.net>
331
333 Copyright 2015- Tatsuhiko Miyagawa
334
336 This library is free software; you can redistribute it and/or modify it
337 under the same terms as Perl itself.
338
340 App::cpanminus Carton
341perl v5.38.0 2023-07-20 Carmel(3)