Awesome work, Noah. Thumbs up. Can't wait to spare a moment and play
with this thoroughly.
Cheers,
David
Am 10.07.2008 um 19:08 schrieb Noah Fontes:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hey everyone!
>
> I've just merged my branch, impl-build_system, into trunk for 1.0.0.
> This means that the old build system is totally replaced from here on
> out in 1.0 development.
>
> Here's a brief-ish overview of how to use it.
>
> == Introduction ==
>
> Using the new build system is very similar in practice to using the
> old
> one. It's still based on Phing, although the wrapper script is a bit
> more complex (for reasons I will explain later).
>
> You'll want to grab either `agavi-dist' or `agavi.bat-dist' from the
> bin/ (not etc/) directory in the repository. (These were separated
> because users who have an external on the etc/ directory don't need
> the
> other stuff in there, as it's only really pertinent for building Agavi
> packages internally.) Then rename your script to `agavi' or
> `agavi.bat'
> and modify it to point to the correct paths to the Agavi src/
> directory;
> this is exactly the same procedure as with the old build system.
>
> Invoking the script should yield a status message outlining a few
> details about your environment, including Agavi, PHP, and individual
> project settings. You can get a list of callable Phing targets that
> have
> been exposed by passing the `-l' option to the script. For more
> information on the script's capabilities, check out the `-h' option.
>
> == Creating a project ==
>
> For creating a project, you've got two options. If you don't like the
> current functionality where Agavi assumes you want a Web environment
> with the system actions preinstalled for you, you can create a
> skeleton
> project. This is easily accomplished using the project-create target;
> simply invoke `agavi project-create' to call it. Otherwise, you can
> head
> straight for the wizard interface that behaves in a similar fashion to
> the old build system: use `agavi project'.
>
> == Project features and customization ==
>
> The build script is currently capable of automatically detecting
> project
> and module directories based on the location where the script is
> invoked. It also reads build.properties from both project root
> directories and module directories.
>
> In addition to specifying build properties in build.properties, users
> may customize the build process by adding project-specific build
> targets. Simply edit the build.xml file in a project root directory
> and
> add new targets to the file; they will be made available to Agavi when
> the `agavi' script is called within that project directory!
>
> The new build system also introduces a customizable hook system for
> listening for events involving targets, tasks, and messages. It is all
> configurable from a project build.xml:
>
> * Start by defining a new object in your build.xml:
> <agavi.object id="my-object" classname="MyAppBuildListener"
> classpath="${project.directory}/libs" />
>
> * Create a new file for your class, in this case
> libs/MyAppBuildListener.php.
>
> * In your class, implement one or many of the following interfaces:
> interface AgaviIPhingTargetListener {
> public function targetEntered(AgaviPhingTargetEvent $event);
> public function targetLeft(AgaviPhingTargetEvent $event);
> }
> interface AgaviIPhingTaskListener {
> public function taskEntered(AgaviPhingTaskEvent $event);
> public function taskLeft(AgaviPhingTaskEvent $event);
> }
> interface AgaviIPhingMessageListener {
> public function messageReported(AgaviPhingMessageEvent $event);
> }
>
> Check the source code documentation in src/build/agavi/phing/ for
> more
> information about implementing these.
>
> * Add a listening event to your new object in your build.xml:
> <agavi.target-listener object="my-object" />
> <agavi.task-listener object="my-object" />
> <agavi.message-listener object="my-object" />
>
> Things should just work(tm)!
>
> (This functionality is the reason that a custom Phing invocation
> script
> is needed: the project directory needs to be pre-determined before
> Phing
> is called :)
>
> == Installing a public directory ==
>
> Since Agavi is designed to be flexible in the most awesome ways
> possible, the `project-create' target doesn't even assume you're
> creating a new Web project. This means that your pub/ directory is
> completely empty after you create a new project! However, a default
> index.php and .htaccess can be quite easily installed; simply invoke
> `agavi public-web-create'. Users of `agavi project' will find their
> pub/
> directory pre-populated for convenience.
>
> == Creating modules ==
>
> The new build system again provides two utilities for creating
> modules,
> `module-create' and `module'. `module-create' creates a skeleton
> structure for a module, and `module' prompts for actions, views, and
> templates to create in addition to creating the basic directory
> structure.
>
> == Creating actions ==
>
> Actions may also be created using two utilities, `action-create' and
> `action'. `action-create' creates a single file for the new action;
> `action' prompts for views and templates to create for the new action.
>
> == Managing the project ==
>
> Several useful targets are also included for handling routine tasks
> within a project. These include:
>
> * project-cache-remove
> * project-configuration-set-system-action (assigns a module and action
> pair to a system action by editing the configuration file; quite
> useful
> when using `project-create' instead of `project')
> * project-model-create
> * project-template-create
> * module-list
> * action-list
> * view-create
> * view-template-create
> * model-create
> * template-create
>
> For a full list of available targets, remember that you can call
> `agavi -l'.
>
> == Automation ==
>
> Most build system targets should be able to be easily automated, with
> the obvious exception of the project, module, and action wizards. Some
> inspection of the targets (which reside in src/build/build.xml) will
> have to be done; the general format for passing a property to the
> build
> system is `agavi -D name value target' (for example, `agavi -D
> module.name MyNewModule module-create').
>
> == Limitations ==
>
> Currently, build templates (those copied when targets create new data)
> must come from one location. This will be resolved before the
> release of
> 1.0.0.
>
> For the record, the entire build template tree can be copied to a new
> directory by calling `agavi system-template-copy-all'. The property
> templates.directory should be set in a project build.properties file
> following this for the build system to recognize the new path.
>
> == Planned improvements ==
>
> Support for version control systems, removing and renaming actions,
> views, templates, etc. and a few other fun features are still slated
> to
> be added to the build system. Check out http://trac.agavi.org/ticket/798
> for more information.
>
> I hope that using this new build system will make managing Agavi
> projects a much more enjoyable experience than it has been in the
> past.
> As always, questions are welcomed, and any bugs should be reported at
> http://trac.agavi.org/newticket.
>
> Thanks and regards,
>
> - --
> Noah Fontes
> Bitextender
> http://www.bitextender.com/
> Phone: +01 919 349 9826
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.6 (GNU/Linux)
>
> iD8DBQFIdkHzhitK+HuUQJQRAjMNAJ9sZIx+P6LrF5N9R/DSwAGrDxZsRwCaArTJ
> 3d6tmfcfBKb5AkCVneBI3QQ=
> =nnee
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Agavi Dev Mailing List
> [email protected]
> http://lists.agavi.org/mailman/listinfo/dev
>
_______________________________________________
Agavi Dev Mailing List
[email protected]
http://lists.agavi.org/mailman/listinfo/dev
