Changeset 443 for tags/1.2.0

Show
Ignore:
Timestamp:
09/19/06 20:28:31 (2 years ago)
Author:
hans
Message:

Updated INSTALL instructions to point to the website.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • tags/1.2.0/generator/INSTALL

    r196 r443  
    1  
    2   I N S T A L L I N G    P R O P E L 
    3   ================================== 
    4  
    5   This is a quick guide for installing Propel and building the provided sample 
    6   bookstore application.  For more information on installation / configuration 
    7   see the online user guide available from main site: http://propel.phpdb.org 
    8    
    9    
    10   Prerequisites 
    11   ------------- 
    12  
    13   Before you can install and run Propel you will need to have the following: 
    14    
    15     * PHP >= 5.0.0 
    16           Propel will only work with PHP5.  Additionally, you must have a command- 
    17           line version of PHP5 in order to use PHING to build the classes and SQL 
    18           files for your data model.  PHP must also have compiled in XML (libxml2, xsl) 
    19           support in order to take advantage of all build options. 
    20  
    21         * PHING >= 2.0.0 
    22           Propel uses the PHING build system to build the classes and SQL definition 
    23           files for your data model.  PHING is an open-source project build system 
    24           based on Apache ANT.  PHING 2 is the (development) version built for PHP5. 
    25           See http://phing.tigris.org/ to learn how to install Phing (it's easy). 
    26            
    27     * Creole >- 1.0.0      
    28           Creole is a Uniform DB API framework for PHP5. Creole is available as a PEAR  
    29           package or can be installed in a more traditional manner. See  
    30           http://creole.phpdb.org/ to get a copy of the Creole classes. 
    31          
    32         * A supported RDBMS 
    33           Creole currently supports MySQL, MS SQL Server, PostgreSQL, and SQLite.  We  
    34           are working on support for Oracle and the new MySQLi drivers but this should  
    35           be considered alpha, at best. 
    36  
    37   Quick Install (PEAR) 
    38   -------------------- 
    39    
    40   It is now possible to install both the Propel runtime and the generator classes as 
    41   PEAR packages.  This is the quickest way to get up and running with Propel, but may 
    42   not be quite as easy to configure as the traditional installation method. 
    43    
    44   * Propel Generator: 
    45    
    46     % pear install http://propel.phpdb.org/pear/propel_generator-current.tgz 
    47    
    48   To use the generator to build sql, php classes, etc. simply use the propel-gen shell  
    49   script: 
    50      
    51         % propel-gen /path/to/my/projectdir 
    52          
    53   (See the sample bookstore project directory in your PEAR data directory for a sample  
    54   projectdir.) 
    55          
    56   * Propel Runtime: 
    57    
    58     %  pear install http://propel.phpdb.org/pear/propel_runtime-current.tgz 
    59    
    60   It is recommended that you read over the traditional install guide also, so that you 
    61   understand the roles of some of the various files.  In the PEAR install these files 
    62   (e.g. the main build.properties and the sample bookstore project) are stored in the 
    63   PEAR data dir (e.g. /usr/local/lib/php/data, C:\PHP\PEAR\data). 
    64    
    65    
    66   Traditional Installation 
    67   ------------------------ 
    68    
    69   Installation of Propel involves a few steps because Propel is composed of a generator 
    70   and runtime classes which are (now) packaged separately. 
    71    
    72   Begin installation of Propel by choosing a base directory and unpacking the archive.  
    73    
    74   For the sake of simplicity, we'll assume that you are installing from a package  
    75   (instead of CVS) into /var/www/php/. 
    76  
    77     % cd /var/www/php 
    78     % tar zxf /path/to/propel-x.x.x.tar.gz 
    79     % ln -s propel-x.x.x propel   
    80    
    81   A. Propel Generator 
    82    
    83   The Propel generator classes don't need any special setup.  The classes and Phing  
    84   scripts are located in the propel-generator/ directory (which in our example is 
    85   /var/www/php/propel/generator). 
    86    
    87   B. Runtime Classes  
    88  
    89   The runtime classes were unpacked to the propel/ directory (in this example,  
    90   /var/www/php/propel). In order to use these classes in runtime applications, you will  
    91   need to make sure that they are on the PHP include_path.  In our example, the  
    92   following directory would need to be added to your PHP include_path:  
    93   /var/www/php/propel/classes.  You could also copy the  
    94   /var/www/php/propel/classes/propel directory to a location that is already on your  
    95   include_path, e.g. the directory where PEAR classes are located: 
    96    
    97     % cp -r /var/www/php/propel/runtime/classes/propel /usr/local/lib/php/ 
    98    
    99   Another option on *nix systems is to create a symlink: 
    100    
    101     % ln -s /var/www/php/propel/runtime/classes/propel /usr/local/lib/php/propel   
    102    
    103    
    104   Quick Test 
    105   ---------- 
    106    
    107   If you want to quickly test & see whether your installation is working, you can use  
    108   the default configuration which will build the example application using SQLite. 
    109    
    110   Here is how to run the simple test on Unix (use corresponding commands for Windows). 
    111   If you  run into trouble, don't panic -- just continue reading the INSTALL guide and  
    112   consult the  Installation chapter of the online user guide at http://propel.phpdb.org. 
    113    
    114   Change to your propel-generator dir (e.g.) 
    115   $> cd /var/www/php/propel/generator 
    116    
    117   If using Propel from CVS, copy/rename the build.properties-sample file: 
    118   $> cp build.properties-sample build.properties 
    119    
    120   Run Phing to build the classes and SQL files, specifying the bookstore project 
    121   $> phing -Dproject=bookstore 
    122    
    123   Run the 'insert-sql' target which will add the tables to the SQLite db 
    124   $> phing -Dproject=bookstore insert-sql 
    125    
    126   Run the test script that uses the generated classes against the bookstore db: 
    127   $> cd test/ 
    128   $> php -f bookstore-test.php 
    129    
    130   You should see a bunch of output as it tests use cases.  Hopefully there aren't any  
    131   "FAILED" messages. If you get a failed message immediately indicating that it can't  
    132   find one of the tables make sure that you a) ran the 'insert'-sql' target and that  
    133   you are running the bookstore-test.php script from the main propel directory *and*  
    134   that you call PHP with the -qC options so that it won't chdir() into the scripts  
    135   directory.  (The path for the bookstore.db is ./test/bookstore.db so you can see  
    136   that you need to be in the main propel directory for that to work.) 
    137    
    138      
    139   Configure 
    140   --------- 
    141    
    142   To get Propel to work with your own db setup, create a new project (easiest way is  
    143   to use the bookstore project directory as a template). Create your datamodel schema,  
    144   modify the build.properties for that project to specify database connection  
    145   information, and set the db connection runtime properties in runtime-conf.xml. 
    146    
    147    
    148   Build 
    149   ----- 
    150    
    151   This assumes that you have already installed and configured a copy of PHING 2. 
    152  
    153     % cd /var/www/php/propel/generator   
    154     % phing -Dproject=mykillerapp     
    155  
    156   This will build the SQL files and the object & peer classes based on your datamodel  
    157   schema XML file. 
    158  
    159   The resulting files will be placed in:  
    160     /var/www/php/propel/generator/projects/mykillerapp/build 
    161  
    162   If you encounter any problems, try adding -verbose or -debug to get more output  
    163   from the PHING build process. 
    164    
    165  
    166   You're Done! 
    167   ------------ 
    168    
    169   At this point hopefully you have successfully built the classes and SQL definitions  
    170   for the sample bookstore application.  If you encountered problems, please visit  
    171   http://propel.phpdb.org to read additional documention, browse through the users  
    172   mailing list, or add a bug report. 
    173    
    174   Enjoy! 
    175    
    176   --$Id: INSTALL,v 1.4 2005/03/24 00:24:07 hlellelid Exp $ 
     1Please see the online documentation for installation instructions: 
     2  
     3  http://propel.phpdb.org/trac/wiki/Users/Documentation/Installation