Re: Directory layout feedback

2001-03-16 Thread Sam Ruby

Peter Donald wrote:

 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.

I'm 180 off of this position.

If there IS a significant advantage to doing it otherways, feel free to do
so.  Live and let live.  Standards be damned.

If there is NOT a significant advantage to doing it otherways, lets see if
we can do it a common way.  I'd like to get to the point where people who
work on one code base can pick up another code base without investing a lot
of time in learning a new build process.

Mostly what I am in favor of, however, is not standardizing anything in
this area - instead what I think the focus should be on is on documenting a
set of "best practices".  It is clear that there are a number of
subprojects actively interested in improving their build processes.

If we end up with nothing else, at least there will be some documentation
produced on an area that I fear is still black magic and voodoo to many...

- Sam Ruby


-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Ceki Gülcü


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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Stefan Bodewig

Ceki Glc [EMAIL PROTECTED] 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Peter Donald

At 03:10  15/3/01 +0100, Ceki Glc 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Ceki Gülcü

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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Peter Donald

At 04:17  15/3/01 +0100, Ceki Glc 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-15 Thread Ceki Gülcü

At 02:46 16.03.2001 +1100, Peter Donald wrote:
At 04:17  15/3/01 +0100, Ceki Glc 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-14 Thread Jon Stevens

on 3/14/01 4:02 PM, "Conor MacNeill" [EMAIL PROTECTED] 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




Re: Directory layout feedback

2001-03-14 Thread jeff

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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]




RE: Directory layout feedback

2001-03-14 Thread Conor MacNeill

Jon,

 From: Jon Stevens [mailto:[EMAIL PROTECTED]]

 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-devm=98018389428408w=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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]