| <!-- saved from url=(0022)http://internet.e-mail --> |
| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="Author" content="Eclipse Project"> |
| <title>Problem Definition - Inflexible Project Structure</title> |
| <link rel="stylesheet" href="../../default_style.css" type="text/css"> |
| </head> |
| <body bgcolor="#FFFFFF" > |
| |
| <div align="left"> |
| <h1>Problem Definition - Inflexible Project Structure</h1> |
| </div> |
| <blockquote> |
| <p><b>Summary</b> <br> |
| Eclipse requires that the contents of each project be stored in a single directory |
| on disk. Every file and folder in that directory tree on disk must belong |
| to the project in the workspace. This restriction makes it difficult to use |
| Eclipse in conjunction with tools that have specific layout requirements for |
| their files, or with users who have legacy file base layouts that they need |
| to maintain. We would like to improve the situation for the 2.1 release of |
| Eclipse. This, the first of two documents, describes the nature of the problem; |
| possible solutions are discussed in a <a href="towards-more-flexible-projects.html"> |
| follow-on document</a>.<br> |
| <br> |
| Last Modified: 14:00 October 4, 2002</p> |
| </blockquote> |
| <p>A number of users of the Eclipse Java IDE complain that Eclipse is overly |
| constraining in where their files are located. Before looking into these |
| complaints, we quickly review how projects are structured in Eclipse (both 2.0 |
| and 1.0).</p> |
| <h2>Review: Properties of Eclipse project structure</h2> |
| <p>Here are the properties of Eclipse workspace projects:</p> |
| <ul> |
| <li>A workspace consists of any number of projects.</li> |
| <li>A workspace has a root directory on disk.</li> |
| <li>The workspace data area holds metadata, and possibly project files.</li> |
| <li>Each project has a root directory on disk.</li> |
| <li>All of a project's files are contained under the root directory.</li> |
| <li>All files under the root directory show up in the project.</li> |
| <li>A project's root directory has a default location within the workspace |
| directory, but can also be assigned to an arbitrary location on disk</li> |
| <li>A project's root directory cannot coincide or overlap with any other |
| project's.</li> |
| <li>Each project can have a team provider.</li> |
| <li>A project descriptor file (".project") appears in the root |
| directory of each project.</li> |
| </ul> |
| <p>The Java development tools uses projects in the following way:</p> |
| <ul> |
| <li>A Java project can have one or more source folders on the compile-time |
| class path.</li> |
| <li>Each source folder contains Java source files and other resources in a |
| Java package hierarchy.</li> |
| <li>A source folder must be a subdirectory under the Java project (at any |
| depth).</li> |
| <li>A source folder must not coincide with or overlap any other source folder.</li> |
| <li>A Java project has one output folder.</li> |
| <li>The output folder must be a subdirectory under the Java project (at any |
| depth) to hold generated class files (and copied resource files).</li> |
| <li>The output folder may coincide with a source folder, but may not be nested |
| within it; and conversely.</li> |
| <li>A Java project can have any number of library JARs on the compile-time |
| class path.</li> |
| <li>A library JAR may be anywhere within the Java project, within a different |
| project, or outside the workspace entirely.</li> |
| <li>A Java project can have any number of other Java projects on the |
| compile-time class path.</li> |
| </ul> |
| <h2>Complaints about lack of flexibility in Eclipse project structure</h2> |
| <p>The following complaints are representative, but not exhaustive. See <a href="#References">References</a> for |
| the related bug reports and newsgroup postings.</p> |
| <h3>Complaint 1: Unable to locate Java output folder elsewhere</h3> |
| <p>There is no way to locate a Java project's output folder other than somewhere |
| under the project subdirectory. There are several different reasons people |
| complain this is too constraining:</p> |
| <ul> |
| <li>It means that generated class files cannot be squirted into a particular location relative to other |
| files. For example, the class files need to be in specific location, such as |
| C:/tomcat/webapps/mytest/WEB-INF/classes/, so that they are seen by a test |
| web server. It is not feasible to locate all the files for the Java project |
| within the test server's directory. This means a separate step is required to copy the files from |
| the Java project output folder to the test server's directory.</li> |
| <li>It can lead to poor performance. The most important files in the project |
| are the source files, so it makes sense to locate these files on a network drive that |
| is backed up regularly. Locating the project's root directory on a network |
| drive provides a developer with protection against losing important work. |
| Unfortunately, this means that the class files in the output folder also end |
| up being stored on that network drive. Many class files are deleted and rewritten |
| each build, leading to increased network load and slower compile times. |
| Performance would be better if the output folder could be put on a |
| local disk drive, separate from irreplaceable project files.</li> |
| </ul> |
| <p>A related complaint is that there is only a single output folder per Java |
| project. It would be more flexible if it was also possible to associate output |
| folders with each Java source folder.</p> |
| <h3>Complaint 2: Unable to deal with Java source files laid out in pre-ordained |
| structures</h3> |
| <p> Many complaints begin with a statement like: "At my company, |
| the directories are structured in a certain way that can't be changed." A |
| pre-ordained layout for source files can come from any number of real-life |
| considerations. The most common one is that many companies have a |
| large pre-existing source code base stored in a company-wide code repository; |
| changing to a different layout would be a very expensive undertaking.</p> |
| <p>As the following examples illustrate, Eclipse cannot deal directly with |
| source files laid out in many pre-ordained |
| structures. This means that using Eclipse requires developers to work instead |
| with a copied and rearranged source file base.</p> |
| <p>Example 1:</p> |
| <p>The source files for the company's products are laid out in one |
| big directory that is version and configuration managed outside Eclipse:</p> |
| <p> |
| |- AllProducts<br> |
| |- Product1<br> |
| |- JavaSourceFiles<br> |
| |- Product2<br> |
| |- JavaSourceFiles<br> |
| </p> |
| <p>If a Java project is created to work on the files in the Product1 directory, |
| the project's output folder and Eclipse metadata files (.classpath and .project), |
| will end up somewhere under AllProducts. This pollutes the source tree with |
| files that do not belong there.</p> |
| <p>Example 2:</p> |
| <p>The Java source files for the company's products are all held in |
| a single package directory like this:</p> |
| <p> |
| |- AllJavaSourceFiles<br> |
| |- com<br> |
| |- xyz<br> |
| |- product1<br> |
| |
| |- P1Main.java<br> |
| |- product2<br> |
| |
| |- P2Main.java<br> |
| </p> |
| <p>If a Java project is created to work on Product 1, AllJavaSourceFiles will |
| need to be specified as a source folder. But this is unworkable because it means that all the source files for |
| Product 2 will also be included in the Java project and will get compiled along with |
| those of Product 1.</p> |
| <p>Example 3:</p> |
| <p>The Java source files for a product are laid out in |
| package directory like this:</p> |
| <p> |
| |- Product1<br> |
| |- JavaSourcesFiles<br> |
| |- com<br> |
| |- xyz<br> |
| |
| |- product1<br> |
| |
| |- P1Main.java<br> |
| |- tests<br> |
| |- com<br> |
| |
| |- xyz<br> |
| |
| |- product1<br> |
| |
| |- tests<br> |
| |
| |- |
| P1Test.java<br> |
| </p> |
| <p>If a Java project is created to work on Product 1, both Product1/JavaSourcesFiles |
| and Product1/JavaSourcesFiles/tests would need to be given as source folders. |
| Eclipse does not allow this (source folder are not allowed to overlap). If |
| Product1/JavaSourcesFiles/tests is not declared as a source folder, then the |
| Eclipse compiler expects P1Test.java to be in an incorrect package |
| ("tests.com.xyz.product1.tests" rather than |
| ("com.xyz.product1.tests"). Putting the tests in a separate Java |
| project does not work either.</p> |
| <p>Example 4: </p> |
| <p> The Java source files for two products require a common framework:</p> |
| <p>|- CommonFramework<br> |
| |- JavaSourceFiles<br> |
| |- Product1<br> |
| |- JavaSourceFiles<br> |
| |- Product2<br> |
| |- JavaSourceFiles<br> |
| </p> |
| <p>If a Java project is created to work on Product 1, both Product1/JavaSourcesFiles |
| and CommonFramework/JavaSourcesFiles need to be specified as source folders so |
| that all the code needed for Product 1 is compiled. This means that CommonFramework/JavaSourcesFiles is |
| included in the same project directory as Product1/JavaSourcesFiles. If a Java |
| project is created to work on Product 2, it would need its own copy of |
| CommonFramework/JavaSourcesFiles. If CommonFramework/JavaSourcesFiles are |
| instead placed in a separate Java project, there will be compilation ordering |
| problems when there are mutual references between the common code and the |
| product code.</p> |
| <p>Other examples could be constructed, but the above ones give the flavor of |
| just how inflexible Eclipse is when dealing with source files arranged in |
| perfectly reasonable ways. </p> |
| <h2>Analysis</h2> |
| <p>Note that although the complaints are coming from Java programmers using Java |
| projects, it is not unreasonable to suppose that similar problems could arise |
| when Eclipse is used for other kinds of development, such as C code or web |
| pages. This suggests that the problem should not be construed narrowly, as just a |
| problem just with JDT. The roots of the problem may lie deeper, in the Eclipse Platform |
| itself; resolving the problem may require reforming both.</p> |
| <p>The most obvious restrictions are that all of a project's files must be |
| contained under a single project root directory in the file system. Eclipse |
| projects are <b>single-rooted</b>. Since a Java project's source and output |
| folders are constrained to lie within the project, they thereby inherit |
| constraints from the Eclipse project.</p> |
| <p>Even if the above restrictions were not the problem, there are the further |
| restrictions that all files in the file system below the project root directory |
| are automatically included in the project, and that all Java source files below |
| a source folder are automatically included on the compile-time class path. In |
| other words, Eclipse projects are <b>all-inclusive</b>, as are the source |
| folders of Java projects. In Examples 2 and 3, the complaint is that there is no |
| way to selectively exclude files.</p> |
| <p>Example 4 illustrates a third angle to the problem: that there is no easy way |
| to share common Java source files between projects. In other words, Eclipse |
| projects are <b>non-overlapping</b>. Nor, as Example 3 illustrates, is it |
| possible to have overlapping source folders within a single Java project.</p> |
| <p>To summarize:</p> |
| <ul> |
| <li>With respect to the files in the local file system, an Eclipse project is |
| single-rooted, all-inclusive, and non-overlapping.</li> |
| <li>A Java project's source folders are all-inclusive and non-overlapping, and |
| constrained to lie within a single Eclipse project.</li> |
| <li>A Java project's output folder is constrained to lie within a Eclipse |
| project.</li> |
| </ul> |
| |
| <h2><a name="References">References</a></h2> |
| <p>Eclipse bug reports touching on inflexible project structure:</p> |
| <ul> |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=6664"> 6664 [resources] Sym-link-like feature</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=3074"> |
| 3074: allow external libs onto the platform classpath?</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=6883"> |
| 6883: Multiple projects using the same location</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8450"> |
| 8450: Project Hierarchy</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8655"> |
| 8655: DCR - Support for external class folders</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8783"> |
| 8783: Availability to add source directories outside project root</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=9508"> |
| 9508: resources outside a projcet tree</a></li> |
| |
| <li><a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=12259"> |
| 12259: Need to exclude some specific src/ directories</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=15335"> |
| 15335: Build output in phisical folder</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=18226"> |
| 18226: Add button disabled on New Classpath Variable Entry dialog</a></li> |
| |
| <li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=19111"> |
| 19111: different out folder/drive for class-files</a></li> |
| |
| <li><a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=24123">24123: Support for multiple output dirs</a></li> |
| </ul> |
| <p>Eclipse newsgroup discussions touching on inflexible project structure:</p> |
| <ul> |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg10359.html"> |
| Request for Comment: Sym-Link/Shortcut Feature Request</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg10527.html"> |
| Unfortunate requirement that source reside in project</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg16443.html"> |
| Project Location Cannot Overlap?</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg17457.html"> |
| Excluding some source directories</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg18684.html"> |
| working with files _not_ in the project folder</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg08082.html"> |
| Source folders</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg19749.html"> |
| Rigid project directory structure?</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg21223.html"> |
| Q: Setup project, classpath, etc.</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg32082.html"> |
| File sharing between projects</a></li> |
| |
| <li><a href="news://www.eclipse.org:119/am7voi$9it$1@rogue.oti.com"> |
| Source directory issue... need help!</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg16371.html"> |
| build classes in seperate directory</a></li> |
| |
| <li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg14088.html"> |
| How do I specify an external directory for classes?</a></li> |
| </ul> |
| </body> |
| </html> |