You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by Ceki Gülcü <cg...@qos.ch> on 2001/05/07 13:13:56 UTC
Proposed dirlayout document
Hi everyone,
Having recently looked at http://jakarta.apache.org/site/dirlayout.html, my impression was that it allowed too many alternatives on a large number of points rendering the document somewhat confusing (useless?). I am against making the dirlayout document an exhaustive list of all possible layout structures. A guideline document should be a bit more assertive.
With your permission I would like to eliminate some of the alternatives. This is surely going upset some people. I am asking for the permission to make some potentially controversial changes. Let me repeat that I do not consider myself as an expert in ANT or to know the optimal directory structures. As such, you are strongly encouraged to make suggestions.
In order to avoid endless discussion, I am willing to cede my role if anyone volunteers to take up the responsibility for the document. Best regards, Ceki
--
Ceki Gülcü
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Jason van Zyl <jv...@apache.org>.
Ceki Gülcü wrote:
>
> Hi everyone,
>
> Having recently looked at http://jakarta.apache.org/site/dirlayout.html, my impression was that it allowed too many alternatives on a large number of points rendering the document somewhat confusing (useless?). I am against making the dirlayout document an exhaustive list of all possible layout structures. A guideline document should be a bit more assertive.
>
> With your permission I would like to eliminate some of the alternatives. This is surely going upset some people. I am asking for the permission to make some potentially controversial changes. Let me repeat that I do not consider myself as an expert in ANT or to know the optimal directory structures. As such, you are strongly encouraged to make suggestions.
>
> In order to avoid endless discussion, I am willing to cede my role if anyone volunteers to take up the responsibility for the document. Best regards, Ceki
+1
I too feel that endless options are a bad thing. I say go for it. If
you're
willing to do the work, I'm willing to accept what you do.
>
> --
> Ceki Gülcü
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
--
jvz.
Jason van Zyl
jvanzyl@apache.org
http://jakarta.apache.org/velocity
http://jakarta.apache.org/turbine
http://jakarta.apache.org/commons
http://tambora.zenplex.org
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Vincent Massol <vm...@octo.com>.
+1 also
Here are some comments I have after reading the dirlayout.html file (for the
first time, I have to admit. Actually I don't know where it is linked to on
the jakarta web site !) ...
I don't want to start a lengthy discussion (as it is very difficult to reach
an agreement on these subjects ... :) ) but I still wanted to help ... :)
1) There is no directory defined for configuration files (top level
properties file, top level xml files, manifest file to include in jar, ...).
Do we want to define a location for these ?
2) The rule for the output directory says : either bin/ or build/. I think
that a) we must make up our minds on one choice only and b) then names are
not well choosen as they be misinterpreted. I would suggest something less
equivocal like out/ : build/ can be both the location of the files needed
for building the project or the result of the build and bin/ can be location
of generated executables or executable needed by the project for some tasks.
Also, bin/ is inherited from previous languages like C/C++ where you built
and executable. In java it is not really an executable, more like a library
but lib/ wouldn't be good either.
3) Until we all agree, I would let the project decide on how to use Ant :
a) as an application that need to be installed on the computer doing the
build. This means no need to have ant.jar, optional.jar, xerces.jar,
xalan.jar, stylebook.jar, .... in the build/lib directory and no .bat or .sh
files needed either.
b) as a "component", i.e. located in build/lib with all it's needed jar
files
4) The section on docs/ is not clear. Is it output docs not in CVS or non
generated docs in CVS. It seems to be both. Should be clarified I think
5) There should be only one name for the build scripts and tools. I would
tend to prefer build/ with the output directory named out/. I don't really
care about the name but there should be only one proposed
6) 2 options should be left to the project for the external jar needed to
build/run the project. Until we reach an agreement on course ... (maybe
CJAN/JJAR - see the discussion on jakarta-commons mailing list - will help)
:
a) leave the external jars out of CVS. i.e. use a build.properties file
(used by Ant) that defines the location of needed external jars
b) or check the needed external libs in CVS with the project.
Hope it helps.
Thanks
Vincent.
----- Original Message -----
From: "Conor MacNeill" <co...@cortexebusiness.com.au>
To: <ge...@jakarta.apache.org>
Sent: Monday, May 07, 2001 1:51 PM
Subject: Re: Proposed dirlayout document
> Ceki,
>
> +1
>
> I agree. Too much optionality in a standard means there is nothing
standard
> about it. I raised some issues about the original layout. These were just
> raising what I thought was the common Jakarta approach to some of these
> things.
>
> So, lets have a single approach with little optionality. It should be
> non-binding with a goal to move current projects to this standard.
>
> I don't think Ant should dictate the structure. I'm confident it will be
> able to support anything reasonable.
>
> Bring it on ...
>
> Conor
>
> ----- Original Message -----
> From: "Ceki Gülcü" <cg...@qos.ch>
> To: <ge...@jakarta.apache.org>
> Sent: Monday, May 07, 2001 9:13 PM
> Subject: Proposed dirlayout document
>
>
>
> Hi everyone,
>
> Having recently looked at http://jakarta.apache.org/site/dirlayout.html,
my
> impression was that it allowed too many alternatives on a large number of
> points rendering the document somewhat confusing (useless?). I am against
> making the dirlayout document an exhaustive list of all possible layout
> structures. A guideline document should be a bit more assertive.
>
> With your permission I would like to eliminate some of the alternatives.
> This is surely going upset some people. I am asking for the permission to
> make some potentially controversial changes. Let me repeat that I do not
> consider myself as an expert in ANT or to know the optimal directory
> structures. As such, you are strongly encouraged to make suggestions.
>
> In order to avoid endless discussion, I am willing to cede my role if
> anyone volunteers to take up the responsibility for the document. Best
> regards, Ceki
>
>
>
> --
> Ceki Gülcü
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Vincent Massol <vm...@octo.com>.
----- Original Message -----
From: "Peter Donald" <do...@apache.org>
To: <ge...@jakarta.apache.org>
Sent: Monday, May 07, 2001 3:28 PM
Subject: Re: Proposed dirlayout document
> At 03:03 7/5/01 +0100, Vincent Massol wrote:
> >1) There is no directory defined for configuration files (top level
> >properties file, top level xml files, manifest file to include in jar,
...).
> >Do we want to define a location for these ?
>
> yup. I recomend
>
> src/conf for config files (as many are manipulated via value substitution)
+1
> src/manifest for manifests .. mainly as it is less unixy than src/etc ;)
>
hum ... do we want so many different directories for config files. I would
prefer just one like src/conf and then leave it up to the project for
creating as many subdirectories as deemed necessary ... Why make it a
special case for manifests ?
> >2) The rule for the output directory says : either bin/ or build/. I
think
> >that a) we must make up our minds on one choice only and b) then names
are
> >not well choosen as they be misinterpreted. I would suggest something
less
> >equivocal like out/
>
> +1 for out (basically intermediates directory right?)
right
>
> >3) Until we all agree, I would let the project decide on how to use Ant :
> >a) as an application that need to be installed on the computer doing the
> >build. This means no need to have ant.jar, optional.jar, xerces.jar,
> >xalan.jar, stylebook.jar, .... in the build/lib directory and no .bat or
.sh
> >files needed either.
> >b) as a "component", i.e. located in build/lib with all it's needed jar
> >files
>
> Again - a lot of projects use build as intermediate directory and it would
> be unnacceptable to have it transmogify into something that contains
> scripts/tools/etc - hence I recomend "tools" dir to hold this if present.
>
No, I meant strategies on how to use Ant : as an installed application vs an
"embedded" application/component.
> >4) The section on docs/ is not clear. Is it output docs not in CVS or non
> >generated docs in CVS. It seems to be both. Should be clarified I think
>
> the problem is the answer is "it depends" until someone implements a
> jakarta wide building of website docs ;)
>
> >5) There should be only one name for the build scripts and tools. I would
> >tend to prefer build/ with the output directory named out/. I don't
really
> >care about the name but there should be only one proposed
>
> I prefer build.xml and build.[sh|bat] if present to be at base of tree
> while the rest of tools/scripts in "tools" dir. This doesnm't cause any
> conflicts with any projects I have noticed.
>
I see. You want to remove the build configuration from the build/tools
directory so that you can have only tools in that directory (basically Ant +
dependent jars) and name it "tools/", right ? So for those who use Ant as an
installed application, this "tools/" directory won't be need (unless they
use other tools).
> >6) 2 options should be left to the project for the external jar needed to
> >build/run the project. Until we reach an agreement on course ... (maybe
> >CJAN/JJAR - see the discussion on jakarta-commons mailing list - will
help)
> >:
> >a) leave the external jars out of CVS. i.e. use a build.properties file
> >(used by Ant) that defines the location of needed external jars
> >b) or check the needed external libs in CVS with the project.
>
> or both ;)
>
Yes. That's why I said "2 options should be left [...]" ... :)
> Cheers,
>
> Pete
Cheers,
Vincent.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Peter Donald <do...@apache.org>.
At 03:03 7/5/01 +0100, Vincent Massol wrote:
>1) There is no directory defined for configuration files (top level
>properties file, top level xml files, manifest file to include in jar, ...).
>Do we want to define a location for these ?
yup. I recomend
src/conf for config files (as many are manipulated via value substitution)
src/manifest for manifests .. mainly as it is less unixy than src/etc ;)
>2) The rule for the output directory says : either bin/ or build/. I think
>that a) we must make up our minds on one choice only and b) then names are
>not well choosen as they be misinterpreted. I would suggest something less
>equivocal like out/
+1 for out (basically intermediates directory right?)
>3) Until we all agree, I would let the project decide on how to use Ant :
>a) as an application that need to be installed on the computer doing the
>build. This means no need to have ant.jar, optional.jar, xerces.jar,
>xalan.jar, stylebook.jar, .... in the build/lib directory and no .bat or .sh
>files needed either.
>b) as a "component", i.e. located in build/lib with all it's needed jar
>files
Again - a lot of projects use build as intermediate directory and it would
be unnacceptable to have it transmogify into something that contains
scripts/tools/etc - hence I recomend "tools" dir to hold this if present.
>4) The section on docs/ is not clear. Is it output docs not in CVS or non
>generated docs in CVS. It seems to be both. Should be clarified I think
the problem is the answer is "it depends" until someone implements a
jakarta wide building of website docs ;)
>5) There should be only one name for the build scripts and tools. I would
>tend to prefer build/ with the output directory named out/. I don't really
>care about the name but there should be only one proposed
I prefer build.xml and build.[sh|bat] if present to be at base of tree
while the rest of tools/scripts in "tools" dir. This doesnm't cause any
conflicts with any projects I have noticed.
>6) 2 options should be left to the project for the external jar needed to
>build/run the project. Until we reach an agreement on course ... (maybe
>CJAN/JJAR - see the discussion on jakarta-commons mailing list - will help)
>:
>a) leave the external jars out of CVS. i.e. use a build.properties file
>(used by Ant) that defines the location of needed external jars
>b) or check the needed external libs in CVS with the project.
or both ;)
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 15:03 07.05.2001 +0100, you wrote:
>+1 also
>
>Here are some comments I have after reading the dirlayout.html file (for the
>first time, I have to admit. Actually I don't know where it is linked to on
>the jakarta web site !) ...
>
>I don't want to start a lengthy discussion (as it is very difficult to reach
>an agreement on these subjects ... :) ) but I still wanted to help ... :)
Sure, all suggestions are welcome and even encouraged.
>1) There is no directory defined for configuration files (top level
>properties file, top level xml files, manifest file to include in jar, ...).
>Do we want to define a location for these ?
Peter's suggestion in a follow up mail makes sense. Just to make sure, what do you mean by configuration files (top level properties file, top level xml files)? Are these config files for ANT?
Let me mention that I have had a hard time to have build.xml file in anywhere except the project top level directory but that might be due to my level of incompetence.
>2) The rule for the output directory says : either bin/ or build/. I think
>that a) we must make up our minds on one choice only and b) then names are
>not well choosen as they be misinterpreted. I would suggest something less
>equivocal like out/ : build/ can be both the location of the files needed
>for building the project or the result of the build and bin/ can be location
>of generated executables or executable needed by the project for some tasks.
>Also, bin/ is inherited from previous languages like C/C++ where you built
>and executable. In java it is not really an executable, more like a library
>but lib/ wouldn't be good either.
I agree, bin/ implies an executable and build/ can be confused with the files required for building, or the intermediary files or the (final) results of the build.
Although out/ is quite reasonable, it also leaves an ambiguity. Does out/ contain the actual distribution (final) results or intermediary results?
>3) Until we all agree, I would let the project decide on how to use Ant :
>a) as an application that need to be installed on the computer doing the
>build. This means no need to have ant.jar, optional.jar, xerces.jar,
>xalan.jar, stylebook.jar, .... in the build/lib directory and no .bat or .sh
>files needed either.
>b) as a "component", i.e. located in build/lib with all it's needed jar
>files
It is up to the project to decide whether to include jar files or not whether in CVS or in the actual distribution.
>4) The section on docs/ is not clear. Is it output docs not in CVS or non
>generated docs in CVS. It seems to be both. Should be clarified I think
IMHO, there is no absolute requirement to have the generated doc files under CVS control. As long the docs/ directory contains all the files in the project's home page it is possible to dump the contents of the docs/ directory to the directory corresponding to http://jakarta.apache.org/some_project.
For log4j, this is what we do:
1) At project build time, we tar and zip the contents of the distribution to jakarta-log4j-vX.X.tar.gz.
2) On the jakarta web server, we untar jakarta-log4j-vX.X.tar.gz in $JAKARTA_WWW/log4j/ where $JAKARTA_WWW is the top-level directory for all jakarta project home pages. This creates a directory called $JAKARTA_WWW/log4j/jakarta-log4j-vX.X/
3) We soft link $JAKARTA_WWW/log4j/jakarta-log4j-vX.X/docs/ to $JAKARTA_WWW/log4j/docs/
4) We also (once and for all) redirect most requests to $JAKARTA_WWW/log4j/ to $JAKARTA_WWW/log4j/docs/. See the .htaccess file under $JAKARTA_WWW/log4j/.
Are you confused yet? I would be... :-) In any case, that is one way to do it without having files in docs/
under CVS control. The drawback of this approach is that you cannot easily change the contents of your web-site without making a new release. That sucks big time unless you mandate that the contents of docs/ in your distribution is identical to the contents of your web-site.
>5) There should be only one name for the build scripts and tools. I would
>tend to prefer build/ with the output directory named out/. I don't really
>care about the name but there should be only one proposed
Sure.
>6) 2 options should be left to the project for the external jar needed to
>build/run the project. Until we reach an agreement on course ... (maybe
>CJAN/JJAR - see the discussion on jakarta-commons mailing list - will help)
>:
>a) leave the external jars out of CVS. i.e. use a build.properties file
>(used by Ant) that defines the location of needed external jars
>b) or check the needed external libs in CVS with the project.
When CJAN/JJAR provide a flexible alternative, I assume that jakarta projects would migrate to benefit from the functionality offered by these tools. I am silently following the discussion in commons. Cheers, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 15:03 07.05.2001 +0100, you wrote:
>+1 also
>
>Here are some comments I have after reading the dirlayout.html file (for the
>first time, I have to admit. Actually I don't know where it is linked to on
>the jakarta web site !) ...
Almost forgot. dirlayout is not linked from anywhere because it is still a draft document. Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
Ceki,
+1
I agree. Too much optionality in a standard means there is nothing standard
about it. I raised some issues about the original layout. These were just
raising what I thought was the common Jakarta approach to some of these
things.
So, lets have a single approach with little optionality. It should be
non-binding with a goal to move current projects to this standard.
I don't think Ant should dictate the structure. I'm confident it will be
able to support anything reasonable.
Bring it on ...
Conor
----- Original Message -----
From: "Ceki Gülcü" <cg...@qos.ch>
To: <ge...@jakarta.apache.org>
Sent: Monday, May 07, 2001 9:13 PM
Subject: Proposed dirlayout document
Hi everyone,
Having recently looked at http://jakarta.apache.org/site/dirlayout.html, my
impression was that it allowed too many alternatives on a large number of
points rendering the document somewhat confusing (useless?). I am against
making the dirlayout document an exhaustive list of all possible layout
structures. A guideline document should be a bit more assertive.
With your permission I would like to eliminate some of the alternatives.
This is surely going upset some people. I am asking for the permission to
make some potentially controversial changes. Let me repeat that I do not
consider myself as an expert in ANT or to know the optimal directory
structures. As such, you are strongly encouraged to make suggestions.
In order to avoid endless discussion, I am willing to cede my role if
anyone volunteers to take up the responsibility for the document. Best
regards, Ceki
--
Ceki Gülcü
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Watchdog
Posted by Tod Thomas <tt...@chubb.com>.
Both the source and the binary download links are returning 404 errors. Where can I pick up the latest, or is it not active anymore?
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Mon, 7 May 2001, Ceki [iso-8859-1] G�lc� wrote:
> At 10:02 07.05.2001 -0700, you wrote:
> >On Mon, 7 May 2001, Ceki [iso-8859-1] G�lc� wrote:
> >
> >>
> >> I have asked this before but is there a need for an intermediary
> >> directory? For example, to take an example I am familiar with, Tomcat
> >> 4.x, a damn good project I might add, has a build/ directory and a
> >> dist/ directory where dist/ is a copy of build/. I do not know why
> >> Tomcat is doing this but it is. Other projects are doing similar
> >> things. I am obviously missing something...
> >>
> >
> >The two targets are *not* identical.
>
>
> >Tomcat developers want to do the minimum amount of work necessary to
> >create a runnable version of Tomcat -- thus, they execute the default
> >build.xml target ("deploy-main") that creates an executable Tomcat 4.0 in
> >the "build" directory. To speed things up, this dispenses with Javadoc
> >creation, JARing things up, and stuff like that.
> >
> >When you're ready to cut a release (or a nightly build), the "dist" target
> >is used, which creates a complete binary distribution. Obviously, large
> >parts of this can be copied from the "build" output (it would not make
> >sense to recompile everything, and so on) -- but there are also additional
> >steps. But this target is not used for daily development work.
> >
> >Bottom line -- having an intermediate build directory substantially
> >improves the turnaround time for me as a Tomcat developer.
>
> Hi Craig,
>
> Thanks for taking the time to clarify the Tomcat build process. If I
> understand you correctly, the reason behind having two target
> directories is to speed up the creation of a "work" version of
> Tomcat. Would it not be possible to have a "build" target that just
> creates compiled classes, a "jar" target to create jar files, a
> "javadoc" target to create javadocs and a "dist" target to create a
> complete distro? (The "dist" target would depend on "jar" and
> "javadoc" targets. The "jar" target would depend on "build".)
>
> Thus, it would be possible to have a working version by invoking the
> build target? Regards, Ceki
>
>
Inside the scripts, that is essentially what happens. To create a
runnable (for development) version of Tomcat 4.0 in a freshly checked out
repository, simply execute
./build.sh
in the top level directory. Then, set CATALINA_HOME to the "build"
directory path (for me, that means
/home/craigmcc/Jakarta/jakarta-tomcat-4.0/build), and start it up by
saying
$CATALINA_HOME/bin/startup.sh
(or the equivalent if you're using Windows).
The default target creates a "work" version in the "build" directory,
without going to any efforts that are not yet necessary. The "dist"
target assumes that the default target has been completed already (with a
"depends" rule) and does some extra stuff to create the binary
distribution -- which my nightly job does every night, and I do when I
create a release. Otherwise, I never run the "dist" target.
Tomcat is not just a JAR file when you get done with it -- you need a
series of files in a series of directories to create the executable
product. Therefore, in real life, the Tomcat build process is more
complex than this in its details, because there are independent build.xml
scripts for the major components (catalina, jasper, webapps) -- but they
all follow the same basic philosophy.
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 10:02 07.05.2001 -0700, you wrote:
>On Mon, 7 May 2001, Ceki [iso-8859-1] Gülcü wrote:
>
>>
>> I have asked this before but is there a need for an intermediary
>> directory? For example, to take an example I am familiar with, Tomcat
>> 4.x, a damn good project I might add, has a build/ directory and a
>> dist/ directory where dist/ is a copy of build/. I do not know why
>> Tomcat is doing this but it is. Other projects are doing similar
>> things. I am obviously missing something...
>>
>
>The two targets are *not* identical.
>Tomcat developers want to do the minimum amount of work necessary to
>create a runnable version of Tomcat -- thus, they execute the default
>build.xml target ("deploy-main") that creates an executable Tomcat 4.0 in
>the "build" directory. To speed things up, this dispenses with Javadoc
>creation, JARing things up, and stuff like that.
>
>When you're ready to cut a release (or a nightly build), the "dist" target
>is used, which creates a complete binary distribution. Obviously, large
>parts of this can be copied from the "build" output (it would not make
>sense to recompile everything, and so on) -- but there are also additional
>steps. But this target is not used for daily development work.
>
>Bottom line -- having an intermediate build directory substantially
>improves the turnaround time for me as a Tomcat developer.
Hi Craig,
Thanks for taking the time to clarify the Tomcat build process. If I understand you correctly, the reason behind having two target directories is to speed up the creation of a "work" version of Tomcat. Would it not be possible to have a "build" target that just creates compiled classes, a "jar" target to create jar files, a "javadoc" target to create javadocs and a "dist" target to create a complete distro? (The "dist" target would depend on "jar" and "javadoc" targets. The "jar" target would depend on "build".)
Thus, it would be possible to have a working version by invoking the build target? Regards, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Vincent Massol <vm...@octo.com>.
----- Original Message -----
From: "Ceki Gülcü" <cg...@qos.ch>
To: <ge...@jakarta.apache.org>
Sent: Monday, May 07, 2001 5:09 PM
Subject: Re: Proposed dirlayout document
[znip]
>I have asked this before but is there a need for an intermediary directory?
For example, to take an example I am familiar with, Tomcat 4.x, a damn good
project I might add, has a build/ directory and a dist/ directory where
dist/ is a copy of build/. I do not know why Tomcat is doing this but it is.
Other projects are doing similar things. I am obviously missing something...
The intermediate directory (out/ in my proposition) is mostly used to
replace tokens and will contain files that are not needed for the
distribution. For example :
- in the Cactus project, I copy all the java source to the out/ directory
and replace the @version@ token by the current version. This is before doing
the compilation and generating the javadoc
- it contains the classes files which are not part of the distribution
- it contains copies of the manifest file in which tokens have been replaced
(@version@ for example)
- for Cactus, this is where I run the servlet engines and run the unit and
functional tests,
- ...
[snip]
Cheers,
Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Peter Donald <do...@apache.org>.
At 08:30 8/5/01 +0200, Ceki Gülcü wrote:
>IMHO, the intermediate build directory can and should be avoided. Instead
of selectively copying from the intermediate build/ directory to dist/, one
can generate directly to dist/ and use tar/zip selectively to create the
distribution. The latter solution keeps just one copy of files which saves
space. More importantly the latter is less error-prone as there is only one
place to edit files. Does that make sense? Ceki
I am not sure why uyou think it is **less** error-prone - I would say it is
far more error prone. Anything which requires a developer to think about
complex structures - many paths to include/exclude (especially when end
product is an Application like Avalon/Phoenix or Tomcat) is much more error
prone.
Intermediate directories reduce complexity for developer - they no longer
have to worry about managing a single directory to do multiple things.
Instead they have extremely controlled copying from intermediate to dist
directory ;) faah simpler, less errror prone ;)
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Tue, 8 May 2001, Ceki Gülcü wrote:
> Hi Craig,
>
> >Ceki, could you expand on why you're objecting to the multistage
> build >process? I'm with Peter on this one ... multi-stage builds
> save time for >the developers (because they do the minimum amount of
> work required), and >also make the "dist" target work better: > >-
> They reuse what's already been done, with transformations as needed >
> (so it runs faster, versus rebuilding everything again)
>
> Indeed.
>
> >- They add any *extra* steps needed (create Javadocs, copy sources,
> etc.) > that are appropriate for the binary distribution.
>
> There is nothing wrong with a multistage build process. It is pretty
> obvious that one needs to split the build process into multiple
> stages. Having a multistaged build is not the same as requiring a
> intermediary build directory.
>
Ok, but ...
> IMHO, the intermediate build directory can and should be avoided.
> Instead of selectively copying from the intermediate build/ directory
> to dist/, one can generate directly to dist/ and use tar/zip
> selectively to create the distribution. The latter solution keeps just
> one copy of files which saves space. More importantly the latter is
> less error-prone as there is only one place to edit files. Does that
> make sense? Ceki
>
It doesn't make sense from my Tomcat perspective. Remember that my goal
for the intermediate directory is *not* to create the equivalent of a
binary distribution -- it is to turn around compiles as quickly as
possible so that I can fix the next problem. My day-to-day work lives in
the intermediate directory, and the "dist" target is used very rarely.
(On a slow box, building Tomcat 4.0 from scratch to the intermediate
target takes a couple of minutes, while running the "dist" target triples
or quadruples that. Multiply this by lots of edit-compile-test cycles
during a day and it *really* adds up.)
Can I get rid of it? Sure, but that costs me having to duplicate *all* of
the compile commands in the "deploy-main" target into the "dist" target as
well, and hope that I don't forget to update in both places when I add
somethng new. The very original Tomcat 3.0 build worked that way, and
proved to be incredibly error prone.
I should say that disk space is absolutely not an issue for me, but even
if it was, the fact that I never create the "dist" target under normal
circumsances makes it moot.
> >- Most fundamentally, they let the "shape" of the intermediate build
> > directory tree be different from that of the binary distribution >
> if that's appropriate to your project.
>
> Couldn't selective tar or zip operation work? Couldn't the <copy>
> operation be avoided?
>
The <copy> operation is what saves me from having to have two sets of
<javac> and <jar> commands (one for the intermediate directory and
one for the dist directory), and all the worry about having to keep
them in synch. It is very very very much worth it for that.
> >What is it that you believe we are missing?
>
> I dunno. The only difference I see is the requirement for an
> intermediate directory. Regards, Ceki
>
See above :-)
Craig
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
Hi Craig,
>Ceki, could you expand on why you're objecting to the multistage build
>process? I'm with Peter on this one ... multi-stage builds save time for
>the developers (because they do the minimum amount of work required), and
>also make the "dist" target work better:
>
>- They reuse what's already been done, with transformations as needed
> (so it runs faster, versus rebuilding everything again)
Indeed.
>- They add any *extra* steps needed (create Javadocs, copy sources, etc.)
> that are appropriate for the binary distribution.
There is nothing wrong with a multistage build process. It is pretty obvious that one needs to split the build process into multiple stages. Having a multistaged build is not the same as requiring a intermediary build directory.
IMHO, the intermediate build directory can and should be avoided. Instead of selectively copying from the intermediate build/ directory to dist/, one can generate directly to dist/ and use tar/zip selectively to create the distribution. The latter solution keeps just one copy of files which saves space. More importantly the latter is less error-prone as there is only one place to edit files. Does that make sense? Ceki
>- Most fundamentally, they let the "shape" of the intermediate build
> directory tree be different from that of the binary distribution
> if that's appropriate to your project.
Couldn't selective tar or zip operation work? Couldn't the <copy> operation be avoided?
>What is it that you believe we are missing?
I dunno. The only difference I see is the requirement for an intermediate directory. Regards, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Tue, 8 May 2001, Ceki [iso-8859-1] G�lc� wrote:
> At 18:36 08.05.2001 +1000, you wrote:
> >At 08:31 8/5/01 +0200, Ceki G�lc� wrote:
> >>At 08:36 08.05.2001 +1000, you wrote:
> >>>At 06:09 7/5/01 +0200, Ceki G�lc� wrote:
> >>>>>Unfortunately half projects use "build" for (1) and half use it for
> >(2). My
> >>>>>recomendation would be to invent a new name for (1) that conflicts with no
> >>>>>existing project - perhaps "intermediate". For (2) I recomend "tools" as
> >>>>>that makes it very clear what is contained within that directory.
> >>>>
> >>>>I have asked this before but is there a need for an intermediary
> >>>directory? For example, to take an example I am familiar with, Tomcat 4.x,
> >>>a damn good project I might add, has a build/ directory and a dist/
> >>>directory where dist/ is a copy of build/. I do not know why Tomcat is
> >>>doing this but it is. Other projects are doing similar things. I am
> >>>obviously missing something...
> >>>
> >>>It is neccessary as a lot of things may be generated but not distributed in
> >>>final distribution. For instance in Avalon/Cornerstone we
> >>>* we create .class files (that are not distributed)
> >>>* pack the classes int jar files (that are not distributed)
> >>>* pack these jar files into another deployment jar (is distributed)
> >>
> >>OK but have you considered <delete>? Cheers, Ceki
> >
> >And rebuild the whole thing every rebuild ? - no thanks - I don't see the
> >need to put in a hack to get around directory names. Directory should
> >integrate into build process - not the reverse.
>
> If deleting is not an option, then one can selectively tar (or zip)
> files for the distro. In your example, you could exclude the .class
> files and the intermediary jar files when creating the distribution
> file(s). How does that sound? Ceki
>
Ceki, could you expand on why you're objecting to the multistage build
process? I'm with Peter on this one ... multi-stage builds save time for
the developers (because they do the minimum amount of work required), and
also make the "dist" target work better:
- They reuse what's already been done, with transformations as needed
(so it runs faster, versus rebuilding everything again)
- They add any *extra* steps needed (create Javadocs, copy sources, etc.)
that are appropriate for the binary distribution.
- Most fundamentally, they let the "shape" of the intermediate build
directory tree be different from that of the binary distribution
if that's appropriate to your project.
What is it that you believe we are missing?
Craig
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 18:36 08.05.2001 +1000, you wrote:
>At 08:31 8/5/01 +0200, Ceki Gülcü wrote:
>>At 08:36 08.05.2001 +1000, you wrote:
>>>At 06:09 7/5/01 +0200, Ceki Gülcü wrote:
>>>>>Unfortunately half projects use "build" for (1) and half use it for
>(2). My
>>>>>recomendation would be to invent a new name for (1) that conflicts with no
>>>>>existing project - perhaps "intermediate". For (2) I recomend "tools" as
>>>>>that makes it very clear what is contained within that directory.
>>>>
>>>>I have asked this before but is there a need for an intermediary
>>>directory? For example, to take an example I am familiar with, Tomcat 4.x,
>>>a damn good project I might add, has a build/ directory and a dist/
>>>directory where dist/ is a copy of build/. I do not know why Tomcat is
>>>doing this but it is. Other projects are doing similar things. I am
>>>obviously missing something...
>>>
>>>It is neccessary as a lot of things may be generated but not distributed in
>>>final distribution. For instance in Avalon/Cornerstone we
>>>* we create .class files (that are not distributed)
>>>* pack the classes int jar files (that are not distributed)
>>>* pack these jar files into another deployment jar (is distributed)
>>
>>OK but have you considered <delete>? Cheers, Ceki
>
>And rebuild the whole thing every rebuild ? - no thanks - I don't see the
>need to put in a hack to get around directory names. Directory should
>integrate into build process - not the reverse.
If deleting is not an option, then one can selectively tar (or zip) files for the distro. In your example, you could exclude the .class files and the intermediary jar files when creating the distribution file(s). How does that sound? Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Peter Donald <do...@apache.org>.
At 08:31 8/5/01 +0200, Ceki Gülcü wrote:
>At 08:36 08.05.2001 +1000, you wrote:
>>At 06:09 7/5/01 +0200, Ceki Gülcü wrote:
>>>>Unfortunately half projects use "build" for (1) and half use it for
(2). My
>>>>recomendation would be to invent a new name for (1) that conflicts with no
>>>>existing project - perhaps "intermediate". For (2) I recomend "tools" as
>>>>that makes it very clear what is contained within that directory.
>>>
>>>I have asked this before but is there a need for an intermediary
>>directory? For example, to take an example I am familiar with, Tomcat 4.x,
>>a damn good project I might add, has a build/ directory and a dist/
>>directory where dist/ is a copy of build/. I do not know why Tomcat is
>>doing this but it is. Other projects are doing similar things. I am
>>obviously missing something...
>>
>>It is neccessary as a lot of things may be generated but not distributed in
>>final distribution. For instance in Avalon/Cornerstone we
>>* we create .class files (that are not distributed)
>>* pack the classes int jar files (that are not distributed)
>>* pack these jar files into another deployment jar (is distributed)
>
>OK but have you considered <delete>? Cheers, Ceki
And rebuild the whole thing every rebuild ? - no thanks - I don't see the
need to put in a hack to get around directory names. Directory should
integrate into build process - not the reverse.
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 08:36 08.05.2001 +1000, you wrote:
>At 06:09 7/5/01 +0200, Ceki Gülcü wrote:
>>>Unfortunately half projects use "build" for (1) and half use it for (2). My
>>>recomendation would be to invent a new name for (1) that conflicts with no
>>>existing project - perhaps "intermediate". For (2) I recomend "tools" as
>>>that makes it very clear what is contained within that directory.
>>
>>I have asked this before but is there a need for an intermediary
>directory? For example, to take an example I am familiar with, Tomcat 4.x,
>a damn good project I might add, has a build/ directory and a dist/
>directory where dist/ is a copy of build/. I do not know why Tomcat is
>doing this but it is. Other projects are doing similar things. I am
>obviously missing something...
>
>It is neccessary as a lot of things may be generated but not distributed in
>final distribution. For instance in Avalon/Cornerstone we
>* we create .class files (that are not distributed)
>* pack the classes int jar files (that are not distributed)
>* pack these jar files into another deployment jar (is distributed)
OK but have you considered <delete>? Cheers, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Peter Donald <do...@apache.org>.
At 06:09 7/5/01 +0200, Ceki Gülcü wrote:
>>Unfortunately half projects use "build" for (1) and half use it for (2). My
>>recomendation would be to invent a new name for (1) that conflicts with no
>>existing project - perhaps "intermediate". For (2) I recomend "tools" as
>>that makes it very clear what is contained within that directory.
>
>I have asked this before but is there a need for an intermediary
directory? For example, to take an example I am familiar with, Tomcat 4.x,
a damn good project I might add, has a build/ directory and a dist/
directory where dist/ is a copy of build/. I do not know why Tomcat is
doing this but it is. Other projects are doing similar things. I am
obviously missing something...
It is neccessary as a lot of things may be generated but not distributed in
final distribution. For instance in Avalon/Cornerstone we
* we create .class files (that are not distributed)
* pack the classes int jar files (that are not distributed)
* pack these jar files into another deployment jar (is distributed)
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Jon Stevens <jo...@latchkey.com>.
on 5/7/01 10:02 AM, "Craig R. McClanahan" <cr...@apache.org> wrote:
> Bottom line -- having an intermediate build directory substantially
> improves the turnaround time for me as a Tomcat developer.
>
> Craig
#1. Compile
#2. Build
#3. Release
Each step inherits from the previous step.
-jon
--
If you come from a Perl or PHP background, JSP is a way to take
your pain to new levels. --Anonymous
<http://jakarta.apache.org/velocity/ymtd/ymtd.html>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Mon, 7 May 2001, Ceki [iso-8859-1] G�lc� wrote:
>
> I have asked this before but is there a need for an intermediary
> directory? For example, to take an example I am familiar with, Tomcat
> 4.x, a damn good project I might add, has a build/ directory and a
> dist/ directory where dist/ is a copy of build/. I do not know why
> Tomcat is doing this but it is. Other projects are doing similar
> things. I am obviously missing something...
>
The two targets are *not* identical.
Tomcat developers want to do the minimum amount of work necessary to
create a runnable version of Tomcat -- thus, they execute the default
build.xml target ("deploy-main") that creates an executable Tomcat 4.0 in
the "build" directory. To speed things up, this dispenses with Javadoc
creation, JARing things up, and stuff like that.
When you're ready to cut a release (or a nightly build), the "dist" target
is used, which creates a complete binary distribution. Obviously, large
parts of this can be copied from the "build" output (it would not make
sense to recompile everything, and so on) -- but there are also additional
steps. But this target is not used for daily development work.
Bottom line -- having an intermediate build directory substantially
improves the turnaround time for me as a Tomcat developer.
Craig
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 00:12 08.05.2001 +1000, Peter Donald wrote:
>At 01:13 7/5/01 +0200, Ceki Gülcü wrote:
>>With your permission I would like to eliminate some of the alternatives.
>This is surely going upset some people. I am asking for the permission to
>make some potentially controversial changes. Let me repeat that I do not
>consider myself as an expert in ANT or to know the optimal directory
>structures. As such, you are strongly encouraged to make suggestions.
>
>The problem is existing projects. We can not create too many conflicts and
>confusing points.
Agreed.
>The sticking points I can remember from last time I
>edited it were located in two groups. The first group
>1. name of intermediate directory
>2. name of directory that contains tools and utilities used in build
>process but not in final product
>
>Unfortunately half projects use "build" for (1) and half use it for (2). My
>recomendation would be to invent a new name for (1) that conflicts with no
>existing project - perhaps "intermediate". For (2) I recomend "tools" as
>that makes it very clear what is contained within that directory.
I have asked this before but is there a need for an intermediary directory? For example, to take an example I am familiar with, Tomcat 4.x, a damn good project I might add, has a build/ directory and a dist/ directory where dist/ is a copy of build/. I do not know why Tomcat is doing this but it is. Other projects are doing similar things. I am obviously missing something...
>The other group was
>1. name of directory of generated local docs if any
>2. name of directory of generated www docs if any
>3. Whether local docs == www docs
>
>Some projects don't have any generated docs in CVS. Others only have one
>version. Others have one version in CVS and one local, the version in CVS
>being dated to last release.
>
>Ideally we wouldn't have any generated docs in CVS but as no-one has
>stepped up to fix that - I guess we gotta keep it.
Have you seen my reply to Vincent on this?
>Some projects don't do "releases" as such and thus can synch the web docs
>whenever they want. Thus they don't need to have a separate www and local
>docs (assuming local==www).
>
>In an ideal world there would not be a need at all for any docs in CVS and
>(thus no www/docs dir) however until this is in place I am really not sure
>what to do.
>
>I think we should make it mandatory that local==www for simplicity sake.
+1
IMHO, it is quite tasteful to have the local (user's) copy of a project to contain an exact replica of the project web-site. Anybody disagree? Cheers, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Charles Benett <ch...@benett1.demon.co.uk>.
Ceki Gülcü wrote:
>
> At 15:22 08.05.2001 +0100, you wrote:
>
> >Peter Donald wrote:
> >> The other group was
> >> 1. name of directory of generated local docs if any
> >> 2. name of directory of generated www docs if any
> >> 3. Whether local docs == www docs
> >>
> >> Some projects don't have any generated docs in CVS. Others only have one
> >> version. Others have one version in CVS and one local, the version in CVS
> >> being dated to last release.
> >>
> >> Ideally we wouldn't have any generated docs in CVS but as no-one has
> >> stepped up to fix that - I guess we gotta keep it.
> >>
> >> Some projects don't do "releases" as such and thus can synch the web docs
> >> whenever they want. Thus they don't need to have a separate www and local
> >> docs (assuming local==www).
> >>
> >> In an ideal world there would not be a need at all for any docs in CVS and
> >> (thus no www/docs dir) however until this is in place I am really not sure
> >> what to do.
> >>
> >> I think we should make it mandatory that local==www for simplicity sake.
> >
> >-1 I think we should let projects choose whether local (ie /docs) ==
> >www. For projects doing releases I guess they would normally want www to
> >describe latest release but /docs to describe current cvs.
>
> Charles,
>
> Agreed. Mandating that the docs contained in the distribution and the docs available on the jakarta web server match exactly is too restrictive. However, allowing the user to browse the documentation locally from the files contained within the distribution is a nice feature. Wouldn't you agree?
Yes - but that doesn't mean that CVS has too contain any generated docs
(see below)
>
> >Ceki's description of log4j's doc dance works, but makes altering www
> >docs post-release tricky. I think docs are likely to be a bit behind the
> >curve, particularly for smaller projects.
>
> True.
>
> >So, the current system of checking out www docs from cvs makes sense - it allows doc amends for
> >last release to be tracked.
>
> I think no one is contesting that tracking source files using CVS is a good idea. However, the CVS update operation is one way of copying the latest version of doc files to the jakarta web server. It is certainly not the only way. Reading your comments below, I think that we are actually in total agreement.
>
> >On the other hand, do we need generated docs in cvs /docs? Obviously we
> >need generated docs in the (binary) dist for nightly builds and
> >milestone releases. But that comes from the build / release process.
> >
> >So I suggest:
> >/src/xdocs - Documentation files in XML format (no change)
> >/docs - empty, standard location for generated docs of current
> >code.
> >/www - if no releases - copy of generated docs
> > if releases - copy of generated docs at last release.
>
> I am afraid I don't get it. First, by generated documentation I assume you mean the javadocs. Right?
> Wouldn't it be possible to have a single top-level documentation directory, says docs/, and have the javadocs go under docs/api/? I believe this is the way the XML projects do it.
Woops, what i meant by 'generated docs' is the output of Anakia or
Stylebook. Javadocs in docs/api is fine. My point was its really only
the binary dists that need generated docs. (And www possibly - see
Craig's email)
Charles
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Charles Benett <ch...@benett1.demon.co.uk>.
"Craig R. McClanahan" wrote:
>
> On Tue, 8 May 2001, Ceki [iso-8859-1] Gülcü wrote:
>
> >
> > I think no one is contesting that tracking source files using CVS is a
> > good idea. However, the CVS update operation is one way of copying the
> > latest version of doc files to the jakarta web server. It is certainly
> > not the only way. Reading your comments below, I think that we are
> > actually in total agreement.
> >
>
> I'm not a fan of the way jakarta-site2 makes you check in the generated
> HTML either. I'd rather see the cycle work like this:
>
> Local machine:
> - Edit XML (or whatever) sources
> - Generate and test
> - Check in XML sources
>
> Daedalus:
> - Check out XML sources
> - Generate in place
>
> Formerly, we didn't have a useful Java2 environment on the server
> (locus). Now we do -- let's use it :-)
Basically, I agree. The only issue is if you want the web docs to
reflect a released version and also have docs for the current state of
CVS. We can either do it by checking in HTML to a www dir (and using
craig's method for docs reflecting current state of cvs) or only have
xml sources in cvs and use the branch facility of cvs (which I fear is
morely likely to get messed up).
Charles
Charles
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Tue, 8 May 2001, Ceki [iso-8859-1] G�lc� wrote:
>
> Agreed. Mandating that the docs contained in the distribution and the
> docs available on the jakarta web server match exactly is too
> restrictive.
+1 -- it should be up to the project. I've got projects that do it both
ways.
> However, allowing the user to browse the documentation
> locally from the files contained within the distribution is a nice
> feature. Wouldn't you agree?
>
Also +1. One approach is to include a webapp of static HTML files that
the user can drop into their container (if they have one), or use as a
static directory of files (if they don't).
>
> >Ceki's description of log4j's doc dance works, but makes altering www
> >docs post-release tricky. I think docs are likely to be a bit behind the
> >curve, particularly for smaller projects.
>
> True.
>
> >So, the current system of checking out www docs from cvs makes sense
> - it allows doc amends for >last release to be tracked.
>
> I think no one is contesting that tracking source files using CVS is a
> good idea. However, the CVS update operation is one way of copying the
> latest version of doc files to the jakarta web server. It is certainly
> not the only way. Reading your comments below, I think that we are
> actually in total agreement.
>
I'm not a fan of the way jakarta-site2 makes you check in the generated
HTML either. I'd rather see the cycle work like this:
Local machine:
- Edit XML (or whatever) sources
- Generate and test
- Check in XML sources
Daedalus:
- Check out XML sources
- Generate in place
Formerly, we didn't have a useful Java2 environment on the server
(locus). Now we do -- let's use it :-)
Craig
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Ceki Gülcü <cg...@qos.ch>.
At 15:22 08.05.2001 +0100, you wrote:
>Peter Donald wrote:
>> The other group was
>> 1. name of directory of generated local docs if any
>> 2. name of directory of generated www docs if any
>> 3. Whether local docs == www docs
>>
>> Some projects don't have any generated docs in CVS. Others only have one
>> version. Others have one version in CVS and one local, the version in CVS
>> being dated to last release.
>>
>> Ideally we wouldn't have any generated docs in CVS but as no-one has
>> stepped up to fix that - I guess we gotta keep it.
>>
>> Some projects don't do "releases" as such and thus can synch the web docs
>> whenever they want. Thus they don't need to have a separate www and local
>> docs (assuming local==www).
>>
>> In an ideal world there would not be a need at all for any docs in CVS and
>> (thus no www/docs dir) however until this is in place I am really not sure
>> what to do.
>>
>> I think we should make it mandatory that local==www for simplicity sake.
>
>-1 I think we should let projects choose whether local (ie /docs) ==
>www. For projects doing releases I guess they would normally want www to
>describe latest release but /docs to describe current cvs.
Charles,
Agreed. Mandating that the docs contained in the distribution and the docs available on the jakarta web server match exactly is too restrictive. However, allowing the user to browse the documentation locally from the files contained within the distribution is a nice feature. Wouldn't you agree?
>Ceki's description of log4j's doc dance works, but makes altering www
>docs post-release tricky. I think docs are likely to be a bit behind the
>curve, particularly for smaller projects.
True.
>So, the current system of checking out www docs from cvs makes sense - it allows doc amends for
>last release to be tracked.
I think no one is contesting that tracking source files using CVS is a good idea. However, the CVS update operation is one way of copying the latest version of doc files to the jakarta web server. It is certainly not the only way. Reading your comments below, I think that we are actually in total agreement.
>On the other hand, do we need generated docs in cvs /docs? Obviously we
>need generated docs in the (binary) dist for nightly builds and
>milestone releases. But that comes from the build / release process.
>
>So I suggest:
>/src/xdocs - Documentation files in XML format (no change)
>/docs - empty, standard location for generated docs of current
>code.
>/www - if no releases - copy of generated docs
> if releases - copy of generated docs at last release.
I am afraid I don't get it. First, by generated documentation I assume you mean the javadocs. Right?
Wouldn't it be possible to have a single top-level documentation directory, says docs/, and have the javadocs go under docs/api/? I believe this is the way the XML projects do it.
What do you think? Regards, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Charles Benett <ch...@benett1.demon.co.uk>.
Peter Donald wrote:
> The other group was
> 1. name of directory of generated local docs if any
> 2. name of directory of generated www docs if any
> 3. Whether local docs == www docs
>
> Some projects don't have any generated docs in CVS. Others only have one
> version. Others have one version in CVS and one local, the version in CVS
> being dated to last release.
>
> Ideally we wouldn't have any generated docs in CVS but as no-one has
> stepped up to fix that - I guess we gotta keep it.
>
> Some projects don't do "releases" as such and thus can synch the web docs
> whenever they want. Thus they don't need to have a separate www and local
> docs (assuming local==www).
>
> In an ideal world there would not be a need at all for any docs in CVS and
> (thus no www/docs dir) however until this is in place I am really not sure
> what to do.
>
> I think we should make it mandatory that local==www for simplicity sake.
-1 I think we should let projects choose whether local (ie /docs) ==
www. For projects doing releases I guess they would normally want www to
describe latest release but /docs to describe current cvs.
Ceki's description of log4j's doc dance works, but makes altering www
docs post-release tricky. I think docs are likely to be a bit behind the
curve, particularly for smaller projects. So, the current system of
checking out www docs from cvs makes sense - it allows doc amends for
last release to be tracked.
On the other hand, do we need generated docs in cvs /docs? Obviously we
need generated docs in the (binary) dist for nightly builds and
milestone releases. But that comes from the build / release process.
So I suggest:
/src/xdocs - Documentation files in XML format (no change)
/docs - empty, standard location for generated docs of current
code.
/www - if no releases - copy of generated docs
if releases - copy of generated docs at last release.
Charles
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Proposed dirlayout document
Posted by Peter Donald <do...@apache.org>.
At 01:13 7/5/01 +0200, Ceki Gülcü wrote:
>Having recently looked at http://jakarta.apache.org/site/dirlayout.html,
my impression was that it allowed too many alternatives on a large number
of points rendering the document somewhat confusing (useless?). I am
against making the dirlayout document an exhaustive list of all possible
layout structures. A guideline document should be a bit more assertive.
agreed.
>With your permission I would like to eliminate some of the alternatives.
This is surely going upset some people. I am asking for the permission to
make some potentially controversial changes. Let me repeat that I do not
consider myself as an expert in ANT or to know the optimal directory
structures. As such, you are strongly encouraged to make suggestions.
The problem is existing projects. We can not create too many conflicts and
confusing points. The sticking points I can remember from last time I
edited it were located in two groups. The first group
1. name of intermediate directory
2. name of directory that contains tools and utilities used in build
process but not in final product
Unfortunately half projects use "build" for (1) and half use it for (2). My
recomendation would be to invent a new name for (1) that conflicts with no
existing project - perhaps "intermediate". For (2) I recomend "tools" as
that makes it very clear what is contained within that directory.
The other group was
1. name of directory of generated local docs if any
2. name of directory of generated www docs if any
3. Whether local docs == www docs
Some projects don't have any generated docs in CVS. Others only have one
version. Others have one version in CVS and one local, the version in CVS
being dated to last release.
Ideally we wouldn't have any generated docs in CVS but as no-one has
stepped up to fix that - I guess we gotta keep it.
Some projects don't do "releases" as such and thus can synch the web docs
whenever they want. Thus they don't need to have a separate www and local
docs (assuming local==www).
In an ideal world there would not be a need at all for any docs in CVS and
(thus no www/docs dir) however until this is in place I am really not sure
what to do.
I think we should make it mandatory that local==www for simplicity sake.
Cheers,
Pete
*-----------------------------------------------------*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof." |
| - John Kenneth Galbraith |
*-----------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org