Re: Proposed dirlayout document
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 > operation be avoided? > The operation is what saves me from having to have two sets of and 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
Less talk. More coding. -jon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
>IMHO, the intermediate build directory can and should be avoided. Instead of s >electively copying from the intermediate build/ directory to dist/, one can ge >nerate directly to dist/ and use tar/zip selectively to create the distributio >n. The latter solution keeps just one copy of files which saves space. More im >portantly the latter is less error-prone as there is only one place to edit fi >les. Does that make sense? Ceki It's pretty normal to do this kind of a thing. The distribution is meant for outside consumption and is automatically generated by the configuration management system (in this case ant), so you never directly modify it. Therefore it shouldn't be any more error-prone. The build tree is meant for internal consumption and can contain a significantly different layout, containing all sorts of stuff such as infrastructure for quality assurance that never makes it into the distribution, but is generally tailored for facilitating development and testing. I think the reason this whole thing is a bit muddled is because we're mostly producing development software, where the line between consumer and producer is blurred. Also, being open source, with an emphasis on open, there's less of an impetus to hide development artifacts from the consumer. At any rate, I think there's a clear need for allowing a development build tree separate from the distribution tree. Projects primarily constituted of development libraries probably won't make use of it, but others consisting of one or more applications, probably will. daniel - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
"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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Technical Reviewer Needed
Randy, Essentially what I'm looking for is a review of about 4 chapters (about 30 - 49 pp) : one is on the Tomcat server in general, and the others are on JSP applications developed with the Tomcat server. Review will probably take place in the next three weeks. I would need each chapter returned to me in about a week. Review will involve reading a document (in .rtf format) and inserting comments into the text where appropriate. Pay is about $ 250-300 in US dollars. Specifically, I'm hoping someone can provide a roadmap of where Tomcat is going, i.e., what features are expected to be in the server in 4.0x and beyond and how that would impact what I've written in my book. Do you have that information? Let me know if you're still interested. Thanks, -- Art --- Randy Layman <[EMAIL PROTECTED]> wrote: > > I might be interested. What level of time commitment are we talking > about (would 2 hours a night plus weekends be fast enough)? Is any prior > editing experience required, or is just using Tomcat enough? (By the way, I > would probably be qualified to do the entire book as well). > > Randy > > > -Original Message- > > From: Art Taylor [mailto:[EMAIL PROTECTED]] > > Sent: Monday, May 07, 2001 2:08 PM > > To: [EMAIL PROTECTED] > > Subject: Technical Reviewer Needed > > > > > > > > I am in the process of completing a Java Web site book which > > features the > > award-winning Tomcat server. I need a tech reviewer for a few > > of the chapters, > > preferably someone who is familiar with the direction of the > > development of the > > Tomcat server (i.e., what is in version 3.3 and 4.0, what > > features will be > > supported in future releases, etc.). > > > > This would only involve a few chapters and yes, there is some > > pay involved. > > > > Any takers? > > > >-- Art Taylor > > > > > > __ > > Do You Yahoo!? > > Yahoo! Auctions - buy the things you want at great prices > > http://auctions.yahoo.com/ > > > > - > > To unsubscribe, e-mail: [EMAIL PROTECTED] > > For additional commands, e-mail: [EMAIL PROTECTED] > > > > - > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > __ Do You Yahoo!? Yahoo! Auctions - buy the things you want at great prices http://auctions.yahoo.com/ - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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 ? 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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 ? 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Proposed dirlayout document
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 ? 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
