Document process to fix the previous situation

1 files changed, 39 insertions, 0 deletions

diff --git a/lib/Carton/Doc/FAQ.pod b/lib/Carton/Doc/FAQ.pod
index e03cbd9..7bfd5e1 100644
--- a/lib/Carton/Doc/FAQ.pod
+++ b/lib/Carton/Doc/FAQ.pod
@@ -118,3 +118,42 @@ that is hard-coded at the top of the C<carton> script.
 
 Carton will do the right thing when calling C<cpanm> to install your dependencies,
 running it under the same C<perl> as Carton is running on.
+
+=head2 Using C<< perl -S carton install >> is ugly, any permanent fix?
+
+The issue is most likelly caused by a inital bad install of C<cpanm>,
+that ended up with a shebang line pointed to the system perl.
+
+To fix:
+
+=over 4
+
+=item Make sure you perlbrew-installed cpanm is not using system perl
+
+Run this: C<< head -1 "$PERLBREW_ROOT/bin/cpanm" >>
+
+If the output is not C<< #!/usr/bin/env perl >>, then you have
+a bad C<cpanm> installed.
+
+Run C<< perlbrew install-cpanm >> to fix it. Re-run the previous
+command to make sure it was fixed.
+
+=item Re-install cpanm on your perlbrew environment
+
+Switch to the perlbrew environment you plan on using and force
+install C<cpanm>. Use C<< "$PERLBREW_ROOT/bin/cpanm -f App::cpanminus >>
+to make sure you use the newly fixed C<cpanm> from perlbrew.
+
+This will make sure that your new environment has a C<cpanm> that will
+use the correct C<perl> for that environment.
+
+=item Re-install Carton on you perlbrew environment
+
+Run C<< cpanm -f Carton >>. This will force-install Carton,
+and because your C<cpanm> is now using the correct C<perl>,
+the same will happen with C<carton>.
+
+=back
+
+After this process, your C<< carton install >> will use the
+correct C<perl>.