Re: Directory layout feedback
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
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
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
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
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
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
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
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
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
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]
