root/tags/2.2.0RC1/classes/phing/Phing.php

<?php
/*
 * $Id: Phing.php,v 1.51 2006/01/06 15:12:33 hlellelid Exp $
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the LGPL. For more information please see
 * <http://phing.info>.
 */
 
require_once 'phing/Project.php';
require_once 'phing/ProjectComponent.php';
require_once 'phing/Target.php';
require_once 'phing/Task.php';

include_once 'phing/BuildException.php';
include_once 'phing/BuildEvent.php';

include_once 'phing/parser/Location.php';
include_once 'phing/parser/ExpatParser.php';
include_once 'phing/parser/AbstractHandler.php';
include_once 'phing/parser/ProjectConfigurator.php';
include_once 'phing/parser/RootHandler.php';
include_once 'phing/parser/ProjectHandler.php';
include_once 'phing/parser/TaskHandler.php';
include_once 'phing/parser/TargetHandler.php';
include_once 'phing/parser/DataTypeHandler.php';
include_once 'phing/parser/NestedElementHandler.php';

include_once 'phing/system/util/Properties.php';
include_once 'phing/util/StringHelper.php';
include_once 'phing/system/io/PhingFile.php';
include_once 'phing/system/io/FileReader.php';
include_once 'phing/system/util/Register.php';

/**
 * Entry point into Phing.  This class handles the full lifecycle of a build -- from 
 * parsing & handling commandline arguments to assembling the project to shutting down
 * and cleaning up in the end.
 *
 * If you are invoking Phing from an external application, this is still
 * the class to use.  Your applicaiton can invoke the start() method, passing
 * any commandline arguments or additional properties.
 *
 * @author    Andreas Aderhold <andi@binarycloud.com>
 * @author    Hans Lellelid <hans@xmpl.org>
 * @version   $Revision: 1.51 $
 * @package   phing
 */
class Phing {

    /** The default build file name */
    const DEFAULT_BUILD_FILENAME = "build.xml";

    /** Our current message output status. Follows PROJECT_MSG_XXX */
    private static $msgOutputLevel = PROJECT_MSG_INFO;

    /** PhingFile that we are using for configuration */
    private $buildFile = null;

    /** The build targets */
    private $targets = array();

    /**
     * Set of properties that are passed in from commandline or invoking code.
     * @var Properties
     */
    private static $definedProps;

    /** Names of classes to add as listeners to project */
    private $listeners = array();

    private $loggerClassname = null;

    /** The class to handle input (can be only one). */
    private $inputHandlerClassname;
    
    /** Indicates if this phing should be run */
    private $readyToRun = false;

    /** Indicates we should only parse and display the project help information */
    private $projectHelp = false;
    
    /** Used by utility function getResourcePath() */
    private static $importPaths;
    
    /** System-wide static properties (moved from System) */
    private static $properties = array();
    
    /** Static system timer. */
    private static $timer;
    
    /** The current Project */
    private static $currentProject;
    
    /** Whether to capture PHP errors to buffer. */
    private static $phpErrorCapture = false;
    
    /** Array of captured PHP errors */
    private static $capturedPhpErrors = array();
    
    /**
     * Prints the message of the Exception if it's not null.
     */
    function printMessage(Exception $t) {
        print($t->getMessage() . "\n");
        if (self::getMsgOutputLevel() === PROJECT_MSG_DEBUG) {
            print($t->getTraceAsString()."\n");
            if ($t instanceof Exception) {                
                $c = $t->getCause();
                if ($c !== null) {
                    print("Wrapped exception trace:\n");
                    print($c->getTraceAsString() . "\n");
                }
            }
        } // if output level is DEBUG
    }

    /** 
     * Entry point allowing for more options from other front ends.
     * 
     * This method encapsulates the complete build lifecycle.
     * 
     * @param array &$args The commandline args passed to phing shell script.
     * @param array $additionalUserProperties   Any additional properties to be passed to Phing (alternative front-end might implement this).
     *                                          These additional properties will be available using the getDefinedProperty() method and will
     *                                          be added to the project's "user" properties.
     * @return void
     * @see execute()
     * @see runBuild()
     */
    public static function start(&$args, $additionalUserProperties = null) {

        try {
            $m = new Phing();
            $m->execute($args);
        } catch (Exception $exc) {
            $m->printMessage($exc);
            self::halt(-1); // Parameter error
        }

        if ($additionalUserProperties !== null) {
            $keys = $m->additionalUserProperties->keys();
            while(count($keys)) {
                $key = array_shift($keys);
                $property = $m->additionalUserProperties->getProperty($key);
                $m->setDefinedProperty($key, $property);
            }
        }

        try {
            $m->runBuild();
        } catch(Exception $exc) {
            self::halt(1); // Errors occured
        }
        
        // everything fine, shutdown
        self::halt(0); // no errors, everything is cake
    }
    
    /**
     * Making output level a static property so that this property
     * can be accessed by other parts of the system, enabling
     * us to display more information -- e.g. backtraces -- for "debug" level.
     * @return int
     */
    public static function getMsgOutputLevel() {
        return self::$msgOutputLevel;
    }        
    
    /**
     * Command line entry point. This method kicks off the building
     * of a project object and executes a build using either a given
     * target or the default target.
     *
     * @param array $args Command line args.
     * @return void
     */
    public static function fire($args) {
        self::start($args, null);
    }
    
    /**
     * Setup/initialize Phing environment from commandline args.
     * @param array $args commandline args passed to phing shell.
     * @return void
     */
    public function execute($args) {
    
        self::$definedProps = new Properties();
        $this->searchForThis = null;

        // cycle through given args
        for ($i = 0, $argcount = count($args); $i < $argcount; ++$i) { 
                            // ++$i intentional here, as first param is script name
            $arg = $args[$i];

            if ($arg == "-help" || $arg == "-h") {
                $this->printUsage();
                return;
            } elseif ($arg == "-version" || $arg == "-v") {
                $this->printVersion();
                return;
            } elseif ($arg == "-quiet" || $arg == "-q") {
                self::$msgOutputLevel = PROJECT_MSG_WARN;
            } elseif ($arg == "-verbose") {
                $this->printVersion();
                self::$msgOutputLevel = PROJECT_MSG_VERBOSE;
            } elseif ($arg == "-debug") {
                $this->printVersion();
                self::$msgOutputLevel = PROJECT_MSG_DEBUG;
            } elseif ($arg == "-logfile") {
                try { // try to set logfile
                    if (!isset($args[$i+1])) {
                        print("You must specify a log file when using the -logfile argument\n");
                        return;
                    } else {
                        $logFile = new PhingFile($args[++$i]);
                        $this->loggerClassname = 'phing.listener.PearLogger';
                        $this->setDefinedProperty('pear.log.name', $logFile->getAbsolutePath());
                    }
                } catch (IOException $ioe) {
                    print("Cannot write on the specified log file. Make sure the path exists and you have write permissions.\n");
                    throw $ioe;
                }
            } elseif ($arg == "-buildfile" || $arg == "-file" || $arg == "-f") {
                if (!isset($args[$i+1])) {
                    print("You must specify a buildfile when using the -buildfile argument\n");
                    return;
                } else {
                    $this->buildFile = new PhingFile($args[++$i]);
                }
            } elseif ($arg == "-listener") {
                if (!isset($args[$i+1])) {
                    print("You must specify a listener class when using the -listener argument\n");
                    return;
                } else {
                    $this->listeners[] = $args[++$i];
                }
                
            } elseif (StringHelper::startsWith("-D", $arg)) {
                $name = substr($arg, 2);
                $value = null;
                $posEq = strpos($name, "=");
                if ($posEq !== false) {
                    $value = substr($name, $posEq+1);
                    $name  = substr($name, 0, $posEq);
                } elseif ($i < count($args)-1) {
                    $value = $args[++$i];
                }
                self::$definedProps->setProperty($name, $value);
            } elseif ($arg == "-logger") {
                if (!isset($args[$i+1])) {
                    print("You must specify a classname when using the -logger argument\n");
                    return;
                } else {
                    $this->loggerClassname = $args[++$i];
                }
            } elseif ($arg == "-inputhandler") {
                if ($this->inputHandlerClassname !== null) {
                    throw new BuildException("Only one input handler class may be specified.");
                }
                if (!isset($args[$i+1])) {
                    print("You must specify a classname when using the -inputhandler argument\n");
                    return;
                } else {
                    $this->inputHandlerClassname = $args[++$i];
                }
            } elseif ($arg == "-projecthelp" || $arg == "-targets" || $arg == "-list" || $arg == "-l") {
                // set the flag to display the targets and quit
                $this->projectHelp = true;
            } elseif ($arg == "-find") {
                // eat up next arg if present, default to build.xml
                if ($i < count($args)-1) {
                    $this->searchForThis = $args[++$i];
                } else {
                    $this->searchForThis = self::DEFAULT_BUILD_FILENAME;
                }
            } elseif (substr($arg,0,1) == "-") {
                // we don't have any more args
                print("Unknown argument: $arg\n");
                $this->printUsage();
                return;
            } else {
                // if it's no other arg, it may be the target
                array_push($this->targets, $arg);
            }
        }

        // if buildFile was not specified on the command line,
        if ($this->buildFile === null) {
            // but -find then search for it
            if ($this->searchForThis !== null) {
                $this->buildFile = $this->_findBuildFile(self::getProperty("user.dir"), $this->searchForThis);
            } else {
                $this->buildFile = new PhingFile(self::DEFAULT_BUILD_FILENAME);
            }
        }
        // make sure buildfile exists
        if (!$this->buildFile->exists()) {
            throw new BuildException("Buildfile: " . $this->buildFile->__toString() . " does not exist!");
        }

        // make sure it's not a directory
        if ($this->buildFile->isDirectory()) {   
            throw new BuildException("Buildfile: " . $this->buildFile->__toString() . " is a dir!");
        }

        $this->readyToRun = true;
    }

    /**
     * Helper to get the parent file for a given file.
     *
     * @param PhingFile $file
     * @return PhingFile Parent file or null if none
     */
    function _getParentFile(PhingFile $file) {
        $filename = $file->getAbsolutePath();
        $file     = new PhingFile($filename);
        $filename = $file->getParent();

        if ($filename !== null && self::$msgOutputLevel >= PROJECT_MSG_VERBOSE) {
            print("Searching in $filename\n");
        }

        return ($filename === null) ? null : new PhingFile($filename);
    }

    /**
     * Search parent directories for the build file.
     *
     * Takes the given target as a suffix to append to each
     * parent directory in search of a build file.  Once the
     * root of the file-system has been reached an exception
     * is thrown.
     * 
     * @param string $start Start file path.
     * @param string $suffix Suffix filename to look for in parents.
     * @return PhingFile A handle to the build file
     *
     * @throws BuildException    Failed to locate a build file
     */
    function _findBuildFile($start, $suffix) {
        if (self::$msgOutputLevel >= PROJECT_MSG_INFO) {
            print("Searching for $suffix ...\n");
        }
        $startf = new PhingFile($start);
        $parent = new PhingFile($startf->getAbsolutePath());
        $file   = new PhingFile($parent, $suffix);

        // check if the target file exists in the current directory
        while (!$file->exists()) {
            // change to parent directory
            $parent = $this->_getParentFile($parent);

            // if parent is null, then we are at the root of the fs,
            // complain that we can't find the build file.
            if ($parent === null) {
                throw new BuildException("Could not locate a build file!");
            }
            // refresh our file handle
            $file = new PhingFile($parent, $suffix);
        }
        return $file;
    }

    /**
     * Executes the build.
     * @return void
     */
    function runBuild() {

        if (!$this->readyToRun) {
            return;
        }
        
        $project = new Project();
        
        self::setCurrentProject($project);
        set_error_handler(array('Phing', 'handlePhpError'));
        
        $error = null;

        $this->addBuildListeners($project);
        $this->addInputHandler($project);
        
        // set this right away, so that it can be used in logging.
        $project->setUserProperty("phing.file", $this->buildFile->getAbsolutePath());

        try {
            $project->fireBuildStarted();
            $project->init();
        } catch (Exception $exc) {
            $project->fireBuildFinished($exc);
            throw $exc;        
        }

        $project->setUserProperty("phing.version", $this->getPhingVersion());

        $e = self::$definedProps->keys();
        while (count($e)) {
            $arg   = (string) array_shift($e);
            $value = (string) self::$definedProps->getProperty($arg);
            $project->setUserProperty($arg, $value);
        }
        unset($e);

        $project->setUserProperty("phing.file", $this->buildFile->getAbsolutePath());

        // first use the Configurator to create the project object
        // from the given build file.
                
        try {
            ProjectConfigurator::configureProject($project, $this->buildFile);
        } catch (Exception $exc) {
            $project->fireBuildFinished($exc);
            restore_error_handler();
            self::unsetCurrentProject();
            throw $exc;
        }         

        // make sure that we have a target to execute
        if (count($this->targets) === 0) {
            $this->targets[] = $project->getDefaultTarget();
        }

        // execute targets if help param was not given
        if (!$this->projectHelp) {
            
            try { 
                $project->executeTargets($this->targets);
            } catch (Exception $exc) {
                $project->fireBuildFinished($exc);
                restore_error_handler();
                self::unsetCurrentProject();
                throw $exc;
            }
        }
        // if help is requested print it
        if ($this->projectHelp) {
            try {
                $this->printDescription($project);
                $this->printTargets($project);
            } catch (Exception $exc) {
                $project->fireBuildFinished($exc);
                restore_error_handler();
                self::unsetCurrentProject();
                throw $exc;
            }
        }
                
        // finally {
        if (!$this->projectHelp) {
            $project->fireBuildFinished(null);
        }
        
        restore_error_handler();
        self::unsetCurrentProject();
    }
    
    /**
     * Bind any default build listeners to this project.
     * Currently this means adding the logger.
     * @param Project $project
     * @return void
     */
    private function addBuildListeners(Project $project) {
        // Add the default listener
        $project->addBuildListener($this->createLogger());
    }
    
    /**
     * Creates the InputHandler and adds it to the project.
     *
     * @param Project $project the project instance.
     *
     * @throws BuildException if a specified InputHandler
     *                           class could not be loaded.
     */
    private function addInputHandler(Project $project) {
        if ($this->inputHandlerClassname === null) {
            $handler = new DefaultInputHandler();
        } else {
            try {
                $clz = Phing::import($this->inputHandlerClassname);
                $handler = new $clz();
                if ($project !== null && method_exists($handler, 'setProject')) {
                    $handler->setProject($project);
                } 
            } catch (Exception $e) {
                $msg = "Unable to instantiate specified input handler "
                    . "class " . $this->inputHandlerClassname . " : "
                    . $e->getMessage();
                throw new BuildException($msg);
            }
        }
        $project->setInputHandler($handler);
    }

    /**
     * Creates the default build logger for sending build events to the log.
     * @return BuildListener The created Logger
     */
    private function createLogger() {
        if ($this->loggerClassname !== null) {
            self::import($this->loggerClassname);
            // get class name part            
            $classname = self::import($this->loggerClassname);
            $logger = new $classname;
        } else {
            require_once 'phing/listener/DefaultLogger.php';
            $logger = new DefaultLogger();
        }
        $logger->setMessageOutputLevel(self::$msgOutputLevel);
        return $logger;
    }
    
    /**
     * Sets the current Project
     * @param Project $p
     */
    public static function setCurrentProject($p) {