You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by Conor MacNeill <co...@cortexebusiness.com.au> on 2001/03/15 01:02:27 UTC
Directory layout feedback
Ceki,
I would like to give you some feedback on the common directory layout
http://jakarta.apache.org/site/dirlayout.html
This is mostly from my Ant perspective and somewhat from my impression of
some other common practices in the Jakarta sub-projects. I do realize that
these are just recommendations.
docs directory
=================
I have noticed a trend to put the sub-project's web pages into this area. I
wonder is that is a good thing since the web pages and the user
documentation are two different things, IMHO. The web pages are potentially
much more ephemeral than the product documentation that accompanies a
release. When you build a release, it may not make much sense to include
that ephemeral information (such as sub-project news) with the project docs.
For Ant, I made a separate directory for the webpages (webpage). I had to do
this anyway since there was already an index.html file in the Ant docs
directory, although I have subsequently moved that.
build directory
================
Many of the Jakarta projects put the build files in the project's root
directory and use the build directory for build results, such as build
classes which will be jarred up into the distribution
build/lib
==========
If this is a non-binding recommendation, I don't see why it supports two
locations to put the binary jars. It should either be lib or build/lib,
IMHO.
dist
=========
I believe this should be a distribution "image" and it is therefore not
really appropriate to place the distribution binaries (.zip, .gz files) in
this location. For Ant, I create the distributions into a directory called
distribution. It contains the source and binary distributions, the latter
being equivalent to the dist directory.
dist/classes
=============
I don't believe we want generally want raw classfiles in the dist directory.
Many projects put this into build/classes and place just jars in the dist
directory.
Other
======
I think that there should be a recommendation that any file/dir not under
CVS control should go into the .cvsignore file.
Do we want to make recommendations about the structure of the dist
directory? This is what end-users will actually use and there may be
benefits in a common approach here too. In Ant, for example, we create a
dist/bin directory to contain scripts and executables useful for running
Ant. we also place all generated jars in the dist/lib directory. Perhaps
they are similar or the same as these recommendations.
Cheers
Conor
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by je...@socialchange.net.au.
On Thu, Mar 15, 2001 at 11:02:27AM +1100, Conor MacNeill wrote:
> Ceki,
>
> I would like to give you some feedback on the common directory layout
> http://jakarta.apache.org/site/dirlayout.html
>
> This is mostly from my Ant perspective and somewhat from my impression of
> some other common practices in the Jakarta sub-projects. I do realize that
> these are just recommendations.
[..]
> build directory
> ================
> Many of the Jakarta projects put the build files in the project's root
> directory and use the build directory for build results, such as build
> classes which will be jarred up into the distribution
>
> build/lib
> ==========
> If this is a non-binding recommendation, I don't see why it supports two
> locations to put the binary jars. It should either be lib or build/lib,
> IMHO.
Not sure what the intention with /lib and /build/lib was, but I have found it
useful to make this distinction:
/lib # compile-time jars
/src/lib # run-time jars
Eg, ant.jar, stylebook.jar and junit.jar are compile-time dependencies. Having
two /lib directories simplifies the creation of binary distributions that don't
require compile-time jars.
--Jeff
> Cheers
> Conor
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by Peter Donald <do...@apache.org>.
At 05:22 15/3/01 +0100, Ceki Gülcü wrote:
>OK but I don't see any big difference between the two approaches. In one
you generate into dist/ + copy into dist/ and the other you tar/zip a set
of files specified in a tar/zip target. You have to be sentient in both
cases or? Ceki
Not really. As a few projects directly use dist (ie the bin-image) in
development it should be well tested/debugged. Creating a new image (even
if it is only marred by the zip/tar files) increases the risk. It also
restricts the type of projects that can use the model.
Just say we are a web-project and want to create a .war as distribution
mechanism. It would not be uncommon for it to also include images under the
directory dist/images. Introducing more risk of corrupted binaries (by
placing zip/tars in images and relying on developer awareness) when it
could be easily avoided is not a good thing ;)
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: Directory layout feedback
Posted by Peter Donald <do...@apache.org>.
I am curious what purpose does the contrib directory serve? It's
description is code that is not officially part of project. What does this
mean?
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: Directory layout feedback
Posted by Ceki Gülcü <cg...@qos.ch>.
At 02:46 16.03.2001 +1100, Peter Donald wrote:
>At 04:17 15/3/01 +0100, Ceki Gülcü wrote:
>>>A lot of projects use dist/, in my personal projects I use out/ while some
>>>projects use bin/.
>>
>>See, these names are like colors, blue, green, or yellow... At face value,
>they are all equivalent. That's what I meant by sticking to a name. It goes
>without saying that the chosen color has to be reasonable, unlike #A26F58
>or SemiHuedVelvetBlue.
>
>True but we tend to have some ... err .. strong willed individuals here who
>we will find difficult to move from their pet structure. You can make a
>standard all you want but we have to get people to follow it ;)
I hear you.
>>Forgive my ignorance but what is so wrong with putting "raw" class files in
>>the distrib along jar files? Is it the wasted disk space?
>
>messy classpath, wasted diskspace, incredibly slow access on certain
>filesystems (ie FAT) etc. Also much more likely to break the 100 char limit
>in tar files etc.
One is free to use jar files, using the class/ dir is an option. The tar char limit is broken by a class file then it is likely to be broken by that file's javadoc equivalent as well. How serious is this tar limitation anyway?
>>I am not aware of the assumption that the dist directory is meant the
>unzipped
>>version of the binary distribution. Not at all.
>
>well theres the rub.
>
>>
>>If the files
>>
>>xdocs/manual.xml
>>build/build.xml
>>build/build.sh
>>build/build.bat
>>build/lib/ant.jar
>>build/lib/xerces.jar
>>src/x.java
>>
>>are contained in the CVS module for project X, then after compiling,
>generating javadocs, jarring, and building a distribution image, one would
>get:
>>
>>docs/manual.html
>>docs/api/
>>docs/api/x.html
>>docs/api/overview.html
>>docs/api/index.html
>>docs/api/etc...
>>build/build.xml
>>build/build.sh
>>build/build.bat
>>build/lib/ant.jar
>>build/lib/xerces.jar
>>src/x.java
>>xdocs/manual.xml
>>dist/classes/x.class
>>dist/lib/X.jar
>>
>>dist/images/X.tar.gz
>>dist/images/X.zip
>
>Maybe in *your* model ...
Yes, that's the model log4j uses although I am adapting the log4j directory structure to match the dirlayout document and this ongoing discussion.
>>where X.tar.gz and X.zip contain all the above files other than
>themselves. The images can be refined to contain only source code,
>documentation, or binaries. Does that make sense? Ceki
>
>It's one way of doing it but it requires developer sentience whilst
>building distributions - something I try to avoid at all costs ;) Besides
>that model only works for certain types of projects. Some projects build
>particular types of images etc. Having everything below dist/* in binary
>distribution is much easier and is a common practice that I believe
>originated in java.apace.org projects and migrated to jakarta/xml groups.
OK but I don't see any big difference between the two approaches. In one you generate into dist/ + copy into dist/ and the other you tar/zip a set of files specified in a tar/zip target. You have to be sentient in both cases or? Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by Peter Donald <do...@apache.org>.
At 04:17 15/3/01 +0100, Ceki Gülcü wrote:
>>A lot of projects use dist/, in my personal projects I use out/ while some
>>projects use bin/.
>
>See, these names are like colors, blue, green, or yellow... At face value,
they are all equivalent. That's what I meant by sticking to a name. It goes
without saying that the chosen color has to be reasonable, unlike #A26F58
or SemiHuedVelvetBlue.
True but we tend to have some ... err .. strong willed individuals here who
we will find difficult to move from their pet structure. You can make a
standard all you want but we have to get people to follow it ;)
>Forgive my ignorance but what is so wrong with putting "raw" class files in
>the distrib along jar files? Is it the wasted disk space?
messy classpath, wasted diskspace, incredibly slow access on certain
filesystems (ie FAT) etc. Also much more likely to break the 100 char limit
in tar files etc.
>I am not aware of the assumption that the dist directory is meant the
unzipped
>version of the binary distribution. Not at all.
well theres the rub.
>
>If the files
>
>xdocs/manual.xml
>build/build.xml
>build/build.sh
>build/build.bat
>build/lib/ant.jar
>build/lib/xerces.jar
>src/x.java
>
>are contained in the CVS module for project X, then after compiling,
generating javadocs, jarring, and building a distribution image, one would
get:
>
>docs/manual.html
>docs/api/
>docs/api/x.html
>docs/api/overview.html
>docs/api/index.html
>docs/api/etc...
>build/build.xml
>build/build.sh
>build/build.bat
>build/lib/ant.jar
>build/lib/xerces.jar
>src/x.java
>xdocs/manual.xml
>dist/classes/x.class
>dist/lib/X.jar
>
>dist/images/X.tar.gz
>dist/images/X.zip
Maybe in *your* model ...
>where X.tar.gz and X.zip contain all the above files other than
themselves. The images can be refined to contain only source code,
documentation, or binaries. Does that make sense? Ceki
It's one way of doing it but it requires developer sentience whilst
building distributions - something I try to avoid at all costs ;) Besides
that model only works for certain types of projects. Some projects build
particular types of images etc. Having everything below dist/* in binary
distribution is much easier and is a common practice that I believe
originated in java.apace.org projects and migrated to jakarta/xml groups.
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: Directory layout feedback
Posted by Ceki Gülcü <cg...@qos.ch>.
At 01:34 16.03.2001 +1100, Peter Donald wrote:
>>>build directory
>>>================
>>>Many of the Jakarta projects put the build files in the project's root
>>>directory and use the build directory for build results, such as build
>>>classes which will be jarred up into the distribution
>>
>>So by build/ you actually mean the dist/ directory of the dirlayout.html
>document. As far as I can see there is nothing wrong with that except that if
>>we make a choice regardless of what it is we should stick to it, a bit like
>>indentation I guess.
>
>Gonna have to disagree. You do whats best when there is no significant
>advantage of doing it otherways. Standardizing on a crap standard because
>someone decrees it a standard is near lunacy.
Sure, no one is suggesting that we standardize on jolt/ for jar files. :-)
>A lot of projects use dist/, in my personal projects I use out/ while some
>projects use bin/.
See, these names are like colors, blue, green, or yellow... At face value, they are all equivalent. That's what I meant by sticking to a name. It goes without saying that the chosen color has to be reasonable, unlike #A26F58 or SemiHuedVelvetBlue.
>>Jon, explained that the build/lib is for building (compiling) and lib/ for
>>runtime. I confess that I don't really understand the difference... See also
>>the last paragraph of this note.
>
>Other projects use tools/lib/* for build/lib. This is where the jars are
>stored for tools that run during build process. None of the jars are
>included in compiling classpath or in final distribution.
>
>>>dist
>>>=========
>>>I believe this should be a distribution "image" and it is therefore not
>>>really appropriate to place the distribution binaries (.zip, .gz files) in
>>>this location. For Ant, I create the distributions into a directory called
>>>distribution. It contains the source and binary distributions, the latter
>>>being equivalent to the dist directory.
>>
>>Why are you making a distinction? What's wrong putting the distribution
>>images, src, birnary, documentation or otherwise in dist/ and the javac
>>generated classes under dist/classes?
>
>Some projects actually want to run from dist target. So the dist target
>should be identical to the one that is included in binary distributions. In
>theory you should be able to go
>
>> cd dist/bin
>> run.sh
Sure.
>>>dist/classes
>>>=============
>>>I don't believe we want generally want raw classfiles in the dist directory.
>>>Many projects put this into build/classes and place just jars in the dist
>>>directory.
>>
>>Why? What's the rationale? Moreover, in the classes directory there might be
>>more classes than in the jars.
>
>Because dist is an image of binary distribution and it is very rare that
>raw class files are included in binary distribution (and if they are the
>developers should be shot).
Forgive my ignorance but what is so wrong with putting "raw" class files in the distrib along jar files? Is it the wasted disk space?
>>How about:
>>
>>dist/lib for generated jar files and extraneous libs
>>dist/bin/ for scripts (generated or not)
>>dist/image for actual project distributions (tar.gz or zip files)
>
>You don't get what is being said. The dist directory is unzipped version of
>binary distribution. So that would be liking distributing Log4j-1.0.zip
>that contained image/Log4j-1.0.zip inside it. That is why it is good to
>make distinction and place distributions in another directory (ie
>distributions).
I am not aware of the assumption that the dist directory is meant the unzipped version of the binary distribution. Not at all.
If the files
xdocs/manual.xml
build/build.xml
build/build.sh
build/build.bat
build/lib/ant.jar
build/lib/xerces.jar
src/x.java
are contained in the CVS module for project X, then after compiling, generating javadocs, jarring, and building a distribution image, one would get:
docs/manual.html
docs/api/
docs/api/x.html
docs/api/overview.html
docs/api/index.html
docs/api/etc...
build/build.xml
build/build.sh
build/build.bat
build/lib/ant.jar
build/lib/xerces.jar
src/x.java
xdocs/manual.xml
dist/classes/x.class
dist/lib/X.jar
dist/images/X.tar.gz
dist/images/X.zip
where X.tar.gz and X.zip contain all the above files other than themselves. The images can be refined to contain only source code, documentation, or binaries. Does that make sense? Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by Peter Donald <do...@apache.org>.
At 03:10 15/3/01 +0100, Ceki Gülcü wrote:
>>For Ant, I made a separate directory for the webpages (webpage). I had to do
>>this anyway since there was already an index.html file in the Ant docs
>>directory, although I have subsequently moved that.
>
>As Jon pointed out earlier, I do not see the advantage for distinguishing
>between documentation and the web pages. It is quite pleasant to be able to
>browse a project web site locally on a file system without requiring a
network
>connection.
depends on whats on the web-pages. If there is a lot of fluff/volatile
material then it can be confusing. Volatile/non-relevent stuff (ie
bug-reports/ news/ patches-to-apply/ branch statuses etc) should be left
out. Then again all the projects I work on have a www directory that is
identical to docs directory ;)
>>build directory
>>================
>>Many of the Jakarta projects put the build files in the project's root
>>directory and use the build directory for build results, such as build
>>classes which will be jarred up into the distribution
>
>So by build/ you actually mean the dist/ directory of the dirlayout.html
document. As far as I can see there is nothing wrong with that except that if
>we make a choice regardless of what it is we should stick to it, a bit like
>indentation I guess.
Gonna have to disagree. You do whats best when there is no significant
advantage of doing it otherways. Standardizing on a crap standard because
someone decrees it a standard is near lunacy.
A lot of projects use dist/, in my personal projects I use out/ while some
projects use bin/.
>Jon, explained that the build/lib is for building (compiling) and lib/ for
>runtime. I confess that I don't really understand the difference... See also
>the last paragraph of this note.
Other projects use tools/lib/* for build/lib. This is where the jars are
stored for tools that run during build process. None of the jars are
included in compiling classpath or in final distribution.
>>dist
>>=========
>>I believe this should be a distribution "image" and it is therefore not
>>really appropriate to place the distribution binaries (.zip, .gz files) in
>>this location. For Ant, I create the distributions into a directory called
>>distribution. It contains the source and binary distributions, the latter
>>being equivalent to the dist directory.
>
>Why are you making a distinction? What's wrong putting the distribution
>images, src, birnary, documentation or otherwise in dist/ and the javac
>generated classes under dist/classes?
Some projects actually want to run from dist target. So the dist target
should be identical to the one that is included in binary distributions. In
theory you should be able to go
> cd dist/bin
> run.sh
>>dist/classes
>>=============
>>I don't believe we want generally want raw classfiles in the dist directory.
>>Many projects put this into build/classes and place just jars in the dist
>>directory.
>
>Why? What's the rationale? Moreover, in the classes directory there might be
>more classes than in the jars.
Because dist is an image of binary distribution and it is very rare that
raw class files are included in binary distribution (and if they are the
developers should be shot).
>>Other
>>======
>>
>>I think that there should be a recommendation that any file/dir not under
>>CVS control should go into the .cvsignore file.
>
>There is no need to adding any files to .cvsignore if you add files to CVS
control individually as in
>
>> cvs add x.java y.java
>
>instead of
>
>> cvs add *
>
>or am I missing something?
yep - .cvsignore is for removing annoying
? blah
messages during update
>How about:
>
>dist/lib for generated jar files and extraneous libs
>dist/bin/ for scripts (generated or not)
>dist/image for actual project distributions (tar.gz or zip files)
You don't get what is being said. The dist directory is unzipped version of
binary distribution. So that would be liking distributing Log4j-1.0.zip
that contained image/Log4j-1.0.zip inside it. That is why it is good to
make distinction and place distributions in another directory (ie
distributions).
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: Directory layout feedback
Posted by Conor MacNeill <co...@cortexebusiness.com.au>.
Jon,
> From: Jon Stevens [mailto:jon@latchkey.com]
>
> I disagree. Documentation == website. All of the documentation
> for a product
> should be available on the website. The reason is simple...we are creating
> open source. Documentation is lacking in general as well as people to
> maintain it. So, whatever we have, we should make it readily accessible.
>
I think I would see that as website >= Documentation. There is stuff that I
want on the web
(Call for Ant 2 requirements & news, for example) that I don't think is
appropriate in the documentaion that ships with the build.
Additionally, in Ant, we don't have the generated API docs in CVS (or the
web site), which we do have in the distributions.
Perhaps your suggestion of docs/site is the way to go. I'll think about that
for Ant.
> > build directory
> > ================
> > Many of the Jakarta projects put the build files in the project's root
> > directory and use the build directory for build results, such as build
> > classes which will be jarred up into the distribution
>
> Right and we are saying it should be "dist/classes" for that directory.
But classes are not part of the "dist" image, if you know what I mean. If
you look at this message,
http://marc.theaimsgroup.com/?l=ant-dev&m=98018389428408&w=2, you will see
that some others also view dist as an image of the binary distribution and
build as a build area. The idea is to be able to use this dist in-situ as
you are developing (by setting ANT_HOME, in the case of Ant).
Personally, I can live with dist not being a distribution image but I was
just reflecting what I thought was the current common practice. If it is not
the common view, then I would certainly try to move Ant into line.
>
> > build/lib
> > ==========
> > If this is a non-binding recommendation, I don't see why it supports two
> > locations to put the binary jars. It should either be lib or build/lib,
> > IMHO.
>
> The reason is to allow easy *.jar separation of files needed for building
> and files need for running. For example, I do not need ant.jar to run
> Velocity.
Ok, that is clear now. I think this page should make that distinction clear
(yes, I will change the XML :-))
>
> Personally, I like bin/classes. :-) Compromise is a bitch eh? :-)
Indeed.
>
> > Other
> > ======
I'll make some changes to the XML tonight to cover the structure of the
generated distribution (wherever it may end up living) :-)
Conor
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by Jon Stevens <jo...@latchkey.com>.
on 3/14/01 4:02 PM, "Conor MacNeill" <co...@cortexebusiness.com.au> wrote:
> Ceki,
>
> I would like to give you some feedback on the common directory layout
> http://jakarta.apache.org/site/dirlayout.html
>
> This is mostly from my Ant perspective and somewhat from my impression of
> some other common practices in the Jakarta sub-projects. I do realize that
> these are just recommendations.
>
> docs directory
> =================
> I have noticed a trend to put the sub-project's web pages into this area. I
> wonder is that is a good thing since the web pages and the user
> documentation are two different things, IMHO. The web pages are potentially
> much more ephemeral than the product documentation that accompanies a
> release. When you build a release, it may not make much sense to include
> that ephemeral information (such as sub-project news) with the project docs.
I disagree. Documentation == website. All of the documentation for a product
should be available on the website. The reason is simple...we are creating
open source. Documentation is lacking in general as well as people to
maintain it. So, whatever we have, we should make it readily accessible.
> For Ant, I made a separate directory for the webpages (webpage). I had to do
> this anyway since there was already an index.html file in the Ant docs
> directory, although I have subsequently moved that.
So: docs/site
This follows more along with the CVS conventions of the module names where
we have the website stored as "jakarta-site".
> build directory
> ================
> Many of the Jakarta projects put the build files in the project's root
> directory and use the build directory for build results, such as build
> classes which will be jarred up into the distribution
Right and we are saying it should be "dist/classes" for that directory.
> build/lib
> ==========
> If this is a non-binding recommendation, I don't see why it supports two
> locations to put the binary jars. It should either be lib or build/lib,
> IMHO.
The reason is to allow easy *.jar separation of files needed for building
and files need for running. For example, I do not need ant.jar to run
Velocity.
> dist
> =========
> I believe this should be a distribution "image" and it is therefore not
> really appropriate to place the distribution binaries (.zip, .gz files) in
> this location. For Ant, I create the distributions into a directory called
> distribution. It contains the source and binary distributions, the latter
> being equivalent to the dist directory.
dist/classes
dist/source
dist/binary
> dist/classes
> =============
> I don't believe we want generally want raw classfiles in the dist directory.
> Many projects put this into build/classes and place just jars in the dist
> directory.
Personally, I like bin/classes. :-) Compromise is a bitch eh? :-)
> Other
> ======
>
> I think that there should be a recommendation that any file/dir not under
> CVS control should go into the .cvsignore file.
Yup. Edit the .xml file and add this in.
> Do we want to make recommendations about the structure of the dist
> directory? This is what end-users will actually use and there may be
> benefits in a common approach here too. In Ant, for example, we create a
> dist/bin directory to contain scripts and executables useful for running
> Ant. we also place all generated jars in the dist/lib directory. Perhaps
> they are similar or the same as these recommendations.
Yup. Edit the .xml file and add this in.
-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: Directory layout feedback
Posted by Stefan Bodewig <bo...@apache.org>.
Ceki Gülc <cg...@qos.ch> wrote:
> At 11:02 15.03.2001 +1100, Conor MacNeill wrote:
>>I think that there should be a recommendation that any file/dir not
>>under CVS control should go into the .cvsignore file.
>
> There is no need to adding any files to .cvsignore if you add files
> to CVS control individually as in
>
>> cvs add x.java y.java
>
> instead of
>
>> cvs add *
>
> or am I missing something?
yes, the annoying
? dist
in
cvs update -d -P
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Directory layout feedback
Posted by Ceki Gülcü <cg...@qos.ch>.
Conor,
At 11:02 15.03.2001 +1100, Conor MacNeill wrote:
>Ceki,
>
>I would like to give you some feedback on the common directory layout
>http://jakarta.apache.org/site/dirlayout.html
>
>This is mostly from my Ant perspective and somewhat from my impression of
>some other common practices in the Jakarta sub-projects. I do realize that
>these are just recommendations.
>
>docs directory
>=================
>I have noticed a trend to put the sub-project's web pages into this area. I
>wonder is that is a good thing since the web pages and the user
>documentation are two different things, IMHO. The web pages are potentially
>much more ephemeral than the product documentation that accompanies a
>release. When you build a release, it may not make much sense to include
>that ephemeral information (such as sub-project news) with the project docs.
>
>For Ant, I made a separate directory for the webpages (webpage). I had to do
>this anyway since there was already an index.html file in the Ant docs
>directory, although I have subsequently moved that.
As Jon pointed out earlier, I do not see the advantage for distinguishing between documentation and the web pages. It is quite pleasant to be able to browse a project web site locally on a file system without requiring a network connection.
>build directory
>================
>Many of the Jakarta projects put the build files in the project's root
>directory and use the build directory for build results, such as build
>classes which will be jarred up into the distribution
So by build/ you actually mean the dist/ directory of the dirlayout.html document. As far as I can see there is nothing wrong with that except that if we make a choice regardless of what it is we should stick to it, a bit like indentation I guess.
>build/lib
>==========
>If this is a non-binding recommendation, I don't see why it supports two
>locations to put the binary jars. It should either be lib or build/lib,
>IMHO.
Jon, explained that the build/lib is for building (compiling) and lib/ for runtime. I confess that I don't really understand the difference... See also the last paragraph of this note.
>dist
>=========
>I believe this should be a distribution "image" and it is therefore not
>really appropriate to place the distribution binaries (.zip, .gz files) in
>this location. For Ant, I create the distributions into a directory called
>distribution. It contains the source and binary distributions, the latter
>being equivalent to the dist directory.
Why are you making a distinction? What's wrong putting the distribution images, src, birnary, documentation or otherwise in dist/ and the javac generated classes under dist/classes?
>dist/classes
>=============
>I don't believe we want generally want raw classfiles in the dist directory.
>Many projects put this into build/classes and place just jars in the dist
>directory.
Why? What's the rationale? Moreover, in the classes directory there might be more classes than in the jars.
>Other
>======
>
>I think that there should be a recommendation that any file/dir not under
>CVS control should go into the .cvsignore file.
There is no need to adding any files to .cvsignore if you add files to CVS control individually as in
> cvs add x.java y.java
instead of
> cvs add *
or am I missing something?
>Do we want to make recommendations about the structure of the dist
>directory? This is what end-users will actually use and there may be
>benefits in a common approach here too. In Ant, for example, we create a
>dist/bin directory to contain scripts and executables useful for running
>Ant. we also place all generated jars in the dist/lib directory. Perhaps
>they are similar or the same as these recommendations.
Restricting the dist/ directory to the binaries that the end-users will actually use is a nice abstraction imho.
How about:
dist/lib for generated jar files and extraneous libs
dist/bin/ for scripts (generated or not)
dist/image for actual project distributions (tar.gz or zip files)
The project distribution files are for those that actually make releases not for the casual user Jon Doe.
As I understand it, there will be build/lib for libraries used only during build and not during runtime, and dist/lib for libraries used in both build time or run time. (dist/lib is perhaps what Jon meant by lib/)
Is that reasonable? Cheers, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org