[Jifty-commit] r4602 - in Jifty-Book: .

jifty-commit at lists.jifty.org jifty-commit at lists.jifty.org
Sat Dec 1 16:18:19 EST 2007


Author: sterling
Date: Sat Dec  1 16:18:19 2007
New Revision: 4602

Modified:
   Jifty-Book/   (props changed)
   Jifty-Book/doc/Jifty/Book/Part-A/03-Creating_a_Jifty_Application.pod

Log:
 r14319 at dynpc145:  andrew | 2007-12-01 15:17:46 -0600
 Added basic info about the CLI and Jifty's directory structure.


Modified: Jifty-Book/doc/Jifty/Book/Part-A/03-Creating_a_Jifty_Application.pod
==============================================================================
--- Jifty-Book/doc/Jifty/Book/Part-A/03-Creating_a_Jifty_Application.pod	(original)
+++ Jifty-Book/doc/Jifty/Book/Part-A/03-Creating_a_Jifty_Application.pod	Sat Dec  1 16:18:19 2007
@@ -14,14 +14,192 @@
 
 =head1 Reference
 
+Getting an application up and running is a very simple process. It doesn't really require a whole chapter, but we'll use this space to also gives some basics on how to use the command-line tools and basic components of your Jifty application.
+
 =head2 Introducing the CLI
 
+Jifty provides a M<Command-Line Interface (CLI)> to perform the initial creation and management of your Jifty application. This tool provides several commands through this tool that are accessed as sub-commands to the main interface.
+
+=head3 Asking for Help
+
+To get started with the CLI, the you can ask it for help:
+
+  % jifty help
+     action - add an action class to your jifty application
+     adopt - localize a stock jifty component
+     app - create the skeleton of a jifty application
+     console - a console for your jifty application
+     database - script for loading/dumping data from jifty
+     deps - looks for module dependencies and attempts to install them from cpan
+     env - access the jifty environment
+     fastcgi - a fastcgi server for your jifty application
+     help - show help
+     modperl2 - a modperl2 handler for your jifty app.
+     model - add a model class to your jifty application
+     plugin - create the skeleton of a jifty plugin
+     po - extract translatable strings from your application
+     schema - create sql to update or create your jifty app's tables
+     server - a standalone webserver for your jifty application
+
+It tells you what all the sub-commands are. You can then ask for help on a specific command.
+
+  % jifty help app
+  NAME
+  
+      app - Create the skeleton of a Jifty application
+  
+  DESCRIPTION
+  
+      Creates a skeleton of a new Jifty application. See
+      Jifty::Manual::Tutorial for an example of its use.
+  
+   options
+  
+      This script only takes one option, --name, which is required; it is the
+      name of the application to create. Jifty will create a directory with
+      that name, and place all of the files it creates inside that directory.
+  
+   run
+  
+      Create a directory for the application, a skeleton directory structure,
+      and a Makefile.PL for you application.
+
+You can run the B<help> command this way for any of the Jifty CLI sub-commands.
+
+Options to the CLI are general given using GNU-style options. For example, when you create an application, you specify the name of the application using the C<--name> option (as described in the help above).
+
+  % jifty app --name MySweetApp
+
+Here we tell the Jifty command to create a new application named "MySweetApp".
+
 =head2 Build an application
 
-=head3 How to run jifty app
+Now that we know the basics of the command-line interface. Let's examine how an application is built.
+
+  % bin/jifty app --name MyApp
+  Creating new application MyApp
+  Creating directory MyApp/lib
+  Creating directory MyApp/lib/MyApp
+  Creating directory MyApp/bin
+  Creating directory MyApp/etc
+  Creating directory MyApp/doc
+  Creating directory MyApp/log
+  Creating directory MyApp/var
+  Creating directory MyApp/var/mason
+  Creating directory MyApp/share
+  Creating directory MyApp/share/po
+  Creating directory MyApp/share/web
+  Creating directory MyApp/share/web/templates
+  Creating directory MyApp/share/web/static
+  Creating directory MyApp/lib/MyApp/Model
+  Creating directory MyApp/lib/MyApp/Action
+  Creating directory MyApp/t
+  Creating configuration file MyApp/etc/config.yml
+
+The command, in return, tells us what it's doing. It will create a new directory from where you've run the command and then build all the directories and files required to create your skeleton application.
+
+=head3 There's CLI in your App
+
+Once the application is created, you can then cd into the directory and your application comes with a copy of the F<jifty> command you can run from your application:
+
+  % bin/jifty help
+
+It's identical to the one installed with Jifty and provided because it is sometimes convenient to have this command nearby, such as when deploying your application.
+
+Typically, this command is preferred when running things related to your application. In the future, your application may be able to provide local sub-commands to this command.
 
 =head3 The Directory Structure
 
+A Jifty application contains a number of directories. This directory structure follows the traditional Unix break-up of directories. If you're familiar with how Unix systems tend to arrange things, you will probably understand the general purpose for most of these directories already.
+
+We'll examine each directory in summary here.
+
+=head4 Main Directory
+
+The top-level directory of your application will contain a file named F<Makefile.PL>. This file is used to help build and test your application. It uses L<Module::Install> to create a makefile and then perform other tasks related to the development of your application. For example, once installed you can run:
+
+  % perl Makefile.PL
+  % make
+  % make test
+
+However, since your F<t/> directory is initially empty, this will probably be fairly dull.
+
+You may want to consider adding a file describing your application's license, a README file on how to build and use your application, a file containing a list of contributors, and other import developer and administrative documentation, particularly if you plan to redistribute your application.
+
+=head4 F<bin/>
+
+This directory contains the local copy of the F<jifty> CLI script. If you need to provide additional scripts to your application such as your own CLI tools, email gateway scripts, utilities, or even GUIs related to your application, this is a good place to put them.
+
+=head4 F<doc/>
+
+This directory is created for your convenience and you may choose to use it or not. It is intended to hold developer documentation related to your application. Do with it what you will.
+
+=head4 F<etc/>
+
+This directory contains your applications main configuration file F<config.yml>. It may also contain additional configuration files, such as the configuration of L<Log::Log4perl> if you choose to configure it in a seperate file. See L<Jifty::Book::Part-B::11-Deployment/Logging Configuration>.
+
+=head4 F<lib/>
+
+This is the directory containing your applications Perl libraries. Additional directories are built within here and described in more detail.
+
+=head4 F<lib/MyApp/>
+
+This is the main directory for your application. Obviously, this directory would be named after your application name, rather than I<MyApp>.N<Unless you go in for such application names, in which case it could actually be named I<MyApp>. Knock yourself out.>
+
+=head4 F<lib/MyApp/Model/>
+
+This is the area for your application's models. Jifty is a data-centric framework and one of your first tasks will likely be to build some models within this directory. In fact, this is what the next chapter is about.
+
+=head4 F<lib/MyApp/Model/Action/>
+
+This is the area for your application's actions. In all likelihood a simple application will not need to provide any custom actions, at least not to start. Jifty automatically builds tools for manipulating your models when you create your models, which takes care of most of the work.
+
+However, non-trivial applications will probably need at least a few custom actions and this is where you will place them.
+
+=head4 F<log/>
+
+This is another convenience directory that you may choose to use or not. It provides a space for you to place your application's configuration files. You may use it or not. You have the power.
+
+=head4 F<share/>
+
+This is the parent directory for your applications non-Perl files. If you need any kind of special files associated with your application, this is a good place for it. It already contains sub-directories for web documents and translations, but you could add additional areas for other special data files your application needs.
+
+=head4 F<share/po/>
+
+This directory is used to contain all of your human language translation files.Jifty has been built by developers of many different nationalities living in various parts of the world and built for use internationally. As such, language translation is fairly important.
+
+See L<Jifty::Book::Part-C::18-Internationalization>.
+
+=head4 F<share/web/>
+
+This is the parent directory for web-related files. Jifty uses this to store Mason templates and static files. Your application might use additional sub-directories if you have files that need to be stored here for purposes not falling into those categories.
+
+=head4 F<share/web/templates/>
+
+Mason templates can be placed into this directory and then will be served from here. 
+
+For example, if you create a template named F<index.html> in this directory, then it will be accessible from U<http://localhost:8888/index.html> when you first test your application. These templates can either be pure HTML or other text (but probably shouldn't be for efficiency reasons) or Mason templates.
+
+See L<Jifty::Book::Part-B::07-Viewing_your_Data>.
+
+=head4 F<share/web/static/>
+
+All the other static files your application needs, such as HTML, cascading stylesheets, XML schemas, JavaScript files, images, movies, etc. can go into this directory. They will be served from here in the same way as described for F<share/web/templates/>, but will served as is.
+
+=head4 F<t/>
+
+This is the home directory for your application's unit tests. Tests are very important if you want to make sure your application works consistently. Once a test is placed into this directory you can make certain now new change to your application breaks existing functionality by running your tests.
+
+We feel this is so important, we dedicated a section to testing in every chapter.
+
+=head4 F<var/>
+
+This is the directory for files that change or are generated by your application. Typically, this is a good place to cache data, store database files, and otherwise place files needed by your application that are changed by your application as it runs.
+
+=head4 F<var/mason/>
+
+This directory contains the Mason object cache. Mason speeds things up by storing templates that have been compiled here. Normally, you don't need to mess with this directory or its contents much, but you may need to be aware of it during production installation and updates to keep your application running properly.
+
 =head2 Prepping your Application
 
 =head3 How to Run jifty schema


More information about the Jifty-commit mailing list