[jsword-devel] Core build documentation

[DM Smith]

This is a great document. It captures the antcall/depends nature of the 
problem. I think this would be a great addition to the website. I think 
that if it were top down or left to right, it would be better for viewing.

You can easily see the relationships, and the shortcomings.

Here are the basic ideas I had in creating core.xml.

The build process would represent a development cycle of edit, build, 
test and install (aka publish). (Edit of course is what we do before we 
run the build.) This cycle would be incremental. Only the things that 
change would build, all tests would run and if the test succeeded the 
changes would be published. The install location is called nightly.

So the target "incremental" depends on build, test and install. I had it 
this way in a one of the patches, but the change was not applied. Test 
as you note in the diagram is an orphan.

Like all good builds, it would have another cycle for a clean build. 
(Currently this target is called "all"). This would be used to build 
everything from scratch. The one thing that I have not done is to have 
it build to two locations, nightly and release.

A difficulty in this implementation is that the layout of the source and 
resource files in JSword for a project is broken up into a "modules" 
(for lack of a better name).

We have all source under "java" and all resources, except resource 
bundles (aka messages), under "resource". We keep work of the past or 
for the future in "limbo", and test code is kept in "test". For common, 
we maintain "config" separately. As a reasonable nod to the 
model-view-controller paradigm, we may have separate directories for 
view code and model/controller code. Earlier this was to be able to 
deliver separate jars for view and non-view code.

There is another notion that the build file introduces, "prepare". The 
purpose of this target is twofold, copy the "external" (not created by 
the project) jar files that are needed for the install from lots of 
different directories into a single directory. We do this up front 
because it makes setting up classpaths easier. Prepare also served 
another purpose to generated OSIS classes. This second purpose gave rise 
to the notion of "extra" which is discussed below.

Additionally, each project could depend upon at most one other project, 
recursively. This relationship would end up building that other project 
first. If we merely wanted to build everything every time, then it would 
make for a very simple build file. Just call the other build file's 
"all" target. But if we want to allow for multiple entry points, we need 
to make sure that there is a mechanism for each of these to invoke the 
corresponding entry point in the other build file.

Currently this has build.dependency for build, prepare.dependency for 
prepare, and so forth. I have not played with it but it looks like 
"subant" can simplify this. It was not a part of ant when I wrote core.xml.

In the build.xml there are three different techniques and purposes in 
dependencies. Sometimes dependencies are used to merely sequentially 
order tasks. This can be seen in the incremental and the all tasks. It 
is especially obvious when there is no body to the task.

Dependencies are also used to have pre-requisites executed before 
particular work is done. This is like the former, but the task also does 
work.

The third kind of dependency doesn't use the depends attribute, but 
"antcall". It is work that needs to be done at a particular point in the 
execution flow that does not easily fit as a value of the depends 
attribute.

Since core.xml is generic and cannot anticipate everything every project 
can do, it has hooks for each project to declare "extra" stuff to do. 
These are done at the end of the body of their corresponding task.

A comment on the init target. I have seen it in almost every ant build 
file. As you noted, it is an orphan for almost all practical purposes, 
in core.xml. I don't see any purpose or value in having it. The build 
seems to work the same with or without it. Unless I am missing something...

Joe Walker wrote:

> 
> Hi,
> 
> I realized that I didn't really understand the core.xml "base class" ant 
> build file. So I wrote a very quick document in OpenOffice describing 
> the targets and how they relate to each other, mostly so I understand 
> but it might help others.
> 
> I'm posting it (and a png export) because I think that some of the 
> dependencies are wrong. The arrows show either "depends" attributes or 
> "antcall" elements. There has been no attempt to show ordering.
> 
> I suspect that test should depend on compile and that prepare should 
> depend on init.
> 
> Joe.
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> jsword-devel mailing list
> jsword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/jsword-devel