script/catalyst.pl

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4 use Getopt::Long;
   5 use Pod::Usage;
   6 BEGIN {
   7 eval " use Catalyst::Devel 1.0; ";
   8
   9 if ($@) {
  10   die <<END;
  11 To use the Catalyst development tools including catalyst.pl and the
  12 generated script/myapp_create.pl you need Catalyst::Helper, which is
  13 part of the Catalyst-Devel distribution. Please install this via a
  14 vendor package or by running one of -
  15
  16   perl -MCPAN -e 'install Catalyst::Devel'
  17   perl -MCPANPLUS -e 'install Catalyst::Devel'
  18 END
  19
  20 }
  21 };
  22
  23 use Catalyst::Helper;
  24
  25 my $force    = 0;
  26 my $help     = 0;
  27 my $makefile = 0;
  28 my $scripts  = 0;
  29
  30 GetOptions(
  31     'help|?'      => \$help,
  32     'force|nonew' => \$force,
  33     'makefile'    => \$makefile,
  34     'scripts'     => \$scripts,
  35 );
  36
  37 pod2usage(1) if ( $help || !$ARGV[0] );
  38
  39 my $helper = Catalyst::Helper->new(
  40     {
  41         '.newfiles' => !$force,
  42         'makefile'  => $makefile,
  43         'scripts'   => $scripts,
  44         'short'     => 0, # FIXME - to be removed.
  45     }
  46 );
  47 pod2usage(1) unless $helper->mk_app( $ARGV[0] );
  48
  49 1;
  50 __END__
  51
  52 =head1 NAME
  53
  54 catalyst - Bootstrap a Catalyst application
  55
  56 =head1 SYNOPSIS
  57
  58 catalyst.pl [options] application-name
  59
  60 'catalyst.pl' creates a skeleton for a new application, and allows you to
  61 upgrade the skeleton of your old application.
  62
  63  Options:
  64    -force      don't create a .new file where a file to be created exists
  65    -help       display this help and exit
  66    -makefile   only update Makefile.PL
  67    -scripts    only update helper scripts
  68
  69  application-name must be a valid Perl module name and can include "::",
  70  which will be converted to '-' in the project name.
  71
  72
  73  Examples:
  74     catalyst.pl My::App
  75     catalyst.pl MyApp
  76
  77  To upgrade your app to a new version of Catalyst:
  78     catalyst.pl -force -scripts MyApp
  79
  80
  81 =head1 DESCRIPTION
  82
  83 The C<catalyst.pl> script bootstraps a Catalyst application, creating a
  84 directory structure populated with skeleton files.
  85
  86 The application name must be a valid Perl module name.  The name of the
  87 directory created is formed from the application name supplied, with double
  88 colons replaced with hyphens (so, for example, the directory for C<My::App> is
  89 C<My-App>).
  90
  91 Using the example application name C<My::App>, the application directory will
  92 contain the following items:
  93
  94 =over 4
  95
  96 =item README
  97
  98 a skeleton README file, which you are encouraged to expand on
  99
 100 =item Changes
 101
 102 a changes file with an initial entry for the creation of the application
 103
 104 =item Makefile.PL
 105
 106 Makefile.PL uses the C<Module::Install> system for packaging and distribution
 107 of the application.
 108
 109 =item lib
 110
 111 contains the application module (C<My/App.pm>) and
 112 subdirectories for model, view, and controller components (C<My/App/M>,
 113 C<My/App/V>, and C<My/App/C>).
 114
 115 =item root
 116
 117 root directory for your web document content.  This is left empty.
 118
 119 =item script
 120
 121 a directory containing helper scripts:
 122
 123 =over 4
 124
 125 =item C<myapp_create.pl>
 126
 127 helper script to generate new component modules
 128
 129 =item C<myapp_server.pl>
 130
 131 runs the generated application within a Catalyst test server, which can be
 132 used for testing without resorting to a full-blown web server configuration.
 133
 134 =item C<myapp_cgi.pl>
 135
 136 runs the generated application as a CGI script
 137
 138 =item C<myapp_fastcgi.pl>
 139
 140 runs the generated application as a FastCGI script
 141
 142 =item C<myapp_test.pl>
 143
 144 runs an action of the generated application from the comand line.
 145
 146 =back
 147
 148 =item t
 149
 150 test directory
 151
 152 =back
 153
 154 The application module generated by the C<catalyst.pl> script is functional,
 155 although it reacts to all requests by outputting a friendly welcome screen.
 156
 157 =head1 NOTE
 158
 159 Neither C<catalyst.pl> nor the generated helper script will overwrite existing
 160 files.  In fact the scripts will generate new versions of any existing files,
 161 adding the extension C<.new> to the filename.  The C<.new> file is not created
 162 if would be identical to the existing file.
 163
 164 This means you can re-run the scripts for example to see if newer versions of
 165 Catalyst or its plugins generate different code, or to see how you may have
 166 changed the generated code (although you do of course have all your code in a
 167 version control system anyway, don't you ...).
 168
 169 =head1 SEE ALSO
 170
 171 L<Catalyst::Manual>, L<Catalyst::Manual::Intro>
 172
 173 =head1 AUTHORS
 174
 175 Catalyst Contributors, see Catalyst.pm
 176
 177 =head1 COPYRIGHT
 178
 179 This library is free software, you can redistribute it and/or modify it under
 180 the same terms as Perl itself.
 181
 182 =cut