-----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
